@goflowstate/widget-sdk
SDK for building widgets that run inside the Flowstate Canvas.
Installation
npm install @goflowstate/widget-sdk
Or via CDN (no bundler required):
<script src="https://unpkg.com/@goflowstate/widget-sdk/dist/canvas-widget-sdk.js"></script>
Quick Start
ESM (bundler / TypeScript)
import { CanvasWidget } from '@goflowstate/widget-sdk';
const widget = await CanvasWidget.init();
// React to display state changes
widget.onStateChange((state) => {
console.log('Widget state:', state); // 'collapsed' | 'expanding' | 'expanded' | 'collapsing'
});
// Expand into modal view
document.getElementById('open-btn')?.addEventListener('click', () => {
widget.requestExpand();
});
Script tag (no bundler)
<script src="canvas-widget-sdk.js"></script>
<script>
CanvasWidget.init().then((widget) => {
widget.onStateChange((state) => console.log(state));
});
</script>
Emitting and Subscribing to Events
const widget = await CanvasWidget.init();
// Broadcast to other widgets on the same canvas
widget.emit('timer:tick', { remaining: 60 });
// Listen for events from other widgets
const unsub = widget.subscribe('timer:tick', (event) => {
console.log(event.topic, event.payload);
});
// Stop listening
unsub();
Persistent Storage
const widget = await CanvasWidget.init();
// Store a value (scoped to this widget installation)
await widget.storage.set('count', 42);
// Retrieve a value
const count = await widget.storage.get('count');
// Remove a value
await widget.storage.delete('count');
AI Completions
Call the platform's models without holding any provider key. Every call is metered and attributed to your publishing org.
const widget = await CanvasWidget.init();
// One-shot completion
const res = await widget.ai.complete({
alias: 'widget.gpt-mini', // widget.* aliases only — never raw model ids
system: 'You summarise kanban boards in one sentence.',
messages: [{ role: 'user', content: boardAsText }],
});
console.log(res.text, res.inputTokens, res.outputTokens);
// Streaming
for await (const ev of widget.ai.stream({
alias: 'widget.haiku',
messages: [{ role: 'user', content: 'Brainstorm three icebreakers.' }],
})) {
if (ev.type === 'text') appendToUi(ev.text);
if (ev.type === 'done') console.log('tokens:', ev.inputTokens, ev.outputTokens);
if (ev.type === 'error') showError(ev.message);
}
Available aliases: widget.haiku (Anthropic, fast), widget.sonnet
(Anthropic, strongest), widget.gpt (OpenAI, strongest), widget.gpt-mini
(OpenAI, fast), widget.gemini (Google, strongest), widget.gemini-mini
(Google, fast), widget.sonar (Perplexity, answers grounded in live web
search), widget.sonar-pro (Perplexity, web-grounded, deeper research).
Aliases are platform-managed; the model behind one can improve without a
code change on your side.
Notes:
maxTokensis clamped server-side to [256, 4096] (default 1024). The floor exists because the OpenAI aliases are reasoning models: a tiny budget gets consumed entirely by invisible reasoning and returns empty text withstopReason: 'length'. If you see empty text, raise the budget.- Breaking out of a
stream()loop cancels the upstream call, so you are not billed for text you stopped reading. - Budget errors surface with messages starting
usage limit reached— catch them to show your own copy.
User Context and Consent
const widget = await CanvasWidget.init();
// Request access to user data
const result = await widget.requestConsent('user:profile', 'Needed to personalise your experience');
if (result.granted) {
console.log('User:', widget.user?.displayName);
}
Notifications
widget.notify('Saved!', { level: 'info', duration: 3000 });
Viewer claims (shell guests)
A session opened from a unishell shell page belongs to a guest whose name,
email or phone the shell has already verified. Those facts arrive on every
state read as state.viewer.claims, and the latest ones are on
session.claims:
const session = CanvasWidget.initSession();
const state = await session.join();
const email = session.claims?.email; // { type, value, source, verifiedAt? } | undefined
Claims are only ever the reader's own, and they are context, not
authorization. session.claims is null for members, for PWA guests and
before the first state arrives.
Flow feedback (the bug icon)
A flow that calls CanvasWidget.initSession() carries the feedback icon with no code of its own.
While the ring has feedback switched on, the session state says so and the SDK puts a round
button in the corner of the page. A tap opens a sheet with one field at once and takes a
screenshot of the page behind it, and neither the icon nor the sheet is in it. The sheet says each
step: corner marks frame the page and the slot reads "Taking a screenshot" (up to 15 seconds),
then "Screenshot attached" with the picture and a check, or "No screenshot" with "Take
screenshot" when it could not be taken or was removed. The button reads "Sending" while the note
goes out, and the sheet ends on "Feedback sent" before it closes. The note is sent through the flow's session to POST /api/w/:slug/feedback.
The icon and the sheet take the look of the page they sit on: its fonts, ground, ink, the fill
and shape of its main button, and its corner radius. To pin a role, set a custom property on
:root:
:root {
--fs-feedback-cta: #5136c4; /* also -cta-ink, -ground, -ink, -font, -font-display, -radius */
--fs-feedback-bottom: 96px; /* where the icon sits; also -right */
}
The sheet's type comes from the words the flow is drawing, not from <body>: the title takes
the face, weight and letter spacing of the flow's largest heading, the note and the field take
the face most of the flow's smaller text is set in, and the send button takes the face, weight,
letter spacing and case of the flow's main button. Pin --fs-feedback-font or
--fs-feedback-font-display when the reading is off.
The button floats over the flow and belongs to the person using it. They can drag it anywhere, and it settles on the nearer side. A flick at an edge, or a drag into one, docks it there as a slim tab with the bug still showing; a tap on the tab opens the sheet, and pulling the tab inward floats it again. The sheet also has a "Tuck the button to the side" link. Where a person leaves the button is remembered.
Until a person moves it, the button keeps clear of the page's own controls. It starts in the bottom corner and, whenever
the page changes, resizes or stops scrolling, looks up the right edge for the lowest spot that is empty. It sits over a line of text only
when empty space is far above it, and on a control only when the whole edge is controls. Pinning
--fs-feedback-bottom turns that off and holds the icon where the flow puts it.
To take the icon off one screen of a flow (a film, a full-screen picture), set
--fs-feedback-display: none from the flow's stylesheet while that screen is up, for example
:root:has(.film) { --fs-feedback-display: none; }.
Name each screen so a report says where it came from: document.body.dataset.pageKey = 'question-2'.
A page that must not show the icon (a projected wall) sets <html data-fs-feedback="off">.
Full API Reference
See the Flowstate developer docs for the complete API reference, the manifest format, the AI integration guide, and the submission pipeline.
License
MIT