@imagineers-cards/toolbar
v0.5.0
Published
Embeddable Cards toolbar — capture scribbles, work items, and screenshots from any host app
Readme
@imagineers-cards/toolbar
An embeddable capture toolbar for the Cards ecosystem. Drop it into any host app; in dev/preview it shows a floating launcher (bottom-right) from which you capture scribbles and work items — with a screenshot attached — straight into a Cards project, without leaving the app under test.
It feeds the project inbox (scribbles + work items), not the chain directly. Promote captures into chain cards later in the Cards web app, where the quality bar belongs.
Two ways to add it
1. Hosted script — drop into any repo (no install)
Add one tag. Works in any app, any framework. The script self-mounts, bundling its own React.
<script src="https://www.imagineers.cards/toolbar.js" data-project="katha" defer></script>| Attribute | Required | Default |
| --- | --- | --- |
| data-project | yes | — |
| data-api | no | the production Cards API |
| data-web | no | https://www.imagineers.cards |
| data-enabled | no | true (set "false" to no-op) |
Gate it to dev/preview yourself — only emit the tag when you want it (e.g. behind your framework's environment check).
2. npm component — first-class in a React app
pnpm add @imagineers-cards/toolbarreact and react-dom are peers (>=18). Renders nothing in production by default.
import { CardsToolbar } from '@imagineers-cards/toolbar';
export default function RootLayout({ children }) {
return (
<body>
{children}
<CardsToolbar project="cards" />
</body>
);
}Both channels build from the same source. Regenerate the hosted bundle with
pnpm --filter @imagineers-cards/toolbar publish:hosted (rebuilds and copies it into the web
app's public/).
Props
| Prop | Default | Notes |
| --- | --- | --- |
| project | — (required) | The Cards project slug captures land in. |
| apiBase | https://cards-api.krishnanandb.workers.dev | Cards Worker API. |
| webBase | https://www.imagineers.cards | Hosts the OAuth authorize popup. |
| enabled | NODE_ENV !== 'production' | Force on/off. |
How it works
- Isolation — the UI mounts in a Shadow DOM, so host CSS can't bleed in and the toolbar's styles can't leak out.
- Auth — on first capture the widget opens a popup to
webBase/authorize, runs an OAuth Authorization-Code + PKCE exchange against the Cards API, and stores a short-lived, project-scoped token insessionStorage. The long-lived credential never leaves the Cards origin. - Screenshots — captured in-page with
modern-screenshot(lazy-loaded on click), uploaded to the API's R2 bucket, and referenced by URL on the capture.
Host API requirements
The host origin must be allowed by the API's TOOLBAR_ORIGINS env (* to reflect any,
or a comma-separated allowlist).