npm - @maccesar/titools - Versions diffs - 5.2.4 → 5.2.5 - Mend

@maccesar/titools 5.2.4 → 5.2.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (26) hide show

package/README.md CHANGED Viewed

@@ -172,7 +172,7 @@ The knowledge index is based on the latest Titanium SDK documentation. If your p
 | ti-ui            | UI/UX patterns                      | Complex layouts, ListViews, platform UI                                                                                                                                                                                                                                                              |
 | ti-game          | 2D games with the `ti.game` module  | Sprites, physics, tile maps, HUDs, camera, focused keyboard/mouse/gamepad actions, Apple Metal/Catalyst                                                                                                                                                                                              |
 | ti-game-assets   | Visual and sound assets             | Image generation/editing, synthesis variants, stereo placement, alpha cleanup, manifests, parallax and complete exports                                                                                                                                                                              |
-| ti-synthengine   | Sound design with `ti.synthengine`  | Tones, chords, retro/UI effects, alarms, sweeps, patterns, ADSR envelopes, resonant filters, FM, detune, binaural positioning, held voices, native sequences, master effects, voice LFOs, engine statistics, bounded attack variation, seeds, instrument/effect fidelity, mixing and troubleshooting |
+| ti-synthengine   | Sound design with `ti.synthengine`  | Tones, finite-tone repetition, chords, retro/UI effects, alarms, sweeps, ADSR, filters, FM, binaural positioning, held voices, native sequences, master effects, LFOs, statistics, bounded attack variation, seeds, TypeScript declarations, instrument/effect fidelity and troubleshooting |
 | ti-admob-unified | Advertising, privacy and mediation  | Official `ti.admob.unified` guides, copy-ready library, banners/fullscreen, UMP/ATT and selected-provider configuration                                                                                                                                                                              |
 | ti-api           | Complete Titanium API reference     | Looking up properties, methods, events                                                                                                                                                                                                                                                               |
 | ti-guides        | SDK fundamentals                    | tiapp.xml, Hyperloop, distribution, JDK/Xcode compatibility, release notes                                                                                                                                                                                                                           |
@@ -184,7 +184,7 @@ Notes:
 - The first eight (`ti-reuse-first`, `ti-expert`, `purgetss`, `ti-ui`, `ti-game`, `ti-game-assets`, `ti-synthengine`, `ti-admob-unified`) are specialist workflow skills reflecting TiTools' Titanium conventions and native-module contracts.
 - `ti-reuse-first` runs before the others. It asks whether a thing needs to exist and what already does it — a search order that stops at the first rung that holds — and sweeps an existing `app/` for near-identical controllers, single-listener events, wrappers around one call, and layout recomputed in JavaScript. It is deliberately two-sided: it says when adding a module or a Widget is the right answer, so the bias does not simply invert.
 - `ti-game` documents the `ti.game` native module (2D sprite engine using OpenGL ES 2.0 on Android and Metal on iPhone, iPad and Mac Catalyst). Its API reference was verified against the module source and records the reviewed upstream commit and fork documentation snapshot; it applies to Alloy and Classic projects alike and does not depend on PurgeTSS.
