Use @casset/apps inside a Casset App.

The package validates your App manifest, types the artist context supplied by Casset, checks permissions and host support, and includes local fixtures for testing. It is included in every downloadable starter and is not published to npm.

Install

Import from the SDK included with your starter.

import {
  defineCassetApp,
  hasCassetPermission,
  hostSupports,
  isCassetDataReady,
  parseCassetAppManifest,
  parseCassetHostSnapshot,
  parseProfileSurfaceContext,
  parseTrackRuntimeContext,
  validateCassetAppManifest,
  type CassetAppHost,
  type CassetHostSnapshot,
  type ProfileSurfaceContext,
  type TrackRuntimeContext,
} from "@casset/apps"

Reference

Exports for native Apps

Casset Apps SDK runtime exports
Export	Purpose	Availability	Constraint
`defineCassetApp(manifest)`	Validate and preserve a typed manifest declaration.	Available	Declaration only; grants no installation or runtime authority.
`validateCassetAppManifest(value)`	Return a non-throwing validation result with field issues.	Available	Rejects unknown fields and illegal permission/context combinations.
`parseCassetAppManifest(value)`	Return a manifest or throw CassetAppValidationError.	Available	Use at untrusted manifest boundaries.
`parseCassetHostSnapshot(value)`	Strictly parse a host snapshot and nested context.	Available	Does not create authorization.
`parseProfileSurfaceContext(value)`	Parse the bounded Profile Surface context.	Available	Unsupported data families must remain unavailable.
`parseTrackRuntimeContext(value)`	Parse the exact app-facing Track Runtime context.	Available	Read-only; URL-free resources are not delivery credentials.
`hasCassetPermission(context, permission)`	Check the granted permission list.	Available	A client check cannot authorize a server action.
`hostSupports(host, capability)`	Detect APP_EXIT or PROFILE_PLAY_TRACK.	Available	Capability and permission are both required for PLAY_TRACK.
`isCassetDataReady(value)`	Narrow CassetData<T> to its ready state.	Available	Never invent a fallback for denied or unavailable data.

Host

Snapshots in. Narrow requests out.

Casset App host interface
Member	Signature	Meaning
`getSnapshot`	`() => CassetHostSnapshot`	Read the latest immutable observation.
`subscribe`	`(listener) => unsubscribe`	Receive context/lifecycle changes; always call the returned cleanup.
`request`	`(command) => Promise<CassetHostCommandDecision>`	Request APP_EXIT or a Profile-only PLAY_TRACK action.

Profile Surface

Read availability-aware Profile data.

const snapshot = host.getSnapshot()
if (snapshot.context.kind !== "PROFILE_SURFACE") return

const { catalog } = snapshot.context
if (isCassetDataReady(catalog)) {
  renderTracks(catalog.data.tracks)
} else if (catalog.status === "permission-denied") {
  renderPermissionDenied(catalog.permission)
} else {
  renderSparseState(catalog.status)
}

Track Runtime

Observe canonical time without taking control.

const context = parseTrackRuntimeContext(untrustedRuntime)

// Canonical seconds come from Casset. Do not start a local clock.
const seconds = context.playback.currentTimeSec
const progress = context.playback.progress
const activeEvents = context.timeline.events.filter(
  (event) => event.atSec <= seconds && (event.endSec === null || seconds <= event.endSec),
)

TrackRuntimeContext includes launch, artist, Track, optional release/theme, permissions, entitlements, installation, playback, timeline, and URL-free resource references.
Its playback capability booleans describe sanitized host state; this alpha exports no Track Runtime playback command.
A RuntimeResourceRef contains identity and scope only. It is not a URL, token, secret, or authorization grant.

Untrusted input

Parse before rendering or requesting.

const parsed = validateCassetAppManifest(untrustedManifest)

if (!parsed.success) {
  for (const issue of parsed.issues) {
    console.error(issue.path, issue.code, issue.message)
  }
} else {
  const manifest = parsed.value
}

Local development

Deterministic fixtures, no production identity.

Casset SDK fixture exports
Export	Use
`createCassetManifestFixture()`	A valid public Profile manifest.
`createProfileSurfaceFixture(options?)`	Profile context with overridable lifecycle, permissions, theme, Catalog, and release states.
`createTrackRuntimeFixture()`	URL-free canonical-time Track context.
`createCassetHostSnapshotFixture(context?)`	A strictly parsed host snapshot around either context.
`createCassetDevelopmentHost(options?)`	A local host with request recording, snapshot updates, subscriptions, and close behavior.