@swiftbrowser/web 0.1.0 → 0.3.0

package/src/blockedHosts.ts

@@ -0,0 +1,29 @@
+// Hosts an app is built not to reach (`swiftbrowser build --block-host
+// <host>`): a request to one of them, or to a subdomain, fails at once as if
+// the network were down, without leaving the page. For a public deploy of
+// an app whose analytics or other services belong to someone else (Ice Cubes'
+// TelemetryDeck signals): the app keeps working, those requests do not go out.
+
+/** Whether `url` is on one of `hosts` (or a subdomain of one). */
+export function isBlocked(url: string, hosts: readonly string[]): boolean {
+  let host: string;
+  try {
+    host = new URL(url).hostname.toLowerCase();
+  } catch {
+    return false;
+  }
+  return hosts.some((blocked) => {
+    const name = blocked.toLowerCase();
+    return host === name || host.endsWith(`.${name}`);
+  });
+}
+
+/** `fetchImpl`, failing requests to `hosts` as a network error does. */
+export function withBlockedHosts(fetchImpl: typeof fetch, hosts: readonly string[]): typeof fetch {
+  if (hosts.length === 0) return fetchImpl;
+  return async (input, init) => {
+    const url = typeof input === 'string' ? input : input instanceof URL ? input.href : input.url;
+    if (isBlocked(url, hosts)) throw new TypeError(`Failed to fetch: ${new URL(url).hostname} is blocked in this build`);
+    return fetchImpl(input, init);
+  };
+}

package/src/canvasDrawing.ts

