@swiftbrowser/web 0.1.0 → 0.3.0

package/src/bitmapPlan.ts

@@ -0,0 +1,143 @@
+/**
+ * A bitmap recipe made only of geometry (`place`, `crop`, `render`,
+ * `roundedClip`) and `tint`, as one canvas drawing: where the source image
+ * lands on the output, which rounded rectangles clip it, and the tint color.
+ * The browser then draws it in one `drawImage`, at the output size, instead
+ * of src/imageOps.ts running each step over a float raster in JavaScript,
+ * which was a quarter of Ice Cubes' main thread at startup (Nuke resizes
+ * every avatar with `place` + `render`).
+ *
+ * The output has the size the raster pipeline gives the same recipe (so the
+ * element shows the same resolution); within it, the image is drawn smoothly
+ * where the pipeline samples the nearest pixel. Recipes with a filter, or a
+ * `clamp` (its edge pixels repeat), are not planned: `planBitmap` answers
+ * null and they take the raster pipeline.
+ */
+
+import type { BitmapStep } from './protocol';
+
+/** A rectangle in output pixels, rows from the top. */
+export interface PixelRect {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+export interface BitmapPlan {
+  /** Output size in pixels; 0 × 0 is an empty image. */
+  width: number;
+  height: number;
+  /** Where the whole source image is drawn. */
+  image: PixelRect;
+  /** Rounded rectangles the drawing is clipped to (corner radii in pixels). */
+  clips: (PixelRect & { rx: number; ry: number })[];
+  /** The image's shape in one color (each pixel's alpha times `a`), when tinted. */
+  tint: { r: number; g: number; b: number; a: number } | null;
+}
+
+/** A rectangle in Core Image's space: units of source pixels, origin at the bottom left, y up. */
+interface UnitRect {
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+}
+
+/**
+ * The drawing for `steps` over a `sourceWidth` × `sourceHeight` source at
+ * `scale` output pixels per source pixel, or null when a step needs pixels
+ * (a filter, `clamp`, an op this module does not know).
+ */
+export function planBitmap(steps: readonly BitmapStep[], sourceWidth: number, sourceHeight: number, scale: number): BitmapPlan | null {
+  // What the raster pipeline tracks: the rectangle the raster covers, its
+  // size in pixels and pixels per unit; and where the image and clips are.
+  let extent: UnitRect = { x: 0, y: 0, w: sourceWidth, h: sourceHeight };
+  let s = scale;
+  let width = Math.max(0, Math.round(sourceWidth * s));
+  let height = Math.max(0, Math.round(sourceHeight * s));
+  let image: UnitRect = { ...extent };
+  let clips: (UnitRect & { rx: number; ry: number })[] = [];
+  let tint = null as BitmapPlan['tint'];
+  const empty: BitmapPlan = { width: 0, height: 0, image: { x: 0, y: 0, width: 0, height: 0 }, clips: [], tint: null };
+
+  for (const step of steps) {
+    switch (step.op) {
+      case 'place': {
+        const { sx, sy, tx, ty } = step;
+        if (!(sx > 0) || !(sy > 0)) return empty;
+        const move = (r: UnitRect): UnitRect => ({ x: r.x * sx + tx, y: r.y * sy + ty, w: r.w * sx, h: r.h * sy });
+        extent = move(extent);
+        image = move(image);
+        clips = clips.map((c) => ({ ...move(c), rx: c.rx * sx, ry: c.ry * sy }));
+        if (Math.abs(sx - sy) <= 1e-9 * Math.max(sx, sy)) {
+          // A uniform scale relabels the raster: the same pixels.
+          s /= sx;
+        } else {
+          s /= Math.min(sx, sy);
+          width = Math.max(0, Math.round(extent.w * s));
+          height = Math.max(0, Math.round(extent.h * s));
+        }
+        break;
+      }
+      case 'crop': {
+        extent = intersect({ x: step.x, y: step.y, w: step.width, h: step.height }, extent);
+        width = Math.max(0, Math.round(extent.w * s));
+        height = Math.max(0, Math.round(extent.h * s));
+        break;
+      }
+      case 'render': {
+        // The raster covers the rectangle (clear outside the image), then its
+        // origin moves to 0, 0: everything shifts by the rectangle's origin.
+        const dx = -step.x;
+        const dy = -step.y;
+        extent = { x: 0, y: 0, w: step.width, h: step.height };
+        width = Math.max(0, Math.round(step.width * s));
+        height = Math.max(0, Math.round(step.height * s));
+        image = { ...image, x: image.x + dx, y: image.y + dy };
+        clips = clips.map((c) => ({ ...c, x: c.x + dx, y: c.y + dy }));
+        break;
+      }
+      case 'roundedClip': {
+        const rx = Math.max(0, Math.min(step.rx, step.width / 2));
+        const ry = Math.max(0, Math.min(step.ry, step.height / 2));
+        clips.push({ x: step.x, y: step.y, w: step.width, h: step.height, rx, ry });
+        break;
+      }
+      case 'tint': {
+        const c = (v: number) => Math.min(1, Math.max(0, Number.isFinite(v) ? v : 0));
+        // A second tint recolors the first's shape: its color, both alphas.
+        tint = { r: c(step.r), g: c(step.g), b: c(step.b), a: c(step.a) * (tint?.a ?? 1) };
+        break;
+      }
+      default:
+        return null;
+    }
+  }
+  if (width === 0 || height === 0 || !(extent.w > 0) || !(extent.h > 0)) return empty;
+
+  // Units to output pixels: x from the extent's left, y down from its top.
+  const kx = width / extent.w;
+  const ky = height / extent.h;
+  const toPixels = (r: UnitRect): PixelRect => ({
+    x: (r.x - extent.x) * kx,
+    y: (extent.y + extent.h - (r.y + r.h)) * ky,
+    width: r.w * kx,
+    height: r.h * ky,
+  });
+  return {
+    width,
+    height,
+    image: toPixels(image),
+    clips: clips.map((c) => ({ ...toPixels(c), rx: c.rx * kx, ry: c.ry * ky })),
+    tint,
+  };
+}
+
+function intersect(a: UnitRect, b: UnitRect): UnitRect {
+  const x0 = Math.max(a.x, b.x);
+  const y0 = Math.max(a.y, b.y);
+  const x1 = Math.min(a.x + a.w, b.x + b.w);
+  const y1 = Math.min(a.y + a.h, b.y + b.h);
+  return { x: x0, y: y0, w: Math.max(0, x1 - x0), h: Math.max(0, y1 - y0) };
+}

package/src/bitmapStore.ts

@@ -0,0 +1,206 @@
+/**
+ * The bitmap sources Swift sent and how to draw a recipe over one: decoded by
+ * the browser, geometry and tints drawn on a canvas (src/bitmapPlan.ts),
+ * filters run by the raster pipeline (src/imageOps.ts), a GIF's frames
+ * composed by src/gif.ts. No DOM beyond canvases and `ImageData`, so the
+ * same store runs in the bitmap worker (src/bitmapWorker.ts) or, where the
+ * browser has no worker canvases, on the page (src/bitmaps.ts).
+ */
+
+import { base64Decode } from './base64';
+import { type BitmapPlan, planBitmap } from './bitmapPlan';
+import { GifDecoder } from './gif';
+import { applySteps, rasterFromRGBA, rasterToRGBA, workingScale } from './imageOps';
+import type { BitmapRecipe, ImageDataOp } from './protocol';
+
+/** What src/bitmaps.ts draws with: this store, or the worker running one. */
+export interface Bitmaps {
+  /** Keeps an `imagedata` op's source for the rest of the run. */
+  add(op: ImageDataOp): void;
+  has(key: string): boolean;
+  sizeOf(key: string): { width: number; height: number } | undefined;
+  /** `recipe` drawn at `scale` raster pixels per source pixel; null for an empty image. */
+  render(recipe: BitmapRecipe, scale: number): Promise<RenderedBitmap | null>;
+  /** The recipe at full resolution as a PNG file. */
+  png(recipe: BitmapRecipe): Promise<Blob | null>;
+}
+
+interface StoredSource {
+  width: number;
+  height: number;
+  /** An encoded file, decoded on first use. */
+  blob?: Blob;
+  /** Straight RGBA, for pixel buffers. */
+  rgba?: Uint8ClampedArray<ArrayBuffer>;
+  decoded?: Promise<CanvasImageSource>;
+  /** A GIF file's bytes, for drawing its frames. */
+  gifBytes?: Uint8Array;
+  /** Its frames, parsed on first use (null: not a GIF the decoder reads). */
+  gif?: GifDecoder | null;
+}
+
+/**
+ * A drawing surface: an `OffscreenCanvas` where the browser has one, else a
+ * detached `<canvas>`. `readBack`: its pixels are read with `getImageData`
+ * (the raster pipeline), which keeps the canvas in memory instead of on the GPU.
+ */
+function surface(width: number, height: number, readBack = true): { canvas: HTMLCanvasElement | OffscreenCanvas; context: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D } {
+  const canvas = typeof OffscreenCanvas === 'function' ? new OffscreenCanvas(width, height) : Object.assign(document.createElement('canvas'), { width, height });
+  const context = canvas.getContext('2d', { willReadFrequently: readBack }) as CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D | null;
+  if (!context) throw new Error('no 2D canvas context');
+  return { canvas, context };
+}
+
+/** A recipe this store drew: pixels from the raster pipeline, or a canvas the browser drew. */
+export type DrawnBitmap = ImageData | { canvas: HTMLCanvasElement | OffscreenCanvas; width: number; height: number };
+
+/** A drawn recipe as src/bitmaps.ts gets it: from this store, or as the worker sends it. */
+export type RenderedBitmap = DrawnBitmap | ImageBitmap;
+
+/** Whether `roundRect` takes elliptical corners here (every current browser); else rounded clips take the raster pipeline. */
+const canRoundRect =
+  typeof OffscreenCanvasRenderingContext2D === 'function'
+    ? typeof OffscreenCanvasRenderingContext2D.prototype.roundRect === 'function'
+    : typeof CanvasRenderingContext2D === 'function' && typeof CanvasRenderingContext2D.prototype.roundRect === 'function';
+
+/** The sources Swift has sent, by key, and how to draw recipes over them. */
+export class BitmapStore implements Bitmaps {
+  private sources = new Map<string, StoredSource>();
+
+  add(op: ImageDataOp): void {
+    if (this.sources.has(op.key)) return;
+    const width = Math.max(0, op.width | 0);
+    const height = Math.max(0, op.height | 0);
+    if (op.data !== undefined) {
+      const bytes = typeof op.data === 'string' ? base64Decode(op.data) : op.data;
+      const source: StoredSource = { width, height, blob: new Blob([bytes as BlobPart], { type: op.mime ?? '' }) };
+      if (op.mime === 'image/gif') source.gifBytes = bytes;
+      this.sources.set(op.key, source);
+      return;
+    }
+    const pixels = typeof op.pixels === 'string' || op.pixels === undefined ? base64Decode(op.pixels ?? '') : op.pixels;
+    const rgba = new Uint8ClampedArray(width * height * 4);
+    if (op.format === 'gray') {
+      for (let i = 0; i < width * height; i++) {
+        const v = pixels[i] ?? 0;
+        rgba[i * 4] = v;
+        rgba[i * 4 + 1] = v;
+        rgba[i * 4 + 2] = v;
+        rgba[i * 4 + 3] = 255;
+      }
+    } else {
+      rgba.set(pixels.subarray(0, rgba.length));
+    }
+    this.sources.set(op.key, { width, height, rgba });
+  }
+
+  has(key: string): boolean {
+    return this.sources.has(key);
+  }
+
+  sizeOf(key: string): { width: number; height: number } | undefined {
+    const source = this.sources.get(key);
+    return source && { width: source.width, height: source.height };
+  }
+
+  /** Frame `frame` of a GIF source, composed; null when the source is not a GIF or has no such frame. */
+  private gifFrame(source: StoredSource, frame: number): CanvasImageSource | null {
+    if (!source.gifBytes) return null;
+    if (source.gif === undefined) source.gif = GifDecoder.parse(source.gifBytes);
+    const gif = source.gif;
+    const rgba = gif?.frame(frame);
+    if (!gif || !rgba) return null;
+    const { canvas, context } = surface(gif.width, gif.height);
+    context.putImageData(new ImageData(rgba, gif.width, gif.height), 0, 0);
+    return canvas;
+  }
+
+  private decode(source: StoredSource, frame?: number): Promise<CanvasImageSource> {
+    if (frame !== undefined) {
+      // A GIF's frame; the file as the browser decodes it when the decoder cannot read it.
+      const image = this.gifFrame(source, frame);
+      if (image) return Promise.resolve(image);
+    }
+    if (!source.decoded) {
+      if (source.blob) {
+        // `createImageBitmap` applies a JPEG's EXIF rotation ("from-image"),
+        // which the size Swift read from the header already accounts for.
+        source.decoded = createImageBitmap(source.blob);
+      } else {
+        const { canvas, context } = surface(Math.max(1, source.width), Math.max(1, source.height));
+        context.putImageData(new ImageData(source.rgba!, Math.max(1, source.width), Math.max(1, source.height)), 0, 0);
+        source.decoded = Promise.resolve(canvas);
+      }
+    }
+    return source.decoded;
+  }
+
+  /**
+   * Draws `recipe` at `scale` raster pixels per source pixel: straight RGBA
+   * of the result and its size. Null for an empty image; rejects when the
+   * source is unknown or the browser cannot decode it (HEIC in Chromium).
+   */
+  async render(recipe: BitmapRecipe, scale: number): Promise<DrawnBitmap | null> {
+    if (recipe.source === null) return null;
+    const source = this.sources.get(recipe.source);
+    if (!source) throw new Error(`no image data for ${recipe.source}`);
+    const image = await this.decode(source, recipe.frame);
+    // Geometry and tints (an image as it is, or resized as Nuke does): one
+    // drawing by the browser (src/bitmapPlan.ts). Filters: the raster pipeline.
+    const plan = planBitmap(recipe.steps, source.width, source.height, scale);
+    if (plan && (plan.clips.length === 0 || canRoundRect)) return drawPlan(plan, image, !source.rgba);
+    const width = Math.max(1, Math.round(source.width * scale));
+    const height = Math.max(1, Math.round(source.height * scale));
+    const { context } = surface(width, height);
+    // A pixel buffer (a QR code's modules) is scaled without smoothing.
+    context.imageSmoothingEnabled = !source.rgba;
+    context.imageSmoothingQuality = 'high';
+    context.drawImage(image, 0, 0, width, height);
+    const pixels = context.getImageData(0, 0, width, height).data;
+    const raster = rasterFromRGBA(pixels, width, height, { x: 0, y: 0, width: source.width, height: source.height }, scale);
+    const result = applySteps(raster, recipe.steps);
+    if (result.width === 0 || result.height === 0) return null;
+    return new ImageData(rasterToRGBA(result), result.width, result.height);
+  }
+
+  /** The recipe at full resolution (as far as `MAX_WORKING_PIXELS` allows) as a PNG file. */
+  async png(recipe: BitmapRecipe): Promise<Blob | null> {
+    if (recipe.source === null || !this.sources.has(recipe.source)) return null;
+    const size = this.sizeOf(recipe.source)!;
+    const scale = workingScale(recipe.width, recipe.height, recipe.width, recipe.height, size.width * size.height);
+    const image = await this.render(recipe, scale);
+    if (!image) return null;
+    let canvas: HTMLCanvasElement | OffscreenCanvas;
+    if (image instanceof ImageData) {
+      const drawn = surface(image.width, image.height);
+      drawn.context.putImageData(image, 0, 0);
+      canvas = drawn.canvas;
+    } else {
+      canvas = image.canvas;
+    }
+    if ('convertToBlob' in canvas) return canvas.convertToBlob({ type: 'image/png' });
+    return new Promise((resolve) => canvas.toBlob(resolve, 'image/png'));
+  }
+}
+
+/** Draws a plan: clipped to its rounded rectangles, the image smoothed (unless it is a pixel buffer), then tinted. */
+function drawPlan(plan: BitmapPlan, image: CanvasImageSource, smooth: boolean): DrawnBitmap | null {
+  if (plan.width === 0 || plan.height === 0) return null;
+  const { canvas, context } = surface(plan.width, plan.height, false);
+  for (const clip of plan.clips) {
+    // Each clip narrows the last, as the raster pipeline's coverages multiply.
+    context.beginPath();
+    context.roundRect(clip.x, clip.y, clip.width, clip.height, [{ x: clip.rx, y: clip.ry }]);
+    context.clip();
+  }
+  context.imageSmoothingEnabled = smooth;
+  context.imageSmoothingQuality = 'high';
+  context.drawImage(image, plan.image.x, plan.image.y, plan.image.width, plan.image.height);
+  if (plan.tint) {
+    const { r, g, b, a } = plan.tint;
+    context.globalCompositeOperation = 'source-in';
+    context.fillStyle = `rgba(${Math.round(r * 255)}, ${Math.round(g * 255)}, ${Math.round(b * 255)}, ${a})`;
+    context.fillRect(0, 0, plan.width, plan.height);
+  }
+  return { canvas, width: plan.width, height: plan.height };
+}

package/src/bitmapWorker.ts

@@ -0,0 +1,41 @@
+/**
+ * The bitmap worker: a src/bitmapStore.ts store off the page's thread. The
+ * page sends each `imagedata` op and each recipe to draw (src/bitmaps.ts);
+ * the worker decodes the source, draws the recipe and answers with an
+ * `ImageBitmap` the page's canvas takes without copying it.
+ */
+
+import { BitmapStore, type DrawnBitmap } from './bitmapStore';
+import type { BitmapWorkerReply, BitmapWorkerRequest } from './bitmapWorkerProtocol';
+
+const store = new BitmapStore();
+const scope = self as unknown as {
+  onmessage: ((event: MessageEvent<BitmapWorkerRequest>) => void) | null;
+  postMessage(message: BitmapWorkerReply, transfer?: Transferable[]): void;
+};
+
+/** A drawing as a transferable bitmap. */
+async function toImageBitmap(drawn: DrawnBitmap): Promise<ImageBitmap> {
+  if (drawn instanceof ImageData) return createImageBitmap(drawn);
+  const canvas = drawn.canvas as OffscreenCanvas;
+  return canvas.transferToImageBitmap();
+}
+
+scope.onmessage = (event) => {
+  const request = event.data;
+  if (request.type === 'add') {
+    store.add(request.op);
+    return;
+  }
+  const answer = async (): Promise<ImageBitmap | Blob | null> => {
+    if (request.type === 'png') return store.png(request.recipe);
+    const drawn = await store.render(request.recipe, request.scale);
+    return drawn && toImageBitmap(drawn);
+  };
+  answer().then(
+    (value) => scope.postMessage({ id: request.id, ok: true, value }, value instanceof ImageBitmap ? [value] : []),
+    (error: unknown) => scope.postMessage({ id: request.id, ok: false, error: error instanceof Error ? error.message : String(error) }),
+  );
+};
+
+scope.postMessage({ ready: true });

package/src/bitmapWorkerProtocol.ts

@@ -0,0 +1,15 @@
+/** Messages between the page (src/bitmaps.ts) and the bitmap worker (src/bitmapWorker.ts). */
+
+import type { BitmapRecipe, ImageDataOp } from './protocol';
+
+export type BitmapWorkerRequest =
+  | { type: 'add'; op: ImageDataOp }
+  | { type: 'render'; id: number; recipe: BitmapRecipe; scale: number }
+  | { type: 'png'; id: number; recipe: BitmapRecipe };
+
+/** The answer to a `render` (an `ImageBitmap`, transferred) or a `png` (a `Blob`); null for an empty image. */
+export type BitmapWorkerReply =
+  | { id: number; ok: true; value: ImageBitmap | Blob | null }
+  | { id: number; ok: false; error: string }
+  /** Sent once, when the worker has started. */
+  | { ready: true };

package/src/bitmaps.ts

@@ -0,0 +1,283 @@
+/**
+ * `UIImage` / `CGImage` bitmaps (`Image(uiImage:)`) on the page. Swift sends
+ * each bitmap's source once (an `imagedata` op: an image file, or a pixel
+ * buffer such as a QR code) and every `image` element that shows a bitmap
+ * carries its recipe: the source's key and the Core Image steps to run
+ * (docs/ops-protocol.md, "Bitmaps and Core Image"). A store keeps the
+ * sources and draws recipes (src/bitmapStore.ts); this module puts each
+ * drawing, at the size the image is shown, on the element's `<canvas>`.
+ *
+ * The store runs in a worker (src/bitmapWorker.ts) where the browser has
+ * canvases there (`OffscreenCanvas`), so decoding, resizing and filters
+ * leave the page's thread free for Swift; the drawing comes back as an
+ * `ImageBitmap` the canvas shows without a copy. Elsewhere, or with
+ * `?bitmaps=main` in the page's URL, the store runs on the page.
+ */
+
+import { BitmapStore, type Bitmaps, type RenderedBitmap } from './bitmapStore';
+import type { BitmapWorkerReply, BitmapWorkerRequest } from './bitmapWorkerProtocol';
+import { workingScale } from './imageOps';
+import type { BitmapRecipe, ImageDataOp } from './protocol';
+
+export { BitmapStore } from './bitmapStore';
+
+/**
+ * The store in the worker. Sources are sent as they arrive; until the worker
+ * says it is running they are also kept here, so that a worker that cannot
+ * start (a blocked script, no canvases there after all) hands everything to
+ * a store on the page instead.
+ */
+class WorkerBitmaps implements Bitmaps {
+  private sizes = new Map<string, { width: number; height: number }>();
+  private pending = new Map<number, { resolve: (value: ImageBitmap | Blob | null) => void; reject: (error: Error) => void }>();
+  private nextId = 1;
+  private worker: Worker | null;
+  /** Sources sent before the worker started (null once it has). */
+  private early: ImageDataOp[] | null = [];
+  /** The store on the page, when the worker failed to start. */
+  private fallback: BitmapStore | null = null;
+
+  constructor(worker: Worker) {
+    this.worker = worker;
+    worker.onmessage = (event: MessageEvent<BitmapWorkerReply>) => {
+      const reply = event.data;
+      if ('ready' in reply) {
+        this.early = null;
+        return;
+      }
+      const request = this.pending.get(reply.id);
+      if (!request) return;
+      this.pending.delete(reply.id);
+      if (reply.ok) request.resolve(reply.value);
+      else request.reject(new Error(reply.error));
+    };
+    worker.onerror = (event) => {
+      event.preventDefault();
+      if (this.early === null) return; // a running worker reports its errors per request
+      console.warn(`[swiftbrowser] the bitmap worker did not start (${event.message || 'error'}); drawing bitmaps on the page`);
+      this.useFallback();
+    };
+  }
+
+  private useFallback(): void {
+    const store = new BitmapStore();
+    for (const op of this.early ?? []) store.add(op);
+    this.early = null;
+    this.fallback = store;
+    this.worker?.terminate();
+    this.worker = null;
+    const failed = [...this.pending.values()];
+    this.pending.clear();
+    for (const request of failed) request.reject(new Error('the bitmap worker stopped'));
+  }
+
+  private send(request: BitmapWorkerRequest): void {
+    this.worker!.postMessage(request);
+  }
+
+  private ask(request: { type: 'render'; recipe: BitmapRecipe; scale: number } | { type: 'png'; recipe: BitmapRecipe }): Promise<ImageBitmap | Blob | null> {
+    const id = this.nextId++;
+    return new Promise((resolve, reject) => {
+      this.pending.set(id, { resolve, reject });
+      this.send({ ...request, id });
+    });
+  }
+
+  add(op: ImageDataOp): void {
+    if (this.sizes.has(op.key)) return;
+    this.sizes.set(op.key, { width: Math.max(0, op.width | 0), height: Math.max(0, op.height | 0) });
+    if (this.fallback) {
+      this.fallback.add(op);
+      return;
+    }
+    if (this.early) {
+      this.early.push(op);
+      this.send({ type: 'add', op });
+      return;
+    }
+    // The bytes from linear memory are this op's own copy: moved, not copied.
+    const bytes = op.data ?? op.pixels;
+    this.worker!.postMessage({ type: 'add', op } satisfies BitmapWorkerRequest, typeof bytes === 'object' ? [bytes.buffer] : []);
+  }
+
+  has(key: string): boolean {
+    return this.sizes.has(key);
+  }
+
+  sizeOf(key: string): { width: number; height: number } | undefined {
+    return this.sizes.get(key);
+  }
+
+  async render(recipe: BitmapRecipe, scale: number): Promise<RenderedBitmap | null> {
+    if (recipe.source === null) return null;
+    if (this.fallback) return this.fallback.render(recipe, scale);
+    if (!this.sizes.has(recipe.source)) throw new Error(`no image data for ${recipe.source}`);
+    try {
+      return (await this.ask({ type: 'render', recipe, scale })) as ImageBitmap | null;
+    } catch (error) {
+      // The worker failed to start while drawing: draw on the page.
+      const fallback = this.fallback as BitmapStore | null;
+      if (fallback) return fallback.render(recipe, scale);
+      throw error;
+    }
+  }
+
+  async png(recipe: BitmapRecipe): Promise<Blob | null> {
+    if (recipe.source === null || !this.sizes.has(recipe.source)) return null;
+    if (this.fallback) return this.fallback.png(recipe);
+    return (await this.ask({ type: 'png', recipe })) as Blob | null;
+  }
+}
+
+/** Whether to draw in a worker: the browser has worker canvases, and the page did not ask otherwise. */
+function wantsWorker(): boolean {
+  if (typeof Worker !== 'function' || typeof OffscreenCanvas !== 'function' || typeof createImageBitmap !== 'function') return false;
+  try {
+    return new URLSearchParams(location.search).get('bitmaps') !== 'main';
+  } catch {
+    return true;
+  }
+}
+
+function makeBitmaps(): Bitmaps {
+  if (!wantsWorker()) return new BitmapStore();
+  try {
+    return new WorkerBitmaps(new Worker(new URL('./bitmapWorker.ts', import.meta.url), { type: 'module', name: 'bitmaps' }));
+  } catch {
+    return new BitmapStore();
+  }
+}
+
+/** The page's bitmaps: one store, as every source is named by its content. */
+export const bitmapStore: Bitmaps = makeBitmaps();
+
+/**
+ * One `<canvas>` showing a recipe. It draws once both the recipe and the
+ * laid-out size are known, again when either changes enough to matter, and
+ * never two drawings at once: a request that arrives during a drawing waits
+ * for it and takes the newest values. Until a drawing finishes the canvas
+ * keeps the previous picture, so a slider dragging a filter never blanks it.
+ */
+class BitmapView {
+  private recipe: BitmapRecipe | null = null;
+  private recipeKey = '';
+  private boxWidth = 0;
+  private boxHeight = 0;
+  private drawn = '';
+  private busy = false;
+  private again = false;
+
+  constructor(
+    private readonly canvas: HTMLCanvasElement,
+    private readonly store: Bitmaps,
+  ) {}
+
+  setRecipe(recipe: BitmapRecipe): void {
+    const key = JSON.stringify(recipe);
+    if (key === this.recipeKey) return;
+    this.recipe = recipe;
+    this.recipeKey = key;
+    this.update();
+  }
+
+  setBox(width: number, height: number): void {
+    if (width === this.boxWidth && height === this.boxHeight) return;
+    this.boxWidth = width;
+    this.boxHeight = height;
+    this.update();
+  }
+
+  private update(): void {
+    const recipe = this.recipe;
+    if (!recipe) return;
+    if (this.busy) {
+      this.again = true;
+      return;
+    }
+    const source = recipe.source === null ? undefined : this.store.sizeOf(recipe.source);
+    // Before layout, draw for the image's own size; layout refines it.
+    const ratio = typeof devicePixelRatio === 'number' && devicePixelRatio > 0 ? devicePixelRatio : 1;
+    const width = this.boxWidth > 0 ? this.boxWidth * ratio : recipe.width;
+    const height = this.boxHeight > 0 ? this.boxHeight * ratio : recipe.height;
+    const scale = workingScale(recipe.width, recipe.height, width, height, source ? source.width * source.height : 0);
+    const key = `${this.recipeKey}@${scale}`;
+    if (key === this.drawn) return;
+    this.busy = true;
+    this.store
+      .render(recipe, scale)
+      .then(
+        (image) => {
+          this.drawn = key;
+          this.paint(image);
+          this.canvas.dataset['sbBitmap'] = 'ready';
+        },
+        (error: unknown) => {
+          this.drawn = key;
+          this.paint(null);
+          this.canvas.dataset['sbBitmap'] = 'error';
+          console.warn(`[swiftbrowser] could not draw a bitmap: ${error instanceof Error ? error.message : String(error)}`);
+        },
+      )
+      .finally(() => {
+        this.busy = false;
+        this.canvas.dispatchEvent(new CustomEvent('sb:bitmap', { bubbles: true }));
+        if (this.again) {
+          this.again = false;
+          this.update();
+        }
+      });
+  }
+
+  private paint(image: RenderedBitmap | null): void {
+    const canvas = this.canvas;
+    if (!image) {
+      canvas.width = 0;
+      canvas.height = 0;
+      return;
+    }
+    if (canvas.width !== image.width) canvas.width = image.width;
+    if (canvas.height !== image.height) canvas.height = image.height;
+    if (isImageBitmap(image)) {
+      // From the worker: handed to the canvas as it is, without a copy.
+      const renderer = canvas.getContext('bitmaprenderer');
+      if (renderer) {
+        renderer.transferFromImageBitmap(image);
+        return;
+      }
+      canvas.getContext('2d')?.drawImage(image, 0, 0);
+      image.close();
+      return;
+    }
+    const context = canvas.getContext('2d');
+    if (!context) return;
+    if (image instanceof ImageData) {
+      context.putImageData(image, 0, 0);
+    } else {
+      context.clearRect(0, 0, image.width, image.height);
+      context.drawImage(image.canvas, 0, 0);
+    }
+  }
+}
+
+function isImageBitmap(image: RenderedBitmap): image is ImageBitmap {
+  return typeof ImageBitmap === 'function' && image instanceof ImageBitmap;
+}
+
+const views = new WeakMap<HTMLCanvasElement, BitmapView>();
+
+/** Shows `recipe` on `canvas` (drawn once the canvas is laid out). */
+export function showBitmap(canvas: HTMLCanvasElement, recipe: BitmapRecipe, store: Bitmaps = bitmapStore): void {
+  let view = views.get(canvas);
+  if (!view) {
+    view = new BitmapView(canvas, store);
+    views.set(canvas, view);
+  }
+  view.setRecipe(recipe);
+}
+
+/** The layout engine placed the `image` element `el` at `width` × `height` points. */
+export function bitmapLaidOut(el: HTMLElement, width: number, height: number): void {
+  const canvas = el.firstElementChild;
+  if (!(canvas instanceof HTMLCanvasElement)) return;
+  views.get(canvas)?.setBox(width, height);
+}