Made of little things.

# Funclet

A compact Wavefunc radio napplet: station discovery, live playback, read-only
favourite lists, music search and now playing. Built with TypeScript and the
installed `@napplet/sdk` and Three.js, with no UI framework or app-owned network client.

## Use

- Search stations by name, genre or location, then select one to listen.
- Press the red key on the 3D receiver to play/pause; drag its volume dial left/right
  or up/down. The visible player buttons and slider also work with touch and keyboard.
- The extruded `[WF]` cube rotates at idle and speeds up during playback. The camera
  drifts gently and responds to the mouse. A procedural signal
  shader animates the screen; it illustrates playback activity, not measured audio.
- Open Station info for artwork, description, genres and alternate streams.
- HTTP-only stations are marked in the directory. Select one to open its Wavefunc
  station page or copy the original stream URL into another player. The host only
  opens HTTPS links, so Funclet does not try to open or play raw HTTP inside the shell.
- Choose Tracks, Artists or Albums to search MusicBrainz through Wavefunc’s CVM.
  These are catalogue results, not audio tracks for playback.
- Connect your Nostr account in the host and open Favourites to read your existing
  Wavefunc lists. Lists are read-only; create/edit them in Wavefunc.
- Host settings control station artwork and the now-playing refresh interval.
  Now playing refreshes only while playing and visible. Audio does not depend on
  metadata availability. After a failed metadata request, pause/resume or retune to retry. The host asks before connecting to the Wavefunc CVM.

Playback uses shell-owned live media sessions. Only public HTTPS streams supported
by the host can play here; HTTP streams use the external fallback. Playlists,
HLS/DASH, FLAC and AAC remain unavailable for in-app playback. The source catalogue contains stations that cannot play in this host.
No playback starts automatically on load. The frame can resize without losing the
selected station. Below 280×260 it shows a resize notice and a compact playback
control for an active station.

## Local development

Read [docs/napplet-space.md](docs/napplet-space.md) for the installed soyLI commands,
capability boundaries and preview cleanup. Do not re-scaffold this workspace.

```sh
soyli dev --no-open --port 0
```

Use its printed URL, then stop the owning session with Ctrl+C after testing.

```sh
pnpm verify              # guidance, domain/player regressions, types, build
pnpm test:conformance    # upstream reference iframe checks
pnpm test:ui             # built artifact with explicit host fixtures
pnpm test:host -- http://127.0.0.1:PORT/
pnpm test:external -- http://127.0.0.1:PORT/
soyli check              # real host artifact check
```

Browser checks use the existing conformance dependency and soyLI’s cached Chromium.
Run `soyli browser install` only if that browser is missing. `test:host` makes real
read-only requests and briefly plays Omarchy Radio; it approves the test’s Wavefunc
CVM connection. It never signs in or publishes. `test:external` verifies IDM Ambient’s HTTP
record and opens its HTTPS Wavefunc page through the real host confirmation. Captures and reports are ignored
under `.napplet-space/testing/`. Build before running the UI/host scripts.

## Data and authority

| Domain | Purpose | Requirement |
| --- | --- | --- |
| OUTBOX | Station discovery, NIP-50 search, current viewer’s favourite lists | Required |
| MEDIA | Canonical shell-owned session, play/pause/volume, actual playback state | Required |
| CVM | Wavefunc metadata and MusicBrainz search | Optional; playback still works |
| IDENTITY | Viewer public key and account-change notifications | Optional; guest listening |
| RESOURCE | Station artwork as bounded image blobs | Optional; radio illustration fallback |
| CONFIG | Artwork and metadata refresh settings | Optional; sensible defaults |
| LINK | Open an HTTP-only station’s HTTPS Wavefunc page | Optional; selectable stream URL fallback |

No RELAY escape hatches, write operations, direct networking, browser persistence,
keys, signing, telemetry identifiers or custom protocol messages. Media sessions,
subscriptions, polling and object URLs are cleaned up on teardown. Responses from
old searches, accounts or media sessions cannot replace newer UI state.

Wavefunc station events are kind 31237. Favourites are kind 30078 with the label
`wavefunc_user_favourite_list` and station address tags. The installed soyLI host
reserves kind-30078 writes for its own scoped app-data validator, so compatible
Wavefunc favourites cannot currently be written. The user chose read-only lists;
Funclet does not migrate them into another format.

Production endpoints and public server identity come from the Wavefunc source:
`wss://relay.wavefunc.live` and CVM public key
`bb0707242a17a4be881919b3dcfea63f42aacedc3ff898a66be30af195ff32b2`, with
`wss://relay2.contextvm.org/` as an additional CVM hint. The shell owns transport,
policy, authorization and routing. Automatic CVM payments are disabled.

## Design and verification

The [build brief](docs/funclet-brief.md) records the Wavefunc paper/ink/red/cyan
palette, 3D broadcast sculpture, responsive layout and port inventory. The receiver,
extruded lettering, textures and shaders are generated locally; no Blender assets,
model loaders or remote fonts are required. Three.js is bundled in the single-file
artifact. Pixel density is capped, the grille is instanced, and continuous rendering
stops when hidden, covered by station info, or reduced motion is requested. The
camera holds steady during control gestures. Case labels are transparent printed
ink textures laid out on the taller receiver face.
A WebGL failure keeps the complete HTML player usable; context restoration resumes
the scene. Geometry, materials, textures, listeners and animation frames are disposed
on teardown. Colors are app-owned and do not
change with the host theme. [Verification notes](docs/funclet-verification.md)
distinguish real host checks, fixture coverage and unverified cases.