render api
Protota is a set of static files on GitHub Pages (https://tuna-os.github.io/protota/).
There is no server-side PNG endpoint: the app renders in the browser, so a
plain curl of any URL returns the HTML shell, never an image. To get a
screenshot, an agent must drive a headless browser (Playwright, Puppeteer, CDP)
and take a screenshot of the rendered page.
Two surfaces exist, and both validate their input loudly. A bad parameter gives visible error text or a rejected promise, never a silently-wrong frame.
1. URL render mode
Adding ?render=1 to the app URL swaps the editor for a chromeless view: no
top bar, panels, bottom bar, or canvas ever mount. One screen renders at 1:1
zoom inside #protota-render-root, anchored at the page origin (0, 0) on a
transparent background.
https://tuna-os.github.io/protota/?render=1&preset=files&width=500&height=440&theme=dark
Parameters
| Param | Values | Default | Meaning |
|---|---|---|---|
render | 1 or true | — (required) | Activates render mode. Anything else loads the editor. |
preset | preset id, e.g. files, settings | the visitor's persisted document | Loads a public preset: gallery source imports (live Blueprint/GtkBuilder import) or any public/presets/<id>.mockup.json. Loaded in-memory only — the visitor's saved document is never overwritten. |
screen | screen id, exact title, or zero-based index | first screen | Selects the screen to render. |
width | integer 100–10000 | the screen's own width | Screen-width override for this render only. |
height | integer 100–10000 | the screen's own height | Screen-height override for this render only. |
theme | light | dark | the document's color scheme | Forces the color scheme. |
width/height are the "states" lever: Adw.Breakpoints evaluate against
the effective dimensions (src/utils/breakpoints.ts). Thus a screen renders
in exactly the adaptive state that it has at that size. For example, the
navigation split view in GNOME Settings collapses its sidebar below its
max-width: 550sp breakpoint.
Readiness contract
The render settles asynchronously (webfonts, icon CSS, custom-element upgrades, preset fetch). Wait for the flag before you take a screenshot:
html[data-protota-ready="true"]— the frame is stable. The same flag the editor publishes; render mode re-publishes it after its own content paints.- On failure (unknown preset/screen, invalid param) the ready flag still
fires and
#protota-render-root [data-protota-render-error]contains visible error text. Check for it — do not screenshot blindly.
Agent recipe (Playwright)
const page = await browser.newPage();
await page.goto('https://tuna-os.github.io/protota/?render=1&preset=settings&width=480&height=600&theme=dark');
await page.waitForSelector('html[data-protota-ready="true"]');
if (await page.locator('[data-protota-render-error]').count()) throw new Error(await page.locator('[data-protota-render-error]').innerText());
await page.locator('#protota-render-root').screenshot({ path: 'settings-narrow-dark.png' });
page.screenshot() of the element is the intended capture path — it is
pixel-faithful (real browser rasterisation, no html2canvas approximation).
2. Programmatic API — protota.renderScreenshot(options)
The live agent handle (window.protota, see src/runtime/agentHandle.ts) can
capture a PNG of any screen of the live document. The capture does not
change the editor: zoom, pan, selection, undo history, and persistence stay
the same. The screen renders into a hidden offscreen container, through the
same renderer + breakpoint-override path that the canvas uses. Then
html2canvas rasterises it, and the API removes the container.
const blob = await protota.renderScreenshot({
screenId: 'Settings', // id or exact title; default: selected screen, else first
width: 480, // integer 100–10000; default: the screen's own size
height: 600,
theme: 'dark', // 'light' | 'dark'; default: the document's scheme
scale: 1, // rasterisation scale (0–4]; default 1 → PNG pixels == CSS pixels
}); // Promise<Blob> (image/png)
Invalid arguments reject with an actionable Error (unknown screens list the
known ones). At scale: 1 the blob decodes to exactly width x height
pixels.
Fidelity limits (honest)
renderScreenshot uses html2canvas, which re-draws the DOM onto a canvas
and does not support everything a real browser paints:
- html2canvas does not support CSS
mask-image. Protota uses CSS masks for symbolic icons. Thus icons can show as solid boxes, or not show. - Box shadows, blend modes, and some gradients are approximate.
For pixel-faithful output, use the URL render mode and take the screenshot in
a real browser. renderScreenshot is for fast feedback loops in the page. For
example, an agent can use it to check the layout/breakpoint state of a screen
that it built.
No server-side rendering — plainly
curl https://tuna-os.github.io/protota/?render=1&preset=files returns the
HTML shell only. A static host has no image endpoint, and never will without
a render service. You must use a headless browser. Local equivalent:
npm run dev and point the browser at
http://localhost:5173/protota/?render=1&….