@maccesar/titools 5.2.4 → 5.3.0

package/skills/ti-synthengine/references/native-variation.md

@@ -1,27 +1,66 @@
-> Source snapshot: official TiSynthEngine documentation at commit `b07c97c762be5905f132cecf33e9d60ea0c21316` (2026-11-02). Published 1.0.2; local 1.1.0 candidates; public API 1.0.0. Upstream `documentation/native-variation.md` SHA-256: `30bbf837a163372aa0d369c6c8e267dc8fc2d3349e8ae30c51d13d20c88cb7eb`.
+> Source snapshot: official TiSynthEngine documentation at commit `9d74aa45f84d3f2822d4aab76874efe37d81257f` (2026-11-03). Published module 2.0.0. Upstream `documentation/native-variation.md` SHA-256: `6cfd65b0741dea79d37bb5eee14d1bcb98445ee6b5db14a8c00e3ccfd00a5190`.
 
 # Native per-attack variation
 
 `variation` lets the engine choose bounded parameter values when it admits an attack. Repeated shots can have different pitch, noise color or filter settings without JavaScript randomization. Each voice keeps the chosen values for its lifetime; existing envelopes, sweeps and LFOs continue from that starting configuration.
 
-Android and iOS support this dictionary in the local 1.1.0 packages, with public API version `1.0.0` and variation schema version `1`. The published 1.0.2 packages do not accept it. The local packages have not been published as a release.
+Android and iOS support this dictionary in TiSynth 2.0.0. The variation data schema is `1`. Store it in `sound.variation`; a pattern step can supply `steps[i].sound.variation`.
 
-## Select the local package
+<!-- TOC-START -->
+## Contents
 
