RNBO Codebox

Language support for Cycling '74 RNBO codebox and codebox~ script files in VS Code and Cursor.

This repository contains the extension source, generated RNBO symbol catalog, validation fixtures, and release tooling.

The VS Code/Cursor extension README is generated from docs/extension-readme.md so the installed extension page stays focused on user-facing features and usage.

Requirements

RNBO Codebox requires VS Code or Cursor compatible with VS Code 1.82 or newer.

Local Strict Mode is optional. It requires a local Max installation with RNBO installed.

Features

• Syntax highlighting for .rnboscr files.
• RNBO-aware completions for operators, constants, constructors, lifecycle functions, I/O variables, and list methods.
• Hover and signature help for source-backed RNBO APIs.
• Document symbols, semantic tokens, and same-file go to definition for parser-backed declarations.
• Built-in diagnostics for common RNBO Codebox issues.
• Optional Local Strict Mode using the RNBO package inside a local Max app.

Using The Extension

Open a .rnboscr file. RNBO Codebox automatically applies the language mode and starts the language server.

If a file is not detected automatically, open the command palette and run RNBO: Switch to RNBO Codebox Language Mode.

Built-In Diagnostics

Built-in diagnostics run by default and do not require Max.

They check common issues such as undefined names, invalid decorator metadata, unsupported constructor usage, invalid fixed-size expressions, type mismatches, unsupported syntax, string-literal boundaries, list/member usage, and known availability differences between codebox and codebox~.

Use rnboLanguageServer.enableStrictValidation to enable or disable these built-in diagnostics.

Codebox Kind

Some RNBO APIs differ between codebox and codebox~.

Use rnboLanguageServer.codeboxKind to control availability diagnostics:

• auto avoids guessing when a standalone .rnboscr file does not identify its owning RNBO object.
• codebox checks plain codebox availability.
• codebox~ checks signal codebox~ availability.

Local Strict Mode

Local Strict Mode is disabled by default. It uses the RNBO package inside a local Max app to run additional RNBO parsing, code generation, and generated C++ syntax validation.

Enable it only if Max with RNBO is installed locally.

macOS default path:

{
  "rnboLanguageServer.localStrictMode.enabled": true,
  "rnboLanguageServer.localStrictMode.xamPackagePath": "/Applications/Max.app/Contents/Resources/C74/packages/RNBO/server/node_modules/@rnbo/xam"
}

Windows default path:

{
  "rnboLanguageServer.localStrictMode.enabled": true,
  "rnboLanguageServer.localStrictMode.xamPackagePath": "C:\\Program Files\\Cycling '74\\Max 9\\resources\\packages\\RNBO\\server\\node_modules\\@rnbo\\xam"
}

Generated C++ syntax validation also requires clang++ on PATH.

Local Strict Mode diagnostics are reported as warnings from rnbo-strict. The normal extension path does not require Max, XAM, or local RNBO compiler internals.

Install From Source

npm install
npm run compile

Open the extension folder as the VS Code or Cursor workspace, then run the extension from a local extension-host launch configuration or package a VSIX and install it manually.

Build A VSIX

npm run build:release

The release build regenerates the RNBO symbol catalog, compiles the client/server/shared projects, runs the validation suite, and writes builds/rnbo-codebox-<version>.vsix.

After packaging, run:

npm run smoke:packaged-vsix

Attach the generated VSIX to the matching GitHub Release instead of committing builds/.

Source Data

The checked-in C74/ folder contains Cycling '74 RNBO documentation, examples, and source-operator files.

• C74/docs provides reference material used by catalog generation.
• C74/source_operators provides source-backed operator metadata.
• C74/examples provides golden validation fixtures for the live language server.

See C74/README.md for provenance and refresh notes.

The VSIX package excludes C74/, scripts, tests, maintainer docs, TypeScript sources, source maps, package locks, nested client/server dependency folders, and local build artifacts. It ships compiled extension code, the generated runtime catalog, grammar/language configuration, package-facing extension docs, public notices, and root runtime dependencies.

Development

See CONTRIBUTING.md for setup, validation, and release notes.

See docs/maintainer-guide.md for the source-data and verification model.

License

The extension code is released under the MIT License.

Cycling '74 owns the upstream RNBO documentation, examples, and source material mirrored under C74/. That material is included as source data for catalog generation and validation, not relicensed as MIT.

See THIRD_PARTY_NOTICES.md.