# Page data API

> The window.fiddle object a prototype uses to save records and send live messages.

`window.fiddle` exists only inside Fiddle. Guard with `window.fiddle?.` if the page should also work as a plain file. See [Page data](https://docs.fiddle.fyi/page-data.md) for rules and helpers.

## Basics

| Member | What it is |
| --- | --- |
| `fiddle.ready` | A promise that resolves once Fiddle is connected |
| `fiddle.me` | `{ id, name, role }`, where role is `"editor"` or `"viewer"` |
| `fiddle.collection(name)` | A collection |
| `fiddle.channel(name)` | A live channel |

## Collections

```js
const cards = fiddle.collection("cards")

await cards.add({ text: "Shipped on time" })   // a new record with a new id
await cards.list()                              // every record you may read
const stop = cards.subscribe((records) => render(records))  // now and on every change

await cards.mine().set({ vote: "a" })           // the record keyed by your id
```

## Records

```js
const card = cards.doc(id)

await card.get()                       // the record, or null
await card.set({ text: "…" })          // create or replace
await card.update({ text: "…" })       // merge fields; null removes one
await card.delete()
card.subscribe((record) => render(record))
```

A record is `{ id, data, author: { id, name, kind }, createdAt, updatedAt }`. `data` is a JSON object up to 256 KB.

A record id that starts with someone's `fiddle.me.id` can only be created by them. That's how "one vote per person" stays honest.

## Channels

Ephemeral messages to everyone on the page right now. Nothing is stored.

```js
const reactions = fiddle.channel("reactions")
reactions.send({ emoji: "👏" })
reactions.on((data, from) => float(data.emoji, from.name))
```

## Events

The no-script helpers fire `fiddle:saved` on their element once a save lands.