-Install the matching locally built Android and iOS 1.1.0 archives in the app and select them in `tiapp.xml`:
+- [Reuse a sound with variation](#reuse-a-sound-with-variation)
+- [Select the module version](#select-the-module-version)
+- [Detect support and start playback](#detect-support-and-start-playback)
+- [Supported locations](#supported-locations)
+- [Dictionary reference](#dictionary-reference)
+- [What amount means](#what-amount-means)
+- [Repeated independent effects](#repeated-independent-effects)
+- [Chords and application gain](#chords-and-application-gain)
+- [Sustained voices and explicit live edits](#sustained-voices-and-explicit-live-edits)
+- [Native loops and dictionary inheritance](#native-loops-and-dictionary-inheritance)
+- [Seeds and reproducibility](#seeds-and-reproducibility)
+- [Rejected configurations](#rejected-configurations)
+- [Studio and game integration](#studio-and-game-integration)
+- [Implementation and verification](#implementation-and-verification)
+
+<!-- TOC-END -->
+
+## Reuse a sound with variation
+
+```javascript
+var synth = require('ti.synthengine')
+var bell = synth.createSound({
+  sound: {
+    waveType: synth.getContract().waveTypes.SINE,
+    volume: 0.25, attack: 5, release: 120,
+    variation: { amount: 0.6, ranges: { volume: [0.18, 0.25], pitchCents: [-8, 8] } }
+  },
+  playback: { type: 'tone', notes: ['A4'], duration: 400 }
+})
+
+bell.play()
+bell.play({ notes: ['C5'] })
+```
+
+Call playback after engine startup. The detailed native dictionaries below explain source restrictions and inheritance. For Sound patterns, root variation belongs in `sound.variation` and a step replacement belongs in `steps[i].sound.variation`.
+
+## Select the module version
+
+Install the matching Android and iOS 2.0.0 archives in the app and select them in `tiapp.xml`:
 
 ```xml
 <modules>
-  <module platform="android" version="1.1.0">ti.synthengine</module>
-  <module platform="iphone" version="1.1.0">ti.synthengine</module>
+  <module platform="android" version="2.0.0">ti.synthengine</module>
+  <module platform="iphone" version="2.0.0">ti.synthengine</module>
 </modules>
 ```
 
-Rebuild and reinstall the application after replacing native modules. Copying module files alone does not update an installed app. Keep the published 1.0.2 archives separate; the new property does not change the reported public API version.
+Rebuild and reinstall the application after replacing native modules. Copying module files alone does not update an installed app. Keep historical released archives separate. The installed module version is available as `getDefaults().version`.
 
 ## Detect support and start playback
 
-Check both metadata fields. API version alone does not identify variation support. Omit the property completely when either announcement is missing, including when the requested amount is zero.
+Check both capability/schema fields, even when the module version matches the one you expect. Omit the property completely if either field is missing, including when the requested amount is zero.
 
 ```javascript
 var synth = require('ti.synthengine')
@@ -35,19 +74,21 @@ synth.start({ maxVoices: 8, maxSequences: 1 })
 synth.setVolume({ volume: 0.6 })
 ```
 
-The following examples use those variables. Handle rejected publications through the normal [return values and diagnostics](api.md#return-values). For rapid effects, size the shared voice pool for overlapping durations and releases.
+The examples below use those variables. Handle rejected publications through the normal [return values and diagnostics](api.md#return-values). For rapid effects, size the shared voice pool for overlapping durations and releases.
 
 ## Supported locations
 
-| Call or score field | Behavior |
-| --- | --- |
-| `playTone({ variation, ... })` | Chooses once for an admitted timed tone |
-| `playChord({ variation, ... })` | Admits the whole chord atomically and chooses independent values for each voice |
-| `noteOn({ variation, ... })` | Chooses at the held voice's attack; sustain and release keep that configuration |
-| `playSequence({ voice: { variation, ... }, ... })` | Supplies the default for sounding steps on every native loop |
-| `steps[i].overrides.variation` | Replaces the entire dictionary inherited from the sequence voice |
-| `updateSequence({ voice, steps, ... })` | Changes future attacks when the revision applies |
-| `updateVoice({ variation, ... })` | Rejected; live edits must name the parameters they change |
+| Call or score field                                | Behavior                                                                                         |
+| -------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
+| `playTone({ variation, ... })`                     | Chooses once for an admitted timed tone                                                          |
+| `repeatTone({ variation, intervalMs, ... })`       | Retains a stream/counter and chooses once per admitted repeated finite attack                    |
+| `updateTone({ toneId, variation, ... })`           | Replaces the whole future-attack dictionary; amount zero disables; seed change resets the stream |
+| `playChord({ variation, ... })`                    | Admits the whole chord atomically and chooses independent values for each voice                  |
+| `noteOn({ variation, ... })`                       | Chooses at the held voice's attack; sustain and release keep that configuration                  |
+| `playSequence({ voice: { variation, ... }, ... })` | Supplies the default for sounding steps on every native loop                                     |
+| `steps[i].overrides.variation`                     | Replaces the entire dictionary inherited from the sequence voice                                 |
+| `updateSequence({ voice, steps, ... })`            | Changes future attacks when the revision applies                                                 |
+| `updateNote({ variation, ... })`                   | Rejected; live edits must name the parameters they change                                        |
 
 Schema 1 varies `volume`, `filterHz`, `filterQ`, `fmDepth`, `noiseRate`, `lowPassHz`, `pulseWidth` and `pitchCents`. Waveform, table contents, ADSR, duration, cadence, FM ratio, routing, priority and voice count retain their authored values.
 
@@ -64,26 +105,26 @@ var variation = {
 }
 ```
 
-| Field | Default | Accepted values |
-| --- | --- | --- |
-| `amount` | `1` | Finite number from `0` to `1` |
-| `seed` | Omitted; engine selects a native stream | Integer from `0` to `4294967295`; `0` is an explicit deterministic seed |
-| `ranges` | Empty dictionary | Any subset of the eight range names below |
+| Field    | Default                                 | Accepted values                                                         |
+| -------- | --------------------------------------- | ----------------------------------------------------------------------- |
+| `amount` | `1`                                     | Finite number from `0` to `1`                                           |
+| `seed`   | Omitted; engine selects a native stream | Integer from `0` to `4294967295`; `0` is an explicit deterministic seed |
+| `ranges` | Empty dictionary                        | Any subset of the eight range names below                               |
 
 Only these keys are accepted. A range must contain exactly two finite numbers in ascending order. Equal endpoints are valid. Strings, booleans, `null`, `NaN`, infinity, reversed bounds and unknown names are rejected. An empty range dictionary makes no parameter changes and consumes no variation event.
 
 The frequency ceiling is the active engine's `limits.frequency.max` value from `getDefaults()`. The maximum is `sampleRate * 0.45`, with a 19,845 Hz fallback before startup. Read `getDefaults()` again after `start()` when preparing device-specific ranges.
 
-| Range | Inclusive validation bounds | Required source or setting |
-| --- | --- | --- |
-| `volume` | `0` to `2` | Any source; existing chord compensation follows selection |
-| `filterHz` | `20` Hz to the active frequency ceiling | Enabled resonant filter: `lowpass`, `highpass` or `bandpass` |
-| `filterQ` | `0.5` to `10` | Enabled resonant filter |
-| `fmDepth` | `0` to `10` | `SINE`, with the normal FM ratio/depth rules |
-| `noiseRate` | `1` Hz to the active frequency ceiling | `NOISE` with authored `noiseRate >= 1` |
-| `lowPassHz` | `20` Hz to the active frequency ceiling | One-pole low-pass already enabled with authored `lowPassHz >= 20` |
-| `pulseWidth` | `0.05` to `0.95` | `SQUARE` |
-| `pitchCents` | `-1200` to `1200` cents | Resulting tuned frequencies and active pitch endpoints must remain within engine limits |
+| Range        | Inclusive validation bounds             | Required source or setting                                                              |
+| ------------ | --------------------------------------- | --------------------------------------------------------------------------------------- |
+| `volume`     | `0` to `2`                              | Any source; existing chord compensation follows selection                               |
+| `filterHz`   | `20` Hz to the active frequency ceiling | Enabled resonant filter: `lowpass`, `highpass` or `bandpass`                            |
+| `filterQ`    | `0.5` to `10`                           | Enabled resonant filter                                                                 |
+| `fmDepth`    | `0` to `10`                             | `SINE`, with the normal FM ratio/depth rules                                            |
+| `noiseRate`  | `1` Hz to the active frequency ceiling  | `NOISE` with authored `noiseRate >= 1`                                                  |
+| `lowPassHz`  | `20` Hz to the active frequency ceiling | One-pole low-pass already enabled with authored `lowPassHz >= 20`                       |
+| `pulseWidth` | `0.05` to `0.95`                        | `SQUARE`                                                                                |
+| `pitchCents` | `-1200` to `1200` cents                 | Resulting tuned frequencies and active pitch endpoints must remain within engine limits |
 
 `filterHz` controls the resonant filter; `lowPassHz` controls the separate one-pole low-pass. A range cannot enable a bypassed filter or turn white noise into colored noise. Pitch cents change oscillator pitch; use `noiseRate` to change a noise source's clock. A zero-depth sine can start with an active FM-depth range when the remaining FM configuration is valid.
 
@@ -112,7 +153,7 @@ Validation checks the complete reachable configuration before admission, includi
 
 ## Repeated independent effects
 
-Leave out `seed` to obtain successive native selections. Call `playTone` for each actual shot; keep the application's existing firing clock.
+Leave out `seed` to obtain successive native selections. Call `playTone` for each actual gameplay event. For periodic repetition of that finite recipe, call `repeatTone` with `intervalMs` once and retain its `toneId`; the renderer then owns the repeated deadlines. Standalone calls, including intentionally timed finite bursts, remain supported and return Boolean acceptance. `updateTone` changes future attacks, preserving the current deadline and variation counter. A changed seed restarts the stream, and dropped attacks consume no selection.
 
 ```javascript
 function fireLaser() {
@@ -131,11 +172,11 @@ function fireLaser() {
 fireLaser()
 ```
 
-The engine samples after admission and before initializing filters, smoothing controls and trajectories. Rejected attacks do not consume a selection. Existing release tails, capacity policy and voice replacement still apply.
+The engine samples after admitting an attack, before initializing its filters, smoothing controls and trajectories. Rejected attacks consume no selection. Release tails, capacity policy and voice replacement remain unchanged.
 
 ## Chords and application gain
 
-One chord is one atomic publication. Each voice uses its position within that attack to obtain independent field samples; it does not reuse the first voice's result. If the chord cannot be admitted, none of its voices starts and no event is consumed.
+A chord is published atomically. Each voice's position within the attack determines its independent field samples, so later voices do not reuse the first voice's result. If the chord cannot be admitted, none of its voices starts and no event is consumed.
 
 Scale a volume range with the same application gain as the authored volume. Let the engine apply its existing chord compensation once.
 
@@ -171,11 +212,11 @@ if (supportsVariation) held.variation = {
   ranges: { fmDepth: [1.1, 1.7], pitchCents: [-10, 10] }
 }
 synth.noteOn(held)
-synth.updateVoice({ voiceId: 71, volume: 0.12 })
+synth.updateNote({ voiceId: 71, volume: 0.12 })
 synth.noteOff({ voiceId: 71 })
 ```
 
-`updateVoice` rejects `variation`. To obtain another varied attack, release the owned voice and start another through the normal ownership path. A sustained motor stays steady under a single held attack. Release owned IDs on cancellation, pause and teardown; keep the usual bounded handling of rejected releases.
+`updateNote` rejects `variation`. To obtain another varied attack, release the owned voice and start another through the normal ownership path. A sustained motor stays steady under a single held attack. Release owned IDs on cancellation, pause and teardown; keep the usual bounded handling of rejected releases.
 
 ## Native loops and dictionary inheritance
 
@@ -232,22 +273,22 @@ if (supportsVariation && sequenceId > 0) {
 }
 ```
 
-Stop the owned sequence through the normal lifecycle when it is no longer needed. Stop/new play starts a new stream.
+Stop the owned sequence during normal lifecycle cleanup when it is no longer needed. Stopping and starting playback again creates a new stream.
 
 ## Seeds and reproducibility
 
-| Usage | Reproducibility |
-| --- | --- |
+| Usage                                                            | Reproducibility                                                           |
+| ---------------------------------------------------------------- | ------------------------------------------------------------------------- |
 | Repeated standalone calls with the same recipe and explicit seed | Reproduce the selected parameter values, starting at event zero each time |
-| Standalone calls without a seed | Use successive native selections |
-| Seeded native loop | Advances its attack counter across loop iterations |
-| Revision with unchanged seed identity | Retains that counter |
-| Revision that changes the root seed | Resets the counter when the revision applies |
-| Stop followed by a new sequence | Starts a new counter |
+| Standalone calls without a seed                                  | Use successive native selections                                          |
+| Seeded native loop                                               | Advances its attack counter across loop iterations                        |
+| Revision with unchanged seed identity                            | Retains that counter                                                      |
+| Revision that changes the root seed                              | Resets the counter when the revision applies                              |
+| Stop followed by a new sequence                                  | Starts a new counter                                                      |
 
 Seed identity includes whether the root seed was declared and its value, plus the sorted multiset of explicit step seed declarations. Moving steps, swapping existing declarations or inserting inherited rests preserves that identity. Adding, removing or changing an explicit step seed declaration changes it and resets the counter. Prefer a root seed for comparisons of a complete score.
 
-The counter is an unsigned 64-bit value and wraps modulo `2^64`. Admitted attack, voice ordinal and field slot determine each sample through the shared integer helper. Field slots are stable, so changing dictionary property order or adding an unrelated range does not shift existing field samples. Variation state is separate from the noise generator. A reproducible seed promises selected parameters, not identical noise PCM or identical DSP output across platforms.
+The counter is an unsigned 64-bit value and wraps modulo `2^64`. Admitted attack, voice ordinal and field slot determine each sample through the shared integer helper. Field slots are stable, so changing dictionary property order or adding an unrelated range does not shift existing field samples. Variation state is separate from the noise generator. A reproducible seed reproduces selected parameters. It does not promise identical noise PCM or identical DSP output across platforms.
 
 ## Rejected configurations
 
@@ -264,7 +305,7 @@ synth.playTone({ variation: {
 } })
 
 // Live updates do not accept an attack-only dictionary.
-synth.updateVoice({ voiceId: 71,
+synth.updateNote({ voiceId: 71,
   variation: { ranges: { pitchCents: [-10, 10] } } })
 ```
 
@@ -274,10 +315,10 @@ Also check pitch corners near 1 Hz or the reported ceiling. A valid base pitch c
 
 Studio calls this control Variantes. Its displayed percentage maps linearly: 25% sends native amount `0.25`, 50% sends `0.5`, and 100% sends `1`. Studio prepares broader ranges for its editor. The games retain their authored range profiles.
 
-Frontier automatically applies authored ranges only to its eligible destruction sounds; Guardian applies them only to its two lasers. Both require the capability/schema pair and keep their existing recipes on older modules. Studio allows any source to opt in through compatible parameter ranges. See [Studio's control and preset guide](https://github.com/macCesar/TiSynth-Studio/blob/main/documentation/variation.md); the native contract in this document does not depend on a consumer app.
+Frontier automatically applies authored ranges only to its eligible destruction sounds; Guardian applies them only to its two lasers. Both require the capability/schema pair. Studio allows any source to opt in through compatible parameter ranges. See [Studio's control and preset guide](https://github.com/macCesar/TiSynth-Studio/blob/main/documentation/variation.md); the native contract in this document does not depend on a consumer app.
 
 ## Implementation and verification
 
-Both renderers use [`shared/synth_variation.h`](https://github.com/macCesar/TiSynthEngine/blob/433d7884800f70fb4803dbfe2e0e869cd5411889/shared/synth_variation.h): stable schema slots, integer-defined SplitMix64 finalization and exact uint32-to-uniform conversion. Parsing prepares a fixed 144-byte configuration outside the audio callback. The callback performs bounded arithmetic without allocation, locks, JavaScript calls or entropy services.
+Both renderers use [`shared/synth_variation.h`](https://github.com/macCesar/TiSynthEngine/blob/9d74aa45f84d3f2822d4aab76874efe37d81257f/shared/synth_variation.h): stable schema slots, integer-defined SplitMix64 finalization and exact uint32-to-uniform conversion. Parsing prepares a fixed 144-byte configuration outside the audio callback. The callback performs bounded arithmetic without allocation, locks, JavaScript calls or entropy services.
 
-Focused checks cover known vectors, both native validators, attack admission, chord ordinals, sustained stability, loops, revisions, rejection and old-renderer compatibility with controlled noise initialization. [Technical verification](native-variation-validation.md) records the measured memory/callback cost and its limits. Host results do not certify physical latency or listening quality on every device.
+Focused checks cover known vectors, both native validators, attack admission, chord ordinals, sustained stability, loops, revisions, rejection and old-renderer compatibility with controlled noise initialization. [Technical verification](https://github.com/macCesar/TiSynthEngine/blob/9d74aa45f84d3f2822d4aab76874efe37d81257f/documentation/native-variation-validation.md) records the measured memory/callback cost and its limits. Host results do not certify physical latency or listening quality on every device.

package/skills/ti-synthengine/references/recipes-interaction.md

@@ -1,10 +1,16 @@
 # Instrument, polyphony and expressive recipes
 
-These curated TiTools recipes use the same running engine and runtime `WAVE`
-constants as [the arcade recipes](recipes.md). Keep one owner, check native
-acceptance and use their [verification checklist](recipes.md#recipe-verification-checklist).
-The expressive envelope/filter/FM ranges are starting points verified against
-the public contract, not device-auditioned presets. Listen before shipping.
+These TiTools recipes use the supported direct interface in 2.0.0 and share
+the running engine and runtime `WAVE` constants from
+[the arcade recipes](recipes.md). Keep one engine owner, check native acceptance
+and follow the [verification checklist](recipes.md#recipe-verification-checklist).
+
+The envelope, filter and FM ranges are starting points checked against the
+public contract. They have not been auditioned on a device, so listen before
+shipping.
+
+For new reusable instruments, read [Sound definitions and controls](sound-api.md).
+Keep these recipes' gains, pitch arrays, envelopes and ownership when adapting them.
 
 ```javascript
 const synth = require('ti.synthengine')
@@ -114,9 +120,8 @@ In a Titanium view:
 - call `gesture.finish()` on both `touchend` and `touchcancel`;
 - keep visual pressed-state counts separate if multiple touches are supported.
 
-The audio release may continue after the finger leaves a bar. That is desired
-for a xylophone. `stopAll()` is a global panic: it also cancels every native
-sequence and invalidates shared effect histories. Use an owner's
+For a xylophone, let the audio release continue after the finger leaves a bar.
+`stopAll()` is a global panic: it also cancels every native sequence and invalidates shared effect histories. Use an owner's
 `stopSequence({ sequenceId })` when only that sequence should stop.
 
 ## Four-pad memory cues
@@ -169,8 +174,8 @@ function playMemoryBank (bankName) {
 
 ### Controlled timbre comparison
 
-For an honest A/B test, hold pitches, duration, envelope and pan constant.
-Change only waveform and its comparison level. Never pass a profile object
+For an A/B test, hold pitches, duration, envelope and pan constant. Change
+only the waveform and its comparison level. Never pass a profile object
 containing labels or other app metadata directly to `playChord()` because its
 options dictionary is closed.
 
@@ -202,8 +207,8 @@ function auditionTimbre (profileName) {
 
 ### Convert MIDI pitch to hertz
 
-The standard A4 = 440 Hz formula makes it easy to build interval recipes
-without embedding a long frequency table.
+Use the standard A4 = 440 Hz formula to build interval recipes without
+embedding a long frequency table.
 
 ```javascript
 function midiToHz (midi) {
@@ -337,7 +342,9 @@ This repeated chord uses one centered native sequence. The one-off layered chord
 
 ### Cancellable repetition
 
-Every repeating sound has an identified native owner. Repeated start requests coalesce until the matching retirement event frees its slot. Stop its sequence ID and cancel pending restarts when its window closes; no JavaScript timer schedules subsequent notes.
+The chord pulse above belongs to one identified sequence owner. Repeated start requests coalesce until the matching `sequenceend` event retires it and frees the slot. When its window closes, stop that sequence ID and cancel pending restarts. The native sequence schedules subsequent chord attacks.
+
+For direct repetition of an original finite tone, use `repeatTone({ intervalMs, ...recipe })`, retain its positive tone ID, edit future attacks with `updateTone`, and cancel with `stopTone`. Each independent layer retains its own tone ID and overlap budget. `stopTone` preserves admitted finite attacks; `stopSequence` releases its sequence's voices. Tone IDs have no completion event, so the sequence retirement/restart procedure above does not apply to them. Independent event calls and intentionally timed finite JavaScript bursts remain supported; cancel any app-owned timers at teardown. See [the repetition contract](api.md#finite-tone-repetition) and [complete effect fidelity](instruments-and-effects.md#repeated-firing-uses-the-native-clock).
 
 ```javascript
 function cleanupAudio () {
@@ -354,9 +361,9 @@ Call `shutdown()` only from the screen or service that owns the shared engine.
 
 ### Plucked marimba note
 
-A short attack, a decay that falls to a low sustain and a release that fits
-give the struck-and-ring shape of a mallet or plucked string. A sustain below 1
-needs a decay, and `attack + decay` must fit inside `duration`.
+A short attack followed by decay to a low sustain gives the strike and ring
+of a mallet or plucked string. Keep the release within the available duration.
+A sustain below 1 needs a decay, and `attack + decay` must fit inside `duration`.
 
 ```javascript
 synth.playTone({
@@ -410,9 +417,9 @@ synth.playTone({
 
 ### Electric piano
 
-Frequency modulation with a 1:1 ratio gives a tine-like tone. Letting the
-modulation index fall through `fmDepthEnd` makes the note mellow as it rings,
-which is what the ear expects from a struck tine. FM needs a sine carrier.
+Frequency modulation with a 1:1 ratio gives a tine-like tone. Reduce the
+modulation index through `fmDepthEnd` so the note mellows as it rings, as a
+struck tine does. FM needs a sine carrier.
 
 ```javascript
 synth.playTone({

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

@@ -1,10 +1,13 @@
 # Curated sound and interaction recipes
 
-These recipes are tuned starting points for `ti.synthengine` 1.0.0. They use
-only public option keys, keep every explicit envelope valid, and obtain
-waveforms from the runtime contract instead of hardcoding integers. Install the
-matching official Android/iOS packages and follow the owning-engine
-[installation and lifecycle guide](guide.md) before using them.
+These recipes use the supported direct native interface in `ti.synthengine` 2.0.0
+and earlier 1.x modules. For reusable definitions in new code, use
+[Sound objects](sound-api.md) while preserving how each recipe renders.
+
+The examples use public option keys and valid explicit envelopes. They read
+waveforms from the runtime contract instead of hardcoding integers. Install
+matching official Android/iOS packages and follow the
+[installation and lifecycle guide](guide.md) to set up the engine owner.
 
 Unless a section says otherwise, the snippets assume one owner has already
 started the engine:
@@ -15,13 +18,13 @@ const contract = synth.getDefaults()
 const WAVE = contract.waveTypes
 ```
 
-Treat levels as starting points, not mastering targets. Test on the actual
-phone speaker and leave headroom when release tails or independent events can
-overlap.
+Use the levels as starting points for listening tests, rather than final
+mastering targets. Test on the actual phone speaker and leave headroom for
+overlapping release tails or independent events.
 
-Instrument interactions, layered chords and expressive synthesis are in
-[the interaction recipes](recipes-interaction.md). Their standard synthesis
-starting ranges require listening on the target device before shipping.
+For instrument interactions, layered chords and expressive synthesis, see
+[the interaction recipes](recipes-interaction.md). Listen to those starting
+ranges on the target device before shipping.
 
 <!-- TOC-START -->
 ## Contents
@@ -165,8 +168,8 @@ if (!sequenceId) throw new Error('Sequence rejected')
 
 ### Fast four-note arpeggio
 
-Very short square notes with a small attack retain the hard cartridge-era
-edge while reducing uncontrolled clicks. The 10 ms rests keep the first three
+Very short square notes with a small attack keep the hard cartridge-era
+edge and reduce uncontrolled clicks. The 10 ms rests keep the first three
 40 ms notes on a 50 ms grid; the final note rings for 80 ms.
 
 ```javascript
@@ -403,8 +406,9 @@ if (!sequenceId) throw new Error('Sequence rejected')
 
 ### Hovering craft
 
-A triangle voice with strong sine vibrato creates a cyclical engine wobble. Slow stereo travel adds movement on headphones while pitch
-remains the primary cue on mono speakers.
+A triangle voice with strong sine vibrato creates a repeating engine wobble.
+Slow stereo travel adds movement on headphones; pitch remains the primary cue
+on mono speakers.
 
 ```javascript
 synth.playTone({

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

@@ -1,14 +1,14 @@
-> Source snapshot: official TiSynthEngine documentation at commit `b07c97c762be5905f132cecf33e9d60ea0c21316` (2026-11-02). Published 1.0.2; local 1.1.0 candidates; public API 1.0.0. Upstream `documentation/recommendations.md` SHA-256: `d3d508efe07fce012baceb44285aa9ab4b850cc5c53a5d14c9b8d193e38ca8fb`.
+> Source snapshot: official TiSynthEngine documentation at commit `9d74aa45f84d3f2822d4aab76874efe37d81257f` (2026-11-03). Published module 2.0.0. Upstream `documentation/recommendations.md` SHA-256: `0e7c55830b05ef21bdd1fd125e7d158ea5b598e02618202e65ddd8b8d2044cab`.
 
 # Recommendations
 
-The defaults work for ordinary tones and chords. The choices below matter when an app has dense overlap, user-controlled values, demanding speakers or several audio systems sharing one lifecycle.
+The defaults work for ordinary tones and chords. Use the guidance below when an app has dense overlap, user-controlled values, demanding speakers or several audio systems sharing one lifecycle.
 
 ## Group simultaneous notes
 
-Use `playChord()` when pitches form one known simultaneous event. The chord is atomic. Protected profiles normalize per-voice source gain by the square root of the event voice count; `raw` bypasses that normalization. Separate `playTone()` calls are appropriate for independent touches and effects, but their start times and gain are independent too.
+Declare `playback.type: 'chord'` when pitches form one known simultaneous event. The chord is atomic. Protected profiles normalize per-voice source gain by the square root of the event voice count; `raw` bypasses that normalization. Separate tone executions suit independent effects, but their start times and gain are independent too.
 
-For keys or pads a user can trigger freely, keep each event around 0.4 to 0.7 until you have listened to the worst overlap. If every event needs gain above 1, consider `balanced` for the session before raising individual notes further.
+For freely triggered keys or pads, keep each event around 0.4 to 0.7 until you have listened to the worst overlap. If every event needs gain above 1, consider `balanced` for the session before raising individual notes further.
 
 ## Choose the mixing profile once
 
@@ -25,7 +25,7 @@ If a phone buzzes under `speakerSafe`, lower the event volume or raise the pitch
 
 ## Size `maxVoices` for real overlap
 
-`maxVoices` controls capacity. It does not make the engine louder or quieter.
+`maxVoices` sets voice capacity without changing event gain.
 
 | App behavior                       | Starting value |
 | ---------------------------------- | -------------: |
@@ -34,7 +34,7 @@ If a phone buzzes under `speakerSafe`, lower the event volume or raise the pitch
 | Chords, keys or long release tails |       16 to 24 |
 | Explicit stress testing            |             32 |
 
-Count release tails along with buttons pressed at the same instant. Replacement first selects the lowest eligible priority; higher-priority voices are protected. Among that priority, timed-only events steal the slot with the least time remaining; sustained/transport voices prefer a releasing slot, then the oldest attack. The short fade avoids a hard click; the stolen note still ends early.
+Count release tails as well as buttons pressed at the same instant. Replacement first selects the lowest eligible priority; higher-priority voices are protected. Among that priority, timed-only events steal the slot with the least time remaining; sustained/transport voices prefer a releasing slot, then the oldest attack. The short fade avoids a hard click; the stolen note still ends early.
 
 ## Keep one lifecycle owner
 
@@ -67,7 +67,7 @@ The resonant filter, FM and stacked detuned voices change level and spectrum mor
 - A resonance that keeps reaching the limiter makes the whole mix pump. Lower the volume or the Q before reaching for a different profile.
 - FM is not band-limited. A high carrier with a large `fmDepth` and `fmRatio` aliases. Keep carriers of bell-like sounds around 500 Hz, or lower the index.
 - A detuned stack is one voice per copy. Count them when choosing `maxVoices`. Protected profiles divide per-voice source gain by the square root of the event voice count; `raw` does not. Correlated or phase-aligned voices can still reinforce each other, so this is not a guarantee of constant loudness or peaks.
-- `sequenceend` reports completion or stopping by sequence identifier. Put contiguous notes into one sequence when sample timing matters; the event crosses JavaScript delivery latency.
+- A pattern control emits `end` on completion or stopping. Put contiguous notes into one pattern when sample timing matters; the event crosses JavaScript delivery latency.
 
 ## Validate values at the app boundary
 
@@ -87,7 +87,7 @@ Do not copy the frequency maximum into application code. It depends on the activ
 
 The same rule applies to `noiseRate`, `lowPassHz` and `filterHz`. Validate a custom `waveTable` as 2 to 64 finite values from -1 to 1, and remember that `bitDepth` accepts zero or an integer from 2 to 16. For `detune`, check the resulting pitch too: a shifted pitch that leaves the frequency range is rejected even when the cents value is in range.
 
-Check each method's documented return value during development: Boolean publication acceptance or a positive sequence ID, with 0 rejecting a sequence. Methods that emit structured validation warnings include the method, key and reason in the native log, but some sequence/control rejection paths do not log. Logging the return at the caller helps identify a stale preset or misspelled field without treating silence in the native log as acceptance.
+Check each method's documented return value during development. Sound playback returns finite acceptance, a playback control, or `false` on operational rejection; invalid Sound configurations throw. Direct native methods keep their documented Boolean or identifier returns. Methods that emit structured validation warnings include the method, key and reason in the native log, but some sequence/control rejection paths do not log. Logging the return at the caller helps identify a stale preset or misspelled field. A silent native log does not establish acceptance.
 
 ## Test the intended sound
 
@@ -103,7 +103,7 @@ Exercise the real worst case:
 - a route change while a note is playing;
 - screen off, interruption and background transitions if the product depends on them.
 
-An underrun counter only describes transport. A clean counter cannot tell you whether a waveform, pitch or mix is pleasant.
+An underrun counter describes transport; it cannot tell you whether a waveform, pitch or mix is pleasant.
 
 ## Binaural placement
 
@@ -111,13 +111,13 @@ Use the [integration guide](guide.md#integrate-binaural-in-a-2d-app) to convert
 
 ## Known limits
 
-- Use `noteOn` with app-supplied IDs for individual release and compatible live updates. Check the required methods before enabling controls; timed events do not return voice handles.
+- Keep the control returned by `sound.noteOn()` or held `play()` for release and compatible live updates. Finite tones and chords return no individual control.
 - Timed tones and chords last at most 60 seconds including release. Sequence intervals and explicit note lengths use the sequence unit, at most 300 beats or 60,000 ms; sequence ADSR remains in milliseconds and release may extend beyond the interval. Sustained `noteOn` voices last until release, replacement or shutdown.
 - The module synthesizes waveforms and does not play audio files.
 - One native transport supports up to four independent sequences, preallocated by `maxSequences`. All share at most 32 voices.
-- A single tone or chord has no completion event. Sequences emit `sequenceend` with their identifier and completed/stopped reason.
+- A single finite tone or chord has no completion event. A pattern control emits `end` with its completed/stopped reason.
 - Voice capacity and mixing profile remain fixed until shutdown.
-- Sequences run on the sample clock in beats or milliseconds. `duration` controls intervals; `length` independently controls note duration.
+- Patterns run on the sample clock in beats or milliseconds. Root and step `interval` control onset spacing; `length` independently controls note duration.
 - `lowPassHz` is a plain one-pole filter. The resonant filter has fixed 12 dB per octave and one exponential sweep; there is no filter envelope.
 - FM has one modulator and works only on `SINE`.
 - Binaural positions occupy a front plane. Spatial held voices support smooth live movement; there is no rear positioning, distance attenuation or head tracking. Output is two channels, without a multichannel 2.1/5.1 routing API.
@@ -128,10 +128,10 @@ Use a sample player or a dedicated music engine when a product needs streaming,
 
 ## Use effects and held voices deliberately
 
-Use `noteOn` for a sound whose duration follows interaction, such as a key, motor or beam; release its ID on touch end, cancellation, pause or scene teardown. Use `playSequence` for a finite musical cue or repeating grid. Neither needs JavaScript to keep an already accepted note alive. Both share the same 32-slot maximum with collision and interface tones; held notes can be stolen, and an accepted `updateVoice` on a stolen ID is a no-op. Optional priority 0-3 affects stealing; it reserves no voices. There is no voice-finished event.
+Use `sound.noteOn()` for a sound whose duration follows interaction, such as a key, motor or beam; release its note control on touch end, cancellation, pause or scene teardown. Use a pattern definition for a finite musical cue or repeating grid. The native engine sustains notes and schedules attacks. Both share the same 32-voice maximum with collision and interface tones; held notes can be stolen, and updates to a stolen note are accepted as no-ops. Optional priority 0-3 affects stealing without reserving voices. There is no voice-finished event.
 
 Keep chorus/delay/reverb mixes modest when dialogue or short game feedback must remain distinct. By default they process all four categories, so enabling reverb for a victory chord also affects simultaneous shots and collisions. Select categories with `applyTo` and assign each voice a `bus`, or use explicit `effectSend` values to choose the processed share. All selected voices share one effects chain. Disabling effects lets tails drain for at most 30 seconds; use panic when immediate history invalidation is required. Start with saturation disabled and compare creative drive at matched levels. Do not use saturation as an automatic substitute for the final limiter.
 
 Fixed input/event gain does not decrease when unrelated voices start. If level dips, inspect `maxLimiterReductionDb` and `preLimiterPeakDb`, then consider same-pitch phase cancellation or the device's speaker protection. Eight coherent independent voices can still exceed the limiter threshold; module capacity is not a clean-mix loudness guarantee. See [measurement example](advanced-examples.md#measure-peaks-and-limiter-reduction).
 
-Measure the complete workload on each target device, including held voices, binaural, LFOs, all enabled effects and tails. The [historical statistics benchmark](stats-performance.md) predates these features; the [current technical report](studio-validation.json) includes an unmet full-chain host deadline criterion. Neither is a guarantee of game-frame rate, physical audio deadlines, heat or battery life.
+Measure the complete workload on each target device, including held voices, binaural, LFOs, all enabled effects and tails. The [historical statistics benchmark](https://github.com/macCesar/TiSynthEngine/blob/9d74aa45f84d3f2822d4aab76874efe37d81257f/documentation/stats-performance.md) predates these features; the [current technical report](https://github.com/macCesar/TiSynthEngine/blob/9d74aa45f84d3f2822d4aab76874efe37d81257f/docs/validation/studio-validation.json) includes an unmet full-chain host deadline criterion. Neither is a guarantee of game-frame rate, physical audio deadlines, heat or battery life.