@tilewise/workbench-client 0.1.0 → 0.1.2

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # Changelog
 
+## 0.1.2 · 2026-11-07 06:11 +04:00
+
+- feat(workbench-client): read the fake API from workbench.json (25e1ad9)
+  - Answer `/api` from the fake API that `viewers.proto.api` in the repository's `workbench.json` declares, from `viewers.proto.folder`, when `workbenchLocal()` is given no `api` option; the option still wins
+  - Read `workbench.json` on each request, so an edit to it counts without restarting Vite
+  - Build each other commit with the fake API its own `workbench.json` declares, else the checkout's
+  - Serve the checkout's setup at `GET /__workbench/setup`, for a workbench without the GitHub App
+  - Describe `workbench.json` in the README's local builds, workspace and fake API sections
+
+## 0.1.1 · 2026-11-06 01:07 +04:00
+
+- feat(workbench-client): build apps in a workspace folder and answer each build's fake API (fc6dba7)
+  - Build each commit from the app's folder in the repository, or from the top for a commit from before the app moved there
+  - Install a workspace commit's own packages, so they link to that commit's and not the checkout's
+  - Keep a commit with no workspace file of its own from taking the checkout's
+  - Run the commit's own Vite, or this plugin's when the commit has none installed
+  - Add the api option: a fake API's fetch handler, answered at /api for Live from its source
+  - Bundle each commit's fake API with its build and answer it under the build, in a worker of its own with no environment, stopped after 30 minutes idle
+  - Never serve the bundle as a file of the build
+  - Describe workspaces and the fake API in README and CLAUDE.md
+- feat(proto,workbench-client): show the app on the iPhone Duo's halves as it folds (e34be11)
+  - Answer the viewer's snapshot with a picture of the screen, handed over as a bitmap, in protocol 4
+  - Take the picture with modern-screenshot, loaded with the first one asked for, leaving out hidden tabs and what's out of view
+  - Ask for a picture before a fold and another once the app is laid out the new way, waiting up to 0.7 s
+  - Show the app as it was on the half that lifts, and laid out the new way on the half that lands
+  - Let the app lay itself out closed under the picture while the Duo shuts, so the closed phone lands lit
+  - Fold dark as before when a build doesn't answer
+  - Read protocol 4 builds as protocol 3's
+
 ## 0.1.0 · 2026-11-03 17:34 +04:00
 
 - Start keeping versions and this changelog

package/README.md

@@ -153,8 +153,10 @@ Mount `<Bridge />` once at the app's root. In the viewer's frame it says
 screen and every value as they change, and does what the viewer asks. It lays
 the app out for the device the viewer draws round it: `--safe-top`,
 `--safe-bottom` and `html[data-platform]`; until a device arrives, the app's
