brsbl · Oct 9, 2026 · Oct 9, 2026 · Oct 9, 2026 · Oct 9, 2026 · Oct 9, 2026
diff --git a/apps/server/src/services/plugins/builtin-registry.ts b/apps/server/src/services/plugins/builtin-registry.ts
@@ -225,6 +225,11 @@ export const OFFICIAL_PLUGINS = [
     pluginId: "github",
     defaultEnabled: true,
   },
+  {
+    name: "playgrounds",
+    pluginId: "bb--playgrounds",
+    defaultEnabled: true,
+  },
   {
     name: "docs",
     pluginId: "simple-notes",

diff --git a/apps/server/test/services/plugins/builtin-plugins.test.ts b/apps/server/test/services/plugins/builtin-plugins.test.ts
@@ -269,6 +269,7 @@ describe("builtin plugin reconciliation", () => {
       "environment-modal-sandbox",
       "browser-automation",
       "github",
+      "playgrounds",
       "docs",
       "memory",
       "tasks",

diff --git a/apps/web/src/marketplace/bundled-marketplace.ts b/apps/web/src/marketplace/bundled-marketplace.ts
@@ -24,6 +24,7 @@ export const INSTALL_ON_REQUEST_BUNDLED_PLUGINS: ReadonlySet<string> = new Set([
   "environment-modal-sandbox",
   "github",
   "memory",
+  "playgrounds",
   "tasks",
   "theme-preview",
 ]);

diff --git a/packages/bundled-plugins/package.json b/packages/bundled-plugins/package.json
@@ -29,6 +29,7 @@
     "bb-plugin-memory": "workspace:*",
     "bb-plugin-monaco-editor": "workspace:*",
     "bb-plugin-pdf-preview": "workspace:*",
+    "bb-plugin-bb--playgrounds": "workspace:*",
     "bb-plugin-plugin-api-docs": "workspace:*",
     "bb-plugin-plugin-api-tester": "workspace:*",
     "bb-plugin-provider-acp": "workspace:*",

diff --git a/packages/templates/src/templates/bb-guide-plugins.md b/packages/templates/src/templates/bb-guide-plugins.md
@@ -26,6 +26,13 @@ or press **Ctrl+R** in a composer to search, preview, star, and insert prompts.
 history; `bb prompts list [--json]`, `bb prompts star <text...> [--json]`, and
 `bb prompts unstar <id> [--json]` manage starred text and mentions. History restores text, mentions, and attachments into an empty composer. Inserting never sends a message.
 
+The bundled Playgrounds plugin is not installed by default. Install it
+with `bb plugin install playgrounds` or from Plugins. Agents publish
+playgrounds, answers you can play with such as calculators, guides, and
+previews, with `bb playgrounds publish --document-stdin | --playground-stdin`;
+`guide` and `example <savings|bill|stepper>` print the schema and starters, and
+`state`, `watch`, `actions`, and `do` read and drive a published playground.
+
 The builtin Custom instructions plugin adds a multiline editor under Settings
 → Custom instructions. Saved text is persisted on this bb host and included in
 agent task instructions; blank text contributes nothing.

diff --git a/plugins/bb-official.json b/plugins/bb-official.json
@@ -38,6 +38,10 @@
     "category": "plugin-development",
     "screenshots": []
   },
+  "playgrounds": {
+    "category": "thread-content",
+    "screenshots": []
+  },
   "inline-vis": {
     "category": "thread-content",
     "screenshots": []

diff --git a/plugins/playgrounds/PLUGIN_OVERVIEW.md b/plugins/playgrounds/PLUGIN_OVERVIEW.md
@@ -0,0 +1,10 @@
+Answers you can play with: calculators, guides, previews. Agents put a playground right in their message, and changing an input updates it immediately, without another agent turn.
+
+## What you get
+
+- Native playgrounds: number fields, sliders, choices, live metrics, line and bar charts, tables, explanations, and interactive diagrams. They run no code and follow bb's theme.
+- HTML playgrounds for custom layouts, illustrations, schematic maps, and photos, rendered in a sandboxed frame that cannot reach bb, your cookies, the conversation, or the network.
+- Inputs saved with the playground, so they follow you across devices and every open copy updates live.
+- An agent that can read your inputs, follow what you do, and drive the playground when you ask it to.
+
+Install Playgrounds from Plugins, then ask for a calculator, a scenario comparison, or a walkthrough.
diff --git a/plugins/playgrounds/README.md b/plugins/playgrounds/README.md
@@ -0,0 +1,76 @@
+# Playgrounds
+
+Answers you can play with: calculators, guides, previews. Agents put a
+playground right in their message, built from native controls or a custom HTML
+interface, and changing an input updates it immediately without another model
+call.
+
+Playgrounds ships with bb but is not installed by default. Install it
+from Plugins or with `bb plugin install playgrounds`.
+
+## Use
+
+Ask for a calculator, scenario comparison, or interactive explanation. The
+plugin gives agents a `playground` tool, a document guide, examples,
+and the `playgrounds` skill. Native documents can include number
+fields, sliders, choices, live metrics, line and bar charts, tables, text,
+expandable explanations, and interactive vector diagrams. Every chart also has
+a data table.
+
+```bash
+bb playgrounds guide
+bb playgrounds example bill | bb playgrounds publish --document-stdin
+bb playgrounds example stepper | bb playgrounds publish --playground-stdin
+```
+
+Emit the returned `::playground{id="…"}` directive on its own line in
+an assistant message.
+
+Inputs are saved with each playground on the bb server, so they follow you across
+devices and every open copy updates live. Inputs are context the agent can
+read, never approvals. Published playgrounds are immutable; a revised playground gets
+a new ID. Playgrounds, their state, and their event logs are stored in the plugin
+database, scoped to their thread, and removed when that thread is deleted.
+Forking a thread copies its playgrounds, inputs included, into the fork. The copy
+is independent: changing it doesn't change the original, and deleting the
+original doesn't affect it. A side chat is part of its thread's conversation,
+so it shows the same live playground as the thread.
+
+## Agents can drive playgrounds
+
+```sh
+bb playgrounds state <id>
+bb playgrounds watch <id> --since 0 --wait 20
+bb playgrounds actions <id>
+bb playgrounds do <id> set --args '{"people": 6}'
+```
+
+Native documents expose `set` and `reset`. HTML playgrounds expose their own
+actions with `window.playground.expose()`. `window.playground.send()` attaches data to
+the user's next message as a pill. Commands run in the copy used most
+recently, and the card shows "Agent · <action>" each time the agent acts.
+
+## HTML playgrounds
+
+HTML playgrounds are served from the plugin's `/frame` route and rendered in an
+`<iframe sandbox="allow-scripts">`, so scripts run in an opaque origin with no
+access to bb, its cookies, or the conversation. The route's
+Content-Security-Policy also blocks the network: `default-src 'none'`, inline
+scripts and styles only, `connect-src 'none'`, `form-action 'none'`,
+`base-uri 'none'`, and images only from `data:`, `blob:`, and
+`https://upload.wikimedia.org`. A playground cannot send what you type anywhere,
+and viewing one contacts no third party except Wikimedia for photos it shows.
+
+The frame talks to bb only through `postMessage`, and bb accepts messages only
+from that frame's window:
+
+- Web links and `window.playground.send()` take effect only while the frame has
+  focus and a fresh user activation, at most once per second, so a playground
+  cannot open tabs or insert composer pills while you type elsewhere. Links
+  open through bb's URL handling and only for `http` and `https`.
+- Events and action lists are rate limited per frame. State, events, command
+  results, and shared data are size limited on the server.
+- bb hands the frame the Inter font it already loaded, so playgrounds make no
+  third-party font request.
+- Height is clamped to 4,000 px, frames load lazily, and data shared with the
+  agent is framed as untrusted.