​

Shortcuts

A shortcut is a small, live, stateful surface that renders inside the thought bubble as a sandboxed iframe card. It’s the right surface for something conversation-adjacent — a quick interaction you want next to the chat, not in its own window. Shortcuts are built with create_shortcut and revised with update_shortcut.

Historically shortcuts are also called “widgets”; their surface ids use the widget- prefix and a few tools keep the legacy name (rename_widget).

​

When BOR builds a shortcut

When the result lives next to the conversation and is small/stateful:

• “Give me a quick currency converter card.”
• “A pay button with an amount input.”
• “A tiny travel itinerary that streams its own AI content.”
• “A Pomodoro card.” / “A waveform player.” / “A one-step API caller.”

The words “card”, “quick”, or “in the bubble” signal a shortcut. When BOR suspects a shortcut would help but you didn’t ask, it can offer one inline with suggest_shortcut — a cheap Yes/No card; click Yes and it builds it next pass.

​

How it renders

Shortcuts render as live iframes in the bubble thread:

• Up to 5 stay live at once. Older ones demote to a “tap to revive” frozen placeholder to save memory.
• When the bubble is hidden, live iframes stop painting to suppress work.
• The card has a title, a close button, and a drag-to-resize handle (the height persists).
• The active theme’s CSS tokens are injected into each shortcut so it matches your theme even though the sandbox has an opaque origin.

​

Full capability

A shortcut has the same power as an app — only the presentation differs. Through the bridge it can:

• Persist state (getState/setState).
• Ask the AI (askAI) and generate images (generateImage).
• Search and fetch the web (webSearch/webFetch).
• Schedule cron jobs and send notifications.
• Launch a full app (launchApp).

So a “translator card” can stream its own AI translations; a “pay button” can call an API; a “weather glance” can fetch live data.

​

Building & updating

• Design gate. Like apps, the first surface in a turn requires get_ux_ui_strict_guidelines. Shortcuts have their own strict spec (design-guideline/shortcut-card.md): heights, allowed primitives, theme tokens, and the API-key UI pattern.
• Doc required. create_shortcut must include a <doc> child.
• Update by id. To change a shortcut, read its doc, then update_shortcut with the existing widget-… id. State persists.
• Third-party keys. If a shortcut needs an API key, it must ship in-shortcut settings UI (masked input, save/clear, how-to-generate, key-needed initial state) as the first interaction.

​

App vs. shortcut, quickly

Pick by where the user will look:

• Its own window, multi-screen, long-lived → app.
• Inside the bubble, adjacent to the conversation, compact → shortcut.
• Unsure between shortcut and app → shortcut. Unsure between shortcut and just answering → suggest_shortcut.

​

Tools

See the Tool reference for exact params, and The bridge for the API surfaces use.