Learn by example

The fastest way to learn the module platform is to read (and run) the samples in examples/modules/. They're ordered here from "hello world" to a full native-compute worker, and every browser sample is one HTML file with no build step — copy it and start changing things.

How a module works (the 30-second version) #

A module's UI runs in a sandboxed, opaque-origin iframe. It can't touch the platform directly — it can only postMessage the parent window, which runs the trusted capability bridge. Every request is gated by the module's declared permissions. That's the whole security model: declared → (approved) → scoped → audited.

So every browser module starts with the same tiny client:

// The entire bridge client. `call(type, payload)` sends one request and resolves
// with the reply (correlated by a request id). Copy this verbatim.
const PROTOCOL = 1, pending = new Map(); let counter = 0;
function call(type, payload = {}) {
  const rid = `r${++counter}`;
  return new Promise((resolve, reject) => {
    pending.set(rid, { resolve, reject });
    parent.postMessage({ v: PROTOCOL, type, rid, ...payload }, '*');
    setTimeout(() => { if (pending.has(rid)) { pending.delete(rid); reject(new Error('timed out')); } }, 15000);
  });
}
window.addEventListener('message', (e) => {
  const m = e.data; if (!m || !m.rid || typeof m.type !== 'string') return;
  const s = pending.get(m.rid); if (!s) return; pending.delete(m.rid);
  m.ok ? s.resolve(m.data) : s.reject(new Error((m.error && m.error.message) || 'failed'));
});

The samples, easiest first #

Foundations

Single-task demos — one capability each

Each of these is focused on exactly one capability so you can read it in a minute and copy just the part you need. Every browser demo is one ui/index.html with the same inline bridge client above; each README also shows the SDK equivalent.

Combined references (kitchen-sink)

If you'd rather see many capabilities exercised in one place: capability-demo (the core bridge) and advanced-capabilities-demo (the newer data/queue/scheduler messages, with their security gates shown).

A suggested path

1. 1Read `hello-world-webpage`, then any one demo-* — you now understand the iframe, the bridge, and one capability end to end.
2. 2Build something with `inventory-tracker` — the data store is the workhorse for app-like modules (inventory, libraries, task managers). Baseline — declare it and go.
3. 3Reach for the worker demos (demo-worker-basic → demo-task-queue → media-toolkit-worker) when you need real compute — that's where the admin-HIGH grant flow becomes concrete.

Package & install a sample #

A module package is just a zip with hanabi.module.json at its root.

# from the repo root
npm --workspace packages/module-cli run hanabi -- module pack examples/modules/inventory-tracker --out inventory-tracker.zip     # → a .zip

Then in the Toolbox: Module Store → Upload, choose the zip, install, and launch. First-party-style samples with only baseline/consent capabilities (1–5 above) run immediately. Samples that declare admin-approved or admin-HIGH capabilities (#6) must be published and granted first — that's the platform working as designed.

Where to read next #

• converting-apps.md — turn an existing HTML or Python app into a module.
• packaging.md — package a module folder into an uploadable .zip.
• capability-api.md — every bridge message + SDK method, and the capability tier table (baseline / consent / admin / admin-HIGH).
• manifest-reference.md — every hanabi.module.json field.
• worker-guide.md — the server half (the run(inputs, options, ctx) contract).
• developer-guide.md — build, test, publish a module end-to-end.
• limitations.md — the honest boundary of what a module can and can't do.