sendspin-js: expose a public SDK surface that conformance can use

[balloob]

Problem

The sendspin-js conformance adapter still depends on internal library modules instead of a supported public SDK surface.

SendspinPlayer is browser-oriented, while the conformance adapter runs headless in Node. Today that mismatch pushes the adapter toward private or internal wiring, which is exactly the pattern we want to avoid.

We already removed the bespoke artwork@v1 path from conformance, and sendspin-js now fails the artwork-role case explicitly. That is the correct behavior until the public SDK actually exposes that role.

Why this matters

Conformance should stay close to the real library API used by applications. If the public SDK cannot support a scenario headlessly, that should show up as a conformance limitation or failure rather than being hidden behind adapter-specific protocol code.

Scope

This should be limited to the smallest public surface needed to make conformance use the real SDK. If some roles remain unsupported, the matrix should keep reflecting that.

Tracking

• Decide which conformance scenarios sendspin-js is expected to support through its public SDK
• If headless support is intended, add the minimal public seams needed to drive the SDK without importing internal modules
• Update the conformance adapter to stop importing internal built modules directly
• Keep artwork@v1 failing until the public SDK really exposes that role
• Re-run the aiosendspin -> sendspin-js conformance slice and confirm the reported support matches the actual SDK surface

[balloob-travel]

Implementation plan

The key constraint for sendspin-js is that conformance must stop depending on internal modules. If the public SDK cannot support a scenario, that scenario should fail or remain unsupported rather than being recreated in the adapter.

Recommended plan:

1. Explicitly define the intended public conformance scope for SendspinPlayer.
   Decide which roles the public SDK is actually meant to support in a headless or testable environment:

   • player
   • metadata
   • controller
   • artwork only if the public SDK really intends to expose artwork@v1, not just metadata.artwork_url

2. Split environment glue from protocol behavior.
   If headless support is intended, add only the minimum public seams needed to let Node provide browser-like environment pieces without importing internal protocol modules. Likely seams are:

   • injectable transport interface instead of hard-wiring WebSocketManager
   • injectable or overridable audio backend abstraction instead of forcing direct AudioProcessor construction
   • optional environment hooks for timers / media session / document-owned audio element creation where needed

3. Add public observation hooks before changing conformance.
   The conformance adapter currently needs exact lifecycle visibility that onStateChange alone does not provide. If the library is meant to support these scenarios publicly, add a small supported hook surface for:

   • connection established / disconnected
   • server/hello seen
   • stream/start seen for negotiated player streams
   • binary audio frame receipt if PCM/encoded verification is meant to be part of the supported public test surface
   • binary artwork frames only if artwork@v1 is intended to be publicly supported

4. Keep artwork@v1 separate from metadata artwork URL support.
   The demo already shows album art through metadata.artwork_url. That is not the same as the protocol artwork role. Do not mark artwork@v1 supported in conformance unless the public SDK can really act as an artwork-role client.

5. Migrate the adapter in stages.
   A safe sequence would be:

   • first, use public SDK support for metadata/controller scenarios if that can be done with minimal environment glue
   • then, only if intended, add the missing public seams for headless player verification
   • leave unsupported roles explicitly failing until their public SDK surface exists

6. Add headless-focused library tests.
   The library should have tests that prove the new public seams work without browser DOM assumptions. That matters because conformance is running in Node, and we do not want the adapter to paper over browser-only assumptions with more custom code.

7. Only then remove internal imports from conformance.
   The adapter should stop importing built internals like protocol/transport classes directly once the public surface is sufficient.

Non-goals:

• building a giant fake browser runtime in conformance
• reproducing protocol logic in the adapter
• claiming artwork@v1 support just because the demo can render artwork_url
• adding broad new player features that are not needed to make the real SDK testable

[balloob]

Sendspin/sendspin-js#82 implements improvements for this ticket.

[balloob]

Quick status update after #53 landed.

What works now via the public SDK

The Node adapter drives SendspinCore directly over an adapter-owned WebSocket (registry for client-initiated, WebSocketServer for server-initiated) and verifies via onStateChange / onAudioData / onStreamStart. Passes server-initiated metadata and controller against aiosendspin.

Scenarios still not possible in Node via the public SDK

• artwork@v1: the SDK does not advertise the role (hardcoded supported_roles: ["player@v1", "controller@v1", "metadata@v1"] in ProtocolHandler.sendClientHello) and has no public surface for artwork binary frames. Kept as an unsupported role family on the adapter.
• FLAC scenarios: SendspinDecoder.decodeFLAC requires OfflineAudioContext, which is browser-only. Kept as supports_flac=false.
• OPUS scenarios: SendspinDecoder uses the WebCodecs AudioDecoder (falls back to opus-encdec with wasm that still expects a browser context). Kept as supports_opus=false.
• PCM hash parity against resampling servers: getSupportedFormats is hardcoded to {48000, 44100} × stereo × 16-bit. The conformance fixture is 8 kHz mono, so servers that resample to satisfy the client's advertised formats (like aiosendspin) end up sending bytes that don't match the pre-resample source_pcm_sha256. Adapters like sendspin-rs work around this by advertising 8 kHz mono; sendspin-js has no config knob to do the same. PCM scenarios against aiosendspin fail for this reason; against non-resampling servers they should pass.

Bespoke bits still in the adapter — candidates to remove next

These are small but each one is a public-surface hint for sendspin-js:

1. No server/hello observer. The adapter attaches a raw addEventListener('message', …) to the socket before core.connect() just to capture peer_hello. A typed hook (onServerHello(payload) or a generic inbound-message observer) would let us delete that listener.
2. onStateChange can't call back into the instance. SendspinCore fires onStateChange synchronously from constructor-adjacent merges, so the closure sees core as undefined. The adapter uses a coreRef holder to break the cycle. Passing core (or a bound this) into the callback would remove it.
3. Per-channel samples with no canonical helper. The adapter interleaves DecodedAudioChunk.samples (per-channel Float32Array[]) to produce the harness's canonical hash layout. This is the same gap [SDK gap] No shared canonical PCM / conformance helper — every language reimplements the same hash #40 called out across SDKs — a canonicalPcmBytes(chunk) / canonicalSamples(chunk) helper on SendspinCore or SendspinDecoder would retire the interleaver in every language adapter.
4. Dist is only consumable through a bundler. The published dist/ uses bundler-style extensionless relative imports (TS moduleResolution: "bundler"). Node can't load it directly; the adapter ships an ESM resolver hook (sdk-loader.mjs) that appends .js. Either emitting explicit extensions (moduleResolution: "node16" / "nodenext") or providing a pre-bundled entry point would let consumers import it without a shim.
5. No config-level control over supported_formats. Related to the PCM-resampling issue above — the adapter can't express "advertise the fixture's native 8 kHz mono" because codecs: ["pcm"] is the only knob. A supportedFormats?: SupportedFormat[] override on SendspinCoreConfig would close that gap.

Happy to file (1)–(5) as discrete issues on sendspin-js if useful.

---

Generated by Claude Code