@tilewise/workbench-client 0.1.0 → 0.1.1

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## 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
 
@@ -175,3 +177,35 @@ the app's router takes `basepath: import.meta.env.BASE_URL`.
 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.
+
+### A fake API
+
+```ts
+workbenchLocal({ base: 'develop', api: { entry: '../fake-api/src/index.ts' } });
+```
+
+`entry` is the fake API's module, from the app's folder. Its default export
+is a fetch handler: a function from `Request` to `Response`, or an object
+with `fetch`, as a Hono app is. `path` is where the app asks it, `/api` unless
+set. The handler is asked without that path, so `/api/bags/b1` reaches it as
+`/bags/b1`.
+
+- **Live:** the dev server answers it at `path`, from its source. Vite loads
+  it again when it changes.
+- **Builds:** each build bundles its commit's fake API, 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.

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,16 @@ export interface Build {
     /** The end of the log, when it failed. */
     error?: string;
 }
+/** A fake API beside the app: its module, from the app's folder, and where the app asks it. */
+export interface ApiOption {
+    entry: 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 +27,19 @@ 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. With `api`, a commit that has the
+ * fake API is bundled too, into `.builds/<sha>/__api/`, so its build asks its
+ * own API, whatever the checkout's API has become since.
  */
 export declare function createBuilds(options: {
     root: () => string;
     git: Git;
+    api?: () => 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,16 @@
 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, resolve } from 'node:path';
+import { appFolder } from './appFolder.js';
+import { bundleApi } from './bundleApi.js';
 import { buildEnvironment } from './environment.js';
+import { isWorkspace } from './isWorkspace.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 +26,30 @@ 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. With `api`, a commit that has the
+ * fake API is bundled too, into `.builds/<sha>/__api/`, so its build asks its
+ * own API, whatever the checkout's API has become since.
  */
 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 +137,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 +179,23 @@ 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.
+            const api = options.api?.() ?? null;
+            let built = null;
+            const entry = api ? resolve(app, api.entry) : 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 +225,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/workbenchLocal.d.ts

@@ -15,7 +15,18 @@ 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.
+ *
+ * `api` is a fake API beside the app: `entry`, its module from the app's
+ * folder, whose default export is a fetch handler, and `path`, where the app
+ * asks it (`/api` unless set). The dev server answers it there for Live, from
+ * its source; each build bundles that commit's 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`.
  */
 export declare function workbenchLocal(options?: {
     base?: string;
+    api?: {
+        entry: string;
+        path?: string;
+    };
 }): Plugin;

package/dist/vite/workbenchLocal.js

@@ -1,8 +1,12 @@
 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 { commits, versions } from './versions.js';
@@ -65,12 +69,30 @@ 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.
+ *
+ * `api` is a fake API beside the app: `entry`, its module from the app's
+ * folder, whose default export is a fetch handler, and `path`, where the app
+ * asks it (`/api` unless set). The dev server answers it there for Live, from
+ * its source; each build bundles that commit's 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`.
  */
 export function workbenchLocal(options = {}) {
     let root = process.cwd();
     let git = gitIn(root);
     let server = null;
-    const builds = createBuilds({ root: () => root, git: (...args) => git(...args) });
+    const api = options.api
+        ? {
+            entry: options.api.entry,
+            path: `/${(options.api.path ?? '/api').replace(/^\/+|\/+$/g, '')}`,
+        }
+        : null;
+    const builds = createBuilds({
+        root: () => root,
+        git: (...args) => git(...args),
+        api: () => api,
+    });
+    const workers = createApiWorkers();
     const base = async () => options.base ?? (await defaultBranch(git));
     async function answer(request, response, url) {
         const path = url.pathname;
@@ -109,11 +131,45 @@ 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. */
+    async function answerLiveApi(request, response) {
+        try {
+            if (!api || !server) {
+                return sendJson(response, 404, { error: 'No fake API' });
+            }
+            const module = await server.ssrLoadModule(resolve(root, api.entry));
+            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)) {
@@ -160,9 +216,18 @@ export function workbenchLocal(options = {}) {
             if (ours) {
                 stack.unshift(ours);
             }
+            // Before Vite's own middleware, which would answer the path with the app's page.
+            if (api) {
+                devServer.middlewares.use(api.path, (request, response) => {
+                    void answerLiveApi(request, response);
+                });
+            }
             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.1",
   "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",