@client-compose/client 0.3.0 → 0.5.0

package/README.md

@@ -66,6 +66,37 @@ Props aren't validated at runtime; generate types with
 [`@client-compose/codegen`](https://www.npmjs.com/package/@client-compose/codegen) to keep them in
 sync with the composer.
 
+## Testing
+
+`@client-compose/client/testing` is a fake composer for tests, with no test framework of its own.
+`createFakeGateway` answers screen and action requests from handlers and records them; pass its
+`fetch` to the client. Build responses with `island`, `islandError`, `screen`, `screenError`,
+`actionOk`, `actionError` and `actionFailure`, typed by the generated descriptors.
+
+```ts
+import { actionError, createFakeGateway } from "@client-compose/client/testing";
+
+const gateway = createFakeGateway({
+  actions: { follow: () => actionError(FollowUserV1, { code: "blocked" }) },
+});
+const res = await callAction(baseUrl, FollowUserV1, { userId }, { client, fetch: gateway.fetch });
+assert.equal(gateway.actionRequests()[0].input.userId, userId);
+```
+
+For code that calls the global `fetch` itself, such as a whole app rendered in a test,
+`installFakeGateway(handlers)` puts the fake composer in its place; call `restore()` afterwards.
+
+For React, `@client-compose/react/testing` adds a provider config built around it.
+
+## Through your own server
+
+`@client-compose/client/proxy` passes a browser's screen and action requests to the composer
+through your server, so it can add what the browser mustn't hold, such as a session kept in an
+httpOnly cookie. `createComposerProxy({ baseUrl, client, headers, onActionResponse })` checks each
+request (anyone can call a server endpoint with anything), sets the client context and headers,
+and returns the composer's failures as data. `@client-compose/react`'s `viaProxy` is the browser
+half.
+
 ## Links
 
 - [Protocol spec](https://github.com/client-compose/client-compose/blob/main/spec/PROTOCOL.md)

package/dist/proxy.d.ts

@@ -0,0 +1,41 @@
+import { type ActionRequest, type ActionResponse, type ClientContext, type ScreenRequest, type ScreenResponse } from "@client-compose/protocol";
+/** A screen request from the browser: the server sets the client context. */
+export type ProxiedScreenRequest = Omit<ScreenRequest, "client">;
+/** An action request from the browser: the server sets the client context. */
+export type ProxiedActionRequest = Omit<ActionRequest, "client">;
+/** The composer's response, or the status and body it failed with. */
+export type ProxyResult<T> = {
+    ok: true;
+    response: T;
+} | {
+    ok: false;
+    status: number;
+    body: string;
+};
+export interface ComposerProxyOptions {
+    /** Composer base URL. */
+    baseUrl: string;
+    /** The client context for each request, e.g. with the locale from the request's cookies. */
+    client: () => ClientContext | Promise<ClientContext>;
+    /** Extra headers for each request, e.g. `Authorization` from a session cookie. */
+    headers?: () => Record<string, string> | Promise<Record<string, string>>;
+    /** Extra options for every request, e.g. `{ cache: "no-store" }`. */
+    requestInit?: RequestInit & Record<string, unknown>;
+    /** Custom fetch implementation. Defaults to the global `fetch`. */
+    fetch?: typeof fetch;
+    /**
+     * Sees each action's response (ok or a declared error) before the browser does, and returns
+     * what the browser gets: e.g. keep a new session in a cookie, and take its token out.
+     */
+    onActionResponse?: (request: ActionRequest, response: ActionResponse) => ActionResponse | Promise<ActionResponse>;
+}
+export interface ComposerProxy {
+    /** Checks a browser's action request, then performs it with the server's context and headers. */
+    performAction(body: unknown): Promise<ProxyResult<ActionResponse>>;
+    /** Checks a browser's screen request, then loads it with the server's context and headers. */
+    loadScreen(body: unknown): Promise<ProxyResult<ScreenResponse>>;
+}
+export declare function isProxiedScreenRequest(value: unknown): value is ProxiedScreenRequest;
+export declare function isProxiedActionRequest(value: unknown): value is ProxiedActionRequest;
+export declare function createComposerProxy(options: ComposerProxyOptions): ComposerProxy;
+//# sourceMappingURL=proxy.d.ts.map

package/dist/proxy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"proxy.d.ts","sourceRoot":"","sources":["../src/proxy.ts"],"names":[],"mappings":"AAeA,OAAO,EAEL,KAAK,aAAa,EAClB,KAAK,cAAc,EAEnB,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,KAAK,cAAc,EACpB,MAAM,0BAA0B,CAAC;AAGlC,6EAA6E;AAC7E,MAAM,MAAM,oBAAoB,GAAG,IAAI,CAAC,aAAa,EAAE,QAAQ,CAAC,CAAC;AACjE,8EAA8E;AAC9E,MAAM,MAAM,oBAAoB,GAAG,IAAI,CAAC,aAAa,EAAE,QAAQ,CAAC,CAAC;AAEjE,sEAAsE;AACtE,MAAM,MAAM,WAAW,CAAC,CAAC,IAAI;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,EAAE,CAAC,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAErG,MAAM,WAAW,oBAAoB;IACnC,yBAAyB;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,4FAA4F;IAC5F,MAAM,EAAE,MAAM,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;IACrD,kFAAkF;IAClF,OAAO,CAAC,EAAE,MAAM,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACzE,qEAAqE;IACrE,WAAW,CAAC,EAAE,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACpD,mEAAmE;IACnE,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;IACrB;;;OAGG;IACH,gBAAgB,CAAC,EAAE,CAAC,OAAO,EAAE,aAAa,EAAE,QAAQ,EAAE,cAAc,KAAK,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;CACnH;AAED,MAAM,WAAW,aAAa;IAC5B,iGAAiG;IACjG,aAAa,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,WAAW,CAAC,cAAc,CAAC,CAAC,CAAC;IACnE,8FAA8F;IAC9F,UAAU,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,WAAW,CAAC,cAAc,CAAC,CAAC,CAAC;CACjE;AAgBD,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,oBAAoB,CAQpF;AAED,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,oBAAoB,CASpF;AASD,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,oBAAoB,GAAG,aAAa,CA8BhF"}

package/dist/proxy.js

@@ -0,0 +1,80 @@
+// Passing a browser's screen and action requests to the composer through your own server, e.g. a
+// Next.js Server Action or a Remix action. The server adds what the browser mustn't hold (a session
+// kept in an httpOnly cookie) and vouches for the client context, so the browser's is ignored.
+//
+//     const proxy = createComposerProxy({
+//       baseUrl: COMPOSER_URL,
+//       client: async () => ({ platform: "web", appVersion, locale: await getLocale() }),
+//       headers: async () => ({ Authorization: `Bearer ${await getSessionToken()}` }),
+//     });
+//     export async function performAction(body: unknown) { return proxy.performAction(body); }
+//
+// Anyone can call a server endpoint with anything, so requests are checked before they're sent on.
+// Errors come back as data, since frameworks often strip thrown errors' details on the way to the
+// browser.
+import { PROTOCOL_VERSION, } from "@client-compose/protocol";
+import { ActionFetchError, fetchAction, fetchScreen, ScreenFetchError } from "./index.js";
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+function isCapabilities(value) {
+    return (isRecord(value) &&
+        Object.values(value).every((versions) => Array.isArray(versions) && versions.every((v) => typeof v === "number")));
+}
+function isStringRecord(value) {
+    return isRecord(value) && Object.values(value).every((v) => typeof v === "string");
+}
+export function isProxiedScreenRequest(value) {
+    return (isRecord(value) &&
+        value.protocol === PROTOCOL_VERSION &&
+        typeof value.screen === "string" &&
+        (value.params === undefined || isStringRecord(value.params)) &&
+        isCapabilities(value.islands));
+}
+export function isProxiedActionRequest(value) {
+    return (isRecord(value) &&
+        value.protocol === PROTOCOL_VERSION &&
+        typeof value.action === "string" &&
+        typeof value.version === "number" &&
+        "input" in value &&
+        (value.idempotencyKey === undefined || typeof value.idempotencyKey === "string"));
+}
+/** What the composer itself answers to a malformed request. */
+const BAD_REQUEST = {
+    ok: false,
+    status: 400,
+    body: JSON.stringify({ protocol: PROTOCOL_VERSION, error: { code: "bad_request" } }),
+};
+export function createComposerProxy(options) {
+    async function init() {
+        const headers = (await options.headers?.()) ?? {};
+        return { ...options.requestInit, headers: { ...options.requestInit?.headers, ...headers } };
+    }
+    async function performAction(body) {
+        if (!isProxiedActionRequest(body))
+            return BAD_REQUEST;
+        const request = { ...body, client: await options.client() };
+        try {
+            const response = await fetchAction(options.baseUrl, request, await init(), options.fetch);
+            return { ok: true, response: (await options.onActionResponse?.(request, response)) ?? response };
+        }
+        catch (error) {
+            if (error instanceof ActionFetchError)
+                return { ok: false, status: error.status, body: error.body };
+            throw error;
+        }
+    }
+    async function loadScreen(body) {
+        if (!isProxiedScreenRequest(body))
+            return BAD_REQUEST;
+        const request = { ...body, client: await options.client() };
+        try {
+            return { ok: true, response: await fetchScreen(options.baseUrl, request, await init(), options.fetch) };
+        }
+        catch (error) {
+            if (error instanceof ScreenFetchError)
+                return { ok: false, status: error.status, body: error.body };
+            throw error;
+        }
+    }
+    return { performAction, loadScreen };
+}
+//# sourceMappingURL=proxy.js.map

package/dist/proxy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"proxy.js","sourceRoot":"","sources":["../src/proxy.ts"],"names":[],"mappings":"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"}

package/dist/testing.d.ts

@@ -0,0 +1,70 @@
+import { type ActionDescriptor, type ActionEffects, type Capabilities, type ClientContext, type DeclaredError, type IslandDescriptor, type IslandEntry, type IslandError, type ScreenMeta } from "@client-compose/protocol";
+/** A response for the fake composer to send. */
+export interface FakeResponse {
+    status: number;
+    body: unknown;
+}
+/** A request the fake composer received. */
+export interface RecordedRequest {
+    url: string;
+    method: string;
+    /** Header names are lower case. */
+    headers: Record<string, string>;
+    /** The JSON body, parsed; or the raw body when it isn't JSON (e.g. a multipart upload). */
+    body: unknown;
+}
+export interface RecordedScreenRequest extends RecordedRequest {
+    screen: string;
+    params: Record<string, string>;
+    client: ClientContext | undefined;
+    islands: Capabilities;
+}
+export interface RecordedActionRequest extends RecordedRequest {
+    action: string;
+    version: number;
+    input: unknown;
+    client: ClientContext | undefined;
+    idempotencyKey: string | undefined;
+}
+export interface FakeGatewayHandlers {
+    /** By screen id. */
+    screens?: Record<string, (request: RecordedScreenRequest) => FakeResponse>;
+    /** By action name. */
+    actions?: Record<string, (request: RecordedActionRequest) => FakeResponse>;
+    /** Anything else, e.g. uploads to storage: return undefined to leave a request to the others. */
+    other?: (request: RecordedRequest) => FakeResponse | undefined;
+}
+export interface FakeGateway {
+    /** Use as the client's `fetch`. Requests without a handler reject, failing the test. */
+    fetch: typeof fetch;
+    /** Every request received, in order. */
+    requests: RecordedRequest[];
+    screenRequests(): RecordedScreenRequest[];
+    actionRequests(): RecordedActionRequest[];
+}
+/** A composer whose screens and actions are the handlers given. */
+export declare function createFakeGateway(handlers?: FakeGatewayHandlers): FakeGateway;
+export interface InstalledFakeGateway extends FakeGateway {
+    /** Puts back the `fetch` that was there before. */
+    restore(): void;
+}
+/**
+ * A fake composer installed as the global `fetch`, for code that fetches by itself (e.g. a whole
+ * app rendered in a test). Call `restore()` after the test.
+ */
+export declare function installFakeGateway(handlers?: FakeGatewayHandlers): InstalledFakeGateway;
+/** An island in a screen response, typed by its generated descriptor. */
+export declare function island<P>(key: string, descriptor: IslandDescriptor<P>, props: P): IslandEntry<P>;
+/** An island that failed on the composer (spec §3.4). */
+export declare function islandError(key: string, descriptor: IslandDescriptor<unknown>, error: IslandError): IslandEntry;
+/** A screen response. */
+export declare function screen(id: string, islands: IslandEntry<unknown>[], meta?: ScreenMeta): FakeResponse;
+/** A screen request that fails, e.g. `screenError(404, "not_found")` or `screenError(401, "unauthenticated")`. */
+export declare function screenError(status: number, code: string): FakeResponse;
+/** An action that succeeded, with its result typed by the descriptor. */
+export declare function actionOk<I, R, E extends DeclaredError>(action: ActionDescriptor<I, R, E>, result: R, effects?: ActionEffects): FakeResponse;
+/** An action that ended with one of its declared errors. */
+export declare function actionError<I, R, E extends DeclaredError>(action: ActionDescriptor<I, R, E>, error: E): FakeResponse;
+/** An action the composer didn't perform, e.g. `actionFailure(401, "unauthenticated")` (spec §5.4). */
+export declare function actionFailure(status: number, code: string): FakeResponse;
+//# sourceMappingURL=testing.d.ts.map

package/dist/testing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"testing.d.ts","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"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"}

package/dist/testing.js

@@ -0,0 +1,160 @@
+// Test helpers for apps built on Client Compose: a fake composer that answers screen and action
+// requests from handlers and records them, and builders for the responses it returns. No test
+// framework of its own, so it works with node:test, Jest, Vitest, Playwright and others.
+//
+//     const gateway = createFakeGateway({
+//       screens: { profile: () => screen("profile", [island("header", ProfileHeaderV1, { name: "Ada" })]) },
+//       actions: { follow: () => actionOk(FollowUserV1, { followers: 8 }) },
+//     });
+//     // pass gateway.fetch as the client's fetch, then assert on gateway.actionRequests()
+//
+// For code that uses the global fetch itself, `installFakeGateway` puts one in its place.
+import { PROTOCOL_VERSION, } from "@client-compose/protocol";
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+function strings(value) {
+    if (!isRecord(value))
+        return {};
+    return Object.fromEntries(Object.entries(value).filter((e) => typeof e[1] === "string"));
+}
+function capabilities(value) {
+    if (!isRecord(value))
+        return {};
+    return Object.fromEntries(Object.entries(value).map(([type, versions]) => [
+        type,
+        Array.isArray(versions) ? versions.filter((v) => typeof v === "number") : [],
+    ]));
+}
+function clientContext(value) {
+    if (!isRecord(value) || typeof value.platform !== "string" || typeof value.appVersion !== "string")
+        return undefined;
+    return { ...value, platform: value.platform, appVersion: value.appVersion };
+}
+function parseBody(body) {
+    if (typeof body !== "string")
+        return body;
+    try {
+        return JSON.parse(body);
+    }
+    catch {
+        return body;
+    }
+}
+function urlOf(input) {
+    if (typeof input === "string")
+        return input;
+    return input instanceof URL ? input.href : input.url;
+}
+function headersOf(init) {
+    const out = {};
+    new Headers(init).forEach((value, name) => (out[name] = value));
+    return out;
+}
+function asScreenRequest(request) {
+    const { body } = request;
+    if (!request.url.includes("/screens/") || !isRecord(body) || typeof body.screen !== "string")
+        return undefined;
+    return {
+        ...request,
+        screen: body.screen,
+        params: strings(body.params),
+        client: clientContext(body.client),
+        islands: capabilities(body.islands),
+    };
+}
+function asActionRequest(request) {
+    const { body } = request;
+    if (!request.url.includes("/actions/") || !isRecord(body) || typeof body.action !== "string")
+        return undefined;
+    return {
+        ...request,
+        action: body.action,
+        version: typeof body.version === "number" ? body.version : 0,
+        input: body.input,
+        client: clientContext(body.client),
+        idempotencyKey: typeof body.idempotencyKey === "string" ? body.idempotencyKey : undefined,
+    };
+}
+function respond(response) {
+    return new Response(JSON.stringify(response.body), {
+        status: response.status,
+        headers: { "content-type": "application/json" },
+    });
+}
+/** A composer whose screens and actions are the handlers given. */
+export function createFakeGateway(handlers = {}) {
+    const requests = [];
+    async function fakeFetch(input, init) {
+        const request = {
+            url: urlOf(input),
+            method: init?.method ?? "GET",
+            headers: headersOf(init?.headers),
+            body: parseBody(init?.body),
+        };
+        requests.push(request);
+        const other = handlers.other?.(request);
+        if (other)
+            return respond(other);
+        const screenRequest = asScreenRequest(request);
+        const screenHandler = screenRequest && handlers.screens?.[screenRequest.screen];
+        if (screenRequest && screenHandler)
+            return respond(screenHandler(screenRequest));
+        const actionRequest = asActionRequest(request);
+        const actionHandler = actionRequest && handlers.actions?.[actionRequest.action];
+        if (actionRequest && actionHandler)
+            return respond(actionHandler(actionRequest));
+        throw new Error(`fake gateway: no handler for ${request.method} ${request.url} ${JSON.stringify(request.body)}`);
+    }
+    return {
+        fetch: fakeFetch,
+        requests,
+        screenRequests: () => requests.flatMap((r) => asScreenRequest(r) ?? []),
+        actionRequests: () => requests.flatMap((r) => asActionRequest(r) ?? []),
+    };
+}
+/**
+ * A fake composer installed as the global `fetch`, for code that fetches by itself (e.g. a whole
+ * app rendered in a test). Call `restore()` after the test.
+ */
+export function installFakeGateway(handlers = {}) {
+    const gateway = createFakeGateway(handlers);
+    const original = globalThis.fetch;
+    globalThis.fetch = gateway.fetch;
+    return {
+        ...gateway,
+        restore: () => {
+            globalThis.fetch = original;
+        },
+    };
+}
+// ---- Responses ----
+/** An island in a screen response, typed by its generated descriptor. */
+export function island(key, descriptor, props) {
+    return { key, type: descriptor.type, version: descriptor.version, status: "ok", props };
+}
+/** An island that failed on the composer (spec §3.4). */
+export function islandError(key, descriptor, error) {
+    return { key, type: descriptor.type, version: descriptor.version, status: "error", error };
+}
+/** A screen response. */
+export function screen(id, islands, meta) {
+    return { status: 200, body: { protocol: PROTOCOL_VERSION, screen: id, islands, ...(meta && { meta }) } };
+}
+/** A screen request that fails, e.g. `screenError(404, "not_found")` or `screenError(401, "unauthenticated")`. */
+export function screenError(status, code) {
+    return { status, body: { protocol: PROTOCOL_VERSION, error: { code } } };
+}
+/** An action that succeeded, with its result typed by the descriptor. */
+export function actionOk(action, result, effects) {
+    const base = { protocol: PROTOCOL_VERSION, action: action.action, version: action.version };
+    return { status: 200, body: { ...base, status: "ok", result, ...(effects && { effects }) } };
+}
+/** An action that ended with one of its declared errors. */
+export function actionError(action, error) {
+    const base = { protocol: PROTOCOL_VERSION, action: action.action, version: action.version };
+    return { status: 200, body: { ...base, status: "error", error } };
+}
+/** An action the composer didn't perform, e.g. `actionFailure(401, "unauthenticated")` (spec §5.4). */
+export function actionFailure(status, code) {
+    return { status, body: { protocol: PROTOCOL_VERSION, error: { code } } };
+}
+//# sourceMappingURL=testing.js.map

package/dist/testing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"testing.js","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"AAAA,gGAAgG;AAChG,8FAA8F;AAC9F,yFAAyF;AACzF,EAAE;AACF,0CAA0C;AAC1C,6GAA6G;AAC7G,6EAA6E;AAC7E,UAAU;AACV,2FAA2F;AAC3F,EAAE;AACF,0FAA0F;AAE1F,OAAO,EACL,gBAAgB,GAUjB,MAAM,0BAA0B,CAAC;AAmDlC,MAAM,QAAQ,GAAG,CAAC,KAAc,EAAoC,EAAE,CACpE,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAEvE,SAAS,OAAO,CAAC,KAAc;IAC7B,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAChC,OAAO,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAyB,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC;AAClH,CAAC;AAED,SAAS,YAAY,CAAC,KAAc;IAClC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAChC,OAAO,MAAM,CAAC,WAAW,CACvB,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,QAAQ,CAAC,EAAE,EAAE,CAAC;QAC9C,IAAI;QACJ,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAe,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,EAAE;KAC1F,CAAC,CACH,CAAC;AACJ,CAAC;AAED,SAAS,aAAa,CAAC,KAAc;IACnC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,OAAO,KAAK,CAAC,QAAQ,KAAK,QAAQ,IAAI,OAAO,KAAK,CAAC,UAAU,KAAK,QAAQ;QAAE,OAAO,SAAS,CAAC;IACrH,OAAO,EAAE,GAAG,KAAK,EAAE,QAAQ,EAAE,KAAK,CAAC,QAAQ,EAAE,UAAU,EAAE,KAAK,CAAC,UAAU,EAAmB,CAAC;AAC/F,CAAC;AAED,SAAS,SAAS,CAAC,IAAa;IAC9B,IAAI,OAAO,IAAI,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IAC1C,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAY,CAAC;IACrC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,SAAS,KAAK,CAAC,KAAwB;IACrC,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC5C,OAAO,KAAK,YAAY,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC;AACvD,CAAC;AAED,SAAS,SAAS,CAAC,IAA6B;IAC9C,MAAM,GAAG,GAA2B,EAAE,CAAC;IACvC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC;IAChE,OAAO,GAAG,CAAC;AACb,CAAC;AAED,SAAS,eAAe,CAAC,OAAwB;IAC/C,MAAM,EAAE,IAAI,EAAE,GAAG,OAAO,CAAC;IACzB,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,WAAW,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,OAAO,IAAI,CAAC,MAAM,KAAK,QAAQ;QAAE,OAAO,SAAS,CAAC;IAC/G,OAAO;QACL,GAAG,OAAO;QACV,MAAM,EAAE,IAAI,CAAC,MAAM;QACnB,MAAM,EAAE,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC;QAC5B,MAAM,EAAE,aAAa,CAAC,IAAI,CAAC,MAAM,CAAC;QAClC,OAAO,EAAE,YAAY,CAAC,IAAI,CAAC,OAAO,CAAC;KACpC,CAAC;AACJ,CAAC;AAED,SAAS,eAAe,CAAC,OAAwB;IAC/C,MAAM,EAAE,IAAI,EAAE,GAAG,OAAO,CAAC;IACzB,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,WAAW,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,OAAO,IAAI,CAAC,MAAM,KAAK,QAAQ;QAAE,OAAO,SAAS,CAAC;IAC/G,OAAO;QACL,GAAG,OAAO;QACV,MAAM,EAAE,IAAI,CAAC,MAAM;QACnB,OAAO,EAAE,OAAO,IAAI,CAAC,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;QAC5D,KAAK,EAAE,IAAI,CAAC,KAAK;QACjB,MAAM,EAAE,aAAa,CAAC,IAAI,CAAC,MAAM,CAAC;QAClC,cAAc,EAAE,OAAO,IAAI,CAAC,cAAc,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC,CAAC,SAAS;KAC1F,CAAC;AACJ,CAAC;AAED,SAAS,OAAO,CAAC,QAAsB;IACrC,OAAO,IAAI,QAAQ,CAAC,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE;QACjD,MAAM,EAAE,QAAQ,CAAC,MAAM;QACvB,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;KAChD,CAAC,CAAC;AACL,CAAC;AAED,mEAAmE;AACnE,MAAM,UAAU,iBAAiB,CAAC,WAAgC,EAAE;IAClE,MAAM,QAAQ,GAAsB,EAAE,CAAC;IACvC,KAAK,UAAU,SAAS,CAAC,KAAwB,EAAE,IAAkB;QACnE,MAAM,OAAO,GAAoB;YAC/B,GAAG,EAAE,KAAK,CAAC,KAAK,CAAC;YACjB,MAAM,EAAE,IAAI,EAAE,MAAM,IAAI,KAAK;YAC7B,OAAO,EAAE,SAAS,CAAC,IAAI,EAAE,OAAO,CAAC;YACjC,IAAI,EAAE,SAAS,CAAC,IAAI,EAAE,IAAI,CAAC;SAC5B,CAAC;QACF,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAEvB,MAAM,KAAK,GAAG,QAAQ,CAAC,KAAK,EAAE,CAAC,OAAO,CAAC,CAAC;QACxC,IAAI,KAAK;YAAE,OAAO,OAAO,CAAC,KAAK,CAAC,CAAC;QACjC,MAAM,aAAa,GAAG,eAAe,CAAC,OAAO,CAAC,CAAC;QAC/C,MAAM,aAAa,GAAG,aAAa,IAAI,QAAQ,CAAC,OAAO,EAAE,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC;QAChF,IAAI,aAAa,IAAI,aAAa;YAAE,OAAO,OAAO,CAAC,aAAa,CAAC,aAAa,CAAC,CAAC,CAAC;QACjF,MAAM,aAAa,GAAG,eAAe,CAAC,OAAO,CAAC,CAAC;QAC/C,MAAM,aAAa,GAAG,aAAa,IAAI,QAAQ,CAAC,OAAO,EAAE,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC;QAChF,IAAI,aAAa,IAAI,aAAa;YAAE,OAAO,OAAO,CAAC,aAAa,CAAC,aAAa,CAAC,CAAC,CAAC;QACjF,MAAM,IAAI,KAAK,CAAC,gCAAgC,OAAO,CAAC,MAAM,IAAI,OAAO,CAAC,GAAG,IAAI,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACnH,CAAC;IACD,OAAO;QACL,KAAK,EAAE,SAAS;QAChB,QAAQ;QACR,cAAc,EAAE,GAAG,EAAE,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,eAAe,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;QACvE,cAAc,EAAE,GAAG,EAAE,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,eAAe,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;KACxE,CAAC;AACJ,CAAC;AAOD;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAAC,WAAgC,EAAE;IACnE,MAAM,OAAO,GAAG,iBAAiB,CAAC,QAAQ,CAAC,CAAC;IAC5C,MAAM,QAAQ,GAAG,UAAU,CAAC,KAAK,CAAC;IAClC,UAAU,CAAC,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC;IACjC,OAAO;QACL,GAAG,OAAO;QACV,OAAO,EAAE,GAAG,EAAE;YACZ,UAAU,CAAC,KAAK,GAAG,QAAQ,CAAC;QAC9B,CAAC;KACF,CAAC;AACJ,CAAC;AAED,sBAAsB;AAEtB,yEAAyE;AACzE,MAAM,UAAU,MAAM,CAAI,GAAW,EAAE,UAA+B,EAAE,KAAQ;IAC9E,OAAO,EAAE,GAAG,EAAE,IAAI,EAAE,UAAU,CAAC,IAAI,EAAE,OAAO,EAAE,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;AAC1F,CAAC;AAED,yDAAyD;AACzD,MAAM,UAAU,WAAW,CAAC,GAAW,EAAE,UAAqC,EAAE,KAAkB;IAChG,OAAO,EAAE,GAAG,EAAE,IAAI,EAAE,UAAU,CAAC,IAAI,EAAE,OAAO,EAAE,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;AAC7F,CAAC;AAED,yBAAyB;AACzB,MAAM,UAAU,MAAM,CAAC,EAAU,EAAE,OAA+B,EAAE,IAAiB;IACnF,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,EAAE,QAAQ,EAAE,gBAAgB,EAAE,MAAM,EAAE,EAAE,EAAE,OAAO,EAAE,GAAG,CAAC,IAAI,IAAI,EAAE,IAAI,EAAE,CAAC,EAAE,EAAE,CAAC;AAC3G,CAAC;AAED,kHAAkH;AAClH,MAAM,UAAU,WAAW,CAAC,MAAc,EAAE,IAAY;IACtD,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,EAAE,QAAQ,EAAE,gBAAgB,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC;AAC3E,CAAC;AAED,yEAAyE;AACzE,MAAM,UAAU,QAAQ,CACtB,MAAiC,EACjC,MAAS,EACT,OAAuB;IAEvB,MAAM,IAAI,GAAG,EAAE,QAAQ,EAAE,gBAAgB,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,OAAO,EAAE,CAAC;IAC5F,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,EAAE,GAAG,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,CAAC,OAAO,IAAI,EAAE,OAAO,EAAE,CAAC,EAAE,EAAE,CAAC;AAC/F,CAAC;AAED,4DAA4D;AAC5D,MAAM,UAAU,WAAW,CAAgC,MAAiC,EAAE,KAAQ;IACpG,MAAM,IAAI,GAAG,EAAE,QAAQ,EAAE,gBAAgB,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,OAAO,EAAE,CAAC;IAC5F,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,EAAE,GAAG,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,EAAE,CAAC;AACpE,CAAC;AAED,uGAAuG;AACvG,MAAM,UAAU,aAAa,CAAC,MAAc,EAAE,IAAY;IACxD,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,EAAE,QAAQ,EAAE,gBAAgB,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC;AAC3E,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@client-compose/client",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Framework-agnostic Client Compose client: island registry, screen requests and render planning.",
   "keywords": [
     "client-compose",
@@ -26,6 +26,14 @@
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     },
+    "./proxy": {
+      "types": "./dist/proxy.d.ts",
+      "default": "./dist/proxy.js"
+    },
+    "./testing": {
+      "types": "./dist/testing.d.ts",
+      "default": "./dist/testing.js"
+    },
     "./package.json": "./package.json"
   },
   "files": [

package/src/proxy.ts

@@ -0,0 +1,132 @@
+// Passing a browser's screen and action requests to the composer through your own server, e.g. a
+// Next.js Server Action or a Remix action. The server adds what the browser mustn't hold (a session
+// kept in an httpOnly cookie) and vouches for the client context, so the browser's is ignored.
+//
+//     const proxy = createComposerProxy({
+//       baseUrl: COMPOSER_URL,
+//       client: async () => ({ platform: "web", appVersion, locale: await getLocale() }),
+//       headers: async () => ({ Authorization: `Bearer ${await getSessionToken()}` }),
+//     });
+//     export async function performAction(body: unknown) { return proxy.performAction(body); }
+//
+// Anyone can call a server endpoint with anything, so requests are checked before they're sent on.
+// Errors come back as data, since frameworks often strip thrown errors' details on the way to the
+// browser.
+
+import {
+  PROTOCOL_VERSION,
+  type ActionRequest,
+  type ActionResponse,
+  type Capabilities,
+  type ClientContext,
+  type ScreenRequest,
+  type ScreenResponse,
+} from "@client-compose/protocol";
+import { ActionFetchError, fetchAction, fetchScreen, ScreenFetchError } from "./index.ts";
+
+/** A screen request from the browser: the server sets the client context. */
+export type ProxiedScreenRequest = Omit<ScreenRequest, "client">;
+/** An action request from the browser: the server sets the client context. */
+export type ProxiedActionRequest = Omit<ActionRequest, "client">;
+
+/** The composer's response, or the status and body it failed with. */
+export type ProxyResult<T> = { ok: true; response: T } | { ok: false; status: number; body: string };
+
+export interface ComposerProxyOptions {
+  /** Composer base URL. */
+  baseUrl: string;
+  /** The client context for each request, e.g. with the locale from the request's cookies. */
+  client: () => ClientContext | Promise<ClientContext>;
+  /** Extra headers for each request, e.g. `Authorization` from a session cookie. */
+  headers?: () => Record<string, string> | Promise<Record<string, string>>;
+  /** Extra options for every request, e.g. `{ cache: "no-store" }`. */
+  requestInit?: RequestInit & Record<string, unknown>;
+  /** Custom fetch implementation. Defaults to the global `fetch`. */
+  fetch?: typeof fetch;
+  /**
+   * Sees each action's response (ok or a declared error) before the browser does, and returns
+   * what the browser gets: e.g. keep a new session in a cookie, and take its token out.
+   */
+  onActionResponse?: (request: ActionRequest, response: ActionResponse) => ActionResponse | Promise<ActionResponse>;
+}
+
+export interface ComposerProxy {
+  /** Checks a browser's action request, then performs it with the server's context and headers. */
+  performAction(body: unknown): Promise<ProxyResult<ActionResponse>>;
+  /** Checks a browser's screen request, then loads it with the server's context and headers. */
+  loadScreen(body: unknown): Promise<ProxyResult<ScreenResponse>>;
+}
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === "object" && value !== null && !Array.isArray(value);
+
+function isCapabilities(value: unknown): value is Capabilities {
+  return (
+    isRecord(value) &&
+    Object.values(value).every((versions) => Array.isArray(versions) && versions.every((v) => typeof v === "number"))
+  );
+}
+
+function isStringRecord(value: unknown): value is Record<string, string> {
+  return isRecord(value) && Object.values(value).every((v) => typeof v === "string");
+}
+
+export function isProxiedScreenRequest(value: unknown): value is ProxiedScreenRequest {
+  return (
+    isRecord(value) &&
+    value.protocol === PROTOCOL_VERSION &&
+    typeof value.screen === "string" &&
+    (value.params === undefined || isStringRecord(value.params)) &&
+    isCapabilities(value.islands)
+  );
+}
+
+export function isProxiedActionRequest(value: unknown): value is ProxiedActionRequest {
+  return (
+    isRecord(value) &&
+    value.protocol === PROTOCOL_VERSION &&
+    typeof value.action === "string" &&
+    typeof value.version === "number" &&
+    "input" in value &&
+    (value.idempotencyKey === undefined || typeof value.idempotencyKey === "string")
+  );
+}
+
+/** What the composer itself answers to a malformed request. */
+const BAD_REQUEST = {
+  ok: false,
+  status: 400,
+  body: JSON.stringify({ protocol: PROTOCOL_VERSION, error: { code: "bad_request" } }),
+} as const;
+
+export function createComposerProxy(options: ComposerProxyOptions): ComposerProxy {
+  async function init(): Promise<RequestInit> {
+    const headers = (await options.headers?.()) ?? {};
+    return { ...options.requestInit, headers: { ...options.requestInit?.headers, ...headers } };
+  }
+
+  async function performAction(body: unknown): Promise<ProxyResult<ActionResponse>> {
+    if (!isProxiedActionRequest(body)) return BAD_REQUEST;
+    const request: ActionRequest = { ...body, client: await options.client() };
+    try {
+      const response = await fetchAction(options.baseUrl, request, await init(), options.fetch);
+      return { ok: true, response: (await options.onActionResponse?.(request, response)) ?? response };
+    } catch (error) {
+      if (error instanceof ActionFetchError) return { ok: false, status: error.status, body: error.body };
+      throw error;
+    }
+  }
+
+  async function loadScreen(body: unknown): Promise<ProxyResult<ScreenResponse>> {
+    if (!isProxiedScreenRequest(body)) return BAD_REQUEST;
+    const request: ScreenRequest = { ...body, client: await options.client() };
+    try {
+      return { ok: true, response: await fetchScreen(options.baseUrl, request, await init(), options.fetch) };
+    } catch (error) {
+      if (error instanceof ScreenFetchError) return { ok: false, status: error.status, body: error.body };
+      throw error;
+    }
+  }
+
+  return { performAction, loadScreen };
+}

package/src/testing.ts

@@ -0,0 +1,242 @@
+// Test helpers for apps built on Client Compose: a fake composer that answers screen and action
+// requests from handlers and records them, and builders for the responses it returns. No test
+// framework of its own, so it works with node:test, Jest, Vitest, Playwright and others.
+//
+//     const gateway = createFakeGateway({
+//       screens: { profile: () => screen("profile", [island("header", ProfileHeaderV1, { name: "Ada" })]) },
+//       actions: { follow: () => actionOk(FollowUserV1, { followers: 8 }) },
+//     });
+//     // pass gateway.fetch as the client's fetch, then assert on gateway.actionRequests()
+//
+// For code that uses the global fetch itself, `installFakeGateway` puts one in its place.
+
+import {
+  PROTOCOL_VERSION,
+  type ActionDescriptor,
+  type ActionEffects,
+  type Capabilities,
+  type ClientContext,
+  type DeclaredError,
+  type IslandDescriptor,
+  type IslandEntry,
+  type IslandError,
+  type ScreenMeta,
+} from "@client-compose/protocol";
+
+/** A response for the fake composer to send. */
+export interface FakeResponse {
+  status: number;
+  body: unknown;
+}
+
+/** A request the fake composer received. */
+export interface RecordedRequest {
+  url: string;
+  method: string;
+  /** Header names are lower case. */
+  headers: Record<string, string>;
+  /** The JSON body, parsed; or the raw body when it isn't JSON (e.g. a multipart upload). */
+  body: unknown;
+}
+
+export interface RecordedScreenRequest extends RecordedRequest {
+  screen: string;
+  params: Record<string, string>;
+  client: ClientContext | undefined;
+  islands: Capabilities;
+}
+
+export interface RecordedActionRequest extends RecordedRequest {
+  action: string;
+  version: number;
+  input: unknown;
+  client: ClientContext | undefined;
+  idempotencyKey: string | undefined;
+}
+
+export interface FakeGatewayHandlers {
+  /** By screen id. */
+  screens?: Record<string, (request: RecordedScreenRequest) => FakeResponse>;
+  /** By action name. */
+  actions?: Record<string, (request: RecordedActionRequest) => FakeResponse>;
+  /** Anything else, e.g. uploads to storage: return undefined to leave a request to the others. */
+  other?: (request: RecordedRequest) => FakeResponse | undefined;
+}
+
+export interface FakeGateway {
+  /** Use as the client's `fetch`. Requests without a handler reject, failing the test. */
+  fetch: typeof fetch;
+  /** Every request received, in order. */
+  requests: RecordedRequest[];
+  screenRequests(): RecordedScreenRequest[];
+  actionRequests(): RecordedActionRequest[];
+}
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === "object" && value !== null && !Array.isArray(value);
+
+function strings(value: unknown): Record<string, string> {
+  if (!isRecord(value)) return {};
+  return Object.fromEntries(Object.entries(value).filter((e): e is [string, string] => typeof e[1] === "string"));
+}
+
+function capabilities(value: unknown): Capabilities {
+  if (!isRecord(value)) return {};
+  return Object.fromEntries(
+    Object.entries(value).map(([type, versions]) => [
+      type,
+      Array.isArray(versions) ? versions.filter((v): v is number => typeof v === "number") : [],
+    ]),
+  );
+}
+
+function clientContext(value: unknown): ClientContext | undefined {
+  if (!isRecord(value) || typeof value.platform !== "string" || typeof value.appVersion !== "string") return undefined;
+  return { ...value, platform: value.platform, appVersion: value.appVersion } as ClientContext;
+}
+
+function parseBody(body: unknown): unknown {
+  if (typeof body !== "string") return body;
+  try {
+    return JSON.parse(body) as unknown;
+  } catch {
+    return body;
+  }
+}
+
+function urlOf(input: RequestInfo | URL): string {
+  if (typeof input === "string") return input;
+  return input instanceof URL ? input.href : input.url;
+}
+
+function headersOf(init: HeadersInit | undefined): Record<string, string> {
+  const out: Record<string, string> = {};
+  new Headers(init).forEach((value, name) => (out[name] = value));
+  return out;
+}
+
+function asScreenRequest(request: RecordedRequest): RecordedScreenRequest | undefined {
+  const { body } = request;
+  if (!request.url.includes("/screens/") || !isRecord(body) || typeof body.screen !== "string") return undefined;
+  return {
+    ...request,
+    screen: body.screen,
+    params: strings(body.params),
+    client: clientContext(body.client),
+    islands: capabilities(body.islands),
+  };
+}
+
+function asActionRequest(request: RecordedRequest): RecordedActionRequest | undefined {
+  const { body } = request;
+  if (!request.url.includes("/actions/") || !isRecord(body) || typeof body.action !== "string") return undefined;
+  return {
+    ...request,
+    action: body.action,
+    version: typeof body.version === "number" ? body.version : 0,
+    input: body.input,
+    client: clientContext(body.client),
+    idempotencyKey: typeof body.idempotencyKey === "string" ? body.idempotencyKey : undefined,
+  };
+}
+
+function respond(response: FakeResponse): Response {
+  return new Response(JSON.stringify(response.body), {
+    status: response.status,
+    headers: { "content-type": "application/json" },
+  });
+}
+
+/** A composer whose screens and actions are the handlers given. */
+export function createFakeGateway(handlers: FakeGatewayHandlers = {}): FakeGateway {
+  const requests: RecordedRequest[] = [];
+  async function fakeFetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response> {
+    const request: RecordedRequest = {
+      url: urlOf(input),
+      method: init?.method ?? "GET",
+      headers: headersOf(init?.headers),
+      body: parseBody(init?.body),
+    };
+    requests.push(request);
+
+    const other = handlers.other?.(request);
+    if (other) return respond(other);
+    const screenRequest = asScreenRequest(request);
+    const screenHandler = screenRequest && handlers.screens?.[screenRequest.screen];
+    if (screenRequest && screenHandler) return respond(screenHandler(screenRequest));
+    const actionRequest = asActionRequest(request);
+    const actionHandler = actionRequest && handlers.actions?.[actionRequest.action];
+    if (actionRequest && actionHandler) return respond(actionHandler(actionRequest));
+    throw new Error(`fake gateway: no handler for ${request.method} ${request.url} ${JSON.stringify(request.body)}`);
+  }
+  return {
+    fetch: fakeFetch,
+    requests,
+    screenRequests: () => requests.flatMap((r) => asScreenRequest(r) ?? []),
+    actionRequests: () => requests.flatMap((r) => asActionRequest(r) ?? []),
+  };
+}
+
+export interface InstalledFakeGateway extends FakeGateway {
+  /** Puts back the `fetch` that was there before. */
+  restore(): void;
+}
+
+/**
+ * A fake composer installed as the global `fetch`, for code that fetches by itself (e.g. a whole
+ * app rendered in a test). Call `restore()` after the test.
+ */
+export function installFakeGateway(handlers: FakeGatewayHandlers = {}): InstalledFakeGateway {
+  const gateway = createFakeGateway(handlers);
+  const original = globalThis.fetch;
+  globalThis.fetch = gateway.fetch;
+  return {
+    ...gateway,
+    restore: () => {
+      globalThis.fetch = original;
+    },
+  };
+}
+
+// ---- Responses ----
+
+/** An island in a screen response, typed by its generated descriptor. */
+export function island<P>(key: string, descriptor: IslandDescriptor<P>, props: P): IslandEntry<P> {
+  return { key, type: descriptor.type, version: descriptor.version, status: "ok", props };
+}
+
+/** An island that failed on the composer (spec §3.4). */
+export function islandError(key: string, descriptor: IslandDescriptor<unknown>, error: IslandError): IslandEntry {
+  return { key, type: descriptor.type, version: descriptor.version, status: "error", error };
+}
+
+/** A screen response. */
+export function screen(id: string, islands: IslandEntry<unknown>[], meta?: ScreenMeta): FakeResponse {
+  return { status: 200, body: { protocol: PROTOCOL_VERSION, screen: id, islands, ...(meta && { meta }) } };
+}
+
+/** A screen request that fails, e.g. `screenError(404, "not_found")` or `screenError(401, "unauthenticated")`. */
+export function screenError(status: number, code: string): FakeResponse {
+  return { status, body: { protocol: PROTOCOL_VERSION, error: { code } } };
+}
+
+/** An action that succeeded, with its result typed by the descriptor. */
+export function actionOk<I, R, E extends DeclaredError>(
+  action: ActionDescriptor<I, R, E>,
+  result: R,
+  effects?: ActionEffects,
+): FakeResponse {
+  const base = { protocol: PROTOCOL_VERSION, action: action.action, version: action.version };
+  return { status: 200, body: { ...base, status: "ok", result, ...(effects && { effects }) } };
+}
+
+/** An action that ended with one of its declared errors. */
+export function actionError<I, R, E extends DeclaredError>(action: ActionDescriptor<I, R, E>, error: E): FakeResponse {
+  const base = { protocol: PROTOCOL_VERSION, action: action.action, version: action.version };
+  return { status: 200, body: { ...base, status: "error", error } };
+}
+
+/** An action the composer didn't perform, e.g. `actionFailure(401, "unauthenticated")` (spec §5.4). */
+export function actionFailure(status: number, code: string): FakeResponse {
+  return { status, body: { protocol: PROTOCOL_VERSION, error: { code } } };
+}