Mini-apps

A mini-app is custom logic that blocks can't express: a game, a calculator, a drawing board, a 3D scene. It's one self-contained HTML document in blueprint.apps, shown by a miniapp block. The AI writes them on request; developers can too.

"apps":  [{ "id": "snake", "name": "Snake", "html": "<canvas id=c></canvas><script>…</script>" }],
"blocks": [{ "id": "snake-game", "kind": "miniapp", "props": { "app": "snake", "height": 420 } }]

The block's settings #

A miniapp block's config prop (plain JSON, up to 16 KB) reaches the app as window.zvessa.config, so one app placed twice can behave twice differently. config.connections names the space connections the app may read through the bridge's connections.call, read-only (MCP tools the server marks read-only, HTTP GET). Big data belongs in a collection, not in config.

Starter mini-apps #

Ready-made mini-apps people add from HQ → Library, each a kit with the same id (group Tools). Code: convex/lib/miniapps/, built from miniapps/*.html with npm run miniapps.

Every starter app also takes words (change any word it shows) and save (a name, so two copies keep separate saved state). Weather and Live info need the bridge; the compass needs it on phones.

Reuse, don't copy. Once an app is in /apps, place more miniapp blocks pointing at it with another config: a second countdown, a golf scorekeeper (lowWins: true). Kits share one copy too (Focus uses the Timer's). To remix, read the app's html from /apps, change it, and add it under a new id.

{ "id": "trip", "kind": "miniapp", "props": { "app": "countdown", "height": 320,
  "config": { "date": "2027-06-01", "title": "Lisbon trip", "words": { "days": "sleeps" } } } }

The sandbox #

Nothing anyone makes runs as code inside Zvessa itself. A mini-app runs:

• on phones in a WebView that can't navigate anywhere (src/components/MiniAppFrame.tsx);
• on the web in an iframe with sandbox="allow-scripts" and no same-origin access (MiniAppFrame.web.tsx). src/components/MiniApp.tsx is the same on both.

Its content policy (src/components/miniAppDoc.ts):

default-src 'none'; script-src 'unsafe-inline'; style-src 'unsafe-inline'; img-src data: blob:; media-src data: blob:; font-src data:;

So a mini-app can run inline scripts and styles and show data: and blob: images, sounds and fonts. It can't load other scripts or images from the internet, fetch anything, open sockets, read the app's sign-in, keys or data, or navigate away. (An https: image would let a mini-app send what people type to any server inside the image's address, so those are out.) Everything else goes through the bridge.

The style #

A mini-app matches every style, including ones made after it, because it gets the resolved style twice:

• CSS variables on :root: every colour by name (--bg, --surface, --raised, --text, --text2, --text3, --line, --accent, --accent2, --onAccent, --success, --warn, --danger, and any named colour such as --gold, --win), plus --radius, --radius-small and --line-width (--line is the line colour). color-scheme is set to light or dark; the body already uses --bg and --text.
• window.zvessa.style: { id, scheme, dark, colors, shape, surface, type } for scripts (canvas games read colors.accent and so on).

<button style="background: var(--accent); color: var(--onAccent); border-radius: var(--radius-small)">Play</button>
<script>
  const { colors, dark } = window.zvessa.style;
  ctx.fillStyle = colors.accent;
</script>

Never write a colour of your own; name one (var(--felt, var(--surface))) so styles can set it.

The bridge #

The bridge is the one way a mini-app reaches the space, the phone and the outside world. The mini-app asks; the host checks, then answers. Code: the list of calls is convex/lib/miniapps/bridge.ts (the AI's guide is built from it), the host is src/kits/miniapps/host.tsx, the server side is convex/miniapps/.

const me = await zvessa.call("me");
await zvessa.call("storage.set", { key: "best", value: 42 });
const off = zvessa.on("sensors.compass", (v) => needle(v.heading), { hz: 15 });
if (zvessa.can("location.get")) { /* show the "use my location" button */ }

• zvessa.call(name, args) answers once (a Promise). zvessa.on(name, handler, args) streams until you call the function it returns.
• A failed call rejects with an Error whose code is one of: denied (not listed in needs, the role can't, or the person said no), missing (no such call), limit (too many calls; try again shortly), unsupported (this device or browser can't), conflict (someone changed it first), invalid (bad arguments), failed (the message says why).
• zvessa.can(name) says whether this mini-app may use a call here, so it can hide a button instead of failing. zvessa.allowed is the full list.
• window.zvessa also has app ({ id, name }), config, style and preview (true while someone tries it from the library: saved state lives in memory and space data is off).
• Mini-apps written for the old name keep working: window.myaibio is the same object as window.zvessa.

What a mini-app declares: needs #

