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:

Target	Editor base URL	Use when
public (default)	https://xcratch.github.io/editor/	Test the extension against the published editor. No local scratch-editor checkout needed.
local	https://localhost:8601/	Test against a local (possibly modified) scratch-editor build — e.g. developing scratch-editor itself, or the extension depends on unreleased editor changes.

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:

Requirement	Detail
Live server running	port 5500, serving the extension build over HTTPS
Extension built	npm run build or npm run watch ran in the extension repo

Target-specific:

Target	Extra requirement
public	mkcert certs in <extension-repo>/.vscode/. Start the live server via the start live server task in the extension's VS Code workspace (or the debug extension on xcratch.github.io editor launch config, which starts it via preLaunchTask).
local	A local scratch-editor checkout running scratch-gui on port 8601, plus mkcert certs in scratch-editor/.vscode/. Start both servers via the start debug servers task in the scratch-editor workspace.

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

Symptom	Likely Cause	Fix
Certificate warning on 0.0.0.0:5500 or localhost:8601	Live server / dev-server cert not trusted by playwright's browser	Launch with the Step 3 config (contextOptions.ignoreHTTPSErrors: true); run playwright-cli kill-all then re-open so it applies
Extension never loads; console shows Permission was denied for this request to access the 'loopback' address space (no fetch to 0.0.0.0:5500)	Chrome Local Network Access prompt blocking public→loopback (public target only); the native dialog can't be clicked from playwright	Launch with the Step 3 config (launchOptions.args --disable-features=...); run playwright-cli kill-all then re-open so the flag applies
404 on ext URL	Build output missing, or wrong live-server root for the target	Run npm run build in the extension repo; re-check the Step 1 path for the chosen target
CORS error	Live server not started with --cors	Check that the start live server task is running
Extension blocks not shown	Extension threw at registration	Check console for JS errors in extension source

Related Skills

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