Building spirits
A spirit is a small web app that travels through sound. You write it in the browser, share it with people nearby, and it runs on their device with no network. Two people with the same spirit can connect over sound and use it together. There is no server: either device can answer the other.
- Open Spirit Studio and pick a template with New.
- Edit the files and press Run. Spirits for two devices run as two previews, A and B, already connected.
- Switch the connection to Sim air to run the real modem with noise and dropouts, and watch the Network tab.
- Press Publish. The spirit is signed with your author key and added to your Séance OS library.
- In Séance OS, press Share over sound. Nearby devices on the Receive tab get it, check the signature and ask to install.
- Both devices open the spirit; one presses Play together, the other accepts and both compare four words.
A spirit has four files. The runtime adds a dark default stylesheet, so plain HTML already looks right.
spirit.json: the manifest.index.html: the body of the page (no<html>or<head>).app.js: runs after the body.window.spiritis ready.style.css: your styles.
{
"name": "Ghost Grid", // up to 32 characters; with your key, it identifies the spirit
"version": 1, // raise it when you change the code
"icon": "👻",
"description": "Tic-tac-toe for two devices.",
"peers": 2, // 0 = alone, 2 = can connect to one other device
"permissions": ["peer", "db"] // peer: messages and GGTP; db: GhostDB
}Every byte goes through the air at roughly 20–40 bytes per second, so keep spirits small. The Budget tab shows the signed size and how long one sharing round takes.
spirit.me // { device, side, name, version, peers }
spirit.on("peer:join", p => …) // p = { device, name, version }
spirit.on("peer:leave", e => …) // e = { reason }
spirit.log("hello") // same as console.log; shows in the studio console
// peer messages (needs "peer")
spirit.peer.connected // true while another device is in the session
await spirit.peer.send("move", { i: 4 }) // resolves once the other side has it
await spirit.peer.send("letter", longText, { // up to ~11 KB; about 27 bytes per second
onProgress: (sent, total) => …
})
spirit.peer.on("move", data => …)
spirit.on("peer:receiving", r => …) // r.bytes so far, while a long message arrives
// GhostDB (needs "db")
await spirit.db.put("note:1", { text: "boo" })
await spirit.db.get("note:1")
await spirit.db.list("note:") // [{ key, value }], sorted by key
await spirit.db.del("note:1")
spirit.db.watch("note:", change => …) // { key, value, deleted, origin: "local" | "peer" }
// GGTP (needs "peer")
spirit.serve("GET", "/search", req => results) // req = { method, path, query, body }
spirit.serve("GET", "/page/*", req => page || { status: 404 })
const r = await spirit.ggtp.get("/search?q=bat") // { ok, status: "2.05 Content", code, body }
await spirit.ggtp.post("/notes", { text: "hi" })
const w = await spirit.ggtp.watch("/score", score => …); w.cancel()
spirit.notify("/score", 3) // tells everyone watching /scoreAll calls return promises. Errors (no peer, missing permission, value too big) reject with a readable message.
Ghost Gibberlink Transfer Protocol is a request/response protocol in the style of CoAP. HTTP headers would cost seconds of airtime, so every GGTP message has a 5-byte header:
[0] 0x40 | type 0 REQ 1 RES 2 NOTIFY 3 MSG 4 CANCEL 5 HELLO
[1] code REQ: 1 GET 2 POST 3 PUT 4 DELETE 5 WATCH
RES: status, class.detail (2.05 Content, 4.04 Not Found …)
[2] token pairs a response with its request
[3] format 0 none 1 text 2 json 3 bytes
[4] path length then the path, then the body- Both devices can serve and request at the same time. There is no host.
- A handler's return value becomes a 2.05 response. Return
{ status: 404 }(or 201, 400, 403…) to choose the status. - Requests time out after 120 s (5.04). When the link drops, open requests fail with 5.03.
- WATCH runs the GET handler, then every
spirit.notify(path)sends a NOTIFY until the watcher cancels. - Paths starting with
/~belong to Séance OS (GhostDB sync uses them).
- Each spirit gets its own store on each device. It works offline.
- When two devices connect, each pulls only what changed since it last synced with that device, then live writes are pushed as they happen. Changes travel on: data written on A reaches C through B.
- Conflicts: every write carries a Lamport clock and the device id. The higher
(clock, device)wins on every device, so both copies end up identical. - Deletes are kept as tombstones so they sync too.
- Keys starting with
local:never leave the device. Use them for private data the other side should ask for over GGTP (see the Ghost Wiki template). - Limits: keys up to 128 characters, values up to 4,000 bytes of JSON, 2,000 keys per spirit.
0 4 bytes magic 00 47 53 01
4 32 bytes author Ed25519 public key
36 64 bytes signature over "ggtf-spirit-v1" + body
100 … body: DEFLATE of {"manifest": …, "files": …}- Your author key is made in this browser the first time you publish and never leaves it. People see it as four words.
- The app id is a hash of your public key and the spirit name. A spirit with the same name from someone else is a different spirit, and the install screen warns about it.
- Anyone can share a spirit they received. Changing a single byte breaks the signature, so the copy C gets from B is exactly what A published.
- Séance OS comes with six starter spirits signed by one GGTF key, so every device has identical copies and two people can play them together without sharing first. Removed starters stay removed until you press Restore starter spirits.
- Sharing uses Haunted QR beams: the bundle is cut into 196-byte pieces that repeat in rounds, so listeners who miss a piece get it next round.
- Two devices only play together when their bundle hashes match. Raise the version when you change a spirit.
- Spirits run in an iframe with
sandbox="allow-scripts allow-forms": an opaque origin with no access to Séance OS, its storage, cookies or other spirits. Forms fire submit events, but the policy below blocks any real form post. - A content security policy blocks fetch, XHR, WebSockets, external images and fonts, and form posts. A spirit can't reach the internet, only the device it is playing with.
- Every call goes through Séance OS and is checked against the spirit's permissions.
- The link between devices is encrypted (X25519, ChaCha20-Poly1305). Both people compare four words to rule out someone in the middle.
- Known limit: a spirit can still navigate its own frame to a web address. It can only carry what the spirit itself holds, which is its own data.
- Messages up to 12,000 bytes, tagged as chat (kind 0) or GGTP (kind 1). Both sides get progress as the pieces arrive.
- The line test never picks Turbo for app sessions: it passes the short test but long frames often fail over real air.
- Fragments are sized by the trained speed: 56 bytes on Sturdy, up to 176 on Fast. After a hard-won fragment the size halves; after clean ones it grows back.
- When a reply is ready within 350 ms, the acknowledgement rides inside it, so a request and its response take 3 frames instead of 4.
- Idle links send a keep-alive every 45 s and notice when the other device has gone.
- Play together sends the spirit's app id inside the call, so the other device knows which spirit you mean before answering.