Xcratch Extension Debug Auto

Debug Extension with Query Parameter

Autonomously load and inspect an Xcratch extension by appending it as the ?extension= query parameter of a Scratch editor. The extension's build output is served by a local HTTPS live server; the editor fetches it from https://0.0.0.0:5500.

Two editor targets are supported — pick one:

The procedure is identical for both targets except for the editor base URL (Step 2) and the live-server root that determines the extension path (Step 1). A single launch config (Step 3) handles the certificate and Local Network Access barriers for both.

When to Use

• Verify that a built extension loads without errors
• Inspect browser console output after extension load
• Check that extension blocks appear in the Scratch editor toolbox
• Reproduce a runtime failure triggered by loading via URL

Prerequisites

Common to both targets:

Target-specific:

Procedure

Step 1 — Resolve the extension URL

The extension is served by the live server at https://0.0.0.0:5500/<path>, where <path> is relative to whatever directory the live server was told to serve:

• public target — the live server runs in the extension repo and serves its root, so the path is the dist file relative to the repo root:

  https://0.0.0.0:5500/dist/xcratchExample.mjs
  

• local target — the scratch-editor start live server task serves .. (the parent workspace that also contains your extension repos), so the path includes the extension repo directory:

  https://0.0.0.0:5500/xcx-my-extension/dist/myExtension.mjs
  

Confirm the dist file exists on disk before navigating.

Step 2 — Compose the editor URL

Combine the target's editor base URL with the extension query parameter:

# public
https://xcratch.github.io/editor/?extension=https://0.0.0.0:5500/<path-to-dist-file>

# local
https://localhost:8601/?extension=https://0.0.0.0:5500/<path-to-dist-file>

Step 3 — Configure playwright-cli to allow the local HTTPS extension

Loading the extension crosses two browser barriers that block the fetch and cannot be clicked away from playwright (they are native browser UI, not in-page elements):

1. Self-signed certificate rejection for https://0.0.0.0:5500 (and, for the local target, for https://localhost:8601 as well — both use mkcert self-signed certs that playwright's bundled browser does not trust).
2. Local Network Access (LNA) permission prompt — only for the public target. Because https://xcratch.github.io is a public origin fetching from the 0.0.0.0:5500 loopback address, Chrome shows "xcratch.github.io is requesting permission to access other apps and services on this device". If not granted, the fetch fails with Permission was denied for this request to access the 'loopback' address space and the extension never loads. The local target does not trigger this (loopback→loopback), but disabling the check is harmless there too.

Both barriers are bypassed by launching the browser with a config file. Create playwright-cli.json (auto-loaded from the current directory, or pass it via --config) — the same config works for both targets:

{
  "browser": {
    "launchOptions": {
      "args": [
        "--disable-features=LocalNetworkAccessChecks,BlockInsecurePrivateNetworkRequests,PrivateNetworkAccessSendPreflights,PrivateNetworkAccessRespectPreflightResults"
      ]
    },
    "contextOptions": {
      "ignoreHTTPSErrors": true
    }
  }
}

• contextOptions.ignoreHTTPSErrors: true → accept the self-signed certs (no "Advanced → Proceed").
• launchOptions.args --disable-features=... → disable the Local Network Access / Private Network Access prompt so a public→loopback fetch is allowed without the (unclickable) permission dialog. Multiple feature names are listed for cross-version safety; harmless extras are ignored.

Step 4 — Open the browser and navigate

The config must be applied at browser launch time, so kill any stale session first, then open:

playwright-cli kill-all
playwright-cli open --headed --config ./playwright-cli.json
playwright-cli goto "<composed editor URL from Step 2>"

If playwright-cli.json sits in the current directory it is auto-loaded and --config can be omitted. With this config the extension loads with no manual clicks — no cert warning, no LNA prompt, no reload.

Step 5 — Wait for the editor to load

Take a snapshot and confirm the Scratch editor UI is visible (stage, toolbox, sprite list):

playwright-cli snapshot

If the editor is still loading, wait and snapshot again.

Step 6 — Check the browser console for errors

playwright-cli console

Look for:

• Failed to load extension messages
• Network errors (CORS, 404, certificate rejection)
• JavaScript exceptions thrown by the extension

Step 7 — Verify extension blocks appear in the toolbox

Take a screenshot of the full editor UI:

playwright-cli screenshot

Inspect the snapshot for a custom category block corresponding to the extension. If not found, the extension likely failed to register — check the console output from Step 6.

Step 8 — Collect network diagnostics (if needed)

playwright-cli network

Confirm the .mjs dist file was fetched with HTTP 200 from https://0.0.0.0:5500.

Step 9 — Report findings

Summarize:

1. Which target was used (public / local) and whether the extension URL loaded successfully (HTTP status)
2. Any console errors and their messages
3. Whether the extension's blocks appeared in the toolbox (with screenshot)
4. Suggested fix if an error was identified

Common Errors and Fixes

Related Skills

• xcratch-extension-debug — full VS Code launch config and source map setup
• playwright-cli — browser automation commands reference