WRNexusJS/AUDIO-PLAYBACK-FIX.md

WRNexusJS CAPTCHA audio playback fix

This patch fixes audio CAPTCHA playback in production and bundled server builds.

Root cause

AssetAudioRenderer originally located WAV files only from import.meta.url. After WRNexusJS bundles the server into dist/server.js, that URL points to the app build folder instead of packages/captcha, so /api/captcha/audio/... fails while trying to read the WAV clips.

Changes

• Resolves audio assets from the installed @wrnexus/captcha/audio package entry.
• Supports WRNEXUS_CAPTCHA_AUDIO_DIR for custom deployments.
• Searches workspace and node_modules layouts as safe fallbacks.
• Keeps the browser Audio instance alive while it plays.
• Stops old audio when a new challenge is loaded.
• Returns a clear HTTP 503 and server log if audio rendering fails.
• Adds a real WAV rendering test.

Apply

Extract this ZIP into the WRNexusJS repository root and replace the included files. Then run:

bun run typecheck
bun test packages/captcha
bun run --cwd examples/captcha-showcase check

Restart the server. If running the production build, rebuild first:

bun run --cwd examples/captcha-showcase build
bun examples/captcha-showcase/dist/server.js

Verify

1. Open the browser Network panel.
2. Click Listen.
3. The /api/captcha/audio/<id>?key=... request must return HTTP 200.
4. Its content-type must be audio/wav.

For a nonstandard package layout, set an absolute path before starting the server:

$env:WRNEXUS_CAPTCHA_AUDIO_DIR="E:\WireJS\packages\captcha\assets\audio"