-own CSS holds the first phone's. Outside a frame it only opens the state
-`?at=` names. [docs/protocol.md](docs/protocol.md) has the protocol.
+own CSS holds the first phone's. When the viewer folds a foldable it asks
+for a picture of the screen, to show on the half that swings: the bridge
+takes it with [modern-screenshot](https://github.com/qq15725/modern-screenshot),
+loaded only then. Outside a frame it only opens the state `?at=` names. [docs/protocol.md](docs/protocol.md) has the protocol.
 
 ## Local builds
 
@@ -172,6 +174,67 @@ git-ignored `.builds/<sha>/`, and checks a branch out, refused while
 anything is uncommitted. Builds are served under `/__workbench/b/<sha>/`, so
 the app's router takes `basepath: import.meta.env.BASE_URL`.
 
+It also reads `workbench.json`, at the repository's top, where the
+repository declares its setup: the fake API comes from it (below), and
+`/__workbench/setup` hands the checkout's to the viewer, as `{ name, viewers }`
+(404 without the file, 422 when it isn't a setup), for a workbench that can't
+read it from GitHub.
+
 Only the viewer may ask: from its origin (`WORKBENCH_URL`, or a viewer on
 localhost) with the token in the link the dev server logs. `pnpm dev` opens
 that link; without `WORKBENCH_URL` the dev server opens no viewer.
+
+### An app in a workspace
+
+The app may live in a folder of a pnpm workspace, such as `apps/app/`, with
+its dev server's root there. Each commit is built from that folder, or from
+the top for a commit from before the app moved there. A workspace commit
+installs its own packages (`pnpm install --frozen-lockfile --prefer-offline`),
+so its packages link to that commit's, never the checkout's. The folder is
+the dev server's root, whatever `workbench.json` says, and a local build
+installs and builds as above, without Proto's `install` and `build`.
+
+### A fake API
+
+Declare it in `workbench.json`, at the repository's top, as Proto's `api`:
+
+```json
+{
+  "name": "Aitems",
+  "viewers": {
+    "proto": { "folder": "apps/app", "api": "../fake-api/src/index.ts" }
+  }
+}
+```
+
+`api` is the fake API's module, from Proto's `folder`: the app's folder from
+the top, or the top when it is `''` or left out. Its default export is a
+fetch handler: a function from `Request` to `Response`, or an object with
+`fetch`, as a Hono app is. The app asks it at `/api`, and the handler is
+asked without that path, so `/api/bags/b1` reaches it as `/bags/b1`. With no
+file, a file that isn't a setup, or no `api` in it, there is no fake API and
+`/api` is the app's own.
+
+- **Live:** the dev server answers it at `/api`, from its source. Vite loads
+  it again when it changes, and the file is read on each request, so
+  declaring the API or moving it needs no restart.
+- **Builds:** each build bundles the fake API its commit's own
+  `workbench.json` declares (the checkout's, for a commit with no file of its
+  own), with every package inside it, into `.builds/<sha>/__api/`, and
+  answers it under the build, at `/__workbench/b/<sha>/api/…`. An old build
+  asks the API it was built with, whatever the checkout's has become. The app
+  asks `` `${import.meta.env.BASE_URL}api/…` ``, which is right in both.
+- Each build's API runs in a worker of its own: loaded on its first request
+  and stopped after 30 minutes with nothing asked, so a visit's data lasts
+  until then. The worker gets no environment variables, and the bundle
+  itself is never served.
+
+The `api` option overrides the file, for Live and for a commit with no file
+of its own:
+
+```ts
+workbenchLocal({ base: 'develop', api: { entry: '../fake-api/src/index.ts', path: '/api' } });
+```
+
+`entry` is the module from the app's folder, the dev server's root; `path` is
+where the app asks it, `/api` unless set.

package/dist/bridge/Bridge.d.ts

@@ -3,7 +3,8 @@
  * it says `hello` with the manifest, and again whenever asked; sends `at`,
  * `blocks` and `values` as they change, and `tone` and `height`; does what
  * the viewer asks (`go`, `set`, `reset`), scrolling to the marked part after
- * `set` or `reset`; and lays the app out for the `device`. Outside a frame it
- * only takes `?at=` from the address.
+ * `set` or `reset`; lays the app out for the `device`; and answers `snapshot`
+ * with a picture of the screen. Outside a frame it only takes `?at=` from the
+ * address.
  */
 export declare function Bridge(): null;

package/dist/bridge/Bridge.js

@@ -7,6 +7,7 @@ import { applyDevice } from './device.js';
 import { isFramed, post } from './post.js';
 import { readViewerMessage } from './readViewerMessage.js';
 import { revealControl } from './revealControl.js';
+import { snapshot } from './snapshot.js';
 import { watchScreen } from './watchScreen.js';
 const nothingSent = () => ({ at: null, values: null, blocks: new Map() });
 /** Tells the viewer what changed since it was last told; `answer` sends `values` even when it didn't. */
@@ -41,8 +42,9 @@ function useApp() {
  * it says `hello` with the manifest, and again whenever asked; sends `at`,
  * `blocks` and `values` as they change, and `tone` and `height`; does what
  * the viewer asks (`go`, `set`, `reset`), scrolling to the marked part after
- * `set` or `reset`; and lays the app out for the `device`. Outside a frame it
- * only takes `?at=` from the address.
+ * `set` or `reset`; lays the app out for the `device`; and answers `snapshot`
+ * with a picture of the screen. Outside a frame it only takes `?at=` from the
+ * address.
  */
 export function Bridge() {
     const app = useApp();
@@ -102,6 +104,13 @@ export function Bridge() {
                 case 'device':
                     applyDevice(message);
                     break;
+                case 'snapshot': {
+                    const { id } = message;
+                    void snapshot().then((image) => {
+                        post({ type: 'snapshot', id, image }, image ? [image] : []);
+                    });
+                    break;
+                }
             }
         };
         window.addEventListener('message', onMessage);

package/dist/bridge/post.d.ts

@@ -1,5 +1,5 @@
 import type { AppSays } from '../protocol/types.js';
-/** Says something to the viewer around the frame, tagged as the app's. */
-export declare function post(message: AppSays): void;
+/** Says something to the viewer around the frame, tagged as the app's; `transfer` is handed over, not copied. */
+export declare function post(message: AppSays, transfer?: Transferable[]): void;
 /** Whether the app is in the viewer's frame, rather than a page of its own. */
 export declare const isFramed: () => boolean;

package/dist/bridge/post.js

@@ -1,8 +1,8 @@
 import { FROM_APP } from '../protocol/protocol.js';
-/** Says something to the viewer around the frame, tagged as the app's. */
-export function post(message) {
+/** Says something to the viewer around the frame, tagged as the app's; `transfer` is handed over, not copied. */
+export function post(message, transfer = []) {
     const tagged = { source: FROM_APP, ...message };
-    window.parent.postMessage(tagged, '*');
+    window.parent.postMessage(tagged, '*', transfer);
 }
 /** Whether the app is in the viewer's frame, rather than a page of its own. */
 export const isFramed = () => window.parent !== window;

package/dist/bridge/readViewerMessage.js

@@ -25,6 +25,8 @@ export function readViewerMessage(data) {
             return typeof message['id'] === 'string' ? { type: 'reset', id: message['id'] } : null;
         case 'device':
             return readDevice(message);
+        case 'snapshot':
+            return typeof message['id'] === 'number' ? { type: 'snapshot', id: message['id'] } : null;
         default:
             return null;
     }

package/dist/bridge/snapshot.d.ts

@@ -0,0 +1,7 @@
+/**
+ * A picture of the screen as it is now, for the viewer to show on the half of
+ * a foldable that swings; null if it can't be taken. The library that takes
+ * it loads with the first one asked for, so an app that is never folded never
+ * loads it.
+ */
+export declare function snapshot(): Promise<ImageBitmap | null>;

package/dist/bridge/snapshot.js

@@ -0,0 +1,47 @@
+/**
+ * What the picture needs: the elements drawn, and not wholly below or right of
+ * the window. A hidden tab's are most of an app's, and the slowest to copy.
+ */
+function inView(node) {
+    if (!(node instanceof HTMLElement)) {
+        return true;
+    }
+    if (getComputedStyle(node).display === 'none') {
+        return false;
+    }
+    const { top, left } = node.getBoundingClientRect();
+    return top < window.innerHeight && left < window.innerWidth;
+}
+/**
+ * A picture of the screen as it is now, for the viewer to show on the half of
+ * a foldable that swings; null if it can't be taken. The library that takes
+ * it loads with the first one asked for, so an app that is never folded never
+ * loads it.
+ */
+export async function snapshot() {
+    try {
+        const { createContext, domToCanvas } = await import('modern-screenshot');
+        const context = await createContext(document.documentElement, {
+            width: window.innerWidth,
+            height: window.innerHeight,
+            scale: Math.min(2, window.devicePixelRatio),
+            filter: inView,
+            // Images that haven't loaded, such as lazy ones out of view, aren't waited for: the
+            // picture fetches each one it shows itself.
+            timeout: 1,
+            autoDestruct: true,
+            features: {
+                restoreScrollPosition: true,
+                copyScrollbar: false,
+                // Safari's fix draws the picture again for every image in it, a tenth of a second apart.
+                fixSvgXmlDecode: false,
+            },
+        });
+        // Fetching those images and drawing the picture get the time they need.
+        context.timeout = 3000;
+        return await createImageBitmap(await domToCanvas(context));
+    }
+    catch {
+        return null;
+    }
+}

package/dist/protocol/protocol.d.ts

@@ -1,5 +1,5 @@
 /** The protocol this package speaks. */
-export declare const PROTOCOL = 3;
+export declare const PROTOCOL = 4;
 /**
  * Every message carries `source`, for every app, as builds from before the
  * package send them. Each side ignores any message without the other's tag.

package/dist/protocol/protocol.js

@@ -1,5 +1,5 @@
 /** The protocol this package speaks. */
-export const PROTOCOL = 3;
+export const PROTOCOL = 4;
 /**
  * Every message carries `source`, for every app, as builds from before the
  * package send them. Each side ignores any message without the other's tag.

package/dist/protocol/types.d.ts

@@ -1,6 +1,6 @@
 import type { Control, Value } from '../controls/types.js';
 /**
- * Protocol 3: what the app and the viewer say to each other through
+ * Protocol 4: what the app and the viewer say to each other through
  * `postMessage`, between the frame and the page around it. Any change to a
  * message or to the manifest bumps the protocol, so the viewer can still read
  * older builds.
@@ -67,7 +67,7 @@ export type Tone = 'light' | 'dark';
 /** What the app says. */
 export type AppSays = {
     type: 'hello';
-    protocol: 3;
+    protocol: 4;
     manifest: Manifest;
 } | {
     type: 'at';
@@ -86,6 +86,12 @@ export type AppSays = {
 } | {
     type: 'height';
     height: number;
+}
+/** The screen as it was when asked, at up to twice its size; null when it couldn't be taken. */
+ | {
+    type: 'snapshot';
+    id: number;
+    image: ImageBitmap | null;
 };
 /** What the app says, as sent: tagged `source: 'aitems'`. */
 export type AppMessage = {
@@ -115,6 +121,11 @@ export type ViewerSays = {
 } | {
     type: 'reset';
     id?: string;
+}
+/** A picture of the screen as it is now, answered with the same `id`. */
+ | {
+    type: 'snapshot';
+    id: number;
 };
 /** What the viewer says, as sent: tagged `source: 'aitems-workbench'`. */
 export type ViewerMessage = {

package/dist/vite/apiFetch.d.ts

@@ -0,0 +1,7 @@
+/** What a fake API answers with: the standard fetch handler, as Hono and most servers give one. */
+export type ApiFetch = (request: Request) => Response | Promise<Response>;
+/**
+ * The fetch handler of a fake API's module: its default export, either the
+ * function itself or an object with `fetch`.
+ */
+export declare function apiFetchOf(module: unknown): ApiFetch;

package/dist/vite/apiFetch.js

@@ -0,0 +1,15 @@
+/**
+ * The fetch handler of a fake API's module: its default export, either the
+ * function itself or an object with `fetch`.
+ */
+export function apiFetchOf(module) {
+    const api = module?.default;
+    if (typeof api === 'function') {
+        return api;
+    }
+    const fetch = api?.fetch;
+    if (typeof fetch === 'function') {
+        return fetch.bind(api);
+    }
+    throw new Error('The fake API has no default export with fetch');
+}

package/dist/vite/apiWorkers.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Each build's fake API, run in a worker of its own: loaded on its first
+ * request, kept while it is asked things, so a visit's data stays, and stopped
+ * after `idle` with nothing asked, which frees its memory. A worker gets no
+ * environment, so a bundle sees none of the dev server's settings.
+ */
+export declare function createApiWorkers(idle?: number): {
+    answer: (key: string, file: string, request: Request) => Promise<Response>;
+    loaded: () => string[];
+    stopAll: () => void;
+};

package/dist/vite/apiWorkers.js

@@ -0,0 +1,111 @@
+import { pathToFileURL } from 'node:url';
+import { Worker } from 'node:worker_threads';
+import { apiFetchOf } from './apiFetch.js';
+/** How long a build's fake API stays loaded with nothing asked of it. */
+const IDLE = 30 * 60 * 1000;
+// The worker's code, as CommonJS: it loads the bundle and answers each request with it.
+const SOURCE = `
+const { parentPort, workerData } = require('node:worker_threads');
+const apiFetchOf = ${apiFetchOf.toString()};
+const loaded = import(workerData.url).then(apiFetchOf);
+parentPort.on('message', async ({ id, method, url, headers, body }) => {
+  try {
+    const answer = await (await loaded)(new Request(url, { method, headers, body }));
+    const bytes = await answer.arrayBuffer();
+    const plain = [...answer.headers].filter(([name]) => name !== 'set-cookie');
+    const cookies = answer.headers.getSetCookie().map((value) => ['set-cookie', value]);
+    parentPort.postMessage({ id, status: answer.status, headers: [...plain, ...cookies], body: bytes }, [bytes]);
+  } catch (failure) {
+    parentPort.postMessage({ id, error: String((failure && failure.stack) || failure) });
+  }
+});
+`;
+/**
+ * Each build's fake API, run in a worker of its own: loaded on its first
+ * request, kept while it is asked things, so a visit's data stays, and stopped
+ * after `idle` with nothing asked, which frees its memory. A worker gets no
+ * environment, so a bundle sees none of the dev server's settings.
+ */
+export function createApiWorkers(idle = IDLE) {
+    const running = new Map();
+    let next = 0;
+    function stop(key) {
+        const entry = running.get(key);
+        running.delete(key);
+        if (entry) {
+            if (entry.timer) {
+                clearTimeout(entry.timer);
+            }
+            void entry.worker.terminate();
+        }
+    }
+    function start(key, file) {
+        const worker = new Worker(SOURCE, {
+            eval: true,
+            env: {},
+            workerData: { url: pathToFileURL(file).href },
+        });
+        worker.unref();
+        const entry = { worker, pending: new Map(), timer: null };
+        const failAll = (error) => {
+            for (const [id, resolve] of entry.pending) {
+                resolve({ id, error });
+            }
+            entry.pending.clear();
+        };
+        worker.on('message', (reply) => {
+            entry.pending.get(reply.id)?.(reply);
+            entry.pending.delete(reply.id);
+        });
+        worker.on('error', (failure) => {
+            failAll(failure.stack ?? String(failure));
+            stop(key);
+        });
+        worker.on('exit', () => {
+            failAll('The fake API stopped');
+            if (running.get(key) === entry) {
+                running.delete(key);
+            }
+        });
+        running.set(key, entry);
+        return entry;
+    }
+    /** Asks the fake API in `file`, run once per `key`, and gives its answer. */
+    async function answer(key, file, request) {
+        const entry = running.get(key) ?? start(key, file);
+        if (entry.timer) {
+            clearTimeout(entry.timer);
+        }
+        entry.timer = setTimeout(() => stop(key), idle);
+        entry.timer.unref();
+        const body = request.method === 'GET' || request.method === 'HEAD' ? null : await request.arrayBuffer();
+        const asked = {
+            id: (next += 1),
+            method: request.method,
+            url: request.url,
+            headers: [...request.headers],
+            body,
+        };
+        const reply = await new Promise((resolve) => {
+            entry.pending.set(asked.id, resolve);
+            entry.worker.postMessage(asked, body ? [body] : []);
+        });
+        if ('error' in reply) {
+            return Response.json({ error: reply.error }, { status: 500 });
+        }
+        const empty = reply.status === 204 || reply.status === 304;
+        return new Response(empty ? null : reply.body, {
+            status: reply.status,
+            headers: reply.headers,
+        });
+    }
+    /** The keys of the fake APIs loaded now, for the tests. */
+    const loaded = () => [...running.keys()];
+    /** Stops every fake API, as the dev server closes. */
+    function stopAll() {
+        for (const key of [...running.keys()]) {
+            stop(key);
+        }
+    }
+    return { answer, loaded, stopAll };
+}

package/dist/vite/appFolder.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Where the app is in a commit's tree: at `path`, the app's folder in the
+ * repository as the checkout has it, or at the top for a commit from before
+ * the app moved there. A folder holds the app when it has Vite's index.html.
+ */
+export declare function appFolder(tree: string, path: string): string;

package/dist/vite/appFolder.js

@@ -0,0 +1,11 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+/**
+ * Where the app is in a commit's tree: at `path`, the app's folder in the
+ * repository as the checkout has it, or at the top for a commit from before
+ * the app moved there. A folder holds the app when it has Vite's index.html.
+ */
+export function appFolder(tree, path) {
+    const moved = join(tree, path);
+    return path !== '' && existsSync(join(moved, 'index.html')) ? moved : tree;
+}

package/dist/vite/builds.d.ts

@@ -8,6 +8,17 @@ export interface Build {
     /** The end of the log, when it failed. */
     error?: string;
 }
+/** A fake API beside the app: where its module is, and where the app asks it. */
+export interface ApiOption {
+    /** Its module in a tree of the repository: `top` is the tree's top, `app` the app's folder in it. */
+    entry: (top: string, app: string) => string;
+    path: string;
+}
+/** A build's own fake API: its bundle, and where the build asks it. */
+export interface BuiltApi {
+    file: string;
+    path: string;
+}
 /** A tree's lockfile and the package manager it belongs to: pnpm, or npm for a commit from before a switch. */
 export declare function lockOf(dir: string): Promise<{
     manager: string;
@@ -17,11 +28,20 @@ export declare function lockOf(dir: string): Promise<{
  * Builds any commit of the app, one at a time, in a git worktree under
  * `.builds/work/`, into `.builds/<sha>/`, served under `/__workbench/b/<sha>/`.
  * The checkout and its uncommitted changes are never touched.
+ *
+ * The app may live in a folder of the repository, such as a pnpm workspace's
+ * `apps/app/`: each commit is built from that folder, or from the top for a
+ * commit from before the app moved there. A commit's fake API is bundled too,
+ * into `.builds/<sha>/__api/`, so its build asks its own API, whatever the
+ * checkout's API has become since: the one the commit's own `workbench.json`
+ * declares, else `api`, the checkout's, when the commit has it.
  */
 export declare function createBuilds(options: {
     root: () => string;
     git: Git;
+    api?: () => Promise<ApiOption | null>;
 }): {
+    apiOf: (sha: string) => Promise<BuiltApi | null>;
     buildOf: (sha: string) => Promise<Build>;
     requestBuild: (sha: string, retry?: boolean) => Promise<Build>;
     settled: () => Promise<void>;

package/dist/vite/builds.js

@@ -1,8 +1,17 @@
 import { spawn } from 'node:child_process';
 import { existsSync } from 'node:fs';
 import { appendFile, lstat, mkdir, readdir, readFile, rename, rm, rmdir, symlink, unlink, writeFile, } from 'node:fs/promises';
-import { join } from 'node:path';
+import { createRequire } from 'node:module';
+import { dirname, join, relative } from 'node:path';
+import { appFolder } from './appFolder.js';
+import { bundleApi } from './bundleApi.js';
 import { buildEnvironment } from './environment.js';
+import { isWorkspace } from './isWorkspace.js';
+import { setupApi } from './setup.js';
+/** The Vite this plugin runs in, for a commit that has none of its own installed. */
+const ownVite = () => {
+    return join(dirname(createRequire(import.meta.url).resolve('vite/package.json')), 'bin', 'vite.js');
+};
 /** A tree's lockfile and the package manager it belongs to: pnpm, or npm for a commit from before a switch. */
 export async function lockOf(dir) {
     const pnpm = await readFile(join(dir, 'pnpm-lock.yaml'), 'utf8').catch(() => null);
@@ -18,12 +27,31 @@ export async function lockOf(dir) {
  * Builds any commit of the app, one at a time, in a git worktree under
  * `.builds/work/`, into `.builds/<sha>/`, served under `/__workbench/b/<sha>/`.
  * The checkout and its uncommitted changes are never touched.
+ *
+ * The app may live in a folder of the repository, such as a pnpm workspace's
+ * `apps/app/`: each commit is built from that folder, or from the top for a
+ * commit from before the app moved there. A commit's fake API is bundled too,
+ * into `.builds/<sha>/__api/`, so its build asks its own API, whatever the
+ * checkout's API has become since: the one the commit's own `workbench.json`
+ * declares, else `api`, the checkout's, when the commit has it.
  */
 export function createBuilds(options) {
     const states = new Map();
     const queue = [];
     let busy = false;
     const folder = () => join(options.root(), '.builds');
+    /** A built commit's fake API, or null when it has none. */
+    async function apiOf(sha) {
+        try {
+            const meta = JSON.parse(await readFile(join(folder(), sha, 'meta.json'), 'utf8'));
+            return meta.ok && meta.api
+                ? { file: join(folder(), sha, meta.api.file), path: meta.api.path }
+                : null;
+        }
+        catch {
+            return null;
+        }
+    }
     async function buildOf(sha) {
         const live = states.get(sha);
         if (live) {
@@ -111,25 +139,39 @@ export function createBuilds(options) {
             await dropWork(work);
             await options.git('worktree', 'prune');
             await options.git('worktree', 'add', '--detach', work, sha);
-            await addBasePath(work);
-            // The same lockfile as the checkout: borrow its node_modules. Otherwise the
+            // The worktree is the whole repository; the app is in its folder, or at the top before a move.
+            const top = (await options.git('rev-parse', '--show-toplevel')).trim();
+            const app = appFolder(work, relative(top, root));
+            await addBasePath(app);
+            // A workspace installs, so its packages link to this commit's, not the checkout's. One
+            // package with the same lockfile as the checkout borrows its node_modules. Otherwise the
             // commit installs its own, with the package manager its lockfile belongs to.
-            const ours = await lockOf(root);
+            const ours = await lockOf(top);
             const theirs = await lockOf(work);
-            if (theirs.text !== null &&
+            if (await isWorkspace(work)) {
+                await step(sha, log, 'pnpm', ['install', '--frozen-lockfile', '--prefer-offline'], work, 'pnpm install');
+            }
+            else if (theirs.text !== null &&
                 theirs.text === ours.text &&
-                existsSync(join(root, 'node_modules'))) {
-                await symlink(join(root, 'node_modules'), join(work, 'node_modules'), 'junction');
+                existsSync(join(top, 'node_modules'))) {
+                await symlink(join(top, 'node_modules'), join(work, 'node_modules'), 'junction');
             }
             else if (theirs.manager === 'pnpm') {
-                await step(sha, log, 'pnpm', ['install', '--frozen-lockfile'], work, 'pnpm install');
+                // The worktree sits inside the checkout: a commit with no workspace file of its own
+                // must not take the checkout's for its own.
+                const alone = existsSync(join(work, 'pnpm-workspace.yaml')) ? [] : ['--ignore-workspace'];
+                await step(sha, log, 'pnpm', ['install', '--frozen-lockfile', ...alone], work, 'pnpm install');
             }
             else {
                 await step(sha, log, 'npm', ['ci', '--no-audit', '--no-fund', '--loglevel=error'], work, 'npm ci');
             }
             const temporary = `${out}.tmp`;
             await rm(temporary, { recursive: true, force: true });
-            const vite = join(work, 'node_modules', 'vite', 'bin', 'vite.js');
+            // The commit's own Vite: the app's, then the workspace's, then this plugin's.
+            const vite = [
+                join(app, 'node_modules', 'vite', 'bin', 'vite.js'),
+                join(work, 'node_modules', 'vite', 'bin', 'vite.js'),
+            ].find((file) => existsSync(file)) ?? ownVite();
             const args = [
                 vite,
                 'build',
@@ -139,9 +181,24 @@ export function createBuilds(options) {
                 temporary,
                 '--emptyOutDir',
             ];
-            await step(sha, log, process.execPath, args, work, 'vite build');
+            await step(sha, log, process.execPath, args, app, 'vite build');
+            // Its own fake API, when the commit has one inside the worktree: the one its own
+            // workbench.json declares, else the checkout's.
+            const api = (await setupApi(work)) ?? (await options.api?.()) ?? null;
+            let built = null;
+            const entry = api ? api.entry(work, app) : null;
+            if (api && entry && !relative(work, entry).startsWith('..')) {
+                const file = await bundleApi((more, cwd) => step(sha, log, process.execPath, [vite, ...more], cwd, 'API bundle'), app, entry, join(temporary, '__api'));
+                built = file ? { file: `__api/${file}`, path: api.path } : null;
+            }
             const protocol = (await bundleText(temporary)).includes('aitems-workbench') ? 1 : 0;
-            await writeFile(join(temporary, 'meta.json'), JSON.stringify({ sha, ok: true, protocol, builtAt: new Date().toISOString() }));
+            await writeFile(join(temporary, 'meta.json'), JSON.stringify({
+                sha,
+                ok: true,
+                protocol,
+                builtAt: new Date().toISOString(),
+                ...(built && { api: built }),
+            }));
             await rm(out, { recursive: true, force: true });
             await rename(temporary, out);
             states.set(sha, { state: 'built', protocol });
@@ -171,14 +228,14 @@ export function createBuilds(options) {
             .git('worktree', 'remove', '--force', work)
             .catch(() => rm(work, { recursive: true, force: true }));
     }
-    return { buildOf, requestBuild, settled, folder };
+    return { apiOf, buildOf, requestBuild, settled, folder };
 }
 /**
  * A router made before the app was served under a base path matches nothing
  * there; such a commit's TanStack router is given `import.meta.env.BASE_URL`.
  */
-async function addBasePath(work) {
-    const main = join(work, 'src', 'main.tsx');
+async function addBasePath(app) {
+    const main = join(app, 'src', 'main.tsx');
     if (!existsSync(main)) {
         return;
     }

package/dist/vite/bundleApi.d.ts

@@ -0,0 +1,9 @@
+/** Runs that commit's Vite with these arguments, in that folder. */
+export type RunVite = (args: string[], cwd: string) => Promise<void>;
+/**
+ * Bundles a commit's fake API, `entry`, into `out`: one module with every
+ * package inside it, so it still runs once the commit's worktree is gone.
+ * The commit's own Vite builds it, without the app's config or plugins. Gives
+ * the bundle's file name in `out`, or null when the commit has no fake API.
+ */
+export declare function bundleApi(runVite: RunVite, app: string, entry: string, out: string): Promise<string | null>;

package/dist/vite/bundleApi.js

@@ -0,0 +1,32 @@
+import { existsSync } from 'node:fs';
+import { readdir, rm, writeFile } from 'node:fs/promises';
+import { basename, extname, join } from 'node:path';
+/**
+ * Bundles a commit's fake API, `entry`, into `out`: one module with every
+ * package inside it, so it still runs once the commit's worktree is gone.
+ * The commit's own Vite builds it, without the app's config or plugins. Gives
+ * the bundle's file name in `out`, or null when the commit has no fake API.
+ */
+export async function bundleApi(runVite, app, entry, out) {
+    if (!existsSync(entry)) {
+        return null;
+    }
+    const config = join(app, '.workbench-api.config.mjs');
+    await writeFile(config, `export default ${JSON.stringify({
+        logLevel: 'warn',
+        publicDir: false,
+        build: { ssr: entry, outDir: out, emptyOutDir: true, minify: false, copyPublicDir: false },
+        ssr: { noExternal: true, target: 'node' },
+    })};\n`);
+    try {
+        await runVite(['build', '--config', config], app);
+    }
+    finally {
+        await rm(config, { force: true });
+    }
+    // The bundle is a module wherever it sits, whatever package.json is above it.
+    await writeFile(join(out, 'package.json'), '{ "type": "module" }\n');
+    const name = basename(entry, extname(entry));
+    const files = await readdir(out);
+    return files.find((file) => file === `${name}.js` || file === `${name}.mjs`) ?? null;
+}

package/dist/vite/fetchBridge.d.ts

@@ -0,0 +1,8 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+/**
+ * A Node request as a fetch `Request` for a fake API, at `path`: the part of
+ * the address after the API's mount, with its query.
+ */
+export declare function toRequest(request: IncomingMessage, path: string): Promise<Request>;
+/** Writes a fake API's fetch `Response` to a Node response. */
+export declare function sendResponse(response: ServerResponse, answer: Response): Promise<void>;

package/dist/vite/fetchBridge.js

@@ -0,0 +1,42 @@
+/** Headers Node works out for itself, from what it sends. */
+const COMPUTED = new Set(['content-length', 'transfer-encoding', 'connection']);
+const bodyOf = (request) => {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        request.on('data', (chunk) => chunks.push(chunk));
+        request.on('end', () => resolve(Buffer.concat(chunks)));
+        request.on('error', reject);
+    });
+};
+/**
+ * A Node request as a fetch `Request` for a fake API, at `path`: the part of
+ * the address after the API's mount, with its query.
+ */
+export async function toRequest(request, path) {
+    const method = request.method ?? 'GET';
+    const headers = new Headers();
+    for (const [name, value] of Object.entries(request.headers)) {
+        if (value === undefined) {
+            continue;
+        }
+        for (const each of Array.isArray(value) ? value : [value]) {
+            headers.append(name, each);
+        }
+    }
+    const body = method === 'GET' || method === 'HEAD' ? null : Uint8Array.from(await bodyOf(request));
+    return new Request(new URL(path, 'http://localhost'), { method, headers, body });
+}
+/** Writes a fake API's fetch `Response` to a Node response. */
+export async function sendResponse(response, answer) {
+    response.statusCode = answer.status;
+    answer.headers.forEach((value, name) => {
+        if (!COMPUTED.has(name) && name !== 'set-cookie') {
+            response.setHeader(name, value);
+        }
+    });
+    const cookies = answer.headers.getSetCookie();
+    if (cookies.length > 0) {
+        response.setHeader('set-cookie', cookies);
+    }
+    response.end(Buffer.from(await answer.arrayBuffer()));
+}

package/dist/vite/isWorkspace.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Whether a tree is a pnpm workspace of several packages. A pnpm-workspace.yaml
+ * without `packages` only holds settings for one package.
+ */
+export declare function isWorkspace(tree: string): Promise<boolean>;

package/dist/vite/isWorkspace.js

@@ -0,0 +1,10 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+/**
+ * Whether a tree is a pnpm workspace of several packages. A pnpm-workspace.yaml
+ * without `packages` only holds settings for one package.
+ */
+export async function isWorkspace(tree) {
+    const text = await readFile(join(tree, 'pnpm-workspace.yaml'), 'utf8').catch(() => '');
+    return /^packages\s*:/m.test(text);
+}

package/dist/vite/serveBuild.d.ts

@@ -1,4 +1,7 @@
 import type { ServerResponse } from 'node:http';
 export declare function sendJson(response: ServerResponse, status: number, body: unknown): void;
-/** A file of a build; a path that is no file is the app's own route, so its index. */
+/**
+ * A file of a build; a path that is no file is the app's own route, so its
+ * index. The build's fake API bundle is run, never served.
+ */
 export declare function serveBuild(response: ServerResponse, folder: string, sha: string, rest: string): Promise<void>;

package/dist/vite/serveBuild.js

@@ -19,13 +19,19 @@ export function sendJson(response, status, body) {
     response.setHeader('Cache-Control', 'no-store');
     response.end(JSON.stringify(body));
 }
-/** A file of a build; a path that is no file is the app's own route, so its index. */
+/**
+ * A file of a build; a path that is no file is the app's own route, so its
+ * index. The build's fake API bundle is run, never served.
+ */
 export async function serveBuild(response, folder, sha, rest) {
     const dir = join(folder, sha);
     let file = resolve(dir, `.${decodeURIComponent(rest || '/')}`);
     if (!file.startsWith(dir + sep) && file !== dir) {
         return sendJson(response, 400, { error: 'Bad path' });
     }
+    if (file === join(dir, '__api') || file.startsWith(join(dir, '__api') + sep)) {
+        return sendJson(response, 404, { error: 'Not found' });
+    }
     const isFile = await stat(file).then((found) => found.isFile(), () => false);
     if (!isFile) {
         file = join(dir, 'index.html');

package/dist/vite/setup.d.ts

@@ -0,0 +1,38 @@
+/** What a repository says about itself in `workbench.json` at its top. */
+export interface Setup {
+    /** '' when the file gives none. */
+    name: string;
+    /** In the file's order, each with its string settings. */
+    viewers: {
+        name: string;
+        options: Record<string, string>;
+    }[];
+}
+/**
+ * The `workbench.json` at `top`, read as the workbench reads it: an object,
+ * whose `viewers` is an object of viewers, each named in lower case and with
+ * an object of settings, of which only strings are kept, cut to 500
+ * characters. `missing` without the file, `invalid` when it isn't JSON or
+ * isn't a setup. Read each time, so an edit to it counts at once.
+ *
+ * ```json
+ * { "name": "Aitems", "viewers": { "proto": { "folder": "apps/app", "api": "../fake-api/src/index.ts" } } }
+ * ```
+ */
+export declare function readSetup(top: string): Promise<{
+    state: 'read';
+    setup: Setup;
+} | {
+    state: 'missing' | 'invalid';
+}>;
+/**
+ * The fake API the `workbench.json` at `top` declares: Proto's `api`, its
+ * module from Proto's `folder` ('' or none for the top), answered at `/api`.
+ * `entry` places that module in any tree of the repository, this one or a
+ * build's worktree. Null when the file is missing or no setup, or declares no
+ * fake API.
+ */
+export declare function setupApi(top: string): Promise<{
+    entry: (tree: string) => string;
+    path: string;
+} | null>;

package/dist/vite/setup.js

@@ -0,0 +1,65 @@
+import { readFile } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+/** An object, as JSON has it: not null, not an array. */
+const isObject = (value) => {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+};
+/**
+ * The `workbench.json` at `top`, read as the workbench reads it: an object,
+ * whose `viewers` is an object of viewers, each named in lower case and with
+ * an object of settings, of which only strings are kept, cut to 500
+ * characters. `missing` without the file, `invalid` when it isn't JSON or
+ * isn't a setup. Read each time, so an edit to it counts at once.
+ *
+ * ```json
+ * { "name": "Aitems", "viewers": { "proto": { "folder": "apps/app", "api": "../fake-api/src/index.ts" } } }
+ * ```
+ */
+export async function readSetup(top) {
+    let text;
+    try {
+        text = await readFile(join(top, 'workbench.json'), 'utf8');
+    }
+    catch {
+        return { state: 'missing' };
+    }
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch {
+        return { state: 'invalid' };
+    }
+    if (!isObject(raw) || (raw['viewers'] !== undefined && !isObject(raw['viewers']))) {
+        return { state: 'invalid' };
+    }
+    const name = typeof raw['name'] === 'string' ? raw['name'].trim().slice(0, 80) : '';
+    const viewers = [];
+    for (const [viewer, settings] of Object.entries(isObject(raw['viewers']) ? raw['viewers'] : {})) {
+        if (!/^[a-z][a-z0-9-]*$/.test(viewer) || !isObject(settings)) {
+            return { state: 'invalid' };
+        }
+        const options = {};
+        for (const [key, value] of Object.entries(settings)) {
+            if (typeof value === 'string') {
+                options[key] = value.slice(0, 500);
+            }
+        }
+        viewers.push({ name: viewer, options });
+    }
+    return { state: 'read', setup: { name, viewers } };
+}
+/**
+ * The fake API the `workbench.json` at `top` declares: Proto's `api`, its
+ * module from Proto's `folder` ('' or none for the top), answered at `/api`.
+ * `entry` places that module in any tree of the repository, this one or a
+ * build's worktree. Null when the file is missing or no setup, or declares no
+ * fake API.
+ */
+export async function setupApi(top) {
+    const read = await readSetup(top);
+    const proto = read.state === 'read' ? read.setup.viewers.find((viewer) => viewer.name === 'proto') : null;
+    const api = proto?.options['api']?.trim() ?? '';
+    const folder = proto?.options['folder']?.trim() ?? '';
+    return api === '' ? null : { entry: (tree) => resolve(tree, folder, api), path: '/api' };
+}

package/dist/vite/workbenchLocal.d.ts

@@ -4,6 +4,7 @@ import type { Plugin } from 'vite';
  * also answers the deployed viewer. It lists this machine's branches and
  * commits, builds any commit, and checks a branch out.
  *
+ *   GET  /__workbench/setup              the checkout's workbench.json: { name, viewers }; 404 none, 422 no setup
  *   GET  /__workbench/versions           branches, tags, what is checked out, changed files
  *   GET  /__workbench/commits?ref=<ref>  that ref's history, newest first, each with its build
  *   POST /__workbench/builds/<sha>       build it; asked again, says how it stands (?retry after a failure)
@@ -15,7 +16,23 @@ import type { Plugin } from 'vite';
  * `base` is the branch the others are compared with: the repository's
  * default branch unless set. Builds are served without the token, as a frame
  * can't send a header. Without WORKBENCH_URL, the dev server opens no viewer.
+ *
+ * A fake API beside the app is declared in `workbench.json` at the
+ * repository's top, as Proto's `api`: its module from Proto's `folder`, whose
+ * default export is a fetch handler, asked at `/api`. The dev server answers
+ * it there for Live, from its source, reading the file on each request; each
+ * build bundles the one its commit declares (the checkout's, for a commit with
+ * no file of its own) and answers it under the build, at
+ * `/__workbench/b/<sha>/api/…`. Either way the handler is asked without the
+ * path, so `/api/bags/b1` reaches it as `/bags/b1`.
+ *
+ * The `api` option overrides the file: `entry`, the module from the app's
+ * folder, and `path`, where the app asks it (`/api` unless set).
  */
 export declare function workbenchLocal(options?: {
     base?: string;
+    api?: {
+        entry: string;
+        path?: string;
+    };
 }): Plugin;

package/dist/vite/workbenchLocal.js

@@ -1,10 +1,15 @@
 import { spawn } from 'node:child_process';
 import { randomBytes } from 'node:crypto';
+import { resolve } from 'node:path';
+import { apiFetchOf } from './apiFetch.js';
+import { createApiWorkers } from './apiWorkers.js';
 import { createBuilds } from './builds.js';
 import { checkout } from './checkout.js';
 import { environment } from './environment.js';
+import { sendResponse, toRequest } from './fetchBridge.js';
 import { defaultBranch, gitIn } from './git.js';
 import { sendJson, serveBuild } from './serveBuild.js';
+import { readSetup, setupApi } from './setup.js';
 import { commits, versions } from './versions.js';
 const PREFIX = '/__workbench';
 const SHA = /^[0-9a-f]{7,40}$/;
@@ -54,6 +59,7 @@ function open(url) {
  * also answers the deployed viewer. It lists this machine's branches and
  * commits, builds any commit, and checks a branch out.
  *
+ *   GET  /__workbench/setup              the checkout's workbench.json: { name, viewers }; 404 none, 422 no setup
  *   GET  /__workbench/versions           branches, tags, what is checked out, changed files
  *   GET  /__workbench/commits?ref=<ref>  that ref's history, newest first, each with its build
  *   POST /__workbench/builds/<sha>       build it; asked again, says how it stands (?retry after a failure)
@@ -65,18 +71,65 @@ function open(url) {
  * `base` is the branch the others are compared with: the repository's
  * default branch unless set. Builds are served without the token, as a frame
  * can't send a header. Without WORKBENCH_URL, the dev server opens no viewer.
+ *
+ * A fake API beside the app is declared in `workbench.json` at the
+ * repository's top, as Proto's `api`: its module from Proto's `folder`, whose
+ * default export is a fetch handler, asked at `/api`. The dev server answers
+ * it there for Live, from its source, reading the file on each request; each
+ * build bundles the one its commit declares (the checkout's, for a commit with
+ * no file of its own) and answers it under the build, at
+ * `/__workbench/b/<sha>/api/…`. Either way the handler is asked without the
+ * path, so `/api/bags/b1` reaches it as `/bags/b1`.
+ *
+ * The `api` option overrides the file: `entry`, the module from the app's
+ * folder, and `path`, where the app asks it (`/api` unless set).
  */
 export function workbenchLocal(options = {}) {
     let root = process.cwd();
     let git = gitIn(root);
+    let top = null;
     let server = null;
-    const builds = createBuilds({ root: () => root, git: (...args) => git(...args) });
+    const given = options.api;
+    const option = given
+        ? {
+            entry: (_top, app) => resolve(app, given.entry),
+            path: `/${(given.path ?? '/api').replace(/^\/+|\/+$/g, '')}`,
+        }
+        : null;
+    /** The repository's top, where workbench.json is; null outside a repository. */
+    const topOf = () => {
+        return (top ??= git('rev-parse', '--show-toplevel').then((output) => output.trim() || null, () => null));
+    };
+    /** The checkout's fake API: the option, else the one its workbench.json declares now. */
+    const currentApi = async () => {
+        if (option) {
+            return option;
+        }
+        const at = await topOf();
+        return at === null ? null : setupApi(at);
+    };
+    const builds = createBuilds({
+        root: () => root,
+        git: (...args) => git(...args),
+        api: currentApi,
+    });
+    const workers = createApiWorkers();
     const base = async () => options.base ?? (await defaultBranch(git));
     async function answer(request, response, url) {
         const path = url.pathname;
         if (request.method === 'GET' && path === '/versions') {
             return sendJson(response, 200, await versions(git, await base(), builds.buildOf));
         }
+        if (request.method === 'GET' && path === '/setup') {
+            const at = await topOf();
+            const read = at === null ? { state: 'missing' } : await readSetup(at);
+            if (read.state === 'read') {
+                return sendJson(response, 200, read.setup);
+            }
+            return read.state === 'missing'
+                ? sendJson(response, 404, { error: 'No workbench.json' })
+                : sendJson(response, 422, { error: "workbench.json isn't a setup" });
+        }
         if (request.method === 'GET' && path === '/commits') {
             const ref = url.searchParams.get('ref') ?? 'HEAD';
             if (!REF.test(ref)) {
@@ -109,11 +162,49 @@ export function workbenchLocal(options = {}) {
         }
         return sendJson(response, 404, { error: 'Not found' });
     }
+    /** A build's own fake API, asked at `rest`, the path under the build; false when it has none there. */
+    async function answerBuildApi(request, response, sha, rest, search) {
+        const own = await builds.apiOf(sha);
+        if (!own || (rest !== own.path && !rest.startsWith(`${own.path}/`))) {
+            return false;
+        }
+        try {
+            const asked = await toRequest(request, `${rest.slice(own.path.length) || '/'}${search}`);
+            await sendResponse(response, await workers.answer(sha, own.file, asked));
+        }
+        catch (failure) {
+            sendJson(response, 500, { error: failure.message });
+        }
+        return true;
+    }
+    /**
+     * The fake API for Live, from its source: Vite loads it again when it
+     * changes. Without one, the path is the app's, as if this were not here.
+     */
+    async function answerLiveApi(request, response, next) {
+        try {
+            const api = await currentApi();
+            if (!api || !server) {
+                return next();
+            }
+            const module = await server.ssrLoadModule(api.entry((await topOf()) ?? root, root));
+            const asked = await toRequest(request, request.url ?? '/');
+            await sendResponse(response, await apiFetchOf(module)(asked));
+        }
+        catch (failure) {
+            sendJson(response, 500, { error: failure.message });
+        }
+    }
     async function handle(request, response) {
         const url = new URL(request.url ?? '/', 'http://local');
         const built = /^\/b\/([0-9a-f]{7,40})(\/.*)?$/.exec(url.pathname);
+        const sha = built?.[1] ?? '';
+        const rest = built?.[2] ?? '/';
+        if (built && (await answerBuildApi(request, response, sha, rest, url.search))) {
+            return;
+        }
         if (built && request.method === 'GET') {
-            return serveBuild(response, builds.folder(), built[1] ?? '', built[2] ?? '/');
+            return serveBuild(response, builds.folder(), sha, rest);
         }
         const origin = request.headers.origin;
         if (allowed(origin)) {
@@ -147,6 +238,7 @@ export function workbenchLocal(options = {}) {
         configResolved(config) {
             root = config.root;
             git = gitIn(root);
+            top = null;
         },
         configureServer(devServer) {
             server = devServer;
@@ -160,9 +252,17 @@ export function workbenchLocal(options = {}) {
             if (ours) {
                 stack.unshift(ours);
             }
+            // Before Vite's own middleware, which would answer the path with the app's page. Always
+            // there without the option, so declaring the API in workbench.json needs no restart.
+            devServer.middlewares.use(option?.path ?? '/api', (request, response, next) => {
+                void answerLiveApi(request, response, next);
+            });
             devServer.httpServer?.once('listening', () => {
                 void announce(devServer);
             });
+            devServer.httpServer?.once('close', () => {
+                workers.stopAll();
+            });
         },
     };
     async function announce(devServer) {

package/docs/protocol.md

@@ -1,4 +1,4 @@
-# Protocol 3
+# Protocol 4
 
 The app and the viewer talk through `postMessage`, between the frame and the
 page around it. The types are exported: `Manifest`, `AppMessage` and
@@ -28,11 +28,13 @@ and forms from it alone, so an old commit shows its own screens and controls.
 | `values` | App | `values` | Every control's value, now |
 | `tone` | App | `top`: light or dark | The top of the screen, so the status bar reads on it |
 | `height` | App | `height` | On Full page, how tall the open screen is laid out whole |
+| `snapshot` | App | `id`, `image` (an `ImageBitmap`) or null | The screen as it was when asked |
 | `hello` | Viewer | None | Say your hello again |
 | `device` | Viewer | `insets` (`top`, `bottom`), `platform`, `whole` | The device drawn round the app |
 | `go` | Viewer | `state` | Go to this state |
 | `set` | Viewer | `id`, `value` | Give this control this value |
 | `reset` | Viewer | `id`, or none for all | Put this control back to its default |
+| `snapshot` | Viewer | `id`, a number | Send a picture of the screen as it is now |
 
 - The app says `hello` as it loads in a frame and whenever the viewer says
   `hello`, then sends `at`, `blocks` and `values`. After that it sends each
@@ -44,6 +46,12 @@ and forms from it alone, so an old commit shows its own screens and controls.
   marked `data-control` with its id.
 - The viewer sends `device` after each `hello` and whenever another device is
   picked.
+- The viewer asks for a `snapshot` just before a foldable folds, and again as
+  it opens, once the app has laid itself out open, and shows them on the
+  halves that swing, as the app's frame can't be in two places. The app
+  answers with the same `id` and hands the picture over, at up to twice the
+  screen's size; `image` is null when it can't be taken. A build before
+  protocol 4 doesn't answer, and the viewer folds it dark.
 - Outside a frame the app sends nothing, and only takes `?at=` from the
   address.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tilewise/workbench-client",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Connects a React prototype to the workbench's viewer: its screens, its controls and the protocol between them.",
   "license": "MIT",
   "repository": {
@@ -53,6 +53,9 @@
     "vite": "^8.2.2",
     "vitest": "^4.1.11"
   },
+  "dependencies": {
+    "modern-screenshot": "^4.7.0"
+  },
   "scripts": {
     "build": "tilewise-build",
     "check:circular": "tilewise-madge src",