Interactive Plotwork diagrams in your own pages and apps

Pan, zoom, trace and drill into the diagrams your team and your AI agents keep in Plotwork,
from your repository or your organisation's library, kept current when a new version is published.

Website  ·  Docs  ·  Viewer reference  ·  Vite plugin  ·  API client  ·  Python  ·  Picture contract  ·  Examples

_{The real component in an app, recorded by pnpm film. Select it to watch on YouTube. New to Plotwork? Watch the product film.}

TL;DR

Question	Answer
What is it?	<plotwork-diagram>, a web component, and <PlotworkDiagram> for React, that show any picture the Plotwork engine drew, with the interactions of the Plotwork portal.
Where do pictures come from?	A file in your repository, a hosted picture, a stable link, or your organisation's library through an embed link.
Does it stay current?	Add live: it checks for a new version every minute while the page is in view, and swaps it in without a reload.
What does it install?	Nothing else. No runtime dependencies, React as an optional peer, and every release is published from CI with a signed provenance statement.
Does it phone home?	No. It fetches only the address you give it, with no cookie.
Can a picture run script in my page?	No. It is shown as an image, and the element never builds markup from text.
Private diagrams in an app?	Sign in with Plotwork: your people sign in with their own Plotwork account, and <plotwork-library> and the viewer's token show their diagrams, private ones included, with no API key in the page.
Other languages?	Every package is built against spec/, one contract and one set of fixtures for every language.

What it does

Pan and zoom Drag, pinch, wheel, double press and the keys. It fits the diagram to its box and keeps it fitted as the page resizes.	Trace a box's lines Hover or press a box: everything else steps back, and its lines, labels and the boxes at the other end light up.	Drill into a part A box that names a part of its series (part=) sends plotwork-drill, and your page opens the detail.
Live updates Revalidates the address on an interval. An unchanged diagram costs a 304; a new version swaps in and keeps your view.	Pin a version fingerprint="sha256-..." shows the diagram only when it is exactly that one, like subresource integrity.	Light and dark Follows the page, or is forced with theme. Themed through --plotwork-* properties and ::part.
Safe by construction The picture is an image from a blob: address, so nothing in it runs. No cookie, no third party.	Accessible One tab stop with a name, labelled controls, traces and updates said politely, reduced motion honoured, any language.	Zero dependencies 54 kB packed, plain ES modules with types. Works with any bundler, or none.

See it

_{A checkout flow in <plotwork-diagram>, with the pointer over Orders API.}

Quick start

npm install @plotwork.official/viewer

Any page

<script type="module">
  import '@plotwork.official/viewer/register'
</script>

<plotwork-diagram src="/diagrams/checkout.svg" label="Checkout flow"></plotwork-diagram>

React

import { PlotworkDiagram } from '@plotwork.official/viewer/react'

export function Architecture() {
  return (
    <PlotworkDiagram
      src="https://cdn.plotwork.dev/l/<your stable link>.svg"
      live
      onDrill={({ part }) => openPart(part)}
    />
  )
}

A .diagram file in a Vite app

// vite.config.ts
import { plotwork } from '@plotwork.official/vite'
export default defineConfig({ plugins: [plotwork()] })

import checkout from './diagrams/checkout.diagram'

<PlotworkDiagram svg={checkout} />

Script the API

import { Plotwork } from '@plotwork.official/sdk'

const plotwork = new Plotwork({ apiKey: process.env.PLOTWORK_API_KEY })
const checked = await plotwork.diagrams.validate({ source })

import os

from plotwork import Plotwork

plotwork = Plotwork(api_key=os.environ["PLOTWORK_API_KEY"])
checked = plotwork.diagrams.validate(source=source)

Sign in with Plotwork, for an app whose people have Plotwork accounts:

import { Plotwork } from '@plotwork.official/sdk'
import { authorizeUrl, createPkce, exchangeCode, parseRedirect, withRefresh } from '@plotwork.official/sdk/oauth'
import { PlotworkLibrary } from '@plotwork.official/viewer/react'

