Casset Apps · Capabilities

What Casset Apps can do.

Build a profile room, interactive discography, visualizer, game, collector experience around an existing Casset purchase, or another artist-native extension. Casset supplies the approved artist context and remains responsible for identity, installation, checkout, entitlement, playback, lifecycle, and exit.

Where it runs

Choose the context that fits the experience.

Casset App context comparison
Context	Use it for	Playback	Current data
`PROFILE_SURFACE`	An experience that lives inside the artist profile.	May request an approved Track through PLAY_TRACK when permission and capability are present.	Artist, theme, catalog, active release; Moments, Campaigns, and Audience are unavailable.
`TRACK_RUNTIME`	A visual experience tied to one active Track.	Reads playback state and time supplied by Casset. No command bridge.	Exact Track, optional release/theme, entitlements, timeline, and URL-free resource references.

Anatomy

Five pieces form the local contract.

casset-app.json          reviewable declaration
src/main.ts(x)          local entry and manifest parsing
src/App.ts(x)           App-owned presentation
CassetAppHost           snapshots, subscription, request channel
cleanup()               unsubscribe and release local interaction

Declaration

Manifest

Names context, placement, requested permissions, compatibility, and fan-access support. It grants nothing.

Observation

Context

Contains only the server-approved data for this launch. It is short-lived and replaceable.

Authority

Host

Supplies snapshots and receives narrow requests. It never hands the App a player or navigation object.

Data states

Handle data that is loading, empty, denied, or unavailable.

Profile data uses CassetData<T>; do not turn missing host data into invented content.

Casset data states
State	Meaning	App response
`loading`	The host is resolving the data.	Show a quiet, non-dominant loading state.
`ready`	Validated data is available.	Render only the supplied fields.
`empty`	The request succeeded but has no visible rows.	Compose an authored empty state; do not fabricate.
`permission-denied`	The required permission was not granted.	Explain the unavailable capability without requesting private data.
`unavailable`	The host lacks an adapter or the family does not apply.	Degrade calmly; do not fetch around the host.

Lifecycle

Update when Casset updates the App.

Live host lifecycle
State	Contract
`CONTEXT_READY`	The host has validated context; prepare presentation without inventing playback.
`ACTIVE`	The App may respond to current host snapshots and local input.
`CLOSED`	Stop reacting, remove listeners, and release App-owned presentation state.

const unsubscribe = host.subscribe((snapshot) => {
  if (snapshot.lifecycle === "CLOSED") {
    deactivate()
    return
  }

  if (snapshot.context.kind === "TRACK_RUNTIME") {
    updateFromCanonicalTime(snapshot.context.playback.currentTimeSec)
  }
})

return () => {
  unsubscribe()
  destroyLocalInteraction()
}

Playback

Your App can observe or request. Casset plays.

Profile Apps guard PLAY_TRACK with playback.control and PROFILE_PLAY_TRACK.
Track Runtime reads currentTimeSec, durationSec, state, progress, and timeline from the canonical host snapshot.
No App receives raw audio URLs, tokens, the audio element, transport store, mutable clock, analyser, scheduler, or render owner.
Local visual preference is allowed; local playback truth is not.

Production access

A local App is not a production install.

Install and enable

The artist's server-owned installation and permission grant must exist before a production host context can be created.

Disable or remove

Future route and context creation fails closed. A fixture cannot simulate or override that authorization.

Collector access

Where supported, Casset checks the existing same-artist Casset purchase before the App implementation mounts.