@maccesar/titools 5.2.3 → 5.2.5

package/skills/ti-synthengine/references/audio-engine.md

@@ -1,4 +1,4 @@
-> Source snapshot: official TiSynthEngine 1.0.2 documentation from reviewed working-tree source based on `4a45f21230ffc5a8838fbd5fc108dd3ab470362a` (2026-10-29). Upstream `documentation/audio-engine.md` SHA-256: `17fb01f7e32a91cc44a3b5c0f30efcd7b5c3d9ec6c49369f7c789e1f22a8b442`.
+> Source snapshot: official TiSynthEngine documentation at commit `ec04f4e634075c41b55f66279eabcd78b9652d58` (2026-11-02). Published module 1.1.0; public API 1.1.0. Upstream `documentation/audio-engine.md` SHA-256: `3e7728703a9f82631f5c4ba2641b1a9735c0d3988ef9001b8e4a4f5e47d1818d`.
 
 # Audio engine
 
@@ -17,6 +17,7 @@ The native signal path explains how mixing profiles and voice capacity affect th
 - [Voice pool](#voice-pool)
 - [Command queue](#command-queue)
 - [Shared DSP core](#shared-dsp-core)
+- [Native per-attack variation](#native-per-attack-variation)
 - [Android implementation](#android-implementation)
 - [iOS implementation](#ios-implementation)
 - [Latency](#latency)
@@ -28,6 +29,7 @@ The native signal path explains how mixing profiles and voice capacity affect th
 - [Sustained voices](#sustained-voices)
 - [Native transport and processing](#native-transport-and-processing)
 - [Unified transport acceptance boundaries](#unified-transport-acceptance-boundaries)
+- [Native finite-tone repetition (API 1.1.0)](#native-finite-tone-repetition-api-110)
 
 <!-- TOC-END -->
 
@@ -67,7 +69,7 @@ The engine has six sources:
 | `NOISE`     | White or variable-rate sample-and-hold pseudo-random generator. |
 | `WAVETABLE` | Caller-supplied 2 to 64-sample stepped cycle.                   |
 
-Pitch can move linearly from `frequency` to `frequencyEnd`. A sine LFO adds `lfoDepth * sin(lfoPhase)` in hertz before the oscillator advances. This makes vibrato depth absolute in hertz rather than cents.
+Pitch can move linearly from `frequency` to `frequencyEnd`. A sine LFO adds `lfoDepth * sin(lfoPhase)` in hertz before the oscillator advances. Vibrato depth is therefore an absolute value in hertz, rather than a value in cents.
 
 Noise rate advances an independent phase accumulator. A zero `noiseRate` uses one new pseudo-random value per output sample; a positive rate holds that value until the accumulator crosses the next update. `noiseRateEnd` changes the increment linearly over the event.
 
@@ -141,11 +143,11 @@ The profile is fixed when `start()` opens the stream.
 
 A single stereo-linked peak limiter sits after master volume and optional creative saturation. Linking preserves the stereo image when only one channel has the largest peak.
 
-| Parameter | Value                            |
-| --------- | -------------------------------- |
-| Retained samples | 0 (no lookahead)          |
-| Release   | 100 ms, exponential              |
-| Ceiling   | 0.85, or 0.70 with `speakerSafe` |
+| Parameter        | Value                            |
+| ---------------- | -------------------------------- |
+| Retained samples | 0 (no lookahead)                 |
+| Release          | 100 ms, exponential              |
+| Ceiling          | 0.85, or 0.70 with `speakerSafe` |
 
 The shared `synth_output.h` core finds the larger absolute channel value for each stereo frame and immediately applies any required reduction to both channels. Recovery toward unity uses a 100 ms exponential constant, bounded by the current frame's required gain; two consecutive quiet stereo frames (each channel ≤1e-12 in magnitude) reset reduction; an isolated zero crossing does not. There is no audio delay buffer. The ceilings bound sample values, not inter-sample peaks or loudspeaker excursion.
 
@@ -171,12 +173,16 @@ Both ports use a 128-slot single-consumer ring buffer. Producers are serialized
 
 `playChord()` publishes its note data and advances the queue index once. The consumer receives the complete event or nothing. `stopAll` and `shutdown` have a control fallback so cleanup is not lost under queue pressure.
 
-`playSequence` runs inside the sample-clock callback; JavaScript publishes entire configurations rather than individual notes. Scheduled releases execute independently of public command-queue capacity. `sequenceend` records are delivered outside the callback and retain their sequence identifier when slots are reused.
+`playSequence` runs inside the sample-clock callback; JavaScript publishes entire configurations instead of individual notes. Scheduled releases execute independently of public command-queue capacity. `sequenceend` records are delivered outside the callback and retain their sequence identifier when slots are reused.
 
 ## Shared DSP core
 
 The envelope, the state-variable filter, the sweep helpers, the FM sine and the cents conversion live once, in `shared/synth_core.h`. It is plain C, header-only and allocation-free. The Android renderer includes it from `android/jni/SynthOboeEngine.cpp` and the iOS renderer from `ios/Classes/TiSynthengineModule.m`, so both platforms run the same code. Backend voice integration and mixing remain separate per platform. Master ramps and final stereo protection share `shared/synth_output.h`. Held envelopes/ramps, transport, master effects, extra modulation and compatible retrigger support also have shared C cores.
 
+## Native per-attack variation
+
+Version 1.1.0 supports optional `variation`; published 1.0.2 packages reject it. Check both `capabilities.variation === true` and `variationSchemaVersion === 1`, then select bounded values at admitted attacks. The chosen configuration stays stable during that voice; existing sweeps, envelopes and explicit live edits keep their normal roles. Parsing prepares fixed-size state outside audio; the callback uses bounded shared arithmetic without allocation or locks. See [native variation](native-variation.md) for supported locations, source constraints, inheritance and seeds, and [technical verification](native-variation-validation.md) for measured compatibility and limits.
+
 ## Android implementation
 
 Android renders in C++ through Oboe. The stream requests floating-point output, low-latency performance and exclusive sharing when the device supports it. If exclusive access is unavailable, Oboe can use shared mode.
@@ -290,13 +296,15 @@ Android ARM64 reuses coefficients across eight consecutive samples, with four-sa
 
 ## Own-platform performance verification
 
+The measurements in this section predate native variation and describe the archived revisions in the cited reports. They do not measure version 1.1.0. Its separate [variation verification](native-variation-validation.md) records compatibility, storage and callback checks.
+
 The [performance review](performance-review.json) separates measured host improvements, exact compatibility checks and pending device acceptance. Its [raw evidence](performance-review-evidence.zip) retains rejected prototypes and the investigation of idle/stereo regressions. The Apple FIR, stable-control cache and exact idle-effects bypass were evaluated as one atomic candidate and then rejected after physical 32-stereo timing regressed. All three production changes were removed together; the full-score publication and control-memory fixes remain.
 
 Matched 48 kHz/1024-frame iPad full-load runs completed 600 audio seconds without callback deadline misses, with p95 load upper bounds 0.427 for the reference and 0.383 for the rejected initial candidate. The original Apple callback was restored because 32-stereo bypass p95 regressed reproducibly, including continuous-voice windows. Android Sim20/Sim80 frame presentation remains near 60 FPS, while occasional Sim80 output underruns persist in both versions. Compact 48 kHz iPad memory growth is about 18.2 MiB in both versions; no material RAM saving or physical 192 kHz acceptance is claimed. These results and qualified listening observations are recorded separately in the review.
 
 `tools/build_ios_render_host.py` compiles the actual Objective-C render-block body and voice/transport helpers on macOS. It replaces hardware/session/Titanium startup and fixes only the noise-seed/disabled-diagnostic clock. Output and semantic state are compared against a separately archived reference from the same platform. This is an Apple renderer test; it does not execute AVAudioEngine or establish iPad scheduling, route recovery, footprint or listening acceptance.
 
-The commands below reproduce the historical pre-pipeline performance review. Use its archived candidate source when requiring exact PCM/state equality with `7ab3110`; the current 1.0.2 renderer intentionally removes the old final-output delay and changes overload behavior, so it cannot satisfy that earlier exact-output comparison. For the later correction, use the [audio pipeline validation](audio-pipeline-validation.md) protocol: align only the former output delay, compare no-overload PCM within the declared tolerance, and retain overload differences separately. The module's `tools/compare_output_pcm.py` checks the corresponding matched Android/Apple capture sets; host comparisons do not establish physical output latency.
+The commands below reproduce the historical pre-pipeline performance review. Use its archived candidate source when requiring exact PCM/state equality with `7ab3110`; the renderer since 1.0.2 intentionally removes the old final-output delay and changes overload behavior, so it cannot satisfy that earlier exact-output comparison. For the later correction, use the [audio pipeline validation](audio-pipeline-validation.md) protocol: align only the former output delay, compare no-overload PCM within the declared tolerance, and retain overload differences separately. The module's `tools/compare_output_pcm.py` checks the corresponding matched Android/Apple capture sets; host comparisons do not establish physical output latency.
 
 ```sh
 mkdir -p /tmp/synth-reference
@@ -354,7 +362,7 @@ python3 tests/run_stats_java.py
 
 ## Sustained voices
 
-`noteOn`, `noteOff` and `updateVoice` use the existing bounded native command queue. Voice storage, smoothing ramps and identity snapshots are preallocated. The callback owns envelopes, oscillator/filter state and replacement decisions; it does not allocate or acquire producer locks. `shared/synth_held.h` supplies the same held ADSR, current-level release and independent 10 ms linear parameter ramps to both renderers. Held attack/decay counters stop advancing after those stages, avoiding sample-counter overflow on long notes.
+`noteOn`, `noteOff` and `updateNote` use the existing bounded native command queue. Voice storage, smoothing ramps and identity snapshots are preallocated. The callback owns envelopes, oscillator/filter state and replacement decisions; it does not allocate or acquire producer locks. `shared/synth_held.h` supplies the same held ADSR, current-level release and independent 10 ms linear parameter ramps to both renderers. Held attack/decay counters stop advancing after those stages, avoiding sample-counter overflow on long notes.
 
 IDs are app-supplied positive 32-bit integers. Atomic 32-bit identity snapshots and queued attacks let producers validate update source compatibility without reading mutable DSP state. The callback checks compatibility again. A full queue rejects note release with `false`; the caller owns its bounded retry and shutdown policy. See the [sustained contract](api.md#noteonoptions) for immutable configuration and supported updates.
 
@@ -365,13 +373,13 @@ Run `tests/held_core_regression.c` with C11 for shared envelope/ramp/identity ch
 
 `shared/synth_transport.h` owns up to four independent sequences and one global tempo/beat/millisecond clock; `shared/synth_sequence.h` advances each traversal with compensated sample increments. Beat lengths follow tempo changes; millisecond lengths remain constant. A serialized producer prepares sorted traversal and all pitches before publishing one of three immutable banks. The callback accepts tempo at the block boundary and structure at a step boundary; swing changes at a pair boundary. Transport voices share the sustained pool, retain owner identifiers and absolute note deadlines beyond internal slot reuse and release independently of the public command queue. See the [public transport contract](api.md#native-sequence-transport).
 
-`shared/synth_effects.h` supplies chorus, ping-pong delay, damped Schroeder reverb and optional saturation; `shared/synth_modulation.h` supplies two phase-preserving LFOs. Buffers allocate at engine initialization and free after the audio backend stops. Epoch tags on 16-sample pages invalidate histories during panic without walking delay memory; recovery clears at most one short page on a first write. Effects start disabled and default rendering follows exact bypass. Enabled effects drain on disable, bounded to 30 seconds. No new external DSP dependency is used.
+`shared/synth_effects.h` supplies chorus, ping-pong delay, damped Schroeder reverb and optional saturation; `shared/synth_modulation.h` supplies two phase-preserving LFOs. Buffers allocate at engine initialization and free after the audio backend stops. Epoch tags on 16-sample pages invalidate histories during panic without walking delay memory; recovery clears at most one short page on a first write. Effects start disabled and default rendering follows exact bypass. Enabled effects drain on disable, bounded to 30 seconds. The implementation uses no additional external DSP dependency.
 
 Pre-limiter peak and maximum limiter reduction accumulate natively until reset, so polling cannot miss a brief intervention. The callback tracks linear extrema and converts to decibels once per block. Existing output peak/RMS and reduction windows remain approximately 200 ms. Diagnostics are optional; host measurements do not establish device audio deadlines or listening acceptance.
 
-Portable checks: compile and run `tests/sequence_core_regression.c`, `tests/effects_core_regression.c` and `tests/modulation_core_regression.c` with C11, optimization and libm. The transport test checks ten minutes at five sample rates against calculated event times, plus edits, swing, rests, chords and publication pressure. Effects tests check bypass, tails, panic, automation, memory and stability at 16, 44.1, 48, 96 and 192 kHz. On macOS, `tests/studio_contract_ios.m` validates the new iOS configuration contract without Titanium.
+Portable checks: compile and run `tests/sequence_core_regression.c`, `tests/effects_core_regression.c` and `tests/modulation_core_regression.c` with C11, optimization and libm. The transport test checks ten minutes at five sample rates against calculated event times, plus edits, swing, rests, chords and publication pressure. Effects tests check bypass, tails, panic, automation, memory and stability at 16, 44.1, 48, 96 and 192 kHz. On macOS, `tests/studio_contract_ios.m` validates the iOS configuration contract without Titanium.
 
-`tools/calibrate_studio.py --studio-root PATH` measures the production Android callback; add `--platform ios` for the production Apple callback. The report covers each preset/scenario at 1, 2, 4, 8, 16 and 32 voices, including independent low/mid/high notes, grouped chords, coherent unisons and overlapping releases. Recommendations target −6 dBFS before protection (with 0.01 dB margin) using the maximum measured peak of the declared usual 1-8-voice configuration and the public voice-volume limit. Larger workloads are separate stress diagnostics. The tool reports fixed scalar recommendations and never edits Studio. Effects and new LFOs are disabled, so recommendations do not guarantee headroom for other configurations. See [audio pipeline validation](audio-pipeline-validation.md).
+`tools/calibrate_studio.py --studio-root PATH` measures the production Android callback; add `--platform ios` for the production Apple callback. The report covers each preset/scenario at 1, 2, 4, 8, 16 and 32 voices, including independent low/mid/high notes, grouped chords, coherent unisons and overlapping releases. Recommendations target −6 dBFS before protection (with 0.01 dB margin) using the maximum measured peak of the declared usual 1-8-voice configuration and the public voice-volume limit. Larger workloads are separate stress diagnostics. The tool reports fixed scalar recommendations and never edits Studio. Effects and additional LFOs are disabled, so recommendations do not guarantee headroom for other configurations. See [audio pipeline validation](audio-pipeline-validation.md).
 
 Device feedback superseded that headroom target for Studio's initial Cristal preset: its fixed gain is restored to 1 because the calibrated setting made a fresh Android installation barely audible. This adds 10.83 dB without saturation or voice-count normalization. Three coherent factory notes remain below the limiter ceiling at maximum master; eight independent coherent notes can require limiting. The calibration recommendations remain recorded separately from this active preset exception.
 
@@ -379,4 +387,10 @@ The [Studio technical validation report](studio-validation.json) records the cal
 
 ## Unified transport acceptance boundaries
 
-The 1.0.0 contract uses one renderer, at most 32 voices and capacity for 1-4 sequences. `bus` categories and per-voice sends share one effects chain. These API changes do not establish complete multiplatform ten-minute maximum-load acceptance; the measured iPad result and Android limits are recorded separately in [physical validation](physical-validation.json) and [the performance summary](stats-performance.md). Host timing, bypass comparisons, memory accounting, actual Android/iOS builds and the remaining device/listening checks are separate evidence. Historical Studio benchmarks below predate these changes and remain historical observations. At 192 kHz, the revised effects buffers use approximately 13.1 MiB; the maximum sequence pool uses approximately 8.23 MiB before renderer voices/queues. Total native accounting must include those remaining structures and recovery peaks; the target is at most 32 MiB additional memory.
+Public API 1.1.0 uses one renderer, at most 32 voices and capacity for 1-4 sequences. `bus` categories and per-voice sends share one effects chain. These API changes do not establish complete multiplatform ten-minute maximum-load acceptance; the measured iPad result and Android limits are recorded separately in [physical validation](physical-validation.json) and [the performance summary](stats-performance.md). Host timing, bypass comparisons, memory accounting, actual Android/iOS builds and the remaining device/listening checks are separate evidence. The cited Studio and unified-transport benchmarks are historical observations. In the pre-variation layout, effects buffers at 192 kHz used approximately 13.1 MiB and four maximum-size triple-bank transports used 8,627,712 bytes (8.23 MiB), excluding renderer voices and queues. Version 1.1.0 grows those four transports to 9,537,152 bytes (9.10 MiB) on the measured 64-bit macOS layout, an increase of 909,440 bytes; see [variation storage measurements](native-variation-validation.md#storage-and-callback-work). These structure sizes are not a new whole-process or physical-device measurement. Total accounting must also include renderer voices/tails, command queues, effects, bridge/canonical options and recovery peaks. The 32 MiB additional-memory target remains a target, not a certified bound for version 1.1.0.
+
+## Native finite-tone repetition (API 1.1.0)
+
+The shared C scheduler owns 32 repetition slots independently of sequence capacity. It retains fractional sample deadlines across normal and spatial render blocks. Each `repeatTone` attack emits the same finite-tone command used by a standalone `playTone`. The first attack starts at the first render opportunity, independent of tempo. Preallocated publication banks carry complete validated configurations; the callback allocates no memory, takes no producer locks and runs no JavaScript. Stop publication has a separate atomic path, so a full ordinary command queue cannot prevent cancellation at the next block.
+
+Each repetition owns its variation stream and admitted-attack counter. Admission failure skips that attack without advancing variation or queuing catch-up work. Updates preserve the pending deadline and affect its attack; a new interval controls the subsequent gap. `stopTone` cancels only future attacks, leaving admitted finite tones to complete. Global stop, shutdown and destruction invalidate slots and pending edits. These implementation guarantees require the updated 1.1.0 binaries; historical measurements elsewhere on this page do not measure this scheduler. See [the public contract](api.md#finite-tone-repetition).

package/skills/ti-synthengine/references/audio-pipeline-validation.md

@@ -1,4 +1,4 @@
-> Source snapshot: official TiSynthEngine 1.0.2 documentation from reviewed working-tree source based on `4a45f21230ffc5a8838fbd5fc108dd3ab470362a` (2026-10-29). Upstream `documentation/audio-pipeline-validation.md` SHA-256: `7359d85de63e9fe94f85477e03a22fc1531c8acaabe30333e7ff2515cc5ec3e9`.
+> Source snapshot: official TiSynthEngine documentation at commit `ec04f4e634075c41b55f66279eabcd78b9652d58` (2026-11-02). Published module 1.1.0; public API 1.1.0. Upstream `documentation/audio-pipeline-validation.md` SHA-256: `7359d85de63e9fe94f85477e03a22fc1531c8acaabe30333e7ff2515cc5ec3e9`.
 
 # Audio pipeline correction
 

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

@@ -1,8 +1,8 @@
-> Source snapshot: official TiSynthEngine 1.0.2 documentation from reviewed working-tree based on commit `4a45f21230ffc5a8838fbd5fc108dd3ab470362a` (2026-10-29). Upstream `documentation/examples.md` SHA-256: `48104b9d413050d439ee605c92a2456a50b42c4c80e2d7c2c05706eecc7db215`.
+> 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`.
 
 # Examples
 
-Every snippet on this page uses the TiSynthEngine 1.0.0 contract. Unless a snippet includes startup code, it assumes the engine is already running.
+Every snippet on this page uses the TiSynthEngine 1.1.0 contract. Unless a snippet includes startup code, it assumes the engine is already running.
 
 Additional [curated recipes](recipes.md) provide application sound and interaction variants.
 
@@ -13,8 +13,8 @@ var synth = require('ti.synthengine')
 var contract = synth.getDefaults()
 var WAVE = contract.waveTypes
 
-if (contract.apiVersion !== '1.0.0') {
-  throw new Error('TiSynthEngine 1.0.0 is required')
+if (contract.apiVersion !== '1.1.0') {
+  throw new Error('TiSynthEngine 1.1.0 is required')
 }
 ```
 
@@ -570,7 +570,7 @@ synth.shutdown()
 
 `stopAll()` stops all native sequences, fades current voices and invalidates effect histories. `shutdown()` also releases the native stream. To stop only one sequence owner, use `stopSequence({ sequenceId })`.
 
-Follow the [interactive demo setup and test checklist](../assets/example/README.md) to run [`example/app.js`](../assets/example/app.js). It includes headphone positioning, session selection, pattern completion/replacement and all three statistics methods. For a service-level statistics recipe, see [read engine statistics](guide.md#read-engine-statistics).
+Follow the [interactive demo setup and test checklist](../assets/example/README.md) to run [`example/app.js`](../assets/example/app.js). It includes headphone positioning, session selection, pattern completion/replacement and the statistics methods `getStats`, `enableStats`, `disableStats` and `resetStats`. For a service-level statistics recipe, see [read engine statistics](guide.md#read-engine-statistics).
 
 ## Positioned headphone effect
 

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

@@ -1,4 +1,4 @@
-> Source snapshot: official TiSynthEngine 1.0.2 documentation from the reviewed working-tree based on `4a45f21230ffc5a8838fbd5fc108dd3ab470362a` (2026-10-29). Upstream `documentation/guide.md` SHA-256: `6241f84ba84e20c0516bf01bc0850f9625d2b41f0bef39289c056e687b21ee37`.
+> Source snapshot: official TiSynthEngine documentation at commit `ec04f4e634075c41b55f66279eabcd78b9652d58` (2026-11-02). Published module 1.1.0; public API 1.1.0. Upstream `documentation/guide.md` SHA-256: `0edc2fb8bccb4412d80e00d63a5a631b455d0ede6178c16642e63e37ce3dd77e`.
 
 # Guide
 
@@ -28,27 +28,30 @@ Install TiSynthEngine, start it after layout settles, and release its native aud
 - [Read engine statistics](#read-engine-statistics)
 - [Next steps](#next-steps)
 - [Diagnose mix headroom](#diagnose-mix-headroom)
+- [Variation support in version 1.1.0](#variation-support-in-version-110)
 
 <!-- TOC-END -->
 
 ## Install the module
 
-Download both official packages from [Android 1.0.2](https://github.com/macCesar/TiSynthEngine/releases/tag/android-1.0.2) and [iOS 1.0.2](https://github.com/macCesar/TiSynthEngine/releases/tag/ios-1.0.2). For source builds, the matching archives are produced under `android/dist` and `ios/dist`:
+Download both official packages from [Android 1.1.0](https://github.com/macCesar/TiSynthEngine/releases/tag/android-1.1.0) and [iOS 1.1.0](https://github.com/macCesar/TiSynthEngine/releases/tag/ios-1.1.0). Matching archives are produced under `android/dist` and `ios/dist`:
 
-- `ti.synthengine-android-1.0.2.zip`
-- `ti.synthengine-iphone-1.0.2.zip`
+- `ti.synthengine-android-1.1.0.zip`
+- `ti.synthengine-iphone-1.1.0.zip`
 
 Put the archives in the Titanium project root or install them through the Titanium CLI. Pin the same version for both platforms:
 
 ```xml
 <modules>
-  <module platform="android" version="1.0.2">ti.synthengine</module>
-  <module platform="iphone" version="1.0.2">ti.synthengine</module>
+  <module platform="android" version="1.1.0">ti.synthengine</module>
+  <module platform="iphone" version="1.1.0">ti.synthengine</module>
 </modules>
 ```
 
 TiSynthEngine requires Titanium SDK 13.2.0.GA or newer. Android projects must compile against API 35 or newer. The iOS module requires iOS 15 or newer.
 
+These declarations select version 1.1.0. Check the [variation metadata](#variation-support-in-version-110) before using native attack variation.
+
 ## Load and verify the contract
 
 Require the module once in the code that owns audio. Check `apiVersion` before starting. Also check the [spatial limits](#detect-the-installed-feature) and [statistics methods](#read-engine-statistics) if the app needs those features. Check [required capabilities](#detect-required-capabilities) for held voices, musical transport and master processing.
@@ -57,8 +60,8 @@ Require the module once in the code that owns audio. Check `apiVersion` before s
 var synth = require('ti.synthengine')
 var contract = synth.getDefaults()
 
-if (contract.apiVersion !== '1.0.0') {
-  throw new Error('TiSynthEngine 1.0.0 is required; found ' + contract.apiVersion)
+if (contract.apiVersion !== '1.1.0') {
+  throw new Error('TiSynthEngine 1.1.0 is required; found ' + contract.apiVersion)
 }
 ```
 
@@ -112,30 +115,30 @@ Use one owner for the engine. Start it once, pass a small audio service to the s
 
 ## Detect required capabilities
 
-Public API version 1.0.0 includes held voices, sample-clock sequences, stereo effects and two optional LFOs. Require the methods used by each feature before enabling its controls:
+Public API version 1.1.0 includes held voices, sample-clock sequences, stereo effects and two optional LFOs. Require the methods used by each feature before enabling its controls:
 
 ```javascript
 function hasMethods (names) {
   return names.every(function (name) { return typeof synth[name] === 'function' })
 }
-var supportsHeld = hasMethods(['noteOn', 'noteOff', 'updateVoice'])
+var supportsHeld = hasMethods(['noteOn', 'noteOff', 'updateNote'])
 var supportsSequence = hasMethods(['playSequence', 'updateSequence', 'stopSequence', 'getSequenceState'])
 var supportsProcessing = hasMethods(['setMasterProcessing'])
 ```
 
-Start the engine successfully before publishing held notes, sequence edits or processing. `getDefaults` and feature checks do not open the stream. Install matching packages for Android/iOS and rebuild the application when replacing a native module. Additional LFOs require the documented modulation contract; check acceptance of the complete configuration. Treat rejected configurations as unavailable rather than silently dropping their keys.
+Start the engine successfully before publishing held notes, sequence edits or processing. `getDefaults` and feature checks do not open the stream. Install matching packages for Android/iOS and rebuild the application when replacing a native module. Additional LFOs require the documented modulation contract; check acceptance of the complete configuration. Treat rejected configurations as unavailable. Do not silently drop their keys.
 
 ## Hold and edit a voice
 
 Use `noteOn({ voiceId, ... })` when duration follows interaction: a piano key, motor, beam, pad or the last chord of a ceremony. Allocate a unique positive integer ID per attack, and release only that ID with `noteOff`. No duration or sweep-end fields are accepted. A chord held this way consists of separate IDs; unlike one `playChord` or sequence chord, separate `noteOn` calls have independent gain and publication.
 
-`updateVoice` changes compatible pitch, volume, cutoff/Q, vibrato, PWM/FM, LFO targets, noise clock, one-pole cutoff, effect send and stereo/spatial position with 10 ms ramps, without restarting oscillator/envelope phase. Source, table, filter type, quantization, ADSR and stereo-versus-spatial mode are fixed at attack. See [complete fields](api.md#updatevoiceoptions). A note that has ended or been stolen accepts updates as a no-op; there is no note-finished event or reserved slot. A `true` return means accepted publication, not proof that the sound is still active.
+`updateNote` changes compatible pitch, volume, cutoff/Q, vibrato, PWM/FM, LFO targets, noise clock, one-pole cutoff, effect send and stereo/spatial position with 10 ms ramps, without restarting oscillator/envelope phase. Source, table, filter type, quantization, ADSR and stereo-versus-spatial mode are fixed at attack. See [complete fields](api.md#updatenoteoptions). A note that has ended or been stolen accepts updates as a no-op; there is no note-finished event or reserved slot. A `true` return means accepted publication, not proof that the sound is still active.
 
 Release on touch end and cancellation as well as ordinary key up. Retry a rejected release twice at 16 ms outside the audio callback, then shut down and report failure if publication remains blocked. Cancel retries during teardown. The [held motor example](advanced-examples.md#sustained-game-motor) implements this ownership policy. For pause/owner close, invalidate app scheduling and shut down; require a new start before future notes.
 
 ## Choose the musical transport
 
-Use `playSequence` for all successive native sounds. `playTone` and `playChord` handle independent timed events; `noteOn`/`noteOff` hold a sound for interaction. Start with `maxSequences: 1…4` to preallocate independent sequence capacity. All use the same pool of up to 32 voices.
+Use `repeatTone({ intervalMs, ...recipe })` for native repetition of an original finite tone, and `playSequence` for ordered native scores. Retain each positive tone ID, edit with `updateTone` and cancel future attacks with `stopTone`; see [finite-tone repetition](api.md#finite-tone-repetition). `playTone` and `playChord` handle independent timed events; `noteOn`/`noteOff` hold a sound for interaction. Start with `maxSequences: 1…4` to preallocate independent sequence capacity. All use the same pool of up to 32 voices.
 
 Store the positive identifier returned by `playSequence`, and include it in each update, stop or state query. 0 rejects publication. Three banks per sequence publish complete edits atomically. Structural edits enter at the next step; swing at the next pair. `setTempo({ bpm })` applies at the next block, preserving beat position. Beat sequences follow it; ms sequences keep fixed times. `stopSequence({ sequenceId })` releases only that owner's voices and leaves effect tails. A retired identifier returns null from `getSequenceState`.
 
@@ -143,7 +146,7 @@ Store the positive identifier returned by `playSequence`, and include it in each
 synth.setTempo({ bpm: 112 })
 var sequenceId = synth.playSequence({
   stepDuration: 0.5, swing: 0.12, bus: 'music',
-  voice: { waveType: WAVE.SQUARE, volume: 0.55 },
+  voice: { waveType: contract.waveTypes.SQUARE, volume: 0.55 },
   steps: [{ notes: [60] }, { notes: [64], overrides: { pan: -0.4, panEnd: 0.4 } },
     { rest: true }, { notes: [67], duration: 1, length: 0.8 }]
 })
@@ -365,7 +368,7 @@ synth.playChord({
 synth.setTempo({ bpm: 112 })
 var sequenceId = synth.playSequence({
   stepDuration: 0.5, swing: 0.12, bus: 'music',
-  voice: { waveType: WAVE.SQUARE, volume: 0.55 },
+  voice: { waveType: contract.waveTypes.SQUARE, volume: 0.55 },
   steps: [{ notes: [60] }, { notes: [64], overrides: { pan: -0.4, panEnd: 0.4 } },
     { rest: true }, { notes: [67], duration: 1, length: 0.8 }]
 })
@@ -394,7 +397,7 @@ synth.setVolume({ volume: 0.7 })
 synth.stopAll()
 ```
 
-Master volume changes use a linear 10 ms ramp. `stopAll()` stops every native sequence, cancels future attacks, fades active voices and invalidates effect histories. Call `stopSequence({ sequenceId })` to stop only one sequence, or `shutdown()` to close the stream and free resources.
+Master volume changes use a linear 10 ms ramp. `stopAll()` stops every native sequence and finite-tone repetition, cancels future attacks, fades active voices and invalidates effect histories. Call `stopSequence({ sequenceId })` to stop only one sequence, or `shutdown()` to close the stream and free resources.
 
 ## Output route changes
 
@@ -509,7 +512,7 @@ if (!playPositionedTone(explosion, 900, 100, 1000, 800)) {
 
 Connect a Titanium switch's `change` event to `audioSettings.binaural = event.value`; connect the two sliders' `change` events to `horizontalPercent` and `heightPercent`. Configure slider minimum 0 and maximum 100, and disable the height slider while the switch is off. Validate restored preference values as finite numbers within those ranges before using them. Do not pass these preference names to `playTone`: that would return `false` with `unsupported_option`.
 
-Supply the current position whenever an effect fires. A projectile launch cue can use the launch position; an impact uses the collision position. Timed event positions remain fixed after submission. An identified sustained voice started spatially can instead change `spatialX`/`spatialY` through `updateVoice`, with 10 ms ramps and retained spatial history. A stereo voice cannot become spatial through an update. Stereo `panEnd` movement cannot be combined with binaural; do not continually retrigger long sounds every frame to imitate movement.
+Supply the current position whenever an effect fires. A projectile launch cue can use the launch position; an impact uses the collision position. Timed event positions remain fixed after submission. An identified sustained voice started spatially can instead change `spatialX`/`spatialY` through `updateNote`, with 10 ms ramps and retained spatial history. A stereo voice cannot become spatial through an update. Stereo `panEnd` movement cannot be combined with binaural; do not continually retrigger long sounds every frame to imitate movement.
 
 ### Chords and patterns
 
@@ -554,7 +557,7 @@ Basic counters are available without enabling optional diagnostics. Reads do not
 ```javascript
 var statsTimer = null
 var statsSupported = typeof synth.getStats === 'function' &&
-  typeof synth.setStatsEnabled === 'function' && typeof synth.resetStats === 'function'
+  typeof synth.enableStats === 'function' && typeof synth.disableStats === 'function' && typeof synth.resetStats === 'function'
 
 function readStats () {
   var stats = synth.getStats()
@@ -565,7 +568,7 @@ function readStats () {
 
 function startDiagnostics () {
   if (!statsSupported || statsTimer !== null) return false
-  if (!synth.setStatsEnabled(true)) return false
+  if (!synth.enableStats()) return false
   statsTimer = setInterval(readStats, 200)
   return true
 }
@@ -573,7 +576,7 @@ function startDiagnostics () {
 function stopDiagnostics () {
   if (statsTimer !== null) clearInterval(statsTimer)
   statsTimer = null
-  if (statsSupported) synth.setStatsEnabled(false)
+  if (statsSupported) synth.disableStats()
 }
 
 // Read basic counters without enabling timing or signal meters:
@@ -598,6 +601,22 @@ See the [complete field contract](api.md#getstats), [measurement limits](stats-p
 
 ## Diagnose mix headroom
 
-The current diagnostics add `preLimiterPeakDb` (maximum signal before final limiting, in dBFS) and `maxLimiterReductionDb` (greatest limiter attenuation in dB) accumulated since reset. Unlike the approximately 200 ms window reduction field, brief peaks remain visible between UI polls. Enable measurements, reset before the scenario and keep `null`/absent fields distinct from measured zero. The [measurement example](advanced-examples.md#measure-peaks-and-limiter-reduction) shows opt-in polling and cleanup.
+The diagnostics include `preLimiterPeakDb` (maximum signal before final limiting, in dBFS) and `maxLimiterReductionDb` (greatest limiter attenuation in dB) accumulated since reset. Unlike the approximately 200 ms window reduction field, brief peaks remain visible between UI polls. Enable measurements, reset before the scenario and keep `null`/absent fields distinct from measured zero. The [measurement example](advanced-examples.md#measure-peaks-and-limiter-reduction) shows opt-in polling and cleanup.
 
 Fixed event/input gain does not normalize continuously by active voice count. Coherent overlapping notes, effects feedback or resonance can still exceed the ceiling; the limiter then acts on the whole stereo sum. Saturation is a separate creative processor, disabled initially. Physical loudness and small-speaker bass response are not measured by these digital meters.
+
+
+<a id="local-native-variation-candidate"></a>
+
+## Variation support in version 1.1.0
+
+Source builds produce archives at `android/dist/ti.synthengine-android-1.1.0.zip` and `ios/dist/ti.synthengine-iphone-1.1.0.zip`. Keep them separate from the published 1.0.2 packages. Install both matching 1.1.0 packages in the consumer app and select them explicitly:
+
+```xml
+<modules>
+  <module platform="android" version="1.1.0">ti.synthengine</module>
+  <module platform="iphone" version="1.1.0">ti.synthengine</module>
+</modules>
+```
+
+Rebuild and reinstall the application after replacing the native modules. Published 1.0.2 retains API `1.0.0`; version 1.1.0 reports API `1.1.0` and supports native finite-tone repetition. Check the variation announcements directly as well. Send a `variation` dictionary only when `getDefaults().capabilities.variation === true` and `getDefaults().variationSchemaVersion === 1`. If either announcement is absent, omit the property completely, including at amount zero. See [native attack variation](native-variation.md) for accepted locations, bounded ranges and seed behavior.

package/skills/ti-synthengine/references/instruments-and-effects.md

@@ -0,0 +1,164 @@
+> Source snapshot: official TiSynthEngine documentation at commit `ec04f4e634075c41b55f66279eabcd78b9652d58` (2026-11-02). Published module 1.1.0; public API 1.1.0. Upstream `documentation/instruments-and-effects.md` SHA-256: `6c9b96c406c54426a1d37a85b42909a50621cc647d08d37fa89c19283b3acfa0`.
+
+# Instruments, sound effects and complete sequences
+
+A playable instrument and a missile sound can use the same oscillator. Their behavior depends on the complete recipe: pitch, envelope, pitch/filter movement, layers, timing, and how the app starts and ends it. This guide explains which public API to use and how to preserve that recipe.
+
+These are application roles built on the same native synthesizer and output chain. They are not different audio engines, quality modes, or guarantees against distortion. An instrument can be noisy or inharmonic; an effect can be a single pitched tone, a chord, or a musical phrase.
+
+## Choose the playback contract
+
+| Intention                                                         | Native methods                                              | Who ends the sound?                                      | What to preserve                                                             |
+| ----------------------------------------------------------------- | ----------------------------------------------------------- | -------------------------------------------------------- | ---------------------------------------------------------------------------- |
+| Play a key until the finger lifts                                 | `noteOn`, `updateNote`, `noteOff`                           | The app releases its unique voice ID                     | Timbre, tuning, envelope, contact ownership                                  |
+| Fire one finite sound                                             | `playTone`                                                  | Native duration and release                              | Original frequency, endpoints, duration, envelope, gain                      |
+| Repeat one finite tone, including simultaneous independent layers | `repeatTone({ intervalMs, ... })`, `updateTone`, `stopTone` | Native audio clock; stop cancels future attacks only     | Original finite-tone recipe, interval, overlap budget and each tone ID       |
+| Fire a simultaneous chord with shared shaping                     | `playChord`                                                 | Native duration and release                              | All pitches, per-note pan/detune, shared envelope, native chord compensation |
+| Play a melody, alarm, layered effect, or repeated firing pattern  | `playSequence`, optionally `updateSequence`                 | Native step clock; `stopSequence` cancels future attacks | Complete ordered steps, rests, lengths, overrides and independent layers     |
+| Add chorus, delay, reverb or creative saturation                  | `setMasterProcessing`                                       | The shared processor owns its tails                      | Routing, sends, input gain, effect settings and output headroom              |
+
+The last row describes audio processing effects. Those processors are different from an authored sound effect, such as a laser or an explosion. A laser may use no reverb or delay at all.
+
+All examples below assume successful startup. Use constants from the installed module and check native acceptance:
+
+```javascript
+var synth = require('ti.synthengine')
+var WAVE = synth.getDefaults().waveTypes
+if (!synth.start({ maxVoices: 32, maxSequences: 4,
+  mixingProfile: 'conservative', audioSession: 'playback' })) {
+  throw new Error('Could not start TiSynthEngine')
+}
+synth.setVolume({ volume: 0.6 })
+```
+
+See [API limits](api.md) and [startup and lifecycle](guide.md) for application integration. Do not call `start` on each key just to reset a voice pool. Shut the engine down when its application owner finishes.
+
+## 1. Playable instruments and sustained voices
+
+An instrument recipe defines the response of a new note: waveform, filter, FM, envelope, level and positioning. The keyboard supplies its pitch and release gesture. Each simultaneous contact needs its own positive voice ID.
+
+```javascript
+var nextVoiceId = 1
+function pressKey(frequency) {
+  var voiceId = nextVoiceId++
+  var accepted = synth.noteOn({ voiceId: voiceId, frequency: frequency,
+    waveType: WAVE.TRIANGLE, volume: 0.16,
+    attack: 8, decay: 220, sustain: 0.35, release: 180,
+    bus: 'music' })
+  return accepted ? voiceId : 0
+}
+function releaseKey(voiceId) {
+  return synth.noteOff({ voiceId: voiceId })
+}
+```
+
+Store the returned ID with that contact. Sliding to another key must release the old owner and admit the new attack; do not release another finger's voice. An app-level Hold control retains selected IDs until explicitly released. If `noteOff` is rejected, keep ownership and follow a bounded retry/error policy; silently forgetting the ID can leave a stuck voice. The [held voice guide](guide.md#hold-and-edit-a-voice) covers lifecycle and compatible live edits.
+
+`noteOn` does not accept timed-event endpoint sweeps such as `frequencyEnd`. A held voice can use its supported vibrato/LFOs and compatible `updateNote` edits. Removing a timed sweep, replacing the original frequency with the key's pitch, and holding indefinitely changes the sound's meaning: that is a new playable timbre, not an exact audition of the original effect.
+
+A short envelope also does not automatically make a held voice finite. With `sustain: 0`, it can become silent while still requiring release of its ID. Choose a timed event for a self-contained strike when contact ownership is unnecessary.
+
+### Instrument demonstrations are musical performances
+
+A demo provides notes and articulation for the current timbre. It should not silently substitute another sound or replace the user's editable pattern. A useful finite phrase has an opening, development and a resolved ending:
+
+- Winds need an appropriate register, separated attacks and breathing spaces.
+- Strings benefit from longer notes and nearly connected lengths.
+- Basses benefit from a low register, rests and a deliberate groove.
+- Guitars and keyboards can use arpeggios, chord changes and varied note lengths.
+- Percussion needs separate strikes and enough room for its decay and release.
+- Slow pads need broad entries long enough for their attack to develop.
+- Unpitched textures demonstrate density, filtering and movement; changing a noise clock is not the same as transposing a harmonic note.
+
+Schedule such phrases with the native transport. Make looping an explicit application choice. See [sequences](api.md#playsequenceoptions) and [sound-design envelopes](sound-design.md#envelope-and-total-duration).
+
+## 2. Independent finite sound effects
+
+A sound effect often communicates a specific action: launch, impact, warning, confirmation. Its original pitch is part of that action. A rising missile and a descending shot can share the same square-wave timbre while conveying different movement.
+
+```javascript
+function fireMissile() {
+  return synth.playTone({ frequency: 196, frequencyEnd: 523,
+    duration: 350, waveType: WAVE.SQUARE,
+    attack: 2, decay: 0, sustain: 1, release: 50,
+    volume: 0.15, bus: 'effects' })
+}
+```
+
+This event completes natively. Repeated independent calls can overlap naturally. Their frequencies and endpoints remain those of the recipe; they are not implicitly transposed to the key being touched.
+
+A keyboard adapter that keeps only the square wave and envelope, starts at C7, and omits `frequencyEnd` will sound very different. Neither result establishes an engine fault: the adapter has selected a different pitch, duration model and motion. An effect audition should execute the whole recipe. Label a separately offered playable adaptation clearly.
+
+Use `playChord` when its contract exactly represents the intended chord. It applies its own chord compensation. Independent layers authored with distinct levels, envelopes or waves are not automatically equivalent to one chord call. Preserve those layers without normalizing them again or flattening them into one source.
+
+## 3. Complete sound sequences and layered effects
+
+Some effects need multiple ordered attacks. Others combine simultaneous body, noise and high-frequency detail, each with a different envelope. A sustained key containing only the first layer cannot reproduce the complete event.
+
+This native sequence defines a missile with 300 ms of pitch motion followed by 50 ms of release. It is a sequence interpretation, not a sample-equivalent conversion of the timed example above:
+
+```javascript
+function missileSequence() {
+  return synth.playSequence({ timeUnit: 'ms', loop: false,
+    voice: { waveType: WAVE.SQUARE, attack: 2,
+      decay: 0, sustain: 1, release: 50, volume: 0.15,
+      bus: 'effects' },
+    steps: [{ frequencies: [196], duration: 350, length: 300,
+      overrides: { frequencyEnd: 523 } }] })
+}
+```
+
+`duration` on a sequence step is the interval until the next attack. `length` is how long that note runs before release starts. Both use the sequence's time unit; attack, decay and release remain milliseconds. A note can extend beyond its step and overlap later attacks. In a timed `playTone` call, `duration` includes release. These values cannot be copied interchangeably without accounting for release.
+
+Timed and sequence routes are not automatically interchangeable. In the current native implementation, a `playTone` endpoint sweep progresses across the total timed duration, including release. A sequence endpoint sweep progresses across its explicit `length`, then holds the endpoint during release. Thus the timed 350 ms example and the sequence with `length: 300` do not have the same pitch trajectory, even though both finish after 350 ms and use the same endpoints. Sequence voices also use the held envelope's minimum 3 ms attack/release edges; very short or zero timed edges can differ. This matters most for short weapon/noise effects and is not corrected by merely copying the option names.
+
+For consistent manual and repeated auditions, use the same native interpretation for both. Preserve the original attack length when changing only the repetition interval; each new attack may overlap the prior voice. Do not claim exact timed-to-sequence fidelity from field equality or validator acceptance. Use API 1.1.0 `repeatTone({ intervalMs, ... })` to repeat the original finite-tone renderer directly. A JavaScript adapter that simply renames `duration` to `length` does not preserve that rendering contract.
+
+For a sequence-owned burst, `stopSequence` also releases emitted voices. To stop repetitions while preserving those attacks, publish a finite traversal with `loop: false`, retain its current effect steps and suppress later variant attacks as appropriate. Natural completion leaves emitted voices to their own lengths/releases. Retain the first attack in an update that can arrive before the initial callback. Handle publication rejection explicitly, with bounded control retries if necessary; those retries must not trigger notes or queue new sound requests.
+
+Use complete step dictionaries and their required overrides. Do not identify variants by guessing from silence, remove an intentional gap, round source frequencies to MIDI integers, discard a sweep, or merge independent layers solely because they begin together. A source importer should carry explicit interpretation, variant boundaries and demo association alongside the recipe.
+
+### Repeated firing uses the native clock
+
+For effects whose complete recipe consists of finite tone calls, pass each original recipe to `repeatTone` with `intervalMs`. Retain every returned tone ID for independent layers. Compound ordered patterns and chords keep their existing sequence/chord interpretation.
+
+```javascript
+function repeatShortShots(intervalMs) {
+  return synth.repeatTone({ frequency: 1380, frequencyEnd: 340,
+    duration: 105, waveType: WAVE.SQUARE, attack: 2,
+    decay: 0, sustain: 1, release: 40, volume: 0.1,
+    bus: 'effects', intervalMs: intervalMs })
+}
+var shotId = repeatShortShots(150)
+if (!shotId) throw new Error('Repeating shot rejected')
+// Keep the next attack deadline; use the new interval after it.
+synth.updateTone({ toneId: shotId, intervalMs: 120 })
+// Current 105 ms attacks finish; future attacks are cancelled.
+synth.stopTone({ toneId: shotId })
+```
+
+Validate the integer interval against the native 1-60,000 ms limits and the application's overlap budget. This recipe retains the 105 ms timed attack, including its 40 ms release; shortening only the interval can overlap voices. The first attack starts at the first render opportunity. The native sample clock preserves fractional samples and is independent of tempo. This native repetition needs no JavaScript attack timer. Independent calls remain supported for gameplay events or an explicitly scheduled finite burst; `playTone` always returns Boolean acceptance. See [the standalone burst example](api.md#finite-tone-repetition).
+
+Each layer consumes one of 32 repetition slots, independently of the four sequence slots. Each admitted attack still consumes shared voice capacity. Preserve headroom for old attacks after edits and for other owners. Rejected attacks are skipped without catch-up or variation consumption. Releasing a momentary pad, disabling fixed repetition, switching presets, backgrounding and owner close should call `stopTone` for all owned IDs. Stop remains publishable with a full ordinary queue; it cancels at the next block, including before the first attack. Global `stopAll` and shutdown also invalidate those IDs and pending edits.
+
+`updateTone` merges changes with the last accepted recipe and validates it as a whole. It changes the next scheduled attack without advancing it. `note` and `frequency` replace each other. A supplied variation dictionary replaces the previous one, and `{ amount: 0 }` disables future variation. Each repetition advances its reproducible native stream only for admitted attacks; parameter edits retain its counter, while changing seed restarts the succession. Sounding attacks keep their original recipe. See [the complete repetition contract](api.md#finite-tone-repetition).
+
+Native sequences remain appropriate for complete ordered scores. Keep every positive sequence ID and wait for matching `sequenceend` retirement when replacing a sequence. `stopSequence` releases that sequence's emitted voices, whereas `stopTone` lets admitted finite attacks finish. Application recipe functions remain ordinary JavaScript; there is no built-in named-recipe registry. Published 1.0.2 packages do not provide finite-tone repetition or variation.
+
+## 4. Polyphony, gain and output protection
+
+Both musical notes and effects share the voice pool and output chain. Either can distort when too many contributions sum at high gain, when filters resonate strongly, when tails overlap, or when creative saturation is enabled. A successful effect in one game does not certify arbitrary held chords, denser firing, different processing, or a device's physical speaker volume.
+
+- `maxVoices` is a capacity, not a loudness control. Reserve for simultaneous attacks and release tails, including future overlap in a repeating score.
+- `maxSequences` limits independent native tracks. Do not silently drop a layer to fit the limit.
+- Check native acceptance. A positive sequence ID acknowledges publication; it does not prove every future note will find enough voices.
+- Native admission can replace eligible voices under pressure. If the product promises no stealing, the application must reserve capacity across all of its sound owners and reject excess work visibly.
+- Do not apply chord normalization to an already authored set of independent layers unless that gain change is intended.
+- Keep headroom at voice, processor input and master stages. Preserve source gains when importing a known recipe; changing the overlap pattern still needs new validation.
+- Creative `saturation` intentionally changes timbre. Final output limiting protects peaks but is not proof that the earlier mix is clean.
+
+Use `getStats` to inspect active/tail voices, pending commands, rejected publications, priority drops and voice steals. Enable diagnostics for `preLimiterPeakDb`, `maxLimiterReductionDb`, output peaks and callback load. See [gain staging](sound-design.md#chords-polyphony-and-gain), [processing](api.md#setmasterprocessingoptions), [statistics](stats-performance.md), and [troubleshooting](troubleshooting.md). Host measurements and successful validation do not replace listening on the target speaker/headphones at the intended overlap and physical volume.
+
+## Verify the route you actually ship
+
+First compare an effect against its original complete recipe, including timing and levels. Separately test its playable adaptation, if offered. For instruments, test single keys, simultaneous keys, slides, Hold, release tails and finite demos. For effects, test rapid taps, native bursts, explicit variants, layered sounds, cancellation and exhausted capacity. Distinguish publication acceptance, rendered output, physical responsiveness and listening results in the report.

package/skills/ti-synthengine/references/native-tone-repetition-validation.md

@@ -0,0 +1,59 @@
+> Source snapshot: official TiSynthEngine documentation at commit `ec04f4e634075c41b55f66279eabcd78b9652d58` (2026-11-02). Published module 1.1.0; public API 1.1.0. Upstream `documentation/native-tone-repetition-validation.md` SHA-256: `b29758b5ec3b50650c4e30e8c408cb9bc680cad3fc158e543c3f6eec00c268a1`.
+
+# Native tone repetition validation: November 2, 2026
+
+The local Android/iOS 1.1.0 candidates announce API 1.1.0. `playTone(recipe)` retains Boolean acceptance for one finite attack, including independent successive JavaScript calls. `repeatTone(recipe)` requires `intervalMs` inside that single dictionary and returns a positive tone ID or numeric zero. `updateTone` and `stopTone` manage future attacks; admitted voices finish their original lifetimes. The [API reference](api.md#repeattoneoptions) describes the contract.
+
+## Native checks
+
+The shared fixed-capacity scheduler was tested for fractional sample remainders, variable render blocks, update deadlines, independent stops and slot reuse. A serialized control producer and an audio consumer exercised 2,000 start/stop cycles and 40,000 revisions under ThreadSanitizer without reported races.
+
+Android production-render hosts cover finite attack PCM parity for all six waveforms and four mixing profiles, controlled noise, spatial onset boundaries, tempo independence, 32 simultaneous repetitions beside four sequences, overlap, partial revisions and variation streams. iOS production-render tests cover all six shapes in stereo/spatial routes, fractional 44.1-frame intervals, deadlines, overlap, capacity, queued stops, revision snapshots and aliases. Existing Apple render fixtures cover 120 rate/scenario combinations. The variation contract corpus passes 156 cases per platform.
+
+Focused regressions reproduce and verify corrections for global-stop ordering (a later accepted repetition survives an earlier stop), immutable accepted nested dictionaries/arrays on iOS, and standalone JavaScript attacks remaining unrestricted. Unknown/stopped IDs, invalid intervals, missing required intervals, source validation, queue saturation and the separate note/stat method aliases are covered.
+
+Relevant commands:
+
+```sh
+clang -std=c11 -O2 tests/tone_core_regression.c -lm -o /tmp/synth-tone-core
+/tmp/synth-tone-core
+clang++ -std=c++17 -O1 -g -fsanitize=thread -pthread tests/tone_concurrency_regression.cpp -o /tmp/synth-tone-tsan
+/tmp/synth-tone-tsan
+python3 tests/run_native_hosts.py tone_engine variation_engine spatial_engine engine_render
+python3 tests/run_stats_java.py
+python3 tools/build_ios_render_host.py --output /tmp/ios-tones --driver tests/ios_tone_repetition.m
+/tmp/ios-tones
+python3 tests/run_sequence_events_ios.py
+python3 tests/run_variation_contracts.py
+node tests/api_contract_regression.js
+node tests/documentation_regression.js
+node --test tests/example_app_regression.js
+```
+
+The runnable example passes ten regressions, including native repetition ownership, edits and teardown. Public linkage checks cover 25 methods. TypeScript declarations pass strict checking and positive/negative contract examples.
+
+## Preallocated memory and host cost
+
+| Platform | Repetition transport storage | Benchmark                                        |
+| -------- | ---------------------------: | ------------------------------------------------ |
+| Android  |                617,744 bytes | 500 callbacks × 256 frames at 48 kHz; thread CPU |
+| iOS      |                620,048 bytes | 1,000 callbacks × 256 frames at 48 kHz; host CPU |
+
+The storage includes 32 slots with three plain-recipe banks each; it is allocated before audio callbacks. The scheduler does not allocate, lock or execute JavaScript in the callback.
+
+| Synthetic workload     | Android callback/deadline | iOS callback/deadline |
+| ---------------------- | ------------------------: | --------------------: |
+| One stereo repetition  |                    0.571% |                 1.01% |
+| 32 stereo repetitions  |                    6.683% |                 3.19% |
+| One spatial repetition |                    2.065% |                 1.40% |
+| 32 spatial repetitions |                   36.840% |                14.95% |
+
+The host workloads use separate configurations. Their results do not rank platform performance, measure physical-device CPU or guarantee real-time behavior. See `tests/tone_benchmark_host.cpp` and `tests/ios_tone_benchmark.m` for their recipes and measurement methods. Existing sequence/voice/effect storage is additional to the transport figures.
+
+## Packaging and consumer integration
+
+Both native module builds pass. Candidates remain package version 1.1.0. Documentation packaging checks ZIP CRC, examples, declaration source equality, links/anchors and unchanged native bytes during the documentation refresh. Studio receives the rebuilt AAR and all three Apple XCFramework variants; binary hashes are checked against their source ZIPs. Official 1.0.2 packages are retained.
+
+Studio uses native repetition for complete finite-tone plans, including parallel layers, while existing chords, compound scores and sustained motors keep their playback. It reserves overlaps and prior recipe tails after edits. Focused regressions cover cancellation, partial publication failure, variation disable and changed-layer capacity accounting. Native attack timing is covered by render hosts; UI gestures and perceived sound remain separate checks.
+
+Raw logs, binary hashes, installation preference comparisons and host measurements are retained outside distribution packages in `Developer/validation-evidence/TiSynthEngine/native-tone-repetition-2026-11-02`. The records above describe checks completed before publication. Release verification records the source commit and final artifact hashes separately.