// Send the person to Plotwork, then trade the code they come back with for their own tokens.
const pkce = await createPkce()
const { url, state } = authorizeUrl({ clientId, redirectUri, scopes: ['library:read'], codeChallenge: pkce.challenge })
const tokens = await exchangeCode({ clientId, code: parseRedirect(location.href, state), redirectUri, codeVerifier: pkce.verifier })
const token = withRefresh(tokens, { clientId, onRefresh: save })

const plotwork = new Plotwork({ accessToken: token })
<PlotworkLibrary token={token} onSelect={({ pictureUrl }) => show(pictureUrl)} />

An API key stays on a server; a token from Sign in with Plotwork is the person's own and fine in a browser. The API client has the full server and browser examples, and the Next.js and React and Vite examples run them.

The viewer renders as the bare element on a server and comes alive in the browser. Every attribute, method, event and style hook is in the viewer reference.

Examples

Apps to clone, add your API key or app to, and run. Each installs the packages from npm as your project would, and CI builds each against every change.

Next.js Sign in with Plotwork as a confidential app, and a route handler that checks and draws with the API client; no key or token reaches the browser.

React and Vite A .diagram file bundled at build time with drill and trace events, Sign in with Plotwork with no server, and a playground through the dev server.

The vanilla page shows the element with no framework. All three are listed in examples/.

Where the pictures come from

You want	Use
The diagram in your repository, redrawn with the code	The Plotwork command line or GitHub Action writes the SVG; point src at it.
The latest published version, without a redeploy	A stable link (cdn.plotwork.dev/l/...) with live.
A private diagram from your organisation's library	An embed link (cdn.plotwork.dev/o/...) the owner made for your site, with live. Other sites get a placeholder, and the source is never sent.
Exactly one version, refused if it changes	fingerprint="sha256-...".

How live updates work

The viewer only checks while its page is in view, never more often than every 15 seconds, and a check that fails leaves the diagram on screen.

Packages

Package	Status	What it is
@plotwork.official/viewer		<plotwork-diagram>, <PlotworkDiagram> for React, <plotwork-library> (/library), a picker of a signed-in person's diagrams, and the core with no element (/core).
@plotwork.official/vite		import checkout from './checkout.diagram': drawn at build time by the command line and redrawn on save, so no engine reaches the browser.
@plotwork.official/sdk		Every /v1 operation of the Plotwork API, typed from its OpenAPI document, on fetch alone, and Sign in with Plotwork (/oauth).
plotwork on PyPI		Every /v1 operation of the Plotwork API from Python, typed from the same OpenAPI document, on the standard library alone, and Sign in with Plotwork (plotwork.oauth).

Supply chain

Measure	Where
No runtime dependencies in any published package, on npm or PyPI; CI fails if one appears	scripts/check-no-runtime-dependencies.mjs
The Python package published only from CI by PyPI trusted publishing, with PEP 740 attestations	.github/workflows/publish-python.yml
Published only from CI by npm trusted publishing (OIDC, no token), with a signed provenance statement	.github/workflows/publish.yml
Exact versions, frozen lockfile, no install scripts	.npmrc, CI
New dependency versions wait a week	pnpm-workspace.yaml, renovate.json
Every action pinned to a commit	.github/workflows/

Check a release yourself with npm audit signatures after installing it.

Develop

git clone git@github.com:plotwork-official/plotwork-sdk.git
cd plotwork-sdk
pnpm install
pnpm check

pnpm shots draws the screenshots above from the real component. The diagrams in this README are Plotwork source in docs/diagrams/, drawn by the command line. The repository follows the engineering standards in .standards/; see CLAUDE.md.

Community

See also

Page	Why
Viewer reference	Attributes, events, theming, content security policy
Vite plugin	Importing .diagram files, options, hot reload
API client	Every /v1 call, errors, retries, Sign in with Plotwork
Python client	The same calls from Python
Examples	Next.js, React and Vite, and a plain page
Picture contract	What every SDK reads from a picture
Editor design	A proposed @plotwork.official/editor: edit a .diagram in a page and see it redrawn
Plotwork docs	Writing diagrams, the command line, the MCP server, organisations

_{MIT licence. Cloud provider names and icons in diagrams are trademarks of their owners.}