mini-apps

name	mini-apps
description	Guide for building custom interactive web apps ("mini apps") displayed in browser tabs — scaffolding, iframe constraints, bidirectional messaging with the sandbox, and iteration workflows.

Mini Apps

Mini apps are custom interactive web apps that render in dedicated stagewise browser tabs. Useful for dashboards, visualizations, forms, interactive tools, and any UI that benefits from rich HTML/CSS/JS beyond plain text.

---

Apps Directory (apps/)

The apps/ mount is always available with full read-write permissions. Each app lives in its own subfolder with index.html as the required entry point. Optional sibling assets (styles.css, script.js, images, etc.) are resolved via relative references.

apps/{appId}/
  index.html      ← entry point (required)
  styles.css      ← optional
  script.js       ← optional

---

Writing App Files

Create and edit app files (index.html, styles.css, script.js), then open or reload via the sandbox with await API.openApp("appId", { title: 'Readable title' }).

---

Iframe Constraints

• Renders inside a dedicated browser tab with normal Stagewise browser chrome.
• The app itself is sandboxed in an app:// iframe inside a trusted stagewise://internal/preview/{appId} shell.
• Design responsively. Always include responsive base styles and a viewport meta tag.

---

Opening Apps (Sandbox)

Use API.openApp(appId, opts?) from the sandbox. The sandbox is used only for opening apps and communicating with them.

Option	Type	Default	Description
pluginId	string	—	Opens a plugin app instead of an agent app
title	string	—	Human-readable tab breadcrumb label
target	'tab'	'tab'	Explicit tab target; retained for compatibility/documentation
setActive	boolean	true	Whether the preview tab should become active immediately

• API.openApp() always opens an internal preview tab with a sandboxed app:// iframe.
• Calling with the same appId opens a refreshed tab — use after editing files.

---

Bidirectional Messaging

Apps and the sandbox communicate via postMessage.

Sandbox → App: API.sendMessage(appId, data, opts?) — sends a JSON-serializable message to the active app.

App → Sandbox: API.onMessage(appId, callback, opts?) — registers a listener for messages the app sends via window.parent.postMessage(data, "*"). Returns an unsubscribe function. Listeners persist across IIFE executions; use globalThis to accumulate messages.

Inside the app (HTML/JS):

• Receive: window.addEventListener("message", (e) => { /* e.data */ })
• Send: window.parent.postMessage({ action: "clicked", id: 1 }, "*")

---

Best Practices

• Sandbox usage: Use the sandbox only for openApp, sendMessage, and onMessage.
• Responsive design: Support both narrow and wide tab widths. Use max-width: 100%, overflow-x: hidden, box-sizing: border-box.
• Viewport meta tag: Always include <meta name="viewport" content="width=device-width, initial-scale=1">.
• File organization: index.html as entry point. Split CSS and JS into separate files for maintainability.
• Message protocol: Define a clear action field to distinguish message types.
• Cleanup listeners: Unsubscribe from API.onMessage when interaction is complete.
• Error handling: Validate incoming messages on both sides. Gracefully handle unexpected data.

References

For detailed examples, see:

• references/examples.md — Full mini app examples (minimal app, multi-file app, interactive picker with messaging)