Synapse Framework (macOS)

Synapse is an advanced, multi-shell script execution environment for Roblox. This is the macOS-adapted version of the Synapse Framework, featuring a powerful Monaco-based editor, a local HTTP executor bridge (Port, Stream, or Compat), an extensible plugin system, and iconic UI themes (Synapse Blue, Synapse Original 2017, Synapse X, V3) for a fast, customizable scripting experience.

Documentation

Doc	Description
docs/PROJECT_OVERVIEW.md	Architecture, routes, IPC, shells, and key file map
docs/EXECUTOR_BRIDGE.md	Executor bridge — Port, Stream, and Compat methods, settings, protocol, Lua clients
docs/PLUGINS.md	Plugin system — install, permissions, host API, bridge providers
docs/SOURCE_DISTRIBUTION.md	Small source archives, ui-export/, verify/pack scripts
Universal CUI/README.md	Universal Custom UI — reusable Unified Bridge server, client, and SDK (future separate project)

Workspace size (read this first)

A full dev folder is often 2+ GiB on disk — that is normal while you build, but it is not the size of the source tree.

Path	Typical size	What it is
src-tauri/target/	~2 GiB	Rust compile output — npm run tauri:build:macos
node_modules/	~200 MiB	npm packages — npm install
dist/	~20 MiB	Vite production bundle — npm run build
ui-export/	~8 MiB	UI porting snapshot — npm run export:ui

Tracked source (src/, src-tauri/ without target/, configs, docs) is about 5–10 MiB.

Delete local build artifacts (nothing in src/ is removed):

npm run clean

Preview first: npm run clean:dry. After cleaning, reinstall when you need to build again: npm install, then npm run build or npm run tauri:build:macos.

Sharing source — do not zip the whole folder. Use npm run source:pack (~11–15 MiB). See docs/SOURCE_DISTRIBUTION.md.

---

Building from Source

Prerequisites

• macOS 12.0+ (Monterey or newer)
• Xcode from the Mac App Store (or Xcode Command Line Tools: xcode-select --install)
• Node.js 18 or newer
• Rust — install via rustup.rs (stable toolchain)

Install dependencies

npm install

Or use the one-shot setup script:

bash scripts/setup-macos-build.sh

Development

npm run dev:macos                   # Tauri dev with macOS config

Or for browser-only UI (no native shell):

npm run dev

Then open http://127.0.0.1:5173.

Production build

npm run tauri:build:macos            # release binary → src-tauri/target/release-macos/app
npm run release:macos                # build + portable zip → bundle/macos/

For faster dev/test builds (thin LTO, more codegen units):

npm run tauri:build:macos:fast      # → src-tauri/target/release-macos-fast/app
npm run release:macos:fast          # build + zip → bundle/macos/

.app bundle and .dmg

npm run bundle:macos:app             # reconstruct .app bundle from existing binary
npm run bundle:macos:dmg             # .app bundle + .dmg installer

Run the binary

npm run run:macos                    # auto-detects release-macos or release-macos-fast

Native binary location

The compiled binary is placed at:

• Apple Silicon (arm64): src-tauri/target/aarch64-apple-darwin/release-macos/app
• Intel (x86_64): src-tauri/target/x86_64-apple-darwin/release-macos/app
• Fallback (no arch in path): src-tauri/target/release-macos/app

Bundle output goes to bundle/macos/Synapse-Framework-macos-portable.zip.

Note on window capture

The theme screenshot feature uses the xcap crate for window capture. On macOS 10.15+, screen recording permission is required for window capture. The system will prompt for permission on first use.

Small source distribution

The canonical build tree is src/ + src-tauri/ + root config files. To check nothing required is missing:

npm run source:verify

After npm install, verify the frontend build:

npm run source:verify:build

Do not zip the whole project folder. On disk it is often 2+ GiB because of src-tauri/target/ and node_modules/. Those are not source — they are rebuilt after extract.

Check what is using space:

npm run source:measure

Create a small shareable zip (~8–15 MiB, include-only from source.manifest.json):

npm run source:pack

Output: synapse-source-small.zip (~30–35 MiB with release update zip: build source, logo presets, Tauri icons/permissions, bundle/macos/Synapse-Framework-macos-portable.zip, ui-export; no target/ or node_modules/). Requires npm run tauri:build:macos (or existing binary) before source:pack so the update zip can be included.

npm run source:pack -- --no-ui-export   # omit ui-export/
npm run source:pack:full                # alias for source:pack (same contents)
npm run source:pack:ui                  # ui-export.zip only for UI porters

UI export (portability)

ui-export/ is a regenerated snapshot of all UI shells for porting into other codebases. It is gitignored (not stored in the repo) to keep source small. Vite does not compile it — the live app always uses src/.

npm run export:ui

This creates ui-export/ locally and writes export-manifest.json (export path → source path). See ui-export/PORTING.md after export. Share via npm run source:pack:ui if needed.

What is not part of the source tree

These paths are generated locally or are reference-only — do not include them when sharing build source (see npm run source:pack):

Path	Regenerated by	Approx. size
node_modules/	npm install	~200 MB
dist/	npm run build	~20 MB
src-tauri/target/	npm run tauri:build:macos or tauri:dev	~2 GB (release)
someone-elses-v3-project-workspace/	— (removed; not part of Synapse)	—
ui-export/	npm run export:ui (also runs on tauri:build:macos / release:macos)	~7 MB (included in default source:pack)

The tracked project source (everything else) is roughly 10–20 MB. A source archive under 100 MB should exclude the artifact paths above; run npm install after extracting before building.

Project structure

Path	Role
src/	React/Vite frontend (Synapse Blue, Synapse Original 2017, Synapse X, V3 shells)
src-tauri/	Rust backend, Tauri config, executor bridge
src-tauri/resources/scripts/	Port Bridge.lua, Stream Bridge.lua, Compat Bridge.lua, and bundled runtime assets
logo presets/	Optional top-bar logo PNGs (loaded at runtime via Vite glob)
ui-export/	Regenerated UI-only snapshot for external porters (npm run export:ui)
bundle/macos/	macOS release zip output
docs/	Architecture and bridge documentation
source.manifest.json	Required paths for npm run source:verify

Architecture (summary)

flowchart LR
  React["React src/"] <-->|invoke| Rust["Rust lib.rs"]
  Rust --> Axum["Axum :31337"]
  Axum <-->|HTTP /port_bridge/*| PortLua["Port Bridge.lua"]
  Axum <-->|HTTP /stream_bridge/*| StreamLua["Stream Bridge.lua"]
  Axum <-->|HTTP /compat_bridge/*| CompatLua["Compat Bridge.lua"]

Loading

Four UI shells share one app, selected via uiMode in src/app/appSettings.ts. Bridge method (bridgeMethod: port | stream | compat) lives in the same settings and is available in every shell's Settings/Options. All three methods are served from one Axum process on :31337; the dropdown changes which connection flag and execute queue the UI uses. Port (Fastest) uses HTTP long-polling and only requires game:HttpGet; Stream adds an optional NDJSON heartbeat; Compat uses short polling for HttpGet-only executors that cannot hold long connections. Cold-start routing is synchronized between src/main.tsx, React Router, and Rust (app_settings_snapshot.json).

See docs/PROJECT_OVERVIEW.md for routes, Tauri commands, persistence, and conventions.