-- `ti-synthengine` translates sound requests into checked JavaScript for published Android/iOS `ti.synthengine` 1.0.2 and local 1.1.0 candidates (public API 1.0.0). Its nineteen-method contract covers timed/held voices, identified native sequences, global tempo, selective categories/sends, master effects, live spatial/noise/filter controls and diagnostics. Two curated recipe guides cover retro cues and interactive instruments. Complete official-source mirrors, validation reports, bundled examples and raw evidence retain provenance; verified corrections are applied to official source prose before mirroring. The reviewed source commit/worktree, platform differences and scoped listening/performance acceptance are explicit in source notes.
+- `ti-synthengine` translates sound requests into checked JavaScript for published Android/iOS `ti.synthengine` 1.1.0 / API 1.1.0, with compatibility guidance for 1.0.2 / API 1.0.0. Its 25-method surface includes finite-tone repetition, held voices, identified native sequences, tempo, categories/sends, master effects, live controls and diagnostics. Two curated recipe guides cover retro cues and interactive instruments. Official-source mirrors, validation reports, bundled examples, TypeScript declarations and raw evidence retain provenance; verified corrections are applied to official source prose before mirroring. Source notes distinguish reviewed source commits, published artifacts, platform differences and scoped listening/performance evidence.
 - `ti-game-assets` treats images and sounds as essential game assets. It coordinates integrated `image_gen` artwork with `ti-synthengine` sound design, variants and stereo placement, and ships Pillow helpers for conservative alpha cleanup and per-world visual/audio manifests.
 - The latter five are documentation-mirror skills, audited against official sources via the internal `titools-skill-auditor`. See [Where the references come from](#where-the-references-come-from).
 - `purgetss` reference files are audited against the official PurgeTSS documentation and against the package source (the CLI and the generated `utilities.tss`), but its workflow conventions are opinionated.
@@ -546,18 +546,18 @@ frequency and pause/audio/input ownership remain application policies.
 ### ti-synthengine
-Sound design and synthesis with the public native `ti.synthengine` 1.0.2 release (public API 1.0.0) for Android and iOS. Local 1.1.0 candidates add capability-gated native per-attack variation while keeping API 1.0.0; they have not been published as releases. Read the [skill entry point](skills/ti-synthengine/SKILL.md) for task routing, exact API references and current source provenance.
+Sound design and synthesis with the public native `ti.synthengine` 1.1.0 release (public API 1.1.0) for Android and iOS. It adds `repeatTone`, `updateTone`, `stopTone`, `updateNote`, `enableStats` and `disableStats`, plus capability-gated native attack variation. Published 1.0.2 / API 1.0.0 remains documented for compatibility; it does not support repetition or variation. Read the [skill entry point](skills/ti-synthengine/SKILL.md) for task routing, exact API references and source provenance.
 Public repository: [macCesar/TiSynthEngine](https://github.com/macCesar/TiSynthEngine).
-Download [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),
+Download [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),
 copy the ZIPs into the Titanium app root and follow the [installation guide](skills/ti-synthengine/references/guide.md).
 Requires Titanium SDK 13.2.0.GA+, Android compile API35+, and iOS 15+; the Apple package also supports Mac Catalyst.
 When it activates:
 - `tiapp.xml` declares `ti.synthengine`, or code calls `require('ti.synthengine')`
 - Generated UI/game cues, instruments, alarms, chords, percussion, sweeps or binaural headphone placement
-- Sustained voices, simultaneous native sequences, shared tempo, selective effects/sends, priorities or live voice controls
+- Finite-tone repetition and future-attack edits, held voices, simultaneous native sequences, shared tempo, selective effects/sends, priorities or live voice controls
 - Bounded native attack variation, deterministic seeds, complete effect playback or playable instrument adaptations
 - Rejected calls, startup glitches, voice/queue diagnostics, render-load measurements or source/artifact compatibility questions
@@ -569,7 +569,9 @@ Example prompts:
 "Run music and a victory cue as independent native sequences, then cancel only the cue."
 "Apply reverb to music while keeping UI dry, and change the global tempo."
 "Explain what the Android Sim80 headphone result proves about performance."
-"Vary repeated impacts natively on local 1.1.0 and retain a clean fallback on published 1.0.2."
+"Vary repeated impacts natively on public 1.1.0 and retain a clean fallback on published 1.0.2."
+"Repeat the original swept shot with repeatTone, edit its interval and stop future attacks without truncating sounding shots."
+"Use updateNote and enableStats/disableStats, and check this recipe against the bundled TypeScript declarations."
 ```
 Key rules:
@@ -577,15 +579,18 @@ Key rules:
 - Preserve complete effects and layer gains when adapting or repeating them; read [instruments and effects](skills/ti-synthengine/references/instruments-and-effects.md)
 - Read constants and exact ranges from the API; strict option dictionaries reject invalid fields or conflicting pitch sources
 - Timed tone/chord `duration` includes release. Native sequence intervals and note lengths are separate; held voices release through their IDs
-- Schedule successive sounds with `playSequence`, retain positive accepted IDs and cancel the owner's sequence. `stopAll()` is global panic
+- Use `repeatTone` for the original finite-tone renderer and `playSequence` for ordered scores; retain each accepted ID. `stopTone` preserves admitted finite attacks, while `stopSequence` releases its emitted voices. `stopAll()` is global panic
+- Native repetition requires its capability and methods, integer `intervalMs` 1–60,000, and capacity for overlaps. Its 32 slots are independent of sequence capacity; all attacks share the voice pool
+- `updateTone` preserves the next deadline, validates merged recipes and changes future attacks. Independent gameplay calls and intentionally JavaScript-timed finite bursts remain supported; clear app-owned timers during teardown
+- Use `updateNote`, `enableStats` and `disableStats` in new 1.1.0 code. `updateVoice` and `setStatsEnabled(Boolean)` remain deprecated equivalent aliases; feature-detect the aliases when supporting 1.0.2
 - `setTempo` drives beat-based transport and synchronized modulation; millisecond sequences keep fixed timing
 - `bus`/`applyTo` select processed categories; explicit `effectSend` overrides that selection. One shared chain and final limiter remain global
 - Held spatial position, noise clock and one-pole cutoff support compatible 10 ms updates. A stereo voice cannot become spatial through an update
 - Omit both spatial coordinates for stereo; zero coordinates enable binaural center. Do not combine binaural coordinates with stereo pan fields
-- Start after layout, keep one lifecycle owner, handle Boolean acceptance and sequence IDs, release held notes on cancellation and shut down during teardown
+- Start after layout, keep one lifecycle owner, handle Boolean acceptance and tone/sequence IDs, release held notes and owned repetitions on cancellation, and shut down during teardown
 - Current platform metadata, zero-envelope and diagnostic differences are documented. Host checks and a short accepted listening scene do not establish complete physical maximum-load acceptance
-The [retro recipes](skills/ti-synthengine/references/recipes.md) and [interaction/instrument recipes](skills/ti-synthengine/references/recipes-interaction.md) preserve acoustic intent, overlap budgets and cleanup. [Source notes](skills/ti-synthengine/references/source-notes.md) identify the reviewed native commit and evidence limits.
+The [retro recipes](skills/ti-synthengine/references/recipes.md) and [interaction/instrument recipes](skills/ti-synthengine/references/recipes-interaction.md) preserve acoustic intent, overlap budgets and cleanup. The [official declarations](skills/ti-synthengine/assets/index.d.ts) provide TypeScript signatures alongside the runtime API. [Repetition validation](skills/ti-synthengine/references/native-tone-repetition-validation.md) separates native checks, transport storage and bounded host measurements from device/listening acceptance. [Source notes](skills/ti-synthengine/references/source-notes.md) identify the reviewed native commit and evidence limits.
 ---
@@ -898,7 +903,7 @@ This pattern is documented across four bundled TiTools skills: `ti-ui`, `ti-expe
 | ti-game          | Native 2D Game Workflow       | 12 files (API, input, source notes, setup, physics, patterns, recipes, tile maps, debugging, roadmap)                                                                                                |
 | ti-game-assets   | Visual and Sound Assets       | 10 guides and a manifest example; alpha and contract validation scripts                                                                                                                              |
 | ti-admob-unified | Unified Advertising           | 20 Markdown references including production, rewarded interstitial, mediation parity, integration library guidance, provenance and game monetization; source/hash checks and official example assets |
-| ti-synthengine   | Native Sound Synthesis        | 17 Markdown references (14 official parts, 2 curated recipe guides, maintenance notes), complete validation reports/evidence and a reversible source hash manifest                                   |
+| ti-synthengine   | Native Sound Synthesis        | 18 Markdown references (15 official parts, 2 curated recipe guides, maintenance notes), official TypeScript declarations, complete validation reports/evidence and a reversible source hash manifest                                   |
 | ti-api           | Titanium API                  | 20 references for core/platform APIs and native modules                                                                                                                                              |
 | ti-guides        | SDK Fundamentals              | 16 references for setup, configuration, CLI and distribution                                                                                                                                         |
 | ti-howtos        | Native Integrations           | 18 references for platform features and integration workflows                                                                                                                                        |

package/docs/examples.md CHANGED Viewed

@@ -37,14 +37,19 @@ an audio or advertising module.
 ## Native synthesis — ti-synthengine
-- "Install the public TiSynthEngine 1.0.2 Android/iOS packages and start audio after the window layout settles."
+- "Install the public TiSynthEngine 1.1.0 Android/iOS packages and start audio after the window layout settles."
 - "Move a held spatial motor, process only music with reverb, and stop one native sequence without cancelling unrelated sounds."
-- "Use native attack variation with local 1.1.0: bounded noise/filter ranges, deterministic seeds and an old-package fallback."
+- "Use native attack variation with public 1.1.0: bounded noise/filter ranges, deterministic seeds and an old-package fallback."
 - "Repeat this complete layered effect natively without changing its envelope, sweep timing or gains."
+- "Use repeatTone for this finite shot, edit its interval with updateTone, and stop future attacks with stopTone while sounding shots finish."
+- "Use updateNote and enableStats/disableStats, checking the bundled TypeScript declarations and a 1.0.2 alias fallback."
+- "Keep these three standalone playTone calls as an intentional finite JavaScript burst and cancel their timers when the owner closes."
 Use the [synthesis skill](../skills/ti-synthengine/SKILL.md) for exact options,
-public downloads and scoped performance evidence. Native sequence scheduling,
-held-voice ownership and historical/private artifacts have distinct contracts.
+public downloads, bundled TypeScript declarations and scoped performance evidence.
+Native finite-tone repetitions, ordered sequences, held voices and standalone
+JavaScript events have distinct ownership and timing contracts. Public 1.0.2 /
+API 1.0.0 lacks repetition and variation; detect support before enabling them.
 ## Advertising — ti-admob-unified

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@maccesar/titools",
-  "version": "5.2.4",
+  "version": "5.2.5",
   "description": "Titanium SDK skills and agents for AI coding assistants, including native game and sound synthesis modules",
   "main": "lib/index.js",
   "type": "module",

package/skills/ti-synthengine/SKILL.md CHANGED Viewed

@@ -1,27 +1,30 @@
 ---
 name: ti-synthengine
-description: "Use when a Titanium app declares ti.synthengine in tiapp.xml, imports require('ti.synthengine'), or needs generated tones, chords, native sequences, sustained game motors, ADSR, sweeps, FM, resonant filters, noise, binaural spatialX/spatialY, held noteOn/noteOff/updateVoice, shared tempo, selective music/effects/ui/ambience processing, effectSend, priorities, chorus/delay/reverb/saturation, LFOs, sequenceend events, gain staging, statistics, bounded native per-attack variation, seeds or render-load diagnosis. Covers published Android/iOS 1.0.2 and local 1.1.0 candidates with public API 1.0.0. Not for audio-file decoding, sample streaming or unrelated synthesizers."
+description: "Use when a Titanium app declares ti.synthengine in tiapp.xml, imports require('ti.synthengine'), or needs generated tones, chords, repeatTone/updateTone/stopTone, native sequences, held noteOn/noteOff/updateNote, ADSR, sweeps, FM, resonant filters, noise, binaural spatialX/spatialY, shared tempo, selective music/effects/ui/ambience processing, effectSend, priorities, chorus/delay/reverb/saturation, LFOs, sequenceend events, gain staging, statistics with enableStats/disableStats, bounded native per-attack variation, seeds, TypeScript declarations or render-load diagnosis. Not for audio-file decoding, sample streaming or unrelated synthesizers."
 ---
 # ti.synthengine — native sound synthesis for Titanium
 Act as an audio engineer and mobile sound designer. Translate the requested sound into acoustically reasoned JavaScript using the exact public contract.
-These references cover **published module 1.0.2 and local 1.1.0 candidates**,
-both with public API 1.0.0. They mirror the corrected official documentation
-at commit `b07c97c762be5905f132cecf33e9d60ea0c21316` (reviewed 2026-11-02).
-Native attack variation requires the local 1.1.0 packages; it is unavailable in
-the public 1.0.2 downloads. Read the [variation guide](references/native-variation.md)
-for both platform declarations, rebuilding and feature detection.
-Download matching [Android](https://github.com/macCesar/TiSynthEngine/releases/tag/android-1.0.2)
-and [iOS](https://github.com/macCesar/TiSynthEngine/releases/tag/ios-1.0.2)
+These references cover **published Android/iOS module 1.1.0 with public API
+1.1.0**, retaining compatibility guidance for published 1.0.2 / API 1.0.0.
+Version 1.1.0 adds native finite-tone repetition, attack variation and the
+recommended held-note/statistics method names. Version 1.0.2 supports the older
+core methods and aliases but lacks repetition and rejects variation options.
+Download matching [Android](https://github.com/macCesar/TiSynthEngine/releases/tag/android-1.1.0)
+and [iOS](https://github.com/macCesar/TiSynthEngine/releases/tag/ios-1.1.0)
 packages from the public [repository](https://github.com/macCesar/TiSynthEngine).
-Source/mirror hashes are in [source-snapshot.json](references/source-snapshot.json);
-artifact checksums and native findings are in [source notes](references/source-notes.md).
-The current [interactive example](assets/example/README.md) includes both helpers.
-Earlier private packages also used version 1.0.0: require current methods and
-install the official platform ZIPs rather than inferring capabilities from that
-version string or adding a second JavaScript audio scheduler.
+Read the [guide](references/guide.md) for both platform declarations, rebuilding
+and installation; check the actual methods and feature metadata your app needs.
+The reviewed source commit/state, reversible source/mirror hashes and release
+artifact checksums are recorded in [source-snapshot.json](references/source-snapshot.json)
+and [source notes](references/source-notes.md).
+The current [interactive example](assets/example/README.md) includes both helpers
+and native repetition controls. The bundled [TypeScript declarations](assets/index.d.ts)
+mirror the official module types; read them with the API rather than substituting
+type-checking for runtime acceptance. Earlier development packages reused API
+version strings, so version checks alone do not establish every capability.
 ## Required workflow
@@ -32,7 +35,10 @@ Read the relevant references before writing or reviewing code. When updating the
 | Any public method, option, default, return value or limit | [API](references/api.md) |
 | Download public releases, install, initialize, own or clean up an engine | [Guide](references/guide.md) |
 | Design an effect, instrument, reward, alarm or game motor | [Sound design](references/sound-design.md), [recipes](references/recipes.md), [examples](references/examples.md) |
-| Complete effect playback, playable adaptations, native repetition, importing layers and audition fidelity | [Instruments and effects](references/instruments-and-effects.md) |
+| Complete effect playback, playable adaptations, importing layers and audition fidelity | [Instruments and effects](references/instruments-and-effects.md) |
+| Repeat an original finite tone, edit its next attacks or cancel while sounding attacks finish | [Repetition API](references/api.md#finite-tone-repetition), [instruments and effects](references/instruments-and-effects.md#repeated-firing-uses-the-native-clock) |
+| Repetition test coverage, transport memory and scoped host measurements | [Repetition verification](references/native-tone-repetition-validation.md) |
+| TypeScript signatures, option dictionaries and return types | [Official declarations](assets/index.d.ts), [API](references/api.md) |
 | Native per-attack variation, ranges, amount, seeds, chords, held starts and loop/revision behavior | [Variation](references/native-variation.md), [API](references/api.md) |
 | Variation memory/callback measurements, package scope and listening follow-up | [Variation verification](references/native-variation-validation.md) |
 | Historical variation design, feasibility and deferred API questions | [Historical proposal](references/native-variation-proposal.md); current behavior comes from the implemented guide |
@@ -64,13 +70,16 @@ if (!synth.start({maxVoices: 32, maxSequences: 4,
 }
 ```
-Both local 1.1.0 platforms announce `capabilities.variation === true` and `variationSchemaVersion === 1`; require both before sending `variation`, even for amount zero. Published 1.0.2 does not accept that key. Android also announces native-sequence/processing/modulation flags and `limits.stepDurationMs`; iOS implements those operations without those Android-only metadata entries. Both return the sequence-capacity, priority and send limits. [source: references/api.md] [source: references/native-variation.md]
+Both 1.1.0 platforms announce `capabilities.variation === true` and `variationSchemaVersion === 1`; require both before sending `variation`, even for amount zero. Published 1.0.2 does not accept that key. Android also announces native-sequence/processing/modulation flags and `limits.stepDurationMs`; iOS implements those operations without those Android-only metadata entries. Both return the sequence-capacity, priority and send limits. [source: references/api.md] [source: references/native-variation.md]
+Use `updateNote` for held-note edits and `enableStats()` / `disableStats()` for diagnostics in new 1.1.0 code. `updateVoice` and `setStatsEnabled(Boolean)` remain deprecated equivalent aliases, without repeated warnings or a scheduled removal date. For 1.0.2 compatibility, detect and use its aliases; detect repetition and variation separately before enabling those features. [source: references/api.md]
 Choose the actual required sequence capacity, 1–4; the snippet's four slots suit games with simultaneous music, effects and cues. One engine and render callback share up to 32 voices. Start after screen layout settles; the owning service/window shuts down on teardown. On iOS, `ambient` respects silent mode and mixes with other apps; `playback` is the default and ignores silent mode. Profile, voice/sequence capacity and session require shutdown before changing them. [source: references/api.md]
 ## Scheduling contract
-- `playTone` is one timed event, `playChord` one simultaneous atomic chord, and `noteOn`/`noteOff`/`updateVoice` own sustained voices. `playSequence` is the only successive-sound scheduler. Do not add aliases or JavaScript note timers.
+- `playTone` plays one finite event and returns Boolean acceptance; it rejects `intervalMs`. `playChord` plays one simultaneous atomic chord. Use `repeatTone` for ongoing native repetition of the original finite-tone recipe, `playSequence` for ordered scores, and `noteOn`/`noteOff`/`updateNote` for interaction-owned held voices.
+- Independent gameplay calls and intentionally JavaScript-timed finite bursts remain supported. Keep their Boolean `playTone` returns and cancel app-owned timers on teardown. Native repetition and sequences own their ongoing sample-clock attacks; UI polling does not drive them.
 - `playSequence(options)` returns a positive identifier or `0`. `updateSequence({sequenceId,...changes})`, `stopSequence({sequenceId})` and `setTempo({bpm})` return Boolean acceptance. `getSequenceState({sequenceId})` returns applied revision/position or `null` for unknown/retired IDs. Acceptance can precede callback application.
 - Sequence IDs do not repeat over module lifetime, including shutdown/start. Keep the accepted ID and cancel only the owner's sequence. An accepted stop does not immediately free capacity: coalesce replacement requests and publish the latest complete score after its matching `sequenceend`. A delayed event for an old ID must not change the new owner.
 - `setTempo({bpm})` accepts 20–300, initially 120. It changes on the next block while conserving musical position. Synced delays/LFOs follow this tempo; free controls keep milliseconds/hertz.
@@ -82,11 +91,21 @@ Choose the actual required sequence capacity, 1–4; the snippet's four slots su
 Preserve migrated score timing deliberately: a former total envelope of 150 ms with 25 ms release becomes `length:125` in a millisecond sequence, with `release:25`. Keep onset intervals separate. [source: references/api.md]
+## Native finite-tone repetition
+Require a present `contract.capabilities` map with `toneRepetition === true` and the presence of `repeatTone`, `updateTone` and `stopTone` before enabling native repetition. Published 1.0.2 lacks it. Keep an existing independent-event path or disable the unavailable control; converting a timed recipe to sequence length/sweeps changes its rendering interpretation. [source: references/api.md] [source: references/instruments-and-effects.md]
+`repeatTone({intervalMs,...recipe})` requires an integer interval of 1–60,000 ms and returns a positive `toneId` or numeric `0`. It preserves the finite-tone envelope, endpoint sweeps, gain, routes and optional variation. The first attack starts at the first render opportunity; later deadlines preserve fractional samples across blocks and ignore tempo changes. There are 32 repetition slots independent of the 1–4 sequence slots, sharing the configured pool of at most 32 voices. Reserve capacity for overlaps, prior attacks after edits and other owners; publication does not guarantee admission of every future attack.
+`updateTone({toneId,...changes})` requires a live ID and at least one change. It merges with the last accepted recipe and validates the complete result; `note` and `frequency` replace one another, while supplying both rejects the edit. Invalid edits retain the accepted recipe. Edits affect the next scheduled attack without moving its deadline; the new interval controls the following gap. Sounding attacks retain their original configuration. A supplied variation dictionary replaces the previous dictionary; `{amount:0}` disables future variation. The native stream/counter survives edits unless the seed identity changes. Dropped attacks consume no variation selection and produce no catch-up work.
+`stopTone({toneId})` returns Boolean acceptance and cancels future attacks at the next block, including before the first attack. Already admitted finite voices finish their original lifetimes. Stop remains publishable when the ordinary command queue is full. Unknown/retired IDs reject edits and stops; IDs never repeat during module lifetime, including shutdown/start. There is no `toneend` event. Retain each layer's ID and cancel it on release, cancellation, preset change, pause and owner close. Global `stopAll`, shutdown and destruction invalidate repetitions and pending edits. [source: references/api.md] [source: references/native-variation.md]
 ## Native attack variation
 Variation samples compatible bounded parameters once per admitted attack, preserving authored envelopes, cadence, routes and voice counts. Read all eight source-dependent bounds before constructing ranges. Amount interpolates linearly from the authored value; pitch uses cents. Keep application gain consistent in authored volume and volume-range endpoints.
-An explicit seed repeats standalone selections; native loops advance their stream across attacks. Chords sample independently by voice ordinal. Sustained voices retain their selection through release; `updateVoice` rejects `variation`. Step dictionaries replace the whole inherited dictionary. Sequence revisions affect future attacks; root omission retains variation, and disabling inherited and explicit-step variation requires appropriate amount-zero replacements. Never add a JavaScript random sampler or note timer. Seeds reproduce parameters, not cross-platform noise PCM. [source: references/native-variation.md]
+An explicit seed repeats standalone selections; native loops advance their stream across attacks. Chords sample independently by voice ordinal. Sustained voices retain their selection through release; `updateNote` rejects `variation`. Step dictionaries replace the whole inherited dictionary. Sequence revisions affect future attacks; root omission retains variation, and disabling inherited and explicit-step variation requires appropriate amount-zero replacements. Use the native sampler for this variation dictionary. Seeds reproduce parameters, not cross-platform noise PCM. [source: references/native-variation.md]
 ## Voices, routes and continuous controls
@@ -94,13 +113,13 @@ An explicit seed repeats standalone selections; native loops advance their strea
 Sustained IDs are positive app-owned integers. Release on key up, touch cancellation, pause and teardown. Handle rejected release by retrying twice at 16 ms, then shut down/report if it still fails. These retry timers are lifecycle/error recovery, not a musical clock. Ended/stolen IDs accept edits as no-ops. [source: references/api.md]
-Compatible `updateVoice` fields include frequency, volume, vibrato, resonant filter targets, pulse width, FM, modulations, `noiseRate`, `lowPassHz`, stereo/spatial position and `effectSend`. Transitions take 10 ms and preserve phase, spatial history and the current envelope. `noiseRate:0` is white noise; `lowPassHz:0` bypasses its one-pole filter. Spatial updates require a voice started spatially; stereo `pan` applies to a stereo voice. Do not combine spatial coordinates with stereo pan fields. [source: references/api.md]
+Compatible `updateNote` fields include frequency, volume, vibrato, resonant filter targets, pulse width, FM, modulations, `noiseRate`, `lowPassHz`, stereo/spatial position and `effectSend`. Transitions take 10 ms and preserve phase, spatial history and the current envelope. `noiseRate:0` is white noise; `lowPassHz:0` bypasses its one-pole filter. Spatial updates require a voice started spatially; stereo `pan` applies to a stereo voice. Do not combine spatial coordinates with stereo pan fields. [source: references/api.md]
 `priority:0…3`, initially 0, controls eligible replacement under the shared voice pool. Higher priorities remain protected. Chords are admitted or discarded completely; there are no reserved per-category quotas. Gain is fixed per event, with initial chord compensation. Starting unrelated voices does not normalize earlier voices. [source: references/api.md]
 Module 1.0.2 retains zero samples at final output: stereo-linked peak protection acts immediately, recovers exponentially with a 100 ms time constant and uses ceilings of 0.85, or 0.70 for `speakerSafe`. These are sample ceilings, not speaker or inter-sample guarantees; overload changes waveform shape. Master volume uses an independent linear 10 ms ramp on both platforms. iOS now applies the documented `raw` gain, so review existing raw mixes when upgrading. Native Android and Apple callback checks run in CI; device latency, listening and extended maximum-load acceptance remain separate. [source: references/audio-pipeline-validation.md]
-`stopAll()` stops every native sequence, cancels future attacks, fades voices and invalidates effect histories. Use `stopSequence({sequenceId})` for one owner’s sequence. Android closes the engine on root activity destruction; explicit owner teardown remains required. Idle event polling stops when no control work remains and does not schedule musical attacks. [source: references/api.md] [source: references/guide.md] [source: references/audio-engine.md]
+`stopAll()` stops every native sequence and finite-tone repetition, cancels future attacks, fades voices and invalidates effect histories. Use `stopSequence({sequenceId})` for one owner’s sequence or `stopTone({toneId})` for its finite repetition. Android closes the engine on root activity destruction; explicit owner teardown remains required. Idle event polling stops when no control work remains and does not schedule musical attacks. [source: references/api.md] [source: references/guide.md] [source: references/audio-engine.md]
 ## Sound and validation rules
@@ -114,8 +133,8 @@ Module 1.0.2 retains zero samples at final output: stereo-linked peak protection
 Binaural coordinates span a headphone front plane. Omit both spatial keys to bypass; two zeros still enable binaural center. Map app percentages explicitly and preserve pitch/envelope recipes. Height perception depends on the listener and sound spectrum; output remains stereo without rear sources, room reflections or head tracking. [source: references/api.md]
-Timed zero attack/release and rejection diagnostics currently differ between native platforms. Check API acceptance directly; do not infer sample-identical envelopes or a complete rejection tally from validator parity. Read [source notes](references/source-notes.md) for independently rechecked findings. [source: references/api.md]
+Timed zero attack/release and rejection diagnostics currently differ between native platforms. Submit exact integer repetition intervals: Apple currently tolerates and truncates extremely near-integer values that Android rejects; see the documented [native interval edge](references/source-notes.md#known-native-interval-edge). Check API acceptance directly; do not infer sample-identical envelopes or a complete rejection tally from validator parity. Read [source notes](references/source-notes.md) for independently rechecked findings. [source: references/api.md]
-Diagnostics are opt-in. Preserve unavailable/null readings; poll UI slowly and clean up its timer. Render load is callback work divided by deadline, not app CPU. Historical host reports, validator parity and hash equality do not establish current physical real-time or listening acceptance. Keep technical results and César's auditory acceptance separate. [source: references/audio-engine.md] [source: references/source-notes.md]
+Diagnostics are opt-in through `enableStats()` / `disableStats()`. Preserve unavailable/null readings; poll UI slowly and clean up its timer. Render load is callback work divided by deadline, not app CPU. Historical host reports, validator parity and hash equality do not establish current physical real-time or listening acceptance. Keep technical results and César's auditory acceptance separate. [source: references/audio-engine.md] [source: references/source-notes.md]
 Use `ti-game` for native movement/physics and `ti-game-assets` for related visual/audio asset production. Audio scheduling remains in TiSynthEngine; do not change gameplay or install on physical devices without the task's authorization.

package/skills/ti-synthengine/assets/example/README.md CHANGED Viewed

@@ -1,28 +1,28 @@
-> 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 `example/README.md` SHA-256: `7906f208b287d31ac400f407f4f3509b7a12041274a4629ab287eea235954518`.
+> Source snapshot: official TiSynthEngine documentation at commit `ec04f4e634075c41b55f66279eabcd78b9652d58` (2026-11-02). Published module 1.1.0; public API 1.1.0. Upstream `example/README.md` SHA-256: `e191a701a3a913c85b15503fd256e0aec085eb731a587b1bf4faa43865c81982`.
 # Interactive example
-The Classic Titanium app in [app.js](app.js) demonstrates the timed sounds, native sequences and statistics with the `sequenceend` event on Android and iOS. It runs with the published 1.0.2 module packages, including binaural and statistics support, or the unpublished local 1.1.0 candidates for native attack variation. Held voices, master processing and voice LFOs have copyable examples in the [advanced documentation](../../references/advanced-examples.md#sustained-game-motor); this reference app does not expose those newer controls. The default engine configuration is 16 voices, `conservative` mixing and the `playback` session; master volume starts at 100% and optional diagnostics start off.
+The Classic Titanium app in [app.js](app.js) demonstrates the timed sounds, native sequences and statistics with the `sequenceend` event on Android and iOS. It requires module version 1.1.0 and public API 1.1.0 for native finite-tone repetition, attack variation and the recommended note/statistics methods. Held voices, master processing and voice LFOs have copyable examples in the [advanced documentation](../../references/advanced-examples.md#sustained-game-motor); this reference app does not expose those newer controls. The default engine configuration is 16 voices, `conservative` mixing and the `playback` session; master volume starts at 100% and optional diagnostics start off.
 ## Run it
 1. Create a Classic Titanium application with Android and/or iOS support. If the app uses Alloy, create a separate Classic test project and leave the Alloy-generated files in place.
-2. Download the official [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) packages, or build the current module source. Source builds now produce local `android/dist/ti.synthengine-android-1.1.0.zip` and `ios/dist/ti.synthengine-iphone-1.1.0.zip` candidates; select version `1.1.0` in both module entries when using them.
-3. Put the archive for each target platform in the test app root. For the published packages, add these entries inside its `tiapp.xml`:
+2. Download the official [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) packages, or build the current module source. Source builds produce `android/dist/ti.synthengine-android-1.1.0.zip` and `ios/dist/ti.synthengine-iphone-1.1.0.zip`; select version `1.1.0` in both module entries when using them.
+3. Put the archive for each target platform in the test app root. Add these entries inside its `tiapp.xml`:
 ```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>
 ```
-For the local candidates, replace both `version="1.0.2"` declarations above with `version="1.1.0"`. They still report public API `1.0.0`; detect variation through both capability/schema announcements. Rebuild and reinstall after switching packages.
+Both packages report public API `1.1.0`; detect variation through both capability/schema announcements. Rebuild and reinstall after switching packages.
 4. Copy the entire `example/` folder into the test app's `Resources/`, including [app.js](app.js), [sequenceScore.js](lib/sequenceScore.js) and [sequenceOwner.js](lib/sequenceOwner.js). It needs no images or audio files.
 5. Build and run the test app with the Titanium CLI or your existing Titanium launch configuration. Use Titanium SDK 13.2.0.GA or newer, Android compile API 35 or newer, and iOS 15 or newer. See the [module installation guide](../../references/guide.md#install-the-module).
-The example checks the installed API version, spatial limits and all three statistics methods before constructing the screen. If it requests current packages, replace the native module, then rebuild and reinstall the app; copying module files alone does not update an app already on a device.
+The example checks the installed API version, spatial limits and the recommended enable/disable statistics methods before constructing the screen. If it requests current packages, replace the native module, then rebuild and reinstall the app; copying module files alone does not update an app already on a device.
 Audio starts after the first layout settles. Sound controls report native rejections. If startup fails, the session buttons remain available to retry. Closing the window removes its sequence listener, clears startup/statistics timers, disables diagnostics and shuts down the engine. The example plays finite sounds in the foreground and does not demonstrate background audio. Turn diagnostics off before leaving it in the background.
@@ -88,4 +88,10 @@ The example regression executes its real action callbacks with simulated Titaniu
 ## Native attack variation
-The **ATTACK VARIATION** button submits the same metal-strike recipe on each press. With `capabilities.variation === true` and `variationSchemaVersion === 1`, the renderer chooses pitch, FM depth and level once per admitted attack. Older packages receive the original recipe without the dictionary. This button uses independent timed events; the [variation guide](../../references/native-variation.md) separately demonstrates sustained ownership and native sequence retriggers. Physical listening acceptance remains separate from host correctness checks.
+The ATTACK VARIATION button submits the same metal-strike recipe on each press. With `capabilities.variation === true` and `variationSchemaVersion === 1`, the renderer chooses pitch, FM depth and level once per admitted attack. Older packages receive the original recipe without the dictionary. This button uses independent timed events; the [variation guide](../../references/native-variation.md) separately demonstrates sustained ownership and native sequence retriggers. Physical listening acceptance remains separate from host correctness checks.
+## Native finite-tone repetition
+START REPEATING calls `repeatTone` once with a complete 105 ms square-wave shot and required `intervalMs: 200`. It retains the positive tone ID. EDIT REPEATING calls `updateTone` for that ID, keeping the next deadline and changing subsequent separation to 150 ms. STOP REPEATING calls `stopTone`, cancelling future attacks while admitted shots finish. Close, session changes and global Stop also release or invalidate ownership. There is no JavaScript attack timer for this demo.
+`playTone` remains a standalone Boolean operation and rejects `intervalMs`; `repeatTone` always returns a numeric ID or 0 and requires the interval. Independent JavaScript calls remain supported, including finite bursts scheduled by an application's own event clock. See [the full contract and standalone burst example](../../references/api.md#finite-tone-repetition).

package/skills/ti-synthengine/assets/example/app.js CHANGED Viewed

@@ -7,14 +7,15 @@ var sequenceOwner = require('lib/sequenceOwner')(Synth, {
 function publishSequence(options) { return sequenceOwner.submit(options) }
 var defaults = Synth.getDefaults()
-if (!defaults || defaults.apiVersion !== '1.0.0') {
-  throw new Error('TiSynthEngine 1.0.0 is required')
+if (!defaults || defaults.apiVersion !== '1.1.0') {
+  throw new Error('TiSynthEngine 1.1.0 is required')
 }
 if (!defaults.limits || !defaults.limits.spatialX || !defaults.limits.spatialY
   || typeof Synth.getStats !== 'function' || typeof Synth.resetStats !== 'function'
-  || typeof Synth.setStatsEnabled !== 'function') {
-  throw new Error('Install the current TiSynthEngine 1.0.0 packages, then rebuild and reinstall this app')
+  || typeof Synth.enableStats !== 'function' || typeof Synth.disableStats !== 'function'
+  || typeof Synth.repeatTone !== 'function' || typeof Synth.updateTone !== 'function' || typeof Synth.stopTone !== 'function') {
+  throw new Error('Install the current TiSynthEngine 1.1.0 packages, then rebuild and reinstall this app')
 }
 var WAVE = defaults.waveTypes
@@ -23,6 +24,7 @@ var engineRunning = false
 var startTimer = null
 var statsTimer = null
 var diagnosticsEnabled = false
+var repeatingToneId = 0
 var selectedSession = 'playback'
 var masterVolume = 1
 var binauralEnabled = true
@@ -200,7 +202,7 @@ function makeHero() {
     height: Ti.UI.SIZE,
     top: dp(16)
   })
-  badgeRow.add(makeBadge('API 1.0.0', COLORS.indigo))
+  badgeRow.add(makeBadge('API 1.1.0', COLORS.indigo))
   badgeRow.add(makeBadge('ANDROID + iOS', COLORS.surfaceMuted))
   hero.add(badgeRow)
   hero.add(statusPill)
@@ -399,6 +401,40 @@ waveNames.forEach(function (name, index) {
 waveSection.add(Ti.UI.createView({ height: dp(12) }))
 scrollView.add(waveSection)
+// A repeated finite recipe uses its native owner ID; there is no attack timer.
+function stopRepeatingTone() {
+  if (!repeatingToneId) return true
+  if (!Synth.stopTone({ toneId: repeatingToneId })) return false
+  repeatingToneId = 0
+  return true
+}
+var repeatSection = makeSection('Finite-tone repetition',
+  'The same complete 105 ms shot repeats every 200 ms. Edit its future attacks; stop lets current shots finish.',
+  COLORS.teal)
+repeatSection.add(makeAction({
+  title: 'START REPEATING', color: COLORS.teal, pressedColor: COLORS.tealPressed,
+  onPress: function () {
+    if (repeatingToneId) return true
+    var id = Synth.repeatTone({ frequency: 1380, frequencyEnd: 340,
+      duration: 105, attack: 2, release: 40, waveType: WAVE.SQUARE,
+      volume: 0.1, intervalMs: 200 })
+    if (!Number.isInteger(id) || id <= 0) return false
+    repeatingToneId = id
+    return true
+  }
+}))
+repeatSection.add(makeAction({
+  title: 'EDIT REPEATING', color: COLORS.teal, pressedColor: COLORS.tealPressed,
+  onPress: function () {
+    return !!repeatingToneId && Synth.updateTone({ toneId: repeatingToneId, intervalMs: 150, volume: 0.08 })
+  }
+}))
+repeatSection.add(makeAction({
+  title: 'STOP REPEATING', color: COLORS.surfaceMuted, pressedColor: COLORS.surfaceRaised,
+  onPress: stopRepeatingTone
+}))
+scrollView.add(repeatSection)
 // ---------------------------------------------------------------------------
 // 2. Note names
 // ---------------------------------------------------------------------------
@@ -999,7 +1035,7 @@ var sessionLabel = makeText('Session: playback', { left: dp(16), right: dp(16),
     color: COLORS.blueDark, pressedColor: COLORS.blue,
     accessibilityHint: 'Restarts the engine with this session policy',
     onPress: function () {
-      sequenceOwner.reset(); Synth.shutdown()
+      repeatingToneId = 0; sequenceOwner.reset(); Synth.shutdown()
       engineRunning = false
       selectedSession = session
       patternEndLabel.text = 'sequenceend: cancelled by shutdown (no event)'
@@ -1046,7 +1082,7 @@ statsSection.add(makeAction({
   title: 'TOGGLE DIAGNOSTICS', color: COLORS.orange, pressedColor: COLORS.orangePressed,
   accessibilityHint: 'Enables or disables timing and signal measurements',
   onPress: function () {
-    if (!Synth.setStatsEnabled(!diagnosticsEnabled)) return false
+    if (!(diagnosticsEnabled ? Synth.disableStats() : Synth.enableStats())) return false
     diagnosticsEnabled = !diagnosticsEnabled
     stopStatsPolling()
     if (diagnosticsEnabled) statsTimer = setInterval(refreshStats, 200)
@@ -1103,10 +1139,10 @@ boostRow.add(makeGridAction({
   title: 'STOP ALL\nRelease active voices',
   color: COLORS.redDark,
   pressedColor: COLORS.red,
-  status: 'Active voices fading; pending pattern steps remain',
-  accessibilityHint: 'Fades current voices without cancelling future pattern steps',
+  status: 'Future attacks cancelled; active voices fading',
+  accessibilityHint: 'Cancels future attacks and fades current voices',
   onPress: function () {
-    sequenceOwner.stop(); Synth.stopAll()
+    repeatingToneId = 0; sequenceOwner.stop(); Synth.stopAll()
   }
 }))
 controlSection.add(boostRow)
@@ -1170,8 +1206,9 @@ function hideAndroidActionBar() {
 }
 function cleanup() {
+  if (!stopRepeatingTone()) Ti.API.warn('Repeating tone stop rejected; shutting down owner')
   stopStatsPolling()
-  Synth.setStatsEnabled(false)
+  Synth.disableStats()
   diagnosticsEnabled = false
   Synth.removeEventListener('sequenceend', onSequenceEnd)
   win.removeEventListener('postlayout', onFirstPostLayout)
@@ -1184,7 +1221,7 @@ function cleanup() {
     startTimer = null
   }
   if (engineRunning) {
-    sequenceOwner.reset(); Synth.shutdown()
+    repeatingToneId = 0; sequenceOwner.reset(); Synth.shutdown()
     engineRunning = false
   }
 }

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

@@ -0,0 +1,106 @@
+/** TiSynthEngine local 1.1.0 candidate, public API 1.1.0. */
+declare namespace synth {
+  type Bus = 'music' | 'effects' | 'ui' | 'ambience';
+  type FilterType = 'none' | 'lowpass' | 'highpass' | 'bandpass';
+  type Range = [number, number];
+  interface Variation {
+    amount?: number;
+    seed?: number;
+    ranges?: Partial<Record<'volume' | 'filterHz' | 'filterQ' | 'fmDepth' |
+      'noiseRate' | 'lowPassHz' | 'pulseWidth' | 'pitchCents', Range>>;
+  }
+  interface VoiceOptions {
+    attack?: number; decay?: number; sustain?: number; release?: number;
+    volume?: number; waveType?: number; pan?: number;
+    lfoFreq?: number; lfoDepth?: number; noiseRate?: number; lowPassHz?: number;
+    pulseWidth?: number; waveTable?: number[]; bitDepth?: number;
+    filterType?: FilterType; filterHz?: number; filterQ?: number;
+    fmRatio?: number; fmDepth?: number; spatialX?: number; spatialY?: number;
+    bus?: Bus; effectSend?: number; priority?: number; variation?: Variation;
+  }
+  type Pitch = { note?: string; frequency?: never } | { frequency?: number; note?: never };
+  interface FiniteOptions extends VoiceOptions {
+    duration?: number; panEnd?: number; frequencyEnd?: number;
+    noiseRateEnd?: number; pulseWidthEnd?: number; filterHzEnd?: number;
+    fmDepthEnd?: number; detune?: number;
+  }
+  type ToneOptions = FiniteOptions & Pitch;
+  type RepeatingToneOptions = ToneOptions & { intervalMs: number };
+  /** Partial changes merge with the latest accepted recipe; never retriggers immediately. */
+  type ToneUpdate = Partial<FiniteOptions> & Pitch & { toneId: number; intervalMs?: number };
+  interface Modulation {
+    target: 'filterHz' | 'pulseWidth' | 'fmDepth';
+    wave?: 'sine' | 'triangle'; rate?: number; sync?: string; depth?: number;
+  }
+  type NoteOptions = VoiceOptions & Pitch & { voiceId: number; detune?: number; modulations?: Modulation[] };
+  type NoteUpdate = Pick<VoiceOptions, 'volume' | 'pan' | 'lfoFreq' | 'lfoDepth' |
+    'noiseRate' | 'lowPassHz' | 'pulseWidth' | 'filterHz' | 'filterQ' |
+    'fmRatio' | 'fmDepth' | 'spatialX' | 'spatialY' | 'effectSend'> & Pitch &
+    { voiceId: number; modulations?: Modulation[] };
+  type ChordOptions = VoiceOptions & { duration?: number; detune?: number;
+    detunes?: number[]; pans?: number[]; panSpread?: number } &
+    ({ notes: string[]; frequencies?: never } | { frequencies: number[]; notes?: never });
+  interface StartOptions {
+    maxVoices?: number; maxSequences?: number;
+    mixingProfile?: 'conservative' | 'raw' | 'balanced' | 'speakerSafe';
+    audioSession?: 'playback' | 'ambient';
+  }
+  interface Defaults {
+    apiVersion: '1.1.0';
+    capabilities: { variation: true; toneRepetition: true; [key: string]: boolean };
+    variationSchemaVersion: 1;
+    limits: Record<string, { min: number; max: number }>;
+    defaults: Record<string, unknown>;
+    waveTypes: Record<'SINE' | 'SQUARE' | 'SAWTOOTH' | 'TRIANGLE' | 'NOISE' | 'WAVETABLE', number>;
+    mixingProfiles: string[]; audioSessions: string[]; buses: Bus[]; filterTypes: FilterType[];
+  }
+  interface SequenceVoice extends Omit<FiniteOptions, 'duration' | 'detune'> { modulations?: Modulation[] }
+  type SequenceStep = { duration?: number; length?: number; gate?: number;
+    overrides?: SequenceVoice; bus?: Bus; effectSend?: number; priority?: number } &
+    ({ notes: number[]; frequencies?: never; rest?: never } |
+    { frequencies: number[]; notes?: never; rest?: never } |
+    { rest: true; notes?: never; frequencies?: never });
+  interface SequenceOptions {
+    timeUnit?: 'beats' | 'ms'; stepDuration?: number; gate?: number; loop?: boolean;
+    swing?: number; mode?: 'normal' | 'up' | 'down' | 'updown'; tuning?: number;
+    detune?: number; voice?: SequenceVoice; steps: SequenceStep[];
+    bus?: Bus; effectSend?: number; priority?: number;
+  }
+  interface SequenceState {
+    sequenceId: number; playing: boolean; step: number; beat: number;
+    position: number; bpm: number; revision: number;
+  }
+  function getDefaults(): Defaults;
+  function start(options?: StartOptions): boolean;
+  /** One finite attack. intervalMs is rejected; use repeatTone for repetition. */
+  function playTone(options: ToneOptions & { intervalMs?: never }): boolean;
+  /** Integer 1-60000 ms: positive module-owned ID, or 0 on rejection. */
+  function repeatTone(options: RepeatingToneOptions): number;
+  function updateTone(options: ToneUpdate): boolean;
+  /** Cancels future attacks at the next block; admitted attacks finish. */
+  function stopTone(options: { toneId: number }): boolean;
+  function playChord(options: ChordOptions): boolean;
+  function noteOn(options: NoteOptions): boolean;
+  function updateNote(options: NoteUpdate): boolean;
+  /** @deprecated Use updateNote; identical behavior and voiceId contract. */
+  function updateVoice(options: NoteUpdate): boolean;
+  function noteOff(options: { voiceId: number }): boolean;
+  function playSequence(options: SequenceOptions): number;
+  function updateSequence(options: Partial<Omit<SequenceOptions, 'timeUnit'>> & { sequenceId: number }): boolean;
+  function stopSequence(options: { sequenceId: number }): boolean;
+  function getSequenceState(options: { sequenceId: number }): SequenceState | null;
+  function setTempo(options: { bpm: number }): boolean;
+  function setVolume(options: { volume: number }): boolean;
+  function setMasterProcessing(options: Record<string, unknown>): boolean;
+  function enableStats(): boolean;
+  function disableStats(): boolean;
+  /** @deprecated Use enableStats or disableStats; identical diagnostic behavior. */
+  function setStatsEnabled(enabled: boolean): boolean;
+  function getStats(): Record<string, number | boolean | string | null>;
+  function resetStats(): void;
+  function stopAll(): void;
+  function shutdown(): void;
+  function addEventListener(name: 'sequenceend', listener: (event: { sequenceId: number; reason: 'completed' | 'stopped' }) => void): void;
+  function removeEventListener(name: 'sequenceend', listener: (event: { sequenceId: number; reason: 'completed' | 'stopped' }) => void): void;
+}
+export = synth;