@obinexusltd/scratch-polycall

Scratch 3/TurboWarp custom extension for libpolycall 1.5, packaged for public distribution through npmjs.org.

Scratch runs inside a browser sandbox and cannot load a C library directly. This package therefore has three deliberately small layers:

1. A sandbox-compatible Scratch extension sends a configuration path with Scratch.fetch.
2. A localhost-only Node.js bridge forwards the path to a native CLI.
3. The native adapter makes exactly one call to polycall_ffi_run_config(config_path, 1) and returns its status unchanged.

No layer parses the shared configuration or duplicates libpolycall runtime logic.

Install from npm

npm install @obinexusltd/scratch-polycall

The package contains the portable extension, localhost bridge, C sources and headers, examples, tests, Makefile, configuration, and binding manifest. Platform-specific native executables are intentionally excluded.

Build the native CLI

Build libpolycall first, then provide its linker flags:

npm run build:cli -- POLYCALL_LDFLAGS="-LC:/path/to/libpolycall/lib -lpolycall"

This creates build/scratch_polycall_cli.exe on Windows or build/scratch_polycall_cli on Unix-like systems. The bridge also accepts an explicit executable through POLYCALL_CLI.

Start the bridge

npm run start:bridge

The bridge listens only on 127.0.0.1:4815 by default and exposes:

• GET /health
• POST /run-config with { "configPath": "scratch-polycallrc" }

Optional environment variables are SCRATCH_POLYCALL_HOST, SCRATCH_POLYCALL_PORT, and POLYCALL_CLI.

Load the Scratch extension

Load src/scratch-polycall.js using TurboWarp's Custom Extension dialog. You may choose the local file directly or serve the repository over HTTP:

python -m http.server 8080

Then load:

http://localhost:8080/src/scratch-polycall.js

The extension is sandbox-compatible and registers exactly once through Scratch.extensions.register.

Blocks

• set polycall bridge [URL] changes the bridge address.
• run polycall config [CONFIG] asynchronously returns the numeric status.
• last polycall run succeeded? reports whether the last status was zero.
• polycall bridge ready? checks the health endpoint.
• last polycall error reports transport or response errors.

Blocks never throw errors into the Scratch VM. A bridge failure returns -1 and records a readable message in last polycall error.

Custom extensions work in TurboWarp and compatible Scratch mods, but projects using them cannot be uploaded to the official Scratch website. They can be packaged with TurboWarp Packager.

Test

npm test

The suite verifies the exact C boundary, Scratch registration and block metadata, asynchronous status behavior, real localhost HTTP requests, path containment, npm metadata, and tarball-safe directory indexing.

JavaScript API

const polycall = require('@obinexusltd/scratch-polycall');

console.log(polycall.extension);
console.log(polycall.bridgeCli);
console.log(polycall.directories.src.relativeFiles);

The subpath exports @obinexusltd/scratch-polycall/extension and @obinexusltd/scratch-polycall/bridge expose the extension class and bridge helpers for embedding or testing.

Publish publicly

npm pack --dry-run
npm publish --access public

publishConfig.access is already set to public. Publishing is not automatic.

Author and license

Nnamdi Michael Okpala ([email protected]). Licensed under MIT.