{"_id":"cuelume","_rev":"5-1ab7fcc0956515d6615eea3c216a2134","name":"cuelume","dist-tags":{"latest":"0.2.2"},"versions":{"0.1.0":{"name":"cuelume","version":"0.1.0","keywords":["web-audio","sound","ui-sounds","sound-effects","interaction-feedback","interface-sounds","hover","click","synthesis"],"author":{"name":"Daniel Belyi"},"license":"MIT","_id":"cuelume@0.1.0","maintainers":[{"name":"danielwh2","email":"danielwh.work@gmail.com"}],"homepage":"https://github.com/Danilaa1/cuelume#readme","bugs":{"url":"https://github.com/Danilaa1/cuelume/issues"},"dist":{"shasum":"a6768ea7655098c908550d0468b75e478bf6a75e","tarball":"https://registry.npmjs.org/cuelume/-/cuelume-0.1.0.tgz","fileCount":11,"integrity":"sha512-J2RRt92Gh1a0ztnjwLEyLfGnDIiWz14vC9aTmg7ZgxRkEk8vR+QxFOz+v1tqntFvl06n5G4si8QCQgHfWjnneA==","signatures":[{"sig":"MEYCIQCUPRU9FU4jX0SD6fct67XlHPUcBSykmztwOAxouQodrwIhAK3tis0sMFJgo7vU00AldejkKEJhdnhnPjaDifeJLVO8","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":32922},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"gitHead":"261fc63f0bc3de0aa4bc9ed917b93b783d1c50f4","scripts":{"test":"npm run build && node --test","build":"npm run clean && tsc","clean":"node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"","prepack":"npm run build"},"_npmUser":{"name":"danielwh2","email":"danielwh.work@gmail.com"},"repository":{"url":"git+https://github.com/Danilaa1/cuelume.git","type":"git"},"_npmVersion":"11.9.0","description":"Curated interaction sounds for the web — synthesized live with zero runtime dependencies.","directories":{},"sideEffects":false,"_nodeVersion":"24.14.0","_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.6.0"},"_npmOperationalInternal":{"tmp":"tmp/cuelume_0.1.0_1783721647868_0.3926664057290967","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"cuelume","version":"0.1.1","keywords":["web-audio","sound","ui-sounds","sound-effects","interaction-feedback","interface-sounds","hover","click","synthesis"],"author":{"name":"Daniel Belyi"},"license":"MIT","_id":"cuelume@0.1.1","maintainers":[{"name":"danielwh2","email":"danielwh.work@gmail.com"}],"homepage":"https://github.com/Danilaa1/cuelume#readme","bugs":{"url":"https://github.com/Danilaa1/cuelume/issues"},"dist":{"shasum":"5c12efb19916036f16a47cc48f7343e542793e7d","tarball":"https://registry.npmjs.org/cuelume/-/cuelume-0.1.1.tgz","fileCount":11,"integrity":"sha512-dVi7mBte6NhYrv08vYAsj/P/CkeTGYs1jfJ4DlEpQJAbeOXy/bD4Gqj5St1m+HyPGxqIfMCuH9fkJa7/e0ry1g==","signatures":[{"sig":"MEQCID22G1z0vERJjy2Qi0aQEndsaFloXuxFfxQ3qDvb06yOAiBWpo5ETGqyw0WkmveAuxv3pftC9PQ7qhaA6JtePCmKcg==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":32988},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"gitHead":"7acae61dad2704ceb6df5507f614355e2fb1dee6","scripts":{"test":"npm run build && node --test","build":"npm run clean && tsc","clean":"node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"","prepack":"npm run build"},"_npmUser":{"name":"danielwh2","email":"danielwh.work@gmail.com"},"repository":{"url":"git+https://github.com/Danilaa1/cuelume.git","type":"git"},"_npmVersion":"11.9.0","description":"Curated interaction sounds for the web — synthesized live with zero runtime dependencies.","directories":{},"sideEffects":false,"_nodeVersion":"24.14.0","_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.6.0"},"_npmOperationalInternal":{"tmp":"tmp/cuelume_0.1.1_1784061331896_0.3638930205142359","host":"s3://npm-registry-packages-npm-production"}},"0.1.2":{"name":"cuelume","version":"0.1.2","keywords":["web-audio","sound","ui-sounds","sound-effects","interaction-feedback","interface-sounds","hover","click","synthesis"],"author":{"name":"Daniel Belyi"},"license":"MIT","_id":"cuelume@0.1.2","maintainers":[{"name":"danielwh2","email":"danielwh.work@gmail.com"}],"homepage":"https://github.com/Danilaa1/cuelume#readme","bugs":{"url":"https://github.com/Danilaa1/cuelume/issues"},"dist":{"shasum":"b06c3c0f7a2dfed1dc210c7652c44bef67390096","tarball":"https://registry.npmjs.org/cuelume/-/cuelume-0.1.2.tgz","fileCount":11,"integrity":"sha512-VxL0k9l1fyKGot3VKM+wm5Xd2K75fVeBHdNTrR1EHiqKRtD6S5Dxy/vY7hwl9gXp3QT/TIywFXUos77n39YZVQ==","signatures":[{"sig":"MEUCIBnNMQI/RLSzLWc0F1osky6UOew0qKZb40ahmaUNrBfYAiEA6ff+oUiMMgSQqj0xR7BUZXSv6B6Pz8FGn1/DhroBPAw=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":39699},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"gitHead":"ce81ececf18b4ee6cd195404546dfbab31b279fe","scripts":{"test":"npm run build && node --test","build":"npm run clean && tsc","clean":"node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"","prepack":"npm run build"},"_npmUser":{"name":"danielwh2","email":"danielwh.work@gmail.com"},"repository":{"url":"git+https://github.com/Danilaa1/cuelume.git","type":"git"},"_npmVersion":"11.9.0","description":"Curated interaction sounds for the web — synthesized live with zero runtime dependencies.","directories":{},"sideEffects":false,"_nodeVersion":"24.14.0","_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.6.0"},"_npmOperationalInternal":{"tmp":"tmp/cuelume_0.1.2_1784138150105_0.06258027440538783","host":"s3://npm-registry-packages-npm-production"}},"0.2.1":{"name":"cuelume","version":"0.2.1","keywords":["web-audio","sound","ui-sounds","sound-effects","interaction-feedback","interface-sounds","hover","click","synthesis"],"author":{"name":"Daniel Belyi"},"license":"MIT","_id":"cuelume@0.2.1","maintainers":[{"name":"danielwh2","email":"danielwh.work@gmail.com"}],"homepage":"https://github.com/Danilaa1/cuelume#readme","bugs":{"url":"https://github.com/Danilaa1/cuelume/issues"},"dist":{"shasum":"ad4a08668a6925fcb769ba865149f92b0e0d8262","tarball":"https://registry.npmjs.org/cuelume/-/cuelume-0.2.1.tgz","fileCount":11,"integrity":"sha512-UFN5GtPRhnkL55r5rz7oalgy72XTtV50QqOec3+wHer0O1hlwOteej99dlRxeFX2ViLUD/CpCu47v5XCTa2tEQ==","signatures":[{"sig":"MEQCIDr4YGVapyqqIZuV5BkJlCEsV2rEqBpWDAaOQuLNMPetAiBcpbTTA8qt60GyyLJh5p1Hj++WQgjoSZETlrHyoVUQfQ==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":41554},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"gitHead":"eca7bb489dfe542b267e754e30277c3c2891e16c","scripts":{"test":"npm run build && node --test","build":"npm run clean && tsc","clean":"node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"","prepack":"npm run build"},"_npmUser":{"name":"danielwh2","email":"danielwh.work@gmail.com"},"repository":{"url":"git+https://github.com/Danilaa1/cuelume.git","type":"git"},"_npmVersion":"11.9.0","description":"Curated interaction sounds for the web — synthesized live with zero runtime dependencies.","directories":{},"sideEffects":false,"_nodeVersion":"24.14.0","_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.6.0"},"_npmOperationalInternal":{"tmp":"tmp/cuelume_0.2.1_1785241447246_0.5679726433540067","host":"s3://npm-registry-packages-npm-production"}},"0.2.2":{"name":"cuelume","version":"0.2.2","description":"Curated interaction sounds for the web — synthesized live with zero runtime dependencies.","keywords":["web-audio","sound","ui-sounds","sound-effects","interaction-feedback","interface-sounds","hover","click","synthesis"],"license":"MIT","author":{"name":"Daniel Belyi"},"repository":{"type":"git","url":"git+https://github.com/Danilaa1/cuelume.git"},"bugs":{"url":"https://github.com/Danilaa1/cuelume/issues"},"type":"module","sideEffects":false,"main":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"scripts":{"clean":"node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"","build":"npm run clean && tsc","test":"npm run build && node --test","prepack":"npm run build"},"devDependencies":{"typescript":"^5.6.0"},"gitHead":"b879b72c01f3b3fa74c45c9b20bbd064baffb282","_id":"cuelume@0.2.2","homepage":"https://github.com/Danilaa1/cuelume#readme","_nodeVersion":"24.14.0","_npmVersion":"11.9.0","dist":{"integrity":"sha512-TiNzJRjhddjC4jy4M7sv63V/86VaFhdIs6iHUCrc4CKhqypaxRBv1aedCBGebrz/cO7nroPkEfqHe/P7fOE2GQ==","shasum":"0c97fdbf4e05a1fdb0d523ab5fca76cb421889f8","tarball":"https://registry.npmjs.org/cuelume/-/cuelume-0.2.2.tgz","fileCount":11,"unpackedSize":47845,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIBHy+aRht6X6qoPoG5Cyr0uxbtpADMjWpplBC+GLgTz8AiBPJChnxko50dk9L+tAdHbwaMlHxPtMQzoj9uCnfKv7NQ=="}]},"_npmUser":{"name":"danielwh2","email":"danielwh.work@gmail.com"},"directories":{},"maintainers":[{"name":"danielwh2","email":"danielwh.work@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/cuelume_0.2.2_1785844499049_0.4140642504946095"},"_hasShrinkwrap":false}},"time":{"created":"2026-07-10T22:14:07.796Z","modified":"2026-08-04T11:54:59.393Z","0.1.0":"2026-07-10T22:14:08.017Z","0.1.1":"2026-07-14T20:35:32.029Z","0.1.2":"2026-07-15T17:55:50.257Z","0.2.1":"2026-07-28T12:24:07.389Z","0.2.2":"2026-08-04T11:54:59.214Z"},"bugs":{"url":"https://github.com/Danilaa1/cuelume/issues"},"author":{"name":"Daniel Belyi"},"license":"MIT","homepage":"https://github.com/Danilaa1/cuelume#readme","keywords":["web-audio","sound","ui-sounds","sound-effects","interaction-feedback","interface-sounds","hover","click","synthesis"],"repository":{"type":"git","url":"git+https://github.com/Danilaa1/cuelume.git"},"description":"Curated interaction sounds for the web — synthesized live with zero runtime dependencies.","maintainers":[{"name":"danielwh2","email":"danielwh.work@gmail.com"}],"readme":"# Cuelume\n\nSeventeen carefully designed interaction sounds for the web. Synthesized live with Web Audio, with no audio files and zero runtime dependencies.\n\nCuelume is a curated sound palette, not an audio engine. It gives buttons, links, toggles, and completed actions clear feedback without asking developers to design sounds themselves. Add an attribute, call `bind()`, done.\n\n## Install\n\n```sh\nnpm install cuelume\n```\n\n## Requirements\n\nCuelume is ESM-only. Use it through native `import` or an ESM-compatible bundler; CommonJS `require()` is not supported.\n\nIt targets modern browsers with ES modules and the Web Audio API. Server-side imports are safe, but sound playback only runs in the browser.\n\n## Quick start\n\nAdd data attributes to your markup:\n\n```html\n<button data-cuelume-press data-cuelume-release>Save</button>\n<a data-cuelume-hover=\"tick\">Docs</a>\n<button data-cuelume-toggle>Dark mode</button>\n<button data-cuelume-press=\"pulse\" data-cuelume-release=\"scan\">Launch</button>\n```\n\nThen wire everything up once:\n\n```ts\nimport { bind } from \"cuelume\";\n\nbind();\n```\n\n| Attribute              | Fires on       | Default sound |\n| ---------------------- | -------------- | ------------- |\n| `data-cuelume-hover`   | `pointerenter` | `chime`       |\n| `data-cuelume-press`   | `pointerdown`  | `press`       |\n| `data-cuelume-release` | `pointerup`    | `release`     |\n| `data-cuelume-toggle`  | `click`        | `toggle`      |\n\nLeave the attribute value empty to use the default, or set it to any sound name.\n\nPrefer code? Play sounds imperatively:\n\n```ts\nimport { play } from \"cuelume\";\n\nawait navigator.clipboard.writeText(text);\nplay(\"success\");\nplay(\"success\", { volume: 0.4 }); // quieter for this play only\n```\n\nNeed sound preferences? Your app owns the settings; Cuelume only applies them:\n\n```ts\nimport { setEnabled, setVolume } from \"cuelume\";\n\nsetVolume(0.7);    // global multiplier, clamped to 0–1\nsetEnabled(false); // future play attempts become no-ops\nsetEnabled(true);  // enable playback again\n```\n\nCuelume starts enabled at full volume and does not read or write storage.\n\n## Sounds\n\n| Name      | Character                    | Suggested use                    |\n| --------- | ---------------------------- | -------------------------------- |\n| `chime`   | Soft two-note ascending bell | Default hover                    |\n| `sparkle` | Quick four-note twinkle      | Playful accents                  |\n| `droplet` | Single note gliding down     | Dismiss, collapse                |\n| `bloom`   | Warm slow swell              | Reveal, expand                   |\n| `whisper` | Soft hush with a falling tone | Tooltips and quiet previews      |\n| `tick`    | Crisp instant tick           | Nav and menu hover               |\n| `press`   | Dull muted knock             | Pointer down                     |\n| `release` | Brighter springy tick        | Pointer up                       |\n| `toggle`  | Mechanical click-clack       | Switches, tabs                   |\n| `success` | Warm three-note confirmation | After an action succeeds (e.g. copy to clipboard) |\n| `error`   | Soft knock and descending refusal | Recoverable errors          |\n| `page`    | Papery flick with a glass tick | Pages, galleries, carousels    |\n| `loading` | Brief unresolved rising shimmer | User-initiated work starting  |\n| `ready`   | Rising lock-on with a clear resolve | Content or system ready     |\n| `pulse`   | Compact synthetic chirp         | Primary buttons and controls  |\n| `scan`    | Fast three-step locator signal  | Menus and secondary buttons   |\n| `arrival` | Rising harmonic portal          | Client-side page arrivals     |\n\n## API\n\n```ts\nimport { play, bind, setEnabled, setVolume, sounds, type SoundName } from \"cuelume\";\n```\n\n- **`play(name?: SoundName, options?: { volume?: number })`** — play a sound immediately. Defaults to `\"chime\"`; `options.volume` controls this play only.\n- **`bind(root?: ParentNode)`** — delegate all `data-cuelume-*` interactions under `root` (defaults to the whole document). Idempotent and handles elements added later.\n- **`setEnabled(enabled: boolean)`** — enable or disable future playback. Does not persist the preference or stop sounds already playing.\n- **`setVolume(volume: number)`** — set the global volume for future playback, clamped to `0–1`. Non-finite values are ignored and preferences are not persisted.\n- **`sounds`** — the list of all sound names.\n- **`SoundName`** — union type of the seventeen sound names.\n\n## Defaults that behave\n\n- **Pointer-aware.** Hover requires a fine mouse pointer. Press and release support mouse, touch, and pen; toggle follows native click activation, including keyboard.\n- **Hover repeat guard.** Hover sounds are globally throttled to one every 150ms, so sweeping across a menu stays quiet.\n- **Audible without clipping.** One shared boosted output stage keeps sounds clear, with native compression protecting overlapping cues.\n- **One lazy `AudioContext`.** Shared across all sounds, created on first use.\n- **Autoplay-friendly.** Attempts to resume suspended audio without surfacing errors when a browser blocks it.\n- **SSR-safe.** Importing on the server is a no-op.\n- **Safe fallback.** Invalid runtime names and unavailable or blocked Web Audio make `play()` a silent no-op.\n- **Dynamic, idempotent binding.** `bind()` never double-attaches listeners, and later DOM additions, removals, and clones work automatically.\n\n## Frameworks\n\nCuelume works anywhere HTML does — plain pages, Astro, React, Vue. Call `bind()` once after the DOM is ready. Delegated listeners keep working when components or routes replace descendants.\n\nReact:\n\n```tsx\nuseEffect(() => {\n  bind();\n}, []);\n```\n\nAstro (with view transitions):\n\n```js\nimport { bind, play } from \"cuelume\";\n\nbind();\ndocument.addEventListener(\"astro:page-load\", () => play(\"arrival\"));\n```\n\nBrowsers block audio on a fresh visit until the user interacts with the page. The arrival cue therefore plays on client-side navigations after that first interaction.\n\n## License\n\nMIT\n","readmeFilename":"README.md"}