P024 Listener Web Shell

Live queue, visible reasons, no fake player.

This listener web surface is the first truthful shell for the current platform. It is built around live queue planning, feedback, explainability, and playback handoff boundaries that already exist in recommendation-api and playback-api.

AI stream mode reranks continuously Rights-first before queue or playback Explainability with causal factors

Live queue plus interaction edge

This listener surface now keeps queue probing and recommendation interaction on the public same-origin edge. Queue planning still runs through POST /api/session/queue with an inline session payload, while POST /api/session/intent and POST /api/session/feedback now target a dedicated browser-safe recommendation interaction worker instead of the shared bootstrap API host.

Probe controls

Session-intent composer plus truthful queue contract probe

Current public edge truth: `api.zenosound.com` currently serves the metadata bootstrap surface, not recommendation-api. The public listener shell now uses a same-origin listener edge instead of pointing the browser at that bootstrap host, and its public candidate source now composes from deployed ingest-backed catalog and active-analysis workers behind that same-origin edge.

The inline fallback probe pack remains contract-grade for local env-free runs and is still seeded with one blocked artist plus energetic boost and calm suppress tag controls so queue explainability and rights filtering stay visible if upstream env wiring is absent. The current public edge is intentionally a bounded read-only ingest seed, so the public queue probe now exercises real ingest-backed catalog and analysis logic without pretending the full internal listener stack is browser-reachable on the public `api` host.

Listener interaction truth today: this public shell now exposes browser-safe session-intent and feedback writes through /api/session/intent and /api/session/feedback on the same-origin listener edge. This first public interaction edge now keeps session-keyed durable-object memory, not durable replay storage. After a successful write, the next queue probe can request stored interaction replay from that same session-keyed edge state and the metadata panel will disclose when replay was applied.

Playback transition truth today: the shell now also exposes bounded same-origin contract probes for /api/playback/startup, /api/playback/metadata/fallback, /api/playback/authorize, and /api/playback/handoff. These calls validate playback transition plus startup-selected metadata/artwork resolution on the public listener edge without pretending the browser already owns a full player launch, CDN token exchange, or download UX.

Request summary
Waiting for live queue probe

No live request sent yet. Run the probe to call the same-origin listener queue edge.

Queued tracks

Queued tracks will appear here with explainability and applied constraints.

Filtered and metadata

Filtered candidates will appear here with explicit reasons.

Metadata and policy metrics will appear here after the first successful probe.

Interaction edge
Waiting for public intent or feedback write

Same-origin intent and feedback writes will summarize their public worker response here.

Playback transition edge
Waiting for startup, metadata, authorize, or handoff probe

Same-origin playback transition and metadata probes will summarize startup, metadata/artwork, authorize, and handoff results here.

Listener interaction rails

These are the product-facing states already backed by current services. The shell stays truthful to the current public edge instead of pretending every backend route is browser-safe already.

Session intent

Capture territory, explicit-policy, blocked artists, tag controls, section focus, and recent-history bias before ranking. The public shell now exposes these controls through the same-origin queue edge instead of leaving them as static copy.

  • Boost, suppress, or block tags at runtime.
  • Keep session constraints explicit instead of hidden in client state.
  • Feed the same policy inputs used by downstream playback checks.

Behavior feedback

Turn listener actions into deterministic feedback state on the public same-origin edge. Queue replay can now opt into that same session-keyed edge state, while the save, skip, dislike, and block/unblock writes no longer depend on the bootstrap `api` host.

  • Save, replay, finish-rate, skip, dislike, artist block/unblock.
  • Same-origin `/api/session/feedback` now forwards to a dedicated public worker.
  • The first public interaction edge is explicit session-keyed durable-object memory, not durable replay storage.
  • Replay stays opt-in and disclosed in queue metadata instead of becoming a silent hidden default.

Playback transition

Queue planning alone is not enough. The shell now runs bounded same-origin startup, metadata/artwork, authorize, and CDN handoff probes so the listener can validate where rights gates re-run and how the selected asset resolves into listener-visible title/artwork without pretending the browser already owns a full player session.

  • Same-origin `/api/playback/startup`, `/api/playback/metadata/fallback`, `/api/playback/authorize`, and `/api/playback/handoff` are now live as contract probes.
  • Metadata/artwork resolution runs against the startup-selected asset without claiming browser stream launch.
  • Startup and handoff reject empty authoritative ledgers.
  • Authorize stays deterministic and rights-first.
  • Blocked decisions and streaming-vs-blocked handoff remain visible instead of being silently suppressed.

Current platform truth

The listener shell should surface these product promises because they already match the backend contract and validation suite.

Queue behavior

AI stream mode is live and event-driven

  • Queue planning horizon stays short instead of prebuilding an endless station.
  • Session events can trigger deterministic replans.
  • Static playlists can coexist with the AI stream rather than replacing it.
Explainability

Every queued track needs visible reasons

  • Top matched tags.
  • Similarity rationale.
  • Applied constraints such as rights, explicit policy, and artist caps.
Curation policy

Hard filters are not optional

  • Territory rights, availability windows, explicit settings, blocks, dislikes.
  • Diversity and novelty guards stay visible as policy, not magic.
  • Promotion is allowed only when it remains labeled and policy-bounded.

Listener-facing API surfaces

These routes are the source of truth for the shell. This page should help product and design work stay aligned to the current service reality.

POST /v1/session/intent

Set live session intent controls and constraints before queue planning.

POST /v1/session/feedback

Apply save, replay, skip, dislike, and manual controls into deterministic behavior state.

POST /v1/session/queue

Resolve current session intent and behavior into a policy-aware queue plan.

POST /v1/playback/startup

Build startup and buffer tracks while revalidating rights on the playback path.

POST /v1/playback/metadata/fallback

Resolve title, artist, and artwork for the startup-selected asset without claiming browser playback launch.

POST /v1/playback/authorize

Produce deterministic allow or deny decisions with reason codes and applied constraints.

POST /v1/playback/handoff

Move from planned queue into listener-ready streaming or explicit blocked fallback state.

This shell now includes a read-only live queue probe plus a session-intent composer plus browser-safe same-origin intent/feedback writes plus bounded same-origin playback transition probes plus startup-selected metadata/artwork fallback probes. Public production now activates live candidate-source mode through deployed ingest-backed catalog and active-analysis workers, while the interaction edge keeps explicit session-keyed durable-object memory and local env-free runs still fall back to the inline probe pack. The queue and playback probes can now request stored interaction replay from the public worker and disclose when that bounded edge state was applied, without pretending full player auth, CDN launch UX, or durable stored-state replay already exist on `app.zenosound.com`.