Basic calls (saved state, haptics, sound, share, clipboard copy, open, resize…) need nothing. Every other call must be listed in the app's needs, and a call on a collection names it:

{ "id": "quiz", "name": "Quiz", "html": "…", "needs": ["records.add:scores", "records.list:scores", "ai.ask", "location.get"],
  "about": "A pub quiz", "icon": "trophy", "age": "everyone" }

Then the host and the server both check, in order: the call exists, it's in needs, the viewer's role allows it (records.add needs add, a shared storage.set needs play…), the person has allowed it on this device when it touches the phone (location, camera, microphone, contacts, calendar, motion; asked once per app, in the app's own words), and the rate limit (bursts of 60, 30 a second, 12 at a time). The server checks again from the saved blueprint, so a changed page can't skip a check.

Outside information #

• connections.call reads from the space's own connections: a read-only MCP tool, or a GET on an HTTP API. Only the connections the block lists in config.connections (a list of ids, or an object such as { "forecast": "weather-forecast" }). Keys stay on the server. It answers { text, json?, status? }.
• ai.ask asks the space's AI ({ prompt, context?, system?, format: "text" | "json" }) on the space's own key.
• A published mini-app added to another space uses only that space's connections, the ones its owner lists in the block's config. Never the author's.

Every call #

Who and where

Saved state

Space data

Scores and events

Together

Outside information

Feel and sound

Sensors

Camera and files

Calendar and contacts

Screen

Later (needs store setup first): in-app purchases through Apple and Google, and reading steps and workouts from Health.

Pausing #

When the app is in the background or the mini-app is off screen, the host sends a pause: animation frames, timers and media stop, events stop arriving, sensors and sounds turn off, and myaibio:pause / myaibio:resume fire. Live values (storage.watch, records.watch, channel, presence) catch up on resume.

The public library #

Mini-apps can be shared with everyone. Nothing is public until its owner taps Publish.

• Publish (people who manage the space, from the Apps page: kit app-library, blocks miniapps.library, miniapps.mine, miniapps.review). Pick a category and an age rating (everyone, teen, mature), write what it does, and send it. The AI can't publish.
• Review. Every version waits for a Zvessa admin, who can try it, then accept or reject with a reason. Only accepted versions can be added anywhere else. Admins can also take a listing down, which stops it in every space, and put it back.
• Browse and add. Anyone signed in can search, read the details and the calls it asks for, and try it in a preview. Add to my space puts it in the space with its own page; Remix makes a copy the space owns and can change. Kids spaces only see and add apps rated everyone.
• Updates. An added app remembers where it came from. When a newer version is accepted, the space's managers see Update, with any new calls it asks for listed first.
• Ratings and reports. One rating per person; reports go to the admins.
• Free: publishing, adding and using cost nothing.

The library over MCP #

Any MCP client can browse the public library: POST {CONVEX_SITE_URL}/mcp/library needs no account or token and offers search_miniapps and view_miniapp (source: true includes the HTML), plus search_templates and view_template for templates and kits. It's read-only and lists only accepted pieces. A space's own /mcp server and the in-app AI get the same two tools plus add_miniapp({ id, remix? }), which is a proposal a person approves. Publishing is still only a person's tap in the app.

Writing a good mini-app #

• One file, no network. Inline everything; images as data: URLs. Outside information comes through connections.call.
• List what you use. Put every non-basic call in needs, and use zvessa.can() to hide what isn't allowed here.
• Fit any width. Phones first: 320 px wide and up, touch first, then mouse and keys.
• Light on the device. Draw with requestAnimationFrame only while something moves; stop when the game is paused or over. Ask sensors for the lowest rate that works (30 Hz is enough for tilt games). More in Performance.
• Paused when hidden. When the app is in the background or the mini-app is off screen, the host calls window.zvessa.setPaused(true): requestAnimationFrame, timers and media stop, and timers never fire faster than every 16 ms. Listen for the myaibio:pause and myaibio:resume events (or read window.zvessa.paused) to save state or stop sounds.
• No dialogs or forms. alert, confirm and form submits are blocked in the sandbox; use a second tap to confirm, and a button (plus Enter) to send an input row.
• No browser storage. It's blocked in the sandbox. Use the bridge's storage.get (answers { value, version } or null) and storage.set; scope: "space" shares a value with everyone and storage.watch keeps it live. Check typeof zvessa.call === "function" so the app still works outside Zvessa.
• Small. Aim for well under 200 KB of HTML; the whole blueprint goes to every device.
• Readable words. Put the app's words near the top of the script so people (and the AI) can change them.
• Accessible. Real buttons, labels, enough contrast (use --text on --bg).

Planned #

Developer apps hosted elsewhere behind the same bridge; in-app purchases and Health once the store setup is done; Skia and GL for native-speed games.