[chrisuthe]

Add SendspinClientConfig::application_roles so an application can list its own _-prefixed, versioned roles in client/hello supported_roles, after the library's roles. A role can also carry a support object, which is sent as "<role>_support" (messaging.md "client/hello", README.md "Application-Specific Roles"). The roles defined in the spec are unchanged.

start() refuses to start (it logs an error and returns false) when:

• a role name is not _<name>@<version> in visible ASCII;
• a role name is listed twice;
• a support object is not exactly one JSON object.

ArduinoJson's parser accepts input that isn't strict JSON, such as unquoted keys and single quotes. So instead of embedding the caller's text, start() re-serializes each support object and sends that. A support object is also refused if a string in it is not valid UTF-8, or has a control character the serializer would write back unescaped.

Application-specific versions of defined roles (player@_x) are out of scope: the library implements those roles itself.

This is the generic hook that local pairing with Music Assistant needs, e.g. "_ma_local_pairing@v1_support": {"port": N}.

Part of Sendspin/backlog#86.

[Copilot]

🟢 Approval recommended

No active review issues block the addition of configurable application roles to client hello messages.

No open issues 🎉

What changed in this PR

Adds a configuration hook for applications to advertise custom roles and optional support objects in client/hello, without changing the library’s built-in roles. This supports integrations such as Music Assistant local pairing.

Changes:

• Adds SendspinApplicationRole and SendspinClientConfig::application_roles.
• Validates role names, rejects duplicates, and normalizes support objects before startup.
• Adds validation and hello-message tests, plus public API documentation.

File	Description
tests/​test_record_store.cpp	Tests startup rejection and configured roles in client hello messages.
tests/​test_protocol.cpp	Tests role formatting, name validation, and support-object normalization.
tests/​CMakeLists.txt	Documents private hello-builder access used by tests.
src/​protocol.cpp	Serializes application roles and their support objects.
src/​protocol_messages.h	Adds application roles to the internal hello message structure.
src/​client.cpp	Validates configuration at startup and supplies roles to hello messages.
src/​application_role.h	Implements role-name, UTF-8, and JSON normalization helpers.
include/​sendspin/​config.h	Defines the public application-role configuration API.
docs/​integration-guide.md	Documents configuration, examples, and validation behavior.

_{Review effort: Balanced}