Project Scenarios

This section describes five example projects, each built on a different part of the Starfish API. The goal is to show which primitive fits which problem. The projects are illustrative but the code is valid against the TypeScript SDK.

Project	Description	Starfish features
Constellation	Public installation where each phone is a point of light	Presence, clock sync, broadcast
Duet	Pairs two anonymous users for low-latency interaction	Pools, WebRTC, unreliable delivery
The Long Mural	Persistent shared drawing canvas	Shared state ops, scopes, optimistic concurrency
Chorus	Audience phones triggered as a synchronized sound system	Clock-scheduled events, broadcast, latest delivery
Wander	One-to-one message exchange between anonymous users	Direct messaging, request/reply

Each example assumes a connected client, created and connected like this:

import { StarfishClient } from "@starfish/client";

const client = new StarfishClient({ server: "wss://stars.example.com" });
await client.connect();

The per-project pages pick up from there with the session join and the feature code.

Choosing a primitive

• Presence — current per-client state (position, status, assignment). Replaces on each update.
• Topics — many-to-many pub/sub within a named channel.
• Broadcast and the clock — coordinate an action across many clients at a shared server time.
• Shared state — persistent state with structured operations (list.add, counter.add, merge, replace) and optional version checks.
• Pools — server-side matchmaking without a shared room name.
• WebRTC — low-latency peer-to-peer data path that bypasses the server.
• Direct messaging — messages addressed to specific clients.

See the Quick Start to get running, and the Cookbook for the individual patterns used across these scenarios.