Debugging

A ScriptWeaver app is real JavaScript, so you can debug it with a real debugger — breakpoints, a call stack, variable inspection, stepping, and a watch/console — from VS Code or VSCodium. The Player ships a small debug adapter that bridges the editor to a debug transport built into the Player. Your app needs no changes and no extra libraries: you debug the same code you run.

Platform support. Out-of-process debugging works on Linux, macOS, and Windows — the Player's debug transport is built into all three. Linux is the continuously tested platform (the acceptance suite); macOS and Windows share the same portable Go + QuickJS code path. One cross-platform caveat: breakpoints bind by exact file path, so open the project at its real, canonical path (matters most on Windows and macOS — see Limitations).

What you get

• Breakpoints in your .js source (e.g. a click handler in handlers.js).
• A call stack of the frames currently on the stack.
• Locals and Closure variable scopes for the selected frame.
• Step over / into / out, continue, and pause.
• Evaluate an expression in the selected frame — type it in the Debug Console, or add a watch.

Get the adapter

The adapter is vscode-scriptweaver-debug/ — a tiny, zero-dependency folder that ships in the ScriptWeaver source repository and inside ScriptWeaver Designer bundles. Load it into your editor in any of the usual ways:

# 1) Open it as a development extension on your project (no install):
codium --extensionDevelopmentPath=/path/to/vscode-scriptweaver-debug  myproject/
#    …or with VS Code:  code --extensionDevelopmentPath=…

# 2) …or package a .vsix once and install it:
cd /path/to/vscode-scriptweaver-debug && npx @vscode/vsce package
codium --install-extension scriptweaver-debug-*.vsix

Use an absolute path for --extensionDevelopmentPath. A relative path — including a bare . — is not resolved against your working directory, so the editor silently loads no extension and F5 then reports debug type 'scriptweaver' is not supported. Pass the full path (or "$PWD" from inside the folder).

The Player binary must be reachable too — either on PATH as scriptweaver, or named explicitly with playerPath in the launch config below.

Set up a launch configuration

Add .vscode/launch.json to your project (or accept the ScriptWeaver: Debug app configuration the extension offers):

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "scriptweaver",
      "request": "launch",
      "name": "ScriptWeaver: Debug app",
      "program": "${workspaceFolder}/main.js", // the app entry the Player runs
      "cwd": "${workspaceFolder}",
      "playerPath": "scriptweaver", // PATH name or an absolute path
      "args": [], // extra app args, e.g. ["--theme","flatly"]
      "stopOnEntry": false // pause before the first line of user code
    }
  ]
}

Now open a source file, click the gutter to set a breakpoint, and press F5. The app launches under the Player; when execution reaches the breakpoint it pauses, and the editor shows the call stack, Locals, and Closure. Step through with the usual controls, hover a variable to see its value, and type expressions in the Debug Console to evaluate them in the selected frame.

How it works (no code changes)

The adapter listens on a local port, launches the Player with the environment variable SCRIPTWEAVER_DEBUG=127.0.0.1:<port>, and the Player dials back. When that variable is present the Player attaches its debugger and pauses at entry so the editor can place breakpoints before your code runs; when it is absent the Player runs normally, with no debugging overhead. Your application code is never touched — debugging is entirely external.

Behind the scenes the adapter translates the editor's standard Debug Adapter Protocol to the Player's debug wire protocol (documented as DEBUGGER-WIRE-PROTOCOL.md, with the adapter's own README.md, in the ScriptWeaver source repository).

Limitations

This first version mirrors what the debug transport exposes today:

• Path-exact breakpoints — breakpoints bind by exact file identity, so the editor must open the app at the same canonical path the Player runs (matters most on Windows and macOS: backslashes, drive-letter case, and /var→/private/var symlinks can otherwise stop a breakpoint from binding).
• Line breakpoints only — no conditional breakpoints, logpoints, or break-on-exception yet.
• Flat variables — locals and closure show as display strings; objects and arrays don't expand into a tree yet.
• Single thread; the stack shows the frames physically on it.
• Loose source only — debug your on-disk .js files. Sealed .swx bundles and baked executables strip the debug information, so they can't be debugged (see Packaging apps).
• The transport is a localhost, single-connection, unauthenticated development channel — meant for debugging on your own machine, not a remote service.

These are transport limits, not adapter limits: as the Player's debug protocol grows, the adapter grows with it.

Next

• Command-line reference — --trace prints the underlying Tk commands, a complementary debugging aid
• Packaging apps — shipping your app (sealed apps can't be debugged)
• System & files — the sw.* runtime APIs