@@ -0,0 +1,361 @@
+/**
+ * A `Canvas` (`canvas` element): the commands its renderer recorded in Swift
+ * (Sources/SwiftUI/API/Canvas.swift), drawn as SVG over the element's box and
+ * clipped to it. SVG rather than a `<canvas>` so paints keep the page's CSS
+ * colors (asset, semantic and accent colors follow the color scheme) and
+ * images are the catalog's files as `<image>`s.
+ *
+ * Each command is a `<g>` (its opacity, blend mode, filters and clip) around
+ * one element (its transform). An update reuses the elements in place, so a
+ * canvas redrawn on every frame (a `TimelineView`) keeps its decoded images
+ * instead of reloading them; only an image whose source changed is swapped.
+ */
+
+import type { AssetCatalog } from './assets';
+import { paintFor, type IdSource } from './chartDom';
+import { colorToCSS } from './styles';
+import { renderSymbol } from './symbols';
+import { resolveTextStyle, textStyleVar, DEFAULT_TYPE_SIZE, TEXT_STYLE_WEIGHT } from './typography';
+import {
+  isAssetImage,
+  isBitmapImage,
+  isUrlImage,
+  type CanvasCommand,
+  type CanvasFilter,
+  type CanvasProps,
+  type CanvasShading,
+  type Font,
+  type FontWeight,
+  type GradientStop,
+  type ImageProps,
+  type ShapeStyle,
+} from './protocol';
+
+const SVG_NS = 'http://www.w3.org/2000/svg';
+
+/** The size a system symbol is drawn at without a rectangle (the body font's). */
+const SYMBOL_SIZE = 20;
+/** The body font's size, for text drawn without a font. */
+const BODY_SIZE = 17;
+
+const WEIGHTS: Record<FontWeight, string> = {
+  ultraLight: '100',
+  thin: '200',
+  light: '300',
+  regular: '400',
+  medium: '500',
+  semibold: '600',
+  bold: '700',
+  heavy: '800',
+  black: '900',
+};
+
+let canvases = 0;
+
+interface CanvasState {
+  svg: SVGSVGElement;
+  defs: SVGDefsElement;
+  content: SVGGElement;
+  prefix: string;
+}
+
+const STATE = new WeakMap<HTMLElement, CanvasState>();
+
+/** The element of a `canvas`: a box that clips the SVG it holds. */
+export function createCanvasElement(): HTMLElement {
+  const el = document.createElement('div');
+  el.className = 'sb-canvas';
+  el.setAttribute('aria-hidden', 'true');
+  return el;
+}
+
+/** Draws `props` into `el` (made by {@link createCanvasElement}). */
+export function applyCanvas(el: HTMLElement, props: CanvasProps, assets: AssetCatalog): void {
+  let state = STATE.get(el);
+  if (!state) {
+    const svg = document.createElementNS(SVG_NS, 'svg');
+    const defs = document.createElementNS(SVG_NS, 'defs');
+    const content = document.createElementNS(SVG_NS, 'g');
+    svg.append(defs, content);
+    el.append(svg);
+    state = { svg, defs, content, prefix: `sb-canvas${++canvases}` };
+    STATE.set(el, state);
+  }
+  const width = finite(props.width, 0);
+  const height = finite(props.height, 0);
+  state.svg.setAttribute('width', String(width));
+  state.svg.setAttribute('height', String(height));
+  state.svg.setAttribute('viewBox', `0 0 ${width} ${height}`);
+  state.defs.replaceChildren();
+  const ids: IdSource = { next: 0, prefix: state.prefix };
+  const box = { x: 0, y: 0, width, height };
+  const commands = Array.isArray(props.commands) ? props.commands : [];
+  const groups = state.content.children;
+  let index = 0;
+  for (const command of commands) {
+    if (!command || typeof command !== 'object') continue;
+    const tag = tagFor(command, assets);
+    if (!tag) continue;
+    let group = groups[index] as SVGGElement | undefined;
+    let shape = group?.firstElementChild as SVGElement | null | undefined;
+    if (!group || !shape || shape.localName !== tag) {
+      const fresh = document.createElementNS(SVG_NS, 'g');
+      shape = tag === 'svg' ? null : document.createElementNS(SVG_NS, tag);
+      if (shape) fresh.append(shape);
+      if (group) group.replaceWith(fresh);
+      else state.content.append(fresh);
+      group = fresh;
+    }
+    const drawn = draw(group, shape ?? null, command, assets, state.defs, ids, box);
+    applyState(group, drawn, command, state.defs, ids);
+    index++;
+  }
+  while (groups.length > index) groups[groups.length - 1]!.remove();
+}
+
+/** The SVG element a command draws with; null for what is not drawn (a bitmap, a missing image). */
+function tagFor(command: CanvasCommand, assets: AssetCatalog): string | null {
+  switch (command.op) {
+    case 'fill':
+    case 'stroke':
+      return 'path';
+    case 'text':
+      return 'text';
+    case 'image': {
+      const image = command.image;
+      if (!image || typeof image !== 'object' || isBitmapImage(image)) return null;
+      if (isUrlImage(image)) return 'image';
+      if (isAssetImage(image)) return assets.images[image.name] ? 'image' : null;
+      return 'svg';
+    }
+    default:
+      return null;
+  }
+}
+
+/** Draws `command` with `shape` (made anew for a symbol); returns the element drawn. */
+function draw(
+  group: SVGGElement,
+  shape: SVGElement | null,
+  command: CanvasCommand,
+  assets: AssetCatalog,
+  defs: SVGDefsElement,
+  ids: IdSource,
+  box: { x: number; y: number; width: number; height: number },
+): SVGElement {
+  switch (command.op) {
+    case 'fill': {
+      const path = shape!;
+      setAttr(path, 'd', command.path ?? '');
+      path.style.fill = paint(command.shading, defs, ids, box);
+      path.style.stroke = 'none';
+      setAttr(path, 'fill-rule', command.evenOdd ? 'evenodd' : null);
+      clearStroke(path);
+      return path;
+    }
+    case 'stroke': {
+      const path = shape!;
+      setAttr(path, 'd', command.path ?? '');
+      path.style.fill = 'none';
+      path.style.stroke = paint(command.shading, defs, ids, box);
+      setAttr(path, 'fill-rule', null);
+      setAttr(path, 'stroke-width', String(finite(command.lineWidth, 1)));
+      setAttr(path, 'stroke-linecap', command.lineCap ?? 'butt');
+      setAttr(path, 'stroke-linejoin', command.lineJoin ?? 'miter');
+      setAttr(path, 'stroke-miterlimit', String(finite(command.miterLimit, 10)));
+      const dash = Array.isArray(command.dash) && command.dash.length > 0 ? command.dash.join(' ') : null;
+      setAttr(path, 'stroke-dasharray', dash);
+      setAttr(path, 'stroke-dashoffset', dash ? String(finite(command.dashPhase, 0)) : null);
+      return path;
+    }
+    case 'text': {
+      const text = shape!;
+      if (text.textContent !== command.text) text.textContent = command.text ?? '';
+      setAttr(text, 'x', String(finite(command.x, 0)));
+      setAttr(text, 'y', String(finite(command.y, 0)));
+      const ax = finite(command.anchor?.x, 0.5);
+      const ay = finite(command.anchor?.y, 0.5);
+      setAttr(text, 'text-anchor', ax < 0.25 ? 'start' : ax > 0.75 ? 'end' : 'middle');
+      setAttr(text, 'dominant-baseline', ay < 0.25 ? 'text-before-edge' : ay > 0.75 ? 'text-after-edge' : 'central');
+      text.style.fill = paint(command.shading, defs, ids, box);
+      applyFont(text, command.font);
+      return text;
+    }
+    case 'image':
+      return drawImage(group, shape, command, assets, defs, ids, box);
+  }
+}
+
+function drawImage(
+  group: SVGGElement,
+  shape: SVGElement | null,
+  command: Extract<CanvasCommand, { op: 'image' }>,
+  assets: AssetCatalog,
+  defs: SVGDefsElement,
+  ids: IdSource,
+  box: { x: number; y: number; width: number; height: number },
+): SVGElement {
+  const size = imageSize(command.image, assets);
+  const width = finite(command.width, size.width);
+  const height = finite(command.height, size.height);
+  const x = finite(command.x, 0) - finite(command.anchor?.x, 0.5) * width;
+  const y = finite(command.y, 0) - finite(command.anchor?.y, 0.5) * height;
+  if (shape === null || shape.localName === 'svg') {
+    // A system symbol: its glyph, painted with the shading (else the foreground).
+    const name = (command.image as { systemName?: string }).systemName ?? '';
+    if (shape === null || shape.dataset['sbSymbol'] !== name) {
+      const glyph = renderSymbol(name) ?? document.createElementNS(SVG_NS, 'svg');
+      glyph.dataset['sbSymbol'] = name;
+      group.replaceChildren(glyph);
+      shape = glyph;
+    }
+    shape.style.color = command.shading ? paint(command.shading, defs, ids, box) : colorToCSS({ name: 'primary' });
+  }
+  setAttr(shape, 'x', String(x));
+  setAttr(shape, 'y', String(y));
+  setAttr(shape, 'width', String(Math.max(0, width)));
+  setAttr(shape, 'height', String(Math.max(0, height)));
+  if (shape.localName === 'image') {
+    setAttr(shape, 'preserveAspectRatio', 'none');
+    const src = imageSource(command.image, assets);
+    if (src && shape.getAttribute('href') !== src) shape.setAttribute('href', src);
+  }
+  return shape;
+}
+
+function imageSize(image: ImageProps, assets: AssetCatalog): { width: number; height: number } {
+  if (isUrlImage(image)) return { width: finite(image.width, 0), height: finite(image.height, 0) };
+  if (isAssetImage(image)) {
+    const asset = assets.images[image.name];
+    return { width: finite(asset?.width, 0), height: finite(asset?.height, 0) };
+  }
+  return { width: SYMBOL_SIZE, height: SYMBOL_SIZE };
+}
+
+function imageSource(image: ImageProps, assets: AssetCatalog): string | null {
+  if (isUrlImage(image)) return image.url;
+  if (isAssetImage(image)) return assets.images[image.name]?.src ?? null;
+  return null;
+}
+
+/** The context state of `command`: transform on the shape; the rest on its group. */
+function applyState(group: SVGGElement, shape: SVGElement, command: CanvasCommand, defs: SVGDefsElement, ids: IdSource): void {
+  const t = command.transform;
+  setAttr(shape, 'transform', Array.isArray(t) && t.length === 6 ? `matrix(${t.map((n) => finite(n, 0)).join(' ')})` : null);
+  const opacity = command.opacity;
+  group.style.opacity = opacity != null && opacity < 1 ? String(Math.max(0, opacity)) : '';
+  group.style.mixBlendMode = command.blendMode && command.blendMode !== 'normal' ? command.blendMode : '';
+  group.style.filter = filterCSS(command.filters);
+  let clip: string | null = null;
+  for (const d of Array.isArray(command.clips) ? command.clips : []) {
+    const id = `${ids.prefix}-clip${ids.next++}`;
+    const clipPath = document.createElementNS(SVG_NS, 'clipPath');
+    clipPath.id = id;
+    // A clip within the previous one: the intersection.
+    if (clip) clipPath.setAttribute('clip-path', `url(#${clip})`);
+    const path = document.createElementNS(SVG_NS, 'path');
+    path.setAttribute('d', d);
+    clipPath.append(path);
+    defs.append(clipPath);
+    clip = id;
+  }
+  setAttr(group, 'clip-path', clip ? `url(#${clip})` : null);
+}
+
+function filterCSS(filters: CanvasFilter[] | undefined): string {
+  if (!Array.isArray(filters)) return '';
+  const parts: string[] = [];
+  for (const filter of filters) {
+    if (!filter || typeof filter !== 'object') continue;
+    if ('blur' in filter) parts.push(`blur(${finite(filter.blur, 0)}px)`);
+    else if ('shadow' in filter) {
+      const { color, radius, x, y } = filter.shadow;
+      parts.push(`drop-shadow(${finite(x, 0)}px ${finite(y, 0)}px ${finite(radius, 0)}px ${colorToCSS(color)})`);
+    } else if ('grayscale' in filter) parts.push(`grayscale(${finite(filter.grayscale, 0)})`);
+    else if ('saturation' in filter) parts.push(`saturate(${finite(filter.saturation, 1)})`);
+    // SwiftUI's brightness adds to each component (0 leaves it as is).
+    else if ('brightness' in filter) parts.push(`brightness(${1 + finite(filter.brightness, 0)})`);
+    else if ('contrast' in filter) parts.push(`contrast(${finite(filter.contrast, 1)})`);
+    else if ('hueRotation' in filter) parts.push(`hue-rotate(${finite(filter.hueRotation, 0)}deg)`);
+    else if ('invert' in filter) parts.push(`invert(${finite(filter.invert, 1)})`);
+  }
+  return parts.join(' ');
+}
+
+/** The SVG paint of a shading; a canvas gradient is in the shape's own coordinates. */
+function paint(shading: CanvasShading | undefined, defs: SVGDefsElement, ids: IdSource, box: { x: number; y: number; width: number; height: number }): string {
+  if (!shading || typeof shading !== 'object') return colorToCSS({ name: 'primary' });
+  if ('canvasLinearGradient' in shading) {
+    const { stops, start, end } = shading.canvasLinearGradient;
+    const gradient = document.createElementNS(SVG_NS, 'linearGradient');
+    setAttrs(gradient, {
+      gradientUnits: 'userSpaceOnUse',
+      x1: finite(start?.x, 0),
+      y1: finite(start?.y, 0),
+      x2: finite(end?.x, 0),
+      y2: finite(end?.y, 0),
+    });
+    return addGradient(gradient, stops, defs, ids);
+  }
+  if ('canvasRadialGradient' in shading) {
+    const { stops, center, startRadius, endRadius } = shading.canvasRadialGradient;
+    const gradient = document.createElementNS(SVG_NS, 'radialGradient');
+    setAttrs(gradient, {
+      gradientUnits: 'userSpaceOnUse',
+      cx: finite(center?.x, 0),
+      cy: finite(center?.y, 0),
+      r: Math.max(0, finite(endRadius, 0)),
+      fr: Math.max(0, finite(startRadius, 0)),
+    });
+    return addGradient(gradient, stops, defs, ids);
+  }
+  return paintFor(document, defs, shading as ShapeStyle, box, ids);
+}
+
+function addGradient(gradient: SVGElement, stops: GradientStop[] | undefined, defs: SVGDefsElement, ids: IdSource): string {
+  const id = `${ids.prefix}-grad${ids.next++}`;
+  gradient.id = id;
+  const valid = (Array.isArray(stops) ? stops : []).filter((stop) => stop && typeof stop === 'object' && stop.color);
+  const colors = valid.length === 0 ? [] : valid.length === 1 ? [valid[0]!, { ...valid[0]!, location: 1 }] : valid;
+  for (const stop of colors) {
+    const el = document.createElementNS(SVG_NS, 'stop');
+    el.setAttribute('offset', String(Math.min(1, Math.max(0, finite(stop.location, 0)))));
+    el.style.stopColor = colorToCSS(stop.color);
+    gradient.append(el);
+  }
+  defs.append(gradient);
+  return `url(#${id})`;
+}
+
+function applyFont(text: SVGElement, font: Font | undefined): void {
+  const s = text.style;
+  s.fontSize = `${BODY_SIZE}px`;
+  s.fontWeight = '';
+  if (!font || typeof font !== 'object') return;
+  if (font.size != null) s.fontSize = `${finite(font.size, BODY_SIZE)}px`;
+  else if (font.textStyle) {
+    s.fontSize = `var(${textStyleVar(font.textStyle, 'size')}, ${resolveTextStyle(font.textStyle, DEFAULT_TYPE_SIZE).fontSize}px)`;
+    const implied = TEXT_STYLE_WEIGHT[font.textStyle];
+    if (!font.weight && implied) s.fontWeight = WEIGHTS[implied];
+  }
+  if (font.weight) s.fontWeight = WEIGHTS[font.weight] ?? '400';
+}
+
+function clearStroke(path: SVGElement): void {
+  for (const name of ['stroke-width', 'stroke-linecap', 'stroke-linejoin', 'stroke-miterlimit', 'stroke-dasharray', 'stroke-dashoffset']) {
+    path.removeAttribute(name);
+  }
+}
+
+function setAttr(el: Element, name: string, value: string | null): void {
+  if (value == null) el.removeAttribute(name);
+  else if (el.getAttribute(name) !== value) el.setAttribute(name, value);
+}
+
+function setAttrs(el: Element, attrs: Record<string, string | number>): void {
+  for (const [name, value] of Object.entries(attrs)) el.setAttribute(name, String(value));
+}
+
+function finite(value: number | undefined | null, fallback: number): number {
+  return typeof value === 'number' && Number.isFinite(value) ? value : fallback;
+}

