XY

XY is a premium cybernetic wavetable synthesizer by Astra Matrix.

Browser-first instrument with a portable DSP / patch model designed for later native VST3 / AU porting. This repository is the canonical source for Cursor (or any agent IDE) to continue development.

Product	XY
Company	Astra Matrix
Status	Playable browser instrument (v0.1)
Stack	React 19 · TypeScript · Vite · TanStack Start · Zustand · Web Audio
Repo	https://github.com/ALaustrup/aether-core (working name; product is XY)

---

What this is

A production-shaped original wavetable synth — not a toy demo:

• 3 wavetable oscillators + sub + noise + transient
• Dual filters with serial / parallel / split / blend routing
• 4 envelopes · 4 LFOs · 2 MSEGs · random generators · 8 macros
• Modulation matrix with typed sources / targets
• Step sequencer / arpeggiator
• Effects rack (distortion, chorus, delay, reverb, bitcrush, limiter, …)
• Factory presets (Machine Cathedral, Neural Collapse, Fractal Pursuit, …)
• Perform / Design / Deep UI density modes
• Keyboard (on-screen + computer keys) + velocity / octave / sustain

Audio engine is separated from UI (src/synth/engine/AudioEngine.ts) so the patch model and DSP logic can be reimplemented in C++ for a native plugin later.

---

Quick start (local / Cursor)

git clone https://github.com/ALaustrup/aether-core.git XY
cd XY
npm install
npm run dev

Open the URL Vite prints (default http://127.0.0.1:8080).

1. Click Power On (browsers require a user gesture for audio).
2. Play notes: on-screen keyboard or keys A–K (notes), Z/X (octave), Space (sustain), Esc (panic).
3. Load factory presets from the browser; try Fractal Pursuit, Machine Cathedral, Neural Collapse.

npm run typecheck
npm run build

---

Open this in Cursor — do this first

1. Clone this repo and open the folder as the Cursor workspace root.
2. Open CURSOR_PROMPT.md and paste it into a new Cursor Agent chat as the master instruction.
3. Cursor will also auto-load .cursor/rules/xy.mdc (project rules).
4. Read docs/ARCHITECTURE.md before large changes.
5. Follow docs/ROADMAP.md for phase order (do not jump to VST3 first).

Recommended Cursor workflow

Phase	Goal	Docs
0	Run + stabilize browser instrument	this README, docs/ARCHITECTURE.md
1	Polish UI / presets / bugs	docs/UI_SYSTEM.md, docs/DSP_MODEL.md
2	Tauri desktop shell (optional)	docs/PORTING_TAURI.md
3	Native VST3 (JUCE) — new C++ tree	docs/PORTING_VST3.md

Critical truth for agents: the Web Audio engine cannot become a VST3 binary by wrapping or transpiling. VST3 requires a native C++ (or Rust) real-time DSP reimplementation that mirrors the patch model in types.ts + algorithms in AudioEngine.ts. The JS/TS code is the reference implementation and product UX, not the plugin binary.

---

Repository layout

.
├── README.md                 # You are here
├── CURSOR_PROMPT.md          # Master prompt — paste into Cursor Agent
├── LICENSE
├── package.json
├── vite.config.ts
├── tsconfig.json
├── .cursor/rules/xy.mdc      # Always-on Cursor rules
├── docs/
│   ├── ARCHITECTURE.md       # System map, data flow, file ownership
│   ├── DSP_MODEL.md          # Patch schema, voice path, modulation
│   ├── UI_SYSTEM.md          # Visual language, panels, modes
│   ├── ROADMAP.md            # Phased product plan
│   ├── PORTING_TAURI.md      # Desktop app path
│   └── PORTING_VST3.md       # Native plugin path (JUCE)
└── src/
    ├── routes/               # TanStack Start routes
    ├── styles.css            # Design tokens + component chrome
    ├── lib/utils.ts          # cn() helper
    └── synth/
        ├── types.ts          # ★ Portable patch / DSP model (source of truth)
        ├── store.ts          # Zustand UI + patch state
        ├── engine/
        │   └── AudioEngine.ts  # ★ Web Audio DSP (reference impl)
        ├── data/
        │   ├── defaultPatch.ts
        │   ├── presets.ts      # Factory banks
        │   └── wavetables.ts   # Procedural tables + warp modes
        └── components/         # Instrument UI

---

Product identity

Field	Value
Name	XY
Company	Astra Matrix
Genre	Cybernetic / cinematic / electronic wavetable
Peer bar	Tone2 Icarus-class ambition (not a clone)
Brand voice	Precise, industrial-luxury, no toy UI

Internal engine codename in older strings may still say Aether Core — rebrand remaining UI copy to XY when polishing.

---

What NOT to do

• Do not claim the browser app is a VST3 plugin.
• Do not put real-time DSP inside React render paths.
• Do not store high-rate oscilloscope data in React state (use vizBus pattern).
• Do not add multiplayer / cloud auth — this product is a self-contained instrument.
• Do not start JUCE until Phase 0–1 are stable and types.ts is frozen as the contract.

---

License

Proprietary — Astra Matrix. All rights reserved unless otherwise stated.

Built with Grok (xAI) as development partner.

---

by ASTRA MATRIX