feat: MakeCode song export (v0.7.1)

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "scorekit"
-version = "0.7.0"
+version = "0.7.1"
 edition = "2024"
 
 [dependencies]

README.md

@@ -19,6 +19,7 @@ Because the score is plain text, it lives in git next to your code: diff it, rev
 - **Scene suites** — intro / explore / combat / victory sections that share the same musical motifs, compiled from a single file.
 - **Exact event clips** — stable-ID pitched/percussion events, section variants, and deterministic step/linear automation for arrangements that need authored syncopation, fills, filter sweeps, or talking-bass motion.
 - **Sound textures** — layer field recordings, ambience, and SFX (water, birds, engines…) as deterministic loops or beat-scheduled one-shots without baking local paths into the scene.
+- **MakeCode songs** — `scorekit makecode` compiles the same scene into ``music.createSong(hex`…`)`` TypeScript for MakeCode Arcade and micro:bit V2, one song per section, with a manifest of every voice mapping.
 - **`meta.json`** — exact loop points and sample counts, ready for your engine to consume.
 
 ## Install

docs-site/src/agent-skill.md

@@ -1,6 +1,6 @@
 # Agent Skill
 
-The release archive and source repository include an Agent skill under `skills/scorekit`. It teaches a skill-capable coding Agent how to query the schema, write scenes, validate musical structure, apply grammar profiles, and build assets.
+The release archive and source repository include an Agent skill under `skills/scorekit`. It teaches a skill-capable coding Agent how to query the schema, write scenes, validate musical structure, apply grammar profiles, build audio assets, and compile MakeCode `music.createSong` TypeScript.
 
 Install it together with the local binary:
 

docs-site/src/architecture.md

@@ -6,15 +6,16 @@ scorekit is a thin compiler and orchestration layer.
 YAML scene
   -> semantic validation
   -> Score IR
-  -> deterministic MIDI
-  -> external renderer
-  -> PCM audio
-  -> external FFmpeg export
+      -> deterministic MIDI
+          -> external renderer
+          -> PCM audio
+          -> external FFmpeg export
+      -> MakeCode song bytes (`scorekit makecode`)
 ```
 
 ## Guarantees
 
-- The same DSL and compiler inputs produce byte-identical MIDI.
+- The same DSL and compiler inputs produce byte-identical MIDI, and the same scene produces byte-identical MakeCode song encoding.
 - Loop and stem lengths are derived from quantized musical time.
 - File-writing commands stage output and publish it atomically.
 - JSON Schema and structured errors expose the same contract used by the CLI.

docs-site/src/commands.md

@@ -14,6 +14,7 @@ All commands accept the global `--json` flag. Successful diagnostic commands wri
 | `schema --resolver` | Print the instrument-resolver config schema |
 | `lint <scene> --grammar <file>` | Check compiled music against measurable style rules |
 | `midi <scene> -o <file>` | Compile deterministic Standard MIDI |
+| `makecode <scene> -o <file>` | Compile MakeCode `music.createSong` TypeScript (plus a `.meta.json` manifest) |
 | `render <midi> -o <wav>` | Render one MIDI file through a selected backend |
 | `export <audio> -o <file>` | Convert or trim audio through FFmpeg |
 | `build <scene> -o <file>` | Run the complete asset pipeline |
@@ -43,6 +44,21 @@ writing the output: the command has no renderer-profile input, and omitting a
 program change would make a generic GM player select piano. Use
 `build --renderer sfizz --orchestration <file>` to render those identities.
 
+`makecode` compiles a scene to Microsoft MakeCode's synth-song format (song
+encoding v0, played by MakeCode Arcade and micro:bit V2): a paste-ready `.ts`
+snippet with one ``let <name> = music.createSong(hex`…`)`` statement per song
+— one song per section for a suite — plus a `.meta.json` manifest reporting
+the tick grid and each track's mapped MakeCode chip or drum voice. Synthesis
+happens entirely in the MakeCode runtime. Chip and drum amplitudes are scaled
+from track `intensity` against a ~1.2 full-scale mix budget so stacked voices
+stay near the MakeCode editor's own 220–384 / 1024 range; tiny PWM speakers
+clip if every voice is written at full scale. Features the format cannot
+express fail with structured exit-2 errors (pitch bends/`glide`, clip CC
+automation, `textures`, timing finer than 255 ticks per beat such as
+`humanize`); `pan`/`reverb` are dropped with a WARN line and a manifest
+record. Keep bass in a chip-safe register — sub-bass square waves distort on
+Arcade and micro:bit speakers.
+
 ## Instrument resolution
 
 `build` and `batch` resolve every track's instrument against what the

docs-site/src/introduction.md

@@ -1,11 +1,12 @@
 # Introduction
 
-scorekit is an Agent-oriented music compiler for game and film-style scoring workflows. It compiles a reviewable YAML scene into deterministic MIDI, then delegates audio rendering and export to established external tools.
+scorekit is an Agent-oriented music compiler for game and film-style scoring workflows. It compiles a reviewable YAML scene into deterministic MIDI, then delegates audio rendering and export to established external tools. The same scene can also compile to a MakeCode synth-song for Arcade and micro:bit V2.
 
-The compiler produces seamless loops, sample-aligned instrument/texture stems, suite sections, metadata, and OGG or WAV assets. Texture tracks bring deterministic field recordings, ambience, and SFX into the score timeline. Creative decisions stay in the upstream Agent and the text scene; scorekit does not contain a generative model.
+The compiler produces seamless loops, sample-aligned instrument/texture stems, suite sections, metadata, OGG or WAV assets, and optional MakeCode `music.createSong` TypeScript. Texture tracks bring deterministic field recordings, ambience, and SFX into the score timeline. Creative decisions stay in the upstream Agent and the text scene; scorekit does not contain a generative model.
 
 ```text
 scene.yaml -> Score IR -> MIDI -> renderer -> WAV -> FFmpeg -> game assets
+                     \-> MakeCode song TypeScript
 ```
 
 The supported render backends are FluidSynth and TiMidity++ for SF2 SoundFonts, and sfizz for SFZ sample libraries.

docs-site/src/machine-interface.md

@@ -11,7 +11,8 @@ The machine interface follows semantic versioning. Within a major version, the f
 - Exit codes: `0` success · `1` I/O failure · `2` invalid input · `3` missing dependency · `4` external tool failure.
 - The `--json` error object shape on stderr (below).
 - The JSON Schemas exported by `scorekit schema`, `schema --grammar`, `schema --profile`, `schema --orchestration`, `schema --texture-profile`, and `schema --resolver` (fields are added, not removed or repurposed).
-- The `meta.json` / `report.json` artifact fields.
+- The `meta.json` / `report.json` artifact fields, including the MakeCode
+  manifest (`target: makecode-song-v0`, per-song header and voice mapping).
 
 Determinism boundary: the same scene + same sound source + same tool versions produces byte-identical MIDI, and audio identical within documented tolerances. Reproducibility across *different* FluidSynth/FFmpeg versions is explicitly **not** promised — pin your toolchain (e.g. in a container image) if you need cross-machine identical audio.
 

docs-site/src/scene-protocol.md

@@ -28,7 +28,7 @@ The scene protocol is versioned by the scorekit binary's semantic version. There
 
 Within a major version:
 
-- **Additive only.** New fields are optional with defaults that preserve prior output — a scene that does not use a new field compiles to *byte-identical MIDI* before and after the addition. (Precedent: when `pan`/`reverb`/`glide` landed in 0.2.0, the golden SMF byte-comparison test did not change.)
+- **Additive only.** New fields are optional with defaults that preserve prior output — a scene that does not use a new field compiles to *byte-identical MIDI* before and after the addition. (Precedent: when `pan`/`reverb`/`glide` landed in 0.2.0, the golden SMF byte-comparison test did not change.) Additional compile targets such as `scorekit makecode` must not add schema fields that only that target can fulfill.
 - **No repurposing.** An existing field's name, type, range, default, or compile semantic does not change. The normative transform order (below) is part of the semantic and is equally frozen.
 - **Old scene, new binary:** always valid, same MIDI bytes.
 - **New scene, old binary:** rejected with exit 2 and the offending field path — a readable upgrade signal, not a corrupted asset.