A small public contract around Casset's trusted host.

The dependency-free SDK centralizes manifests, app-facing contexts, strict parsers, capability helpers, and deterministic fixtures. It is repository-local and vendored into the downloadable starters—not published to npm.

Availability

Consume one root export.

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

Reference

Core runtime exports

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.