@maccesar/titools 5.2.5 → 5.4.0

package/skills/ti-synthengine/assets/example/lib/sequenceOwner.js

@@ -1,15 +1,8 @@
-// One application owner, with latest-request coalescing across native retirement.
-// A stop is accepted before its slot becomes reusable. Only sequenceend permits
-// the next complete publication; JavaScript never schedules individual notes.
+// Wait for native retirement before publishing the latest requested pattern.
+var SoundPreset = require('./soundPreset')
 module.exports = function createSequenceOwner(synth, options) {
   options = options || {}
-  var current = 0, pending = null, stopping = false, listening = false
-  function listen() {
-    if (!listening) {
-      synth.addEventListener('sequenceend', ended)
-      listening = true
-    }
-  }
+  var current = null, pending = null, stopping = false, recipe = null, listener = null
   function rejected(method, payload) {
     if (options.rejected) options.rejected(method, payload)
     return false
@@ -18,32 +11,40 @@ module.exports = function createSequenceOwner(synth, options) {
     if (!pending) return true
     var payload = pending
     pending = null
-    var id = synth.playSequence(payload)
-    if (!Number.isInteger(id) || id <= 0) return rejected('playSequence', payload)
-    current = id
-    if (options.published) options.published(id, payload)
+    var control = synth.createSound(SoundPreset.fromRecipe('pattern', payload)).play()
+    if (!control) return rejected('playSequence', payload)
+    current = control
+    recipe = payload
+    listener = function(event) {
+      if (current !== control) return
+      control.removeEventListener('end', listener)
+      current = null
+      listener = null
+      stopping = false
+      if (pending) publish()
+      if (options.ended) options.ended(event)
+    }
+    control.addEventListener('end', listener)
+    if (options.published) options.published(control, payload)
     return true
   }
-  function ended(event) {
-    if (event.sequenceId !== current) return
-    current = 0
-    stopping = false
-    if (pending) publish()
-    if (options.ended) options.ended(event)
-  }
   function requestStop() {
     if (!current || stopping) return true
     stopping = true
-    if (synth.stopSequence({ sequenceId: current })) return true
-    // A naturally retired ID can already have its completion queued for JS.
-    // Its slot still needs event draining before a replacement publication.
-    if (synth.getSequenceState({ sequenceId: current }) === null) return true
+    if (current.stop()) return true
+    // An ended pattern can have its completion queued for JavaScript.
+    if (current.getState() === null) return true
     stopping = false
-    return rejected('stopSequence', { sequenceId: current })
+    return rejected('stopSequence', {})
+  }
+  function merged(previous, changes) {
+    var voice = changes.voice ? Object.assign({}, previous.voice || {}, changes.voice) : previous.voice
+    var next = Object.assign({}, previous, changes)
+    if (voice) next.voice = voice
+    return next
   }
   return {
     submit: function(payload) {
-      listen()
       pending = payload
       if (!current) return publish()
       if (!requestStop()) {
@@ -54,28 +55,26 @@ module.exports = function createSequenceOwner(synth, options) {
     },
     update: function(changes) {
       if (pending) {
-        if (changes.steps !== undefined) {
-          pending = changes
-          return true
-        }
-        var voice = changes.voice ? Object.assign({}, pending.voice || {}, changes.voice) : pending.voice
-        pending = Object.assign({}, pending, changes)
-        if (voice) pending.voice = voice
+        pending = changes.steps !== undefined ? changes : merged(pending, changes)
         return true
       }
       if (!current || stopping) return false
-      return synth.updateSequence(Object.assign({ sequenceId: current }, changes))
+      var next = merged(recipe, changes)
+      var preset = SoundPreset.fromRecipe('pattern', next)
+      if (!current.update(Object.assign({}, preset.sound, preset.playback))) return false
+      recipe = next
+      return true
     },
     stop: function() { pending = null; return requestStop() },
     reset: function() {
       pending = null
-      current = 0
+      if (current && listener) current.removeEventListener('end', listener)
+      current = null
+      listener = null
+      recipe = null
       stopping = false
-      if (listening) {
-        synth.removeEventListener('sequenceend', ended)
-        listening = false
-      }
     },
+    getState: function() { return current ? current.getState() : null },
     id: function() { return current },
     pending: function() { return pending !== null },
     stopping: function() { return stopping }

package/skills/ti-synthengine/assets/example/lib/soundPreset.js

@@ -0,0 +1,34 @@
+// Convert an editable recipe to a Sound definition; this module never plays audio.
+exports.fromRecipe = function(type, recipe) {
+  var source = JSON.parse(JSON.stringify(recipe || {}))
+  var sound = type === 'pattern' ? source.voice || {} : {}
+  var playback = { type: type }
+  if (type === 'pattern') {
+    ;['timeUnit', 'gate', 'loop', 'swing', 'mode', 'tuning'].forEach(function(key) {
+      if (source[key] !== undefined) playback[key] = source[key]
+    })
+    if (sound.frequencyEnd !== undefined) {
+      playback.frequencyEnd = sound.frequencyEnd
+      delete sound.frequencyEnd
+    }
+    if (source.detune !== undefined) sound.detune = source.detune
+    if (source.stepDuration !== undefined) playback.interval = source.stepDuration
+    playback.steps = (source.steps || []).map(function(step) {
+      var result = {}
+      ;['notes', 'frequencies', 'rest', 'length', 'gate'].forEach(function(key) {
+        if (step[key] !== undefined) result[key] = step[key]
+      })
+      if (step.duration !== undefined) result.interval = step.duration
+      if (step.overrides !== undefined) result.sound = step.overrides
+      return result
+    })
+  } else {
+    Object.keys(source).forEach(function(key) {
+      if (key === 'note') playback.notes = [source[key]]
+      else if (key === 'frequency') playback.frequencies = [source[key]]
+      else if (['notes', 'frequencies', 'frequencyEnd', 'duration'].indexOf(key) >= 0) playback[key] = source[key]
+      else sound[key] = source[key]
+    })
+  }
+  return { sound: sound, playback: playback }
+}

package/skills/ti-synthengine/assets/index.d.ts

@@ -1,4 +1,4 @@
-/** TiSynthEngine local 1.1.0 candidate, public API 1.1.0. */
+/** TiSynthEngine 2.0.0 candidate. One module version for the entire public interface. */
 declare namespace synth {
   type Bus = 'music' | 'effects' | 'ui' | 'ambience';
   type FilterType = 'none' | 'lowpass' | 'highpass' | 'bandpass';
@@ -46,7 +46,7 @@ declare namespace synth {
     audioSession?: 'playback' | 'ambient';
   }
   interface Defaults {
-    apiVersion: '1.1.0';
+    version: string;
     capabilities: { variation: true; toneRepetition: true; [key: string]: boolean };
     variationSchemaVersion: 1;
     limits: Record<string, { min: number; max: number }>;
@@ -70,27 +70,147 @@ declare namespace synth {
     sequenceId: number; playing: boolean; step: number; beat: number;
     position: number; bpm: number; revision: number;
   }
+  /** Numbers are MIDI notes 12..119; strings are native note names. */
+  type Notes = string[] | number[];
+  type SoundType = 'tone' | 'chord' | 'repeat' | 'pattern' | 'held';
+  type ModernPitch = { notes?: Notes; frequencies?: never } | { frequencies?: number[]; notes?: never };
+  /** Shared allowlist; each interpretation also validates source-specific compatibility. */
+  interface SoundProperties extends VoiceOptions {
+    detune?: number; panEnd?: number; noiseRateEnd?: number; pulseWidthEnd?: number;
+    filterHzEnd?: number; fmDepthEnd?: number; detunes?: number[]; pans?: number[];
+    panSpread?: number; modulations?: Modulation[];
+  }
+  type TonePlayback = ModernPitch & { type?: 'tone'; duration?: number; frequencyEnd?: number };
+  type ChordPlayback = ({ notes: Notes; frequencies?: never } | { frequencies: number[]; notes?: never }) & { type: 'chord'; duration?: number };
+  type RepeatPlayback = ModernPitch & { type: 'repeat'; duration?: number; frequencyEnd?: number; interval: number };
+  type HeldPlayback = ModernPitch & { type: 'held' };
+  type PatternStep = { interval?: number; length?: number; gate?: number;
+    sound?: SoundProperties & { frequencyEnd?: number } } &
+    ({ notes: Notes; frequencies?: never; rest?: never } |
+    { frequencies: number[]; notes?: never; rest?: never } |
+    { rest: true; notes?: never; frequencies?: never });
+  interface PatternPlayback {
+    type?: 'pattern'; timeUnit?: 'beats' | 'ms'; interval?: number; gate?: number;
+    loop?: boolean; swing?: number; mode?: 'normal' | 'up' | 'down' | 'updown';
+    tuning?: number; frequencyEnd?: number; steps: PatternStep[];
+  }
+  type SoundPlayback = TonePlayback | ChordPlayback | RepeatPlayback | PatternPlayback | HeldPlayback;
+  interface SoundPreset { name?: string; sound?: SoundProperties; playback?: SoundPlayback }
+  /** Objects merge recursively; arrays replace. Null removes a leaf if the resulting preset is valid. */
+  type PresetPatch<T> = T extends unknown[] ? T | null : T extends object ?
+    { [K in keyof T]?: PresetPatch<T[K]> } : T | null;
+  interface SoundChanges {
+    name?: string;
+    sound?: PresetPatch<SoundProperties>;
+    playback?: PresetPatch<SoundPlayback>;
+  }
+  /** Execution overrides are flat, unlike the stored sound/playback definition. */
+  type RepeatChanges = PresetPatch<SoundProperties> & ModernPitch & {
+    type?: 'repeat'; duration?: number | null; frequencyEnd?: number | null; interval?: number;
+  };
+  type PatternChanges = PresetPatch<SoundProperties> & PresetPatch<Partial<PatternPlayback>>;
+  type SoundOverrides = SoundProperties & (TonePlayback | Partial<ChordPlayback> | HeldPlayback |
+    (ModernPitch & { type?: 'repeat'; duration?: number; frequencyEnd?: number; interval?: number }) |
+    Partial<PatternPlayback>);
+  type NoteChanges = Pick<VoiceOptions, 'volume' | 'pan' | 'lfoFreq' | 'lfoDepth' |
+    'noiseRate' | 'lowPassHz' | 'pulseWidth' | 'filterHz' | 'filterQ' | 'fmRatio' |
+    'fmDepth' | 'spatialX' | 'spatialY' | 'effectSend'> & ModernPitch & { modulations?: Modulation[] };
+  interface Note {
+    /** Ramps compatible live fields without retriggering. Attack-only fields are rejected. */
+    update(changes: NoteChanges): boolean;
+    /** Begins this note's release; false after release, shutdown or invalidation. */
+    noteOff(): boolean;
+  }
+  interface RepeatingPlaybackControl {
+    /** Applies at the next scheduled attack without moving its existing deadline. */
+    update(changes: RepeatChanges): boolean;
+    /** Cancels future attacks; already sounding finite attacks finish. */
+    stop(): boolean;
+  }
+  type PatternState = Omit<SequenceState, 'sequenceId'>;
+  interface PatternEndEvent { reason: 'completed' | 'stopped' }
+  interface PatternPlaybackControl {
+    update(changes: PatternChanges): boolean;
+    stop(): boolean;
+    getState(): PatternState | null;
+    /** Transport retirement, not a promise of audible silence. No native ID is exposed. */
+    addEventListener(name: 'end', listener: (event: PatternEndEvent) => void): void;
+    removeEventListener(name: 'end', listener: (event: PatternEndEvent) => void): void;
+  }
+  type PlaybackResult = boolean | Note | RepeatingPlaybackControl | PatternPlaybackControl;
+  interface Sound {
+    getPreset(): SoundPreset;
+    /** Validates before replacing the stored definition; affects future executions only. */
+    set(changes: SoundChanges): void;
+    play(changes: SoundOverrides & { type: 'held' }): Note | false;
+    play(changes: SoundOverrides & { type: 'pattern' }): PatternPlaybackControl | false;
+    play(changes: SoundOverrides & { type: 'repeat' }): RepeatingPlaybackControl | false;
+    play(changes: SoundOverrides & { type: 'tone' | 'chord' }): boolean;
+    /** The stored type can change through set(), so an omitted type has a mixed return. */
+    play(changes?: SoundOverrides): PlaybackResult;
+    noteOn(changes?: SoundProperties & ModernPitch): Note | false;
+  }
+  interface Contract extends Defaults {
+    capabilities: Defaults['capabilities'] & { soundObjects: true };
+    interpretations: SoundType[];
+    units: { envelope: 'ms'; duration: 'msIncludingRelease'; repetitionInterval: 'ms'; pattern: ('beats' | 'ms')[] };
+    soundProperties: (keyof SoundProperties)[];
+    playbackProperties: string[];
+  }
+  type Sync = 'off' | 'quarter' | 'eighth' | 'sixteenth' | 'quarterTriplet' | 'eighthTriplet' | 'sixteenthTriplet';
+  interface ProcessingOptions {
+    inputGain?: number; applyTo?: Bus[];
+    chorus?: { enabled?: boolean; rate?: number; depth?: number; mix?: number };
+    /** time is milliseconds; timeMs is a deprecated exclusive input spelling. */
+    delay?: { enabled?: boolean; sync?: Sync; feedback?: number; mix?: number } &
+      ({ time?: number; timeMs?: never } | { time?: never; timeMs?: number });
+    /** decay is milliseconds (200..8000), unlike setMasterProcessing's seconds. */
+    reverb?: { enabled?: boolean; decay?: number; damping?: number; mix?: number };
+    saturation?: { enabled?: boolean; drive?: number; mix?: number };
+  }
+  function createSound(preset: SoundPreset): Sound;
+  function getContract(): Contract;
+  /** Strict configuration errors throw; operational rejection returns false. */
+  function setProcessing(options: ProcessingOptions): boolean;
+  /** Installed module version, native defaults, limits and capabilities. */
   function getDefaults(): Defaults;
   function start(options?: StartOptions): boolean;
   /** One finite attack. intervalMs is rejected; use repeatTone for repetition. */
+  /** @deprecated Use createSound(...).play(). The existing signature and behavior remain supported. */
   function playTone(options: ToneOptions & { intervalMs?: never }): boolean;
   /** Integer 1-60000 ms: positive module-owned ID, or 0 on rejection. */
+  /** @deprecated Use a Sound with playback.type repeat and its playback control. The existing signature and behavior remain supported. */
   function repeatTone(options: RepeatingToneOptions): number;
+  /** @deprecated Use the repetition control update(). The existing signature and behavior remain supported. */
   function updateTone(options: ToneUpdate): boolean;
   /** Cancels future attacks at the next block; admitted attacks finish. */
+  /** @deprecated Use the repetition control stop(). The existing signature and behavior remain supported. */
   function stopTone(options: { toneId: number }): boolean;
+  /** @deprecated Use a Sound with playback.type chord. The existing signature and behavior remain supported. */
   function playChord(options: ChordOptions): boolean;
+  /** @deprecated Use Sound.noteOn() or a Sound with playback.type held. The existing signature and behavior remain supported. */
   function noteOn(options: NoteOptions): boolean;
+  /** @deprecated Use Note.update(). The existing signature and behavior remain supported. */
   function updateNote(options: NoteUpdate): boolean;
   /** @deprecated Use updateNote; identical behavior and voiceId contract. */
   function updateVoice(options: NoteUpdate): boolean;
+  /** @deprecated Use Note.noteOff(). The existing signature and behavior remain supported. */
   function noteOff(options: { voiceId: number }): boolean;
+  /** @deprecated Use a Sound with playback.type pattern. The existing signature and behavior remain supported. */
   function playSequence(options: SequenceOptions): number;
+  /** @deprecated Use the pattern control update(). The existing signature and behavior remain supported. */
   function updateSequence(options: Partial<Omit<SequenceOptions, 'timeUnit'>> & { sequenceId: number }): boolean;
+  /** @deprecated Use the pattern control stop(). The existing signature and behavior remain supported. */
   function stopSequence(options: { sequenceId: number }): boolean;
+  /** @deprecated Use the pattern control getState(). The existing signature and behavior remain supported. */
   function getSequenceState(options: { sequenceId: number }): SequenceState | null;
+  function setTempo(bpm: number): boolean;
+  /** @deprecated Use setTempo(bpm); the dictionary signature remains supported. */
   function setTempo(options: { bpm: number }): boolean;
+  function setVolume(volume: number): boolean;
+  /** @deprecated Use setVolume(volume); the dictionary signature remains supported. */
   function setVolume(options: { volume: number }): boolean;
+  /** @deprecated Use setProcessing(); its reverb decay unit is milliseconds. The existing signature and behavior remain supported. */
   function setMasterProcessing(options: Record<string, unknown>): boolean;
   function enableStats(): boolean;
   function disableStats(): boolean;

package/skills/ti-synthengine/references/advanced-examples.md

@@ -1,8 +1,8 @@
-> Source snapshot: official TiSynthEngine documentation at commit `ec04f4e634075c41b55f66279eabcd78b9652d58` (2026-11-02). Published module 1.1.0; public API 1.1.0. Upstream `documentation/examples.md` SHA-256: `1b3be798d8f606381696d9e00cda330c11475402397e4760dcbc3041a39ef404`.
+> Source snapshot: official TiSynthEngine documentation at commit `9d74aa45f84d3f2822d4aab76874efe37d81257f` (2026-11-03). Published module 2.0.0. Upstream `documentation/examples.md` SHA-256: `ee8aed566a63062ae63ae78f0b96fa8d73c70ab2f50aed81081c26acc24718af`.
 
 ## Sustained game motor
 
-Assume one running engine owned by this service. The positive voice ID belongs to the app; do not reuse it during the session or share its counter with an independent audio owner. There is no `duration` or `*End` target on `noteOn`.
+This example assumes the service owns one running engine. The positive voice ID belongs to the app; do not reuse it during the session or share its counter with an independent audio owner. There is no `duration` or `*End` target on `noteOn`.
 
 ```javascript
 if (!['noteOn', 'noteOff', 'updateNote'].every(function (name) {
@@ -92,7 +92,7 @@ The UI timer presents state; native audio schedules every attack/release. For fi
 
 ## Chorus, delay, reverb and creative saturation
 
-This configures the selected share of a running engine; `applyTo` defaults to all categories. Check method presence and Boolean acceptance; partial section updates merge with the last accepted settings. Effects start disabled, input gain starts at 1, and no LFOs are added to voices implicitly.
+The example below configures the selected share of a running engine; `applyTo` defaults to all categories. Check method presence and Boolean acceptance; partial section updates merge with the last accepted settings. Effects start disabled, input gain starts at 1, and no LFOs are added to voices implicitly.
 
 ```javascript
 if (typeof synth.setMasterProcessing !== 'function') {
@@ -175,7 +175,7 @@ Call `closeMixMeter` when its owner hides or closes. Display unavailable or unme
 
 ## Bounded variation for repeated noise impacts
 
-The 1.1.0 packages choose values once per admitted attack. This example keeps the noise source and envelope fixed, varies the initial noise/filter settings, and lets the authored sweep endpoints finish unchanged. Call it for actual gameplay events after normal engine startup. For periodic repetition, pass the finite recipe to `repeatTone` with `intervalMs` and retain its positive tone ID; use `stopTone` on cancellation.
+The native engine chooses values once per admitted attack. This example keeps the noise source and envelope fixed, varies the initial noise/filter settings, and lets the authored sweep endpoints finish unchanged. Call it for actual gameplay events after normal engine startup. For periodic repetition, pass the finite recipe to `repeatTone` with `intervalMs` and retain its positive tone ID; use `stopTone` on cancellation.
 
 ```javascript
 var synth = require('ti.synthengine')

package/skills/ti-synthengine/references/api.md

@@ -1,17 +1,18 @@
-> Source snapshot: official TiSynthEngine documentation at commit `ec04f4e634075c41b55f66279eabcd78b9652d58` (2026-11-02). Published module 1.1.0; public API 1.1.0. Upstream `documentation/api.md` SHA-256: `b58d60cf38a96157e523722d1f9cb9508f785cc2de9c2c1ff306e328c77df9dc`.
+> Source snapshot: official TiSynthEngine documentation at commit `9d74aa45f84d3f2822d4aab76874efe37d81257f` (2026-11-03). Published module 2.0.0. Upstream `documentation/api.md` SHA-256: `ca5b7f1a44ef79543399fd1a40fa83024c190c086b6412fb79dc54de91a2a329`.
 
 # API reference
 
 Module id: `ti.synthengine`
 
-Public API version: `1.1.0`
+Module version: `2.0.0`. Read the [Sound object reference](sound-api.md) for reusable definitions, playback controls and property units. This page documents the global controls and direct native parameters behind those interpretations.
 
-Android and iOS expose the same public methods, one event and waveform values. Option objects are strict: an unknown key is rejected with `unsupported_option`. Reported metadata and rejection diagnostics have platform differences; this reference does not promise sample-identical rendering between Android and iOS.
+Android and iOS expose the same public methods and waveform values. Pattern controls emit `end`; direct native sequences emit `sequenceend`. Option objects are strict: an unknown key is rejected with `unsupported_option`. Reported metadata and rejection diagnostics have platform differences; this reference does not promise sample-identical rendering between Android and iOS.
 
 <!-- TOC-START -->
 ## Contents
 
-- [Native attack variation (package 1.1.0)](#native-attack-variation-package-110)
+- [Sound interface](#sound-interface)
+- [Native attack variation](#native-attack-variation)
 - [Return values](#return-values)
 - [`getDefaults()`](#getdefaults)
 - [Limits](#limits)
@@ -42,9 +43,30 @@ Android and iOS expose the same public methods, one event and waveform values. O
 
 <!-- TOC-END -->
 
-## Native attack variation (package 1.1.0)
+## Sound interface
 
-The optional `variation` dictionary is accepted by `playTone`, `repeatTone`, `playChord`, `noteOn`, sequence `voice` and step `overrides`. Version 1.1.0 reports public API `1.1.0`. Both platforms advertise `capabilities.variation: true` and `variationSchemaVersion: 1`; consumers must require both before sending the dictionary. The published 1.0.2 packages do not support it. See [native variation](native-variation.md) for fields, source restrictions, seeds and examples. Native `amount` is linear; Studio divides its displayed percentage by 100. `updateNote` rejects the dictionary. An override replaces the whole inherited dictionary, and an amount-zero dictionary still validates its ranges.
+| Method | Result |
+| --- | --- |
+| `getContract()` | Installed module version, capabilities, units and structural property allowlists |
+| `createSound({ name?, sound?, playback? })` | A reusable validated Sound; no audio starts |
+| `Sound.play(changes?)` | Finite acceptance or an independent note/repetition/pattern control |
+| `Sound.noteOn(changes?)` | One held-note control, or `false` on operational rejection |
+| `Sound.set({ sound?, playback? })` | Atomic stored revision for future executions |
+| `Sound.getPreset()` | Detached authored definition |
+| Note `update(changes)`, `noteOff()` | Edit or release that held note |
+| Repetition `update(changes)`, `stop()` | Edit future finite attacks or cancel repetition |
+| Pattern `update(changes)`, `stop()`, `getState()` | Edit, stop or inspect that pattern |
+| Pattern `addEventListener('end', fn)`, `removeEventListener('end', fn)` | Subscribe to that pattern's completion or stopping |
+| `setProcessing(options)` | Shared effects with delay `time` and reverb `decay` in milliseconds |
+| `setVolume(number)`, `setTempo(number)` | Global gain and beats per minute |
+
+Sound definitions split synthesis into `sound` and execution defaults into `playback`. `play()` and `noteOn()` accept flat temporary overrides. Invalid configurations throw before publication; operational playback rejection returns `false`. Finite events end naturally without individual controls. Shutdown invalidates controls while definitions remain reusable.
+
+The [Sound reference](sound-api.md) supplies all properties, defaults, units and interpretation restrictions. The direct native methods below remain supported and document the validators and rendering parameters behind each interpretation. Use the [upgrade guide](upgrade-2.0.0.md) for method mappings.
+
+## Native attack variation
+
+The optional `variation` dictionary is accepted by `playTone`, `repeatTone`, `playChord`, `noteOn`, sequence `voice` and step `overrides`. Both platforms advertise `capabilities.variation: true` and `variationSchemaVersion: 1`; consumers must require both before sending the dictionary. See [native variation](native-variation.md) for fields, source restrictions, seeds and examples. Native `amount` is linear; Studio divides its displayed percentage by 100. `updateNote` rejects the dictionary. An override replaces the whole inherited dictionary, and an amount-zero dictionary still validates its ranges.
 
 ## Return values
 
@@ -60,11 +82,11 @@ Returns the installed contract without starting the audio stream.
 var contract = synth.getDefaults()
 ```
 
-The shared result in version 1.1.0 has this shape; Android adds the platform metadata described below. Published 1.0.2 packages retain the core contract but omit the variation capability/schema fields:
+The shared result in TiSynth 2.0.0 has this shape; Android adds the platform metadata described below. `version` identifies the installed module, with no independent API version:
 
 ```javascript
 {
-  apiVersion: '1.1.0',
+  version: '2.0.0',
   capabilities: { variation: true, toneRepetition: true },
   variationSchemaVersion: 1,
   defaults: {
@@ -127,7 +149,7 @@ The shared result in version 1.1.0 has this shape; Android adds the platform met
 
 `fmDepthEnd`, `detunes`, `spatialX` and `spatialY` have no reported default: their presence changes how the call is interpreted. Supplying a spatial coordinate enables binaural; the other coordinate then defaults to 0 internally. The maximum frequency is `sampleRate * 0.45`. Before the stream opens, the reported fallback is 19,845 Hz. Read the object again after `start()` if the precise device limit matters.
 
-In version 1.1.0, both platforms report `capabilities.variation: true` and `variationSchemaVersion: 1`. Android also reports `nativeSequence`, `masterProcessing` and `modulations` capability flags and `limits.stepDurationMs`. iOS omits those three older flags and `limits.stepDurationMs` while implementing the corresponding methods and millisecond sequences. Published 1.0.2 packages do not advertise variation; their iOS metadata has no `capabilities` map. Detect a required core method with `typeof synth.playSequence === 'function'` (and the other methods your feature needs); require the capability/schema pair specifically for variation. Both platforms report `limits.maxSequences`, `limits.priority` and `limits.effectSend`. `limits.stepDuration` is in beats on both platforms; millisecond sequences accept `4000 / sampleRate` through 60,000 even when `limits.stepDurationMs` is absent.
+Both platforms report `capabilities.variation: true` and `variationSchemaVersion: 1`. Android also reports `nativeSequence`, `masterProcessing` and `modulations` capability flags and `limits.stepDurationMs`. iOS omits those three flags and `limits.stepDurationMs` while implementing the corresponding methods and millisecond sequences. Detect a required core method with `typeof synth.playSequence === 'function'` (and the other methods your feature needs); require the capability/schema pair specifically for variation. Both platforms report `limits.maxSequences`, `limits.priority` and `limits.effectSend`. `limits.stepDuration` is in beats on both platforms; millisecond sequences accept `4000 / sampleRate` through 60,000 even when `limits.stepDurationMs` is absent.
 
 ## Limits
 
@@ -192,7 +214,7 @@ On iOS, `playback` ignores the silent switch and interrupts other apps' audio. `
 
 ## `noteOn(options)`
 
-Starts a sustained native voice. Detect `typeof synth.noteOn === 'function'`, `noteOff` and `updateNote` before enabling their controls; the current `apiVersion` is `1.1.0`. There is no duration limit and no JavaScript timer holds the note.
+Starts a sustained native voice. Check `typeof synth.noteOn === 'function'`, `noteOff` and `updateNote` before enabling their controls. Read the installed module version from `getDefaults().version`. The note has no duration limit and needs no JavaScript timer to remain held.
 
 | Field                                   | Rule                                                                                                                               |
 | --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
@@ -251,7 +273,7 @@ Begins release from the current level, including during attack or decay. Repeate
 | `spatialX`, `spatialY`   | Target position for a spatial held voice; omitted coordinate stays unchanged.    |
 | `effectSend`             | Explicit processed share, 0-1, overriding category selection.                    |
 
-At least one change is required. An incompatible change rejects the entire request when the ID is known; unknown/ended IDs accept publication as a no-op. The callback also checks source compatibility before applying a command. Changed continuous parameters ramp linearly from their current values over 10 ms. New targets retarget that ramp without restarting oscillator phase or the envelope. Unchanged parameters retain their current ramps. This also works during release.
+Supply at least one change. An incompatible change rejects the entire request when the ID is known; unknown/ended IDs accept publication as a no-op. The callback also checks source compatibility before applying a command. Changed continuous parameters ramp linearly from their current values over 10 ms. A new target redirects the ramp without restarting oscillator phase or the envelope. Unchanged parameters keep their current ramps. These edits also work during release.
 
 Pitch updates are absolute: an initial `detune` is already included in the note's starting frequency. To edit tuning later, compute the desired effective frequency in the app and send `frequency`. There is no `detune` update field. Filter type, ADSR, quantization and wavetable require a new attack. Noise clock, low-pass cutoff, send and compatible stereo/spatial position support live 10 ms updates.
 
@@ -319,7 +341,7 @@ Plays one pitch. It uses 440 Hz when neither pitch field is present. Note names
 
 Omitted attack/release values are shortened to fit an event smaller than the default envelope. Explicit values must satisfy the documented envelope rules. `getDefaults()` reports the baseline defaults, not these per-event adjustments.
 
-In the current 1.0.2/1.1.0 implementations, the iOS timed tone/chord command builder
+In the native implementation, the iOS timed tone/chord command builder
 initially rounds accepted zero attack/release values to one sample, before
 trimming them to the event duration budget. Android retains zero samples.
 Validator acceptance does not imply identical zero-edge rendering. Held notes
@@ -375,7 +397,7 @@ Those three calls use JavaScript timing and independent attack selection. For an
 
 Returns Boolean acceptance. Requires a known positive repetition identifier and at least one change. Accepts partial finite-tone options, including `intervalMs`, and merges them with the latest accepted recipe before validating the entire result. Supplying `note` replaces an earlier `frequency`; supplying `frequency` replaces an earlier `note`. Supplying both is invalid. Invalid edits leave the last accepted recipe intact.
 
-An accepted edit affects the next already scheduled attack, preserving its deadline. The new interval determines separation after that attack. Active attacks retain their original configuration. A supplied `variation` dictionary replaces the whole previous dictionary; `{ amount: 0 }` disables future variation. Each repetition retains its own seed and admitted-attack counter. Edits preserve the stream; changing its seed restarts that succession. Unknown or retired IDs reject edits.
+An accepted edit affects the next scheduled attack without moving its deadline. The new interval sets the gap after that attack. Active attacks keep their original configuration. A supplied `variation` dictionary replaces the whole previous dictionary; `{ amount: 0 }` disables future variation. Each repetition keeps its own seed and admitted-attack counter. Edits preserve the stream unless the seed changes, which restarts it. Unknown or retired IDs reject edits.
 
 ### `stopTone({ toneId })`
 
@@ -440,7 +462,7 @@ synth.stopSequence({ sequenceId: musicId })
 
 Selected audio follows fixed input gain → chorus → ping-pong delay → reverb → master volume → optional saturation. Dry audio receives the same global input/master gains, then recombines before one final sample-peak protector with no retained samples. Independent notes never trigger voice-count normalization. The limiter remains the final protection.
 
-Requires a running engine and returns Boolean acceptance. Partial updates merge into the last accepted processing configuration, validate the complete result and publish atomically. Continuous controls ramp over 10 ms. Unknown fields, numeric booleans and non-finite values reject the whole edit. Detect method presence before use.
+This method requires a running engine and returns Boolean acceptance. It merges partial updates into the last accepted processing configuration, validates the complete result and publishes it atomically. Continuous controls ramp over 10 ms. Unknown fields, numeric booleans and non-finite values reject the whole edit. Check that the method exists before calling it.
 
 | Section      | Fields and initial values                                                                                                                                                                                                     |
 | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -455,7 +477,7 @@ Delay sync accepts `off`, `quarter`, `eighth`, `sixteenth`, `quarterTriplet`, `e
 
 Processing uses one shared chain for the selected categories. `applyTo` is an array drawn from `music`, `effects`, `ui` and `ambience`; default all four. Each event or held voice uses `bus: 'effects'` by default. Optional `effectSend: 0…1` overrides category selection for that voice. Input gain and master volume remain global. Selected audio receives chorus, delay, reverb and optional saturation, then recombines with dry audio before one final limiter. Send changes ramp over 10 ms.
 
-Defaults keep all effects and saturation disabled, input gain at unity, and preserve the earlier render exactly. Enabling saturation is an explicit sound-design choice. Output protection is still required with dense voices and effect feedback.
+Defaults keep all effects and saturation disabled, input gain at unity, and route audio through the unprocessed path. Enabling saturation is an explicit sound-design choice. Output protection is still required with dense voices and effect feedback.
 
 ## Additional voice modulation
 
@@ -469,7 +491,7 @@ Defaults keep all effects and saturation disabled, input gain at unity, and pres
 | `depth`  | 0-1, default 0; scales up to four cutoff octaves, 0.45 PWM offset or ten FM-index units. Two contributions sum with safe clamping.                                                                                       |
 | `sync`   | Same musical values as delay; default off. Synced rates follow native tempo (up to 30 Hz at 300 BPM in sixteenth-note triplets).                                                                                         |
 
-Edits preserve oscillator/LFO phases. Continuous modulation contributions ramp over 10 ms; cutoff stays within 20 Hz and the frequency maximum, PWM within 0.05-0.95, FM index within 0-10. Initial modulations may also be inherited by sequence voices and overridden per step. These two slots coexist with the independent `lfoFreq`/`lfoDepth` pitch vibrato; they are not accepted by timed tones, chords .
+Edits preserve oscillator/LFO phases. Continuous modulation contributions ramp over 10 ms; cutoff stays within 20 Hz and the frequency maximum, PWM within 0.05-0.95, FM index within 0-10. Sequence voices can inherit initial modulations, and steps can override them. These two slots coexist with the independent `lfoFreq`/`lfoDepth` pitch vibrato. Timed tones and chords reject them.
 
 ## `playChord(options)`
 
@@ -669,7 +691,7 @@ Listen with stereo headphones. Height perception depends on the listener, headph
 
 Use `typeof synth.getStats === 'function'` to check that the expected module is installed before enabling a diagnostics panel.
 
-Returns a new snapshot without resetting counters. Available before start and after shutdown. Occupancy is the last completed render block; queued commands are read at query time. No audio-thread allocation, locks or waiting are added.
+This method returns a new snapshot without resetting counters and is available before start and after shutdown. Occupancy comes from the last completed render block; queued commands are read at query time. The query adds no audio-thread allocation, locks or waiting.
 
 | Field                      | Meaning                                                                                                                     |
 | -------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
@@ -697,7 +719,7 @@ Returns a new snapshot without resetting counters. Available before start and af
 | `bufferFrames`             | Android Oboe output buffer size; otherwise `null`. This is distinct from `callbackFrames`.                                  |
 | `estimatedOutputLatencyMs` | Android timestamp-based stream-to-DAC estimate, when valid; otherwise `null` (always `null` on this iOS backend).           |
 
-In the current 1.0.2/1.1.0 implementations, iOS early rejections in tempo/sequence operations and a
+In the native implementation, iOS early rejections in tempo/sequence operations and a
 stopped `setMasterProcessing` call can bypass rejection counters. Incompatible
 held spatial-mode or modulation updates also have uncounted iOS returns.
 Android counts more of these cases, but an unknown/retired `stopSequence` return