[kahrendt]

Summary

First step of moving the public API from std::string to std::string_view. Metadata and group text already live in fixed storage (#256, #258); the public structs still copied it into std::strings kept allocation-free only by ReservedText (about 3 KB of internal RAM for metadata). The view forms hand consumers that storage directly; the string forms are deprecated and go in v0.11.0 with ReservedText. Part of Sendspin/backlog#92.

Migration: override on_track_metadata(const TrackMetadata&) instead of on_metadata(), on_group_state(const GroupState&) instead of on_group_update(), and call group_state() instead of get_group_state(). Text fields become std::optional<std::string_view>: copy them if you keep them past the callback (or, for group_state(), past the next return to loop() or stop()). A view is not guaranteed to be NUL-terminated, so print it with %.*s or copy it before handing it to a C-string API. docs/integration-guide.md "Deprecated String API" has the full table.

Change

• Metadata: TrackMetadata views the role's current text block, valid for the callback.
• Group: GroupState serves both the delta on_group_state() receives (the fields changed by the group/update messages since the last call) and the merged state group_state() returns. Both view an inline copy the main loop keeps, so the views outlive the string forms' removal.
• Dispatch: the library calls the new callback, then the deprecated one; both default to no-ops, so a consumer overrides one. A stop() inside the new callback skips the deprecated call (group: the drain generation; metadata: TeardownTracker::completed(), since the protocol task may bump the cleanup generation meanwhile).
• Deprecated with @deprecated and [[deprecated("...; removed in v0.11.0")]]: ServerMetadataStateObject, on_metadata(), GroupUpdateObject, on_group_update(), get_group_state(). A consumer of only the new API compiles warning-free; the library silences the warning only at its own compat sites.
• get_track_progress_ms() / get_track_duration_ms() read the role's current state, so the removal can delete the deprecated object outright. The examples use the new API.

Tests

• The metadata and group content tests check both forms carry identical content (cut text, unkept fields, cleared fields, delta versus merged state) and that the views do not point into the deprecated strings.
• Listener-form tables: only new, only old, both (new first), a stop() from the new callback, and a protocol-task teardown during it (pins completed() over accepts()). The progress getters are pinned with and without a listener.
• The metadata and group alloc windows stay at 0 with listeners overriding both forms. Mutants caught include views into the deprecated strings, the deprecated call skipped or reordered, the re-entrancy skip removed, and the getters reading the deprecated object.
• Builds checked: -DENABLE_WERROR=ON with examples, -DSENDSPIN_ENABLE_METADATA=OFF, and an ESP-IDF esp32s3 build with no deprecation warnings from the library.

Next in the series: the pairing listener strings, server information and token getters; then the vector callbacks, the persistence provider and the configs.

[Copilot]

🟡 Changes recommended

Metadata and group-state callbacks can detach their listeners without stopping, causing subsequent delivery paths to dereference null listeners.

5 open issues

• Guard group-state delivery after listener detachment · New
• Recheck listener after metadata callback detaches it · New
• Clarify view API behavior and deprecated string copies · New
• Warn that metadata views may not be NUL-terminated · New
• Use field-wise equality assertions for clearer failures · New

What changed in this PR

Begins the public text-API migration to std::string_view, exposing existing fixed storage for metadata and group text while retaining deprecated string-based APIs until v0.11.0.

Changes:

• Adds TrackMetadata, GroupState, new callbacks, and the group_state() getter.
• Delivers view callbacks before compatibility callbacks, with teardown guards.
• Migrates examples and documentation, and extends content, lifecycle, and allocation tests.

File	Description
tests/​test_encrypted_lifecycle.cpp	Tests content parity, view storage, callback order, and progress getters.
tests/​test_client_lifecycle.cpp	Migrates lifecycle tests and checks both group-state forms reset.
tests/​test_allocations.cpp	Checks allocation behavior with both callback forms enabled.
tests/​lifecycle_test_fixtures.h	Migrates the shared metadata listener.
tests/​CMakeLists.txt	Documents updated white-box test access.
src/​teardown_tracker.h	Exposes the completed teardown generation.
src/​protocol_messages.h	Updates payload comments for view-backed public types.
src/​metadata_role.cpp	Builds metadata views, delivers both forms, and updates progress reads.
src/​metadata_role_impl.h	Declares view helpers and clarifies current versus compatibility state.
src/​client.cpp	Maintains inline group state and dispatches both callback forms.
include/​sendspin/​types.h	Adds GroupState and deprecates GroupUpdateObject.
include/​sendspin/​metadata_role.h	Adds TrackMetadata and its callback; deprecates string forms.
include/​sendspin/​config.h	Updates metadata configuration comments.
include/​sendspin/​client.h	Adds the group view API and documents its lifetime.
examples/​tui_client/​tui.cpp	Polls group state through the new getter.
examples/​tui_client/​main.cpp	Migrates metadata and group callbacks.
examples/​basic_client/​main.cpp	Prints metadata views using explicit lengths.
docs/​internals.md	Describes view delivery, storage, and teardown handling.
docs/​integration-guide.md	Documents migration, view lifetimes, and deprecated replacements.
docs/​conventions.md	Establishes the convention for view-backed public text.

_{Review effort: Max}