package/src/chartDom.ts

@@ -159,7 +159,7 @@ function gridLines(axis: ChartAxis | null | undefined): number[] {
   return axis && Array.isArray(axis.gridLines) ? axis.gridLines.filter((v) => typeof v === 'number' && Number.isFinite(v)) : [];
 }
 
-interface IdSource {
+export interface IdSource {
   next: number;
   prefix: string;
 }
@@ -325,7 +325,7 @@ function clipPathFor(doc: Document, defs: SVGDefsElement, mask: ChartMark, plot:
  * a `<linearGradient>` / `<radialGradient>` to `defs`. `bbox` is the mark's
  * pixel bounds, which a radial gradient's center and radii refer to.
  */
-function paintFor(doc: Document, defs: SVGDefsElement, style: ShapeStyle | undefined, bbox: Rect, ids: IdSource): string {
+export function paintFor(doc: Document, defs: SVGDefsElement, style: ShapeStyle | undefined, bbox: Rect, ids: IdSource): string {
   if (!style || typeof style !== 'object') return 'var(--sb-color-accent)';
   if (isColor(style)) return colorToCSS(style);
   if (isHierarchicalStyle(style)) return styleToCSS(style, 'paint').value;

package/src/chromeColor.ts

@@ -0,0 +1,179 @@
+/**
+ * The browser's own chrome around the app on a phone (device mode): the
+ * status bar strip and the safe areas Safari tints, which take their color
+ * from `theme-color`, the page background and (in recent Safari) the fixed
+ * element at the top edge. The page's defaults follow the OS appearance, not
+ * the app, so an app with its own bar color (Ice Cubes' themes) or its own
+ * `.preferredColorScheme` sat under a strip of a different color.
+ *
+ * After each layout this samples the color the app draws at the middle of
+ * its top edge (every layer there, translucent bars over what is behind
+ * them) and gives it to `theme-color`, the page background and the device
+ * element; the page's `color-scheme` follows the app's.
+ */
+
+/** An RGBA color, 0–255 channels and 0–1 alpha. */
+interface Rgba {
+  r: number;
+  g: number;
+  b: number;
+  a: number;
+}
+
+/** `rgb(…)` / `rgba(…)` as computed styles write it, or `#rgb` / `#rrggbb`; null for anything else. */
+export function parseCssColor(value: string): Rgba | null {
+  const hex = /^#([0-9a-f]{3}|[0-9a-f]{6})$/i.exec(value.trim());
+  if (hex) {
+    const digits = hex[1]!.length === 3 ? [...hex[1]!].map((d) => d + d).join('') : hex[1]!;
+    const n = Number.parseInt(digits, 16);
+    return { r: (n >> 16) & 255, g: (n >> 8) & 255, b: n & 255, a: 1 };
+  }
+  const match = /^rgba?\(\s*([\d.]+)[,\s]+([\d.]+)[,\s]+([\d.]+)(?:\s*[,/]\s*([\d.]+%?))?\s*\)$/.exec(value.trim());
+  if (!match) return null;
+  let a = 1;
+  if (match[4] !== undefined) a = match[4].endsWith('%') ? Number.parseFloat(match[4]) / 100 : Number(match[4]);
+  return { r: Number(match[1]), g: Number(match[2]), b: Number(match[3]), a };
+}
+
+/**
+ * The color seen through `layers`, topmost first, over an opaque `base`
+ * (source-over compositing; layers below an opaque one do not show).
+ */
+export function compositeColors(layers: readonly Rgba[], base: Rgba): Rgba {
+  let r = 0;
+  let g = 0;
+  let b = 0;
+  let a = 0;
+  for (const layer of [...layers, { ...base, a: 1 }]) {
+    const weight = (1 - a) * layer.a;
+    r += layer.r * weight;
+    g += layer.g * weight;
+    b += layer.b * weight;
+    a += weight;
+    if (a >= 0.999) break;
+  }
+  return { r: r / a, g: g / a, b: b / a, a: 1 };
+}
+
+/** `#rrggbb`. */
+export function hexColor(color: Rgba): string {
+  const channel = (value: number): string =>
+    Math.round(Math.min(255, Math.max(0, value)))
+      .toString(16)
+      .padStart(2, '0');
+  return `#${channel(color.r)}${channel(color.g)}${channel(color.b)}`;
+}
+
+/** At most one sample in this many milliseconds. */
+const MIN_INTERVAL = 250;
+
+/** A painted background under the sampled point, and where it paints in the stack. */
+interface Layer {
+  color: Rgba;
+  /** The explicit `z-index`es from the screen down to it. */
+  z: number[];
+  /** Its document order. */
+  order: number;
+}
+
+/** Whether `a` paints above `b`: by stacking order, then later in the document. */
+function above(a: Layer, b: Layer): number {
+  for (let i = 0; i < Math.max(a.z.length, b.z.length); i++) {
+    const d = (a.z[i] ?? 0) - (b.z[i] ?? 0);
+    if (d !== 0) return -d;
+  }
+  return b.order - a.order;
+}
+
+/**
+ * The backgrounds painted at (`x`, `y`) inside `root`, topmost first. Only
+ * elements whose box holds the point are walked (the engine places children
+ * inside their parents; a zero-size slot is walked through), so this reads
+ * tens of boxes and styles, not the page. `elementsFromPoint` would skip the many app layers that let
+ * pointers through (`pointer-events: none`), and turning that off restyles
+ * every element.
+ */
+export function layersAt(root: Element, x: number, y: number): Rgba[] {
+  const view = root.ownerDocument.defaultView;
+  if (!view) return [];
+  const layers: Layer[] = [];
+  let order = 0;
+  const walk = (parent: Element, opacity: number, z: number[]): void => {
+    for (const el of parent.children) {
+      const r = el.getBoundingClientRect();
+      const inside = x >= r.left && x < r.right && y >= r.top && y < r.bottom;
+      // A zero-size wrapper (a slot) is walked through: its children overflow it.
+      if (!inside && r.width > 0 && r.height > 0) continue;
+      const style = view.getComputedStyle(el);
+      if (style.display === 'none') continue;
+      const alpha = opacity * Number(style.opacity || 1);
+      if (alpha <= 0.001) continue;
+      const own = style.position !== 'static' && style.zIndex !== 'auto' ? [...z, Number(style.zIndex) || 0] : z;
+      const color = inside && style.visibility === 'visible' ? parseCssColor(style.backgroundColor) : null;
+      if (color && color.a > 0) layers.push({ color: { ...color, a: color.a * alpha }, z: own, order: order++ });
+      walk(el, alpha, own);
+    }
+  };
+  walk(root, 1, []);
+  return layers.sort(above).map((layer) => layer.color);
+}
+
+/** Keeps the browser chrome's color in step with the app's top edge. */
+export class ChromeColor {
+  private scheduled = false;
+  private last = 0;
+  private applied = '';
+  private readonly meta: HTMLMetaElement;
+
+  constructor(
+    private readonly device: HTMLElement,
+    private readonly screen: HTMLElement,
+  ) {
+    const doc = device.ownerDocument;
+    // One `theme-color` the page sets, in place of the per-appearance pair.
+    for (const meta of doc.querySelectorAll('meta[name="theme-color"]')) meta.remove();
+    this.meta = doc.createElement('meta');
+    this.meta.name = 'theme-color';
+    doc.head.append(this.meta);
+    // A push, pop or sheet changes the top edge when its animation ends.
+    screen.addEventListener('animationend', () => this.schedule());
+    screen.addEventListener('transitionend', () => this.schedule());
+  }
+
+  /** Sample again once the current frame is drawn (call after each layout and theme change). */
+  schedule(): void {
+    if (this.scheduled) return;
+    this.scheduled = true;
+    const wait = Math.max(0, this.last + MIN_INTERVAL - performance.now());
+    setTimeout(() => {
+      requestAnimationFrame(() => {
+        this.scheduled = false;
+        this.last = performance.now();
+        this.sample();
+      });
+    }, wait);
+  }
+
+  private sample(): void {
+    const doc = this.device.ownerDocument;
+    const rect = this.screen.getBoundingClientRect();
+    if (rect.width === 0 || rect.height === 0) return;
+    const view = doc.defaultView;
+    if (!view) return;
+    const layers = layersAt(this.screen, rect.left + rect.width / 2, rect.top + 1);
+    const theme = this.device.dataset['theme'] === 'dark' ? 'dark' : 'light';
+    const base =
+      parseCssColor(view.getComputedStyle(this.device).getPropertyValue('--sb-color-system-background')) ??
+      (theme === 'dark' ? { r: 0, g: 0, b: 0, a: 1 } : { r: 255, g: 255, b: 255, a: 1 });
+    const color = hexColor(compositeColors(layers, base));
+    const key = `${color}|${theme}`;
+    if (key === this.applied) return;
+    this.applied = key;
+    this.meta.content = color;
+    const root = doc.documentElement;
+    root.style.colorScheme = theme;
+    root.style.backgroundColor = color;
+    doc.body.style.backgroundColor = color;
+    this.device.style.backgroundColor = color;
+  }
+}

package/src/clipboard.ts

@@ -0,0 +1,78 @@
+/**
+ * `UIPasteboard.general` (Sources/UIKit/Pasteboard.swift): what the app
+ * copies also goes to the system clipboard, through the Async Clipboard API.
+ * Text is written with `writeText`; a picture as an `image/png` clipboard
+ * item (the one image type browsers accept), converted from JPEG or another
+ * format when needed. The write is started before the request's first
+ * `await`, while the tap that copied may still count as user activation
+ * (Safari requires it; Chromium wants the document focused). Reading
+ * (`readText`) may ask the viewer, or be refused; the app's own pasteboard
+ * keeps what it copied either way. See docs/ops-protocol.md, "Sharing and media".
+ */
+
+import type { ClipboardRequestParams } from './protocol';
+
+/** The system clipboard; tests substitute it. */
+export interface ClipboardHost {
+  writeText(text: string): Promise<void>;
+  /** Writes a PNG. `png` may still be on its way: the write itself must start within the tap. */
+  writeImage(png: Promise<Blob>): Promise<void>;
+  readText(): Promise<string>;
+}
+
+/** The browser's `navigator.clipboard`, where the page has one (a secure context). */
+export function browserClipboardHost(): ClipboardHost | undefined {
+  if (typeof navigator === 'undefined' || !navigator.clipboard) return undefined;
+  const clipboard = navigator.clipboard;
+  return {
+    writeText: (text) => clipboard.writeText(text),
+    writeImage: (png) =>
+      typeof ClipboardItem === 'function'
+        ? clipboard.write([new ClipboardItem({ 'image/png': png })])
+        : Promise.reject(new Error('unsupported: this browser cannot copy images')),
+    readText: () => clipboard.readText(),
+  };
+}
+
+/**
+ * Performs a `clipboard` request. `pictures` gathers the request's files,
+ * catalog images and bitmaps (hostRequests.ts); the first becomes the
+ * copied image.
+ */
+export async function performClipboard(
+  params: ClipboardRequestParams,
+  host: ClipboardHost | undefined,
+  pictures: () => Promise<File[]>,
+): Promise<{ text?: string }> {
+  if (!host) throw new Error('unsupported: this page has no clipboard');
+  if (params.action === 'readText') return { text: await host.readText() };
+  if (typeof params.text === 'string') {
+    await host.writeText(params.text);
+    return {};
+  }
+  const png = pictures().then((files) => {
+    const first = files[0];
+    if (!first) throw new Error('unsupported: nothing to copy');
+    return toPNG(first);
+  });
+  await host.writeImage(png);
+  return {};
+}
+
+/** The picture as PNG: as it is when it is one, else drawn on a canvas and encoded. */
+export async function toPNG(blob: Blob): Promise<Blob> {
+  if (blob.type === 'image/png') return blob;
+  const bitmap = await createImageBitmap(blob);
+  if (typeof OffscreenCanvas === 'function') {
+    const canvas = new OffscreenCanvas(bitmap.width, bitmap.height);
+    canvas.getContext('2d')?.drawImage(bitmap, 0, 0);
+    return canvas.convertToBlob({ type: 'image/png' });
+  }
+  const canvas = document.createElement('canvas');
+  canvas.width = bitmap.width;
+  canvas.height = bitmap.height;
+  canvas.getContext('2d')?.drawImage(bitmap, 0, 0);
+  return new Promise((resolve, reject) =>
+    canvas.toBlob((png) => (png ? resolve(png) : reject(new Error('unsupported: could not encode PNG'))), 'image/png'),
+  );
+}