Capabilities

Everything the host offers is on window.cherry. Types are in cherry.d.ts.

Conventions

Errors

try {
  await cherry.storage.set('save', data)
} catch (e) {
  if (e.name === 'QuotaExceeded') showStorageFullDialog()
  // Back off rather than loop: a background budget does not refill on a timer.
  else if (e.name === 'RateLimited') retryLater()
  else throw e
}

cherry.app

Environment reads. No permission needed.

There is no theme field: use matchMedia('(prefers-color-scheme: dark)'), which also reports changes. See Theming.

cherry.ai

params:

{
  messages: { role: 'system' | 'user' | 'assistant'; content: string }[]  // 1–64 messages, text only
  reasoning?: 'on' | 'off'  // whether a reasoning model may think first; 'off' when omitted
  model?: 'default' | 'quick'  // which of the user's two model slots answers; 'default' when omitted
}

Which model answers is the user's choice, never yours: every app has a default and a quick slot (the same two Cherry keeps globally), each falling back to the global model of that name, and neither is ever revealed. Use quick for short, latency-sensitive calls. getCapabilities({ model }) describes the slot you are about to use — whether it reasons and how large its context is — so you can degrade instead of crash when the user swaps it. A slot the user has left empty, or whose model they deleted, comes back as { available: false } instead of rejecting: check it before calling chat, which does reject in that state. There is no image input and no tool calling; vision and tools are deliberately not reported.

callId is your own label for the call. It must be unique among your in-flight calls (reusing one rejects with InvalidArgument) and is what cancel takes. After cancel, no further chunks arrive and the chat Promise settles — normally resolving { ok: true }, or rejecting with Cancelled when the abort surfaces as an error. Handle both; whatever onChunk already delivered stays delivered.

There is no spending budget in tokens or money. Every completed call is attributed to your app in the user's usage ledger; the concurrency and burst limits throttle you while the user is watching, and the background allowance bounds what you can spend while they are not.

let out = ''
await cherry.ai.chat(
  { messages: [{ role: 'user', content: 'Name a color.' }] },
  { onChunk: (t) => (out += t), callId: 'hint-1' }
)

cherry.storage

A single JSON save file per app: string keys, string values, persistent, never evicted. The whole file is rewritten on every write, and a write is committed when its Promise resolves.

There are no multi-key transactions. State that must change together belongs in one key as one JSON string.

cherry.file

A flat namespace of named blobs, separate from storage, for larger payloads. Names are logical — there are no directories and no paths.

data must be valid base64; a malformed string rejects with InvalidArgument rather than being silently repaired.

const bytes = new Uint8Array(await blob.arrayBuffer())
await cherry.file.save('level1.bin', btoa(String.fromCharCode(...bytes)))

Exporting

export is the only way a sandbox file reaches the user's disk: the host opens its own save dialog, parented to the window showing your app and titled with your app's name, and copies the file to whatever path the user picks. That path is never returned to you.

Browser downloads (<a download>, URL.createObjectURL + click) and the File System Access pickers are blocked in the sandbox — see Sandbox.

cherry.notification

Notifications are one-way: there is no click event back to the app.

cherry.clipboard

Plain text only. Both calls require the app to be visible and to have keyboard focus: while the user is typing or clicking elsewhere in Cherry, or while your app sits hidden in the pool, they reject PermissionDenied. Focus is the one signal the user gives without a dialog; without it a background app could read what they copied elsewhere or replace what they are about to paste. Call from a click handler and you have it.

navigator.clipboard stays denied. Pasting into your own inputs with the keyboard is a browser behaviour and needs nothing.

cherry.network

The request is made by the host, not by the page, so it is not subject to CORS. A non-2xx status is a result, not a rejection.

const { status, body } = await cherry.network.fetch({
  url: 'https://api.example.com/scores',
  method: 'POST',
  headers: { 'content-type': 'application/json' },
  body: btoa(JSON.stringify({ score: 42 }))
})
const json = JSON.parse(atob(body))

cherry.on

const off = cherry.on('app.visibilityChange', ({ visible }) => { ... })
off()

Both are fire-and-forget: the host does not wait for your handler, and a handler that throws or rejects affects nothing. There is no destroy event, no permission-change event and no theme event — see Lifecycle.

Guest-side length caps

These run inside the page before anything is sent, so an oversized payload never leaves your process. They are the same numbers as the host's, expressed in characters: