@opsydyn/effect-three-foldkit 0.0.0-stage → 0.1.0

package/src/dom/overlays.ts

@@ -0,0 +1,63 @@
+/**
+ * Moves the application's overlay HTML to where the scene placed each overlay, as Drei's
+ * `Html` does every frame (`src/web/Html.tsx` at `bf6f4ad`): a translate to the point,
+ * the distance scale, centring, the depth's z-index, and hiding when not visible.
+ *
+ * @module
+ */
+import type { OverlayPlacement } from '@opsydyn/effect-three';
+
+/** The data attribute naming the overlay an element's HTML belongs to. */
+export const overlayData = {
+  key: 'effect-three-overlay',
+  attribute: 'data-effect-three-overlay',
+} as const;
+
+const transformOf = (placement: OverlayPlacement): string =>
+  `translate3d(${placement.x}px,${placement.y}px,0) scale(${placement.scale})${
+    placement.center ? ' translate(-50%,-50%)' : ''
+  }`;
+
+/** Writes one placement, touching only the style values that changed. */
+const write = (element: HTMLElement, placement: OverlayPlacement): void => {
+  const { style } = element;
+  const transform = transformOf(placement);
+  if (style.transform !== transform) style.transform = transform;
+  const zIndex = String(placement.zIndex);
+  if (style.zIndex !== zIndex) style.zIndex = zIndex;
+  const visibility = placement.visible ? 'visible' : 'hidden';
+  if (style.visibility !== visibility) style.visibility = visibility;
+};
+
+export type OverlayWriter = {
+  /** Takes the latest placements and writes them. */
+  readonly place: (placements: ReadonlyArray<OverlayPlacement>) => void;
+  /** Writes the latest placements again, for overlay elements the view has just made. */
+  readonly rewrite: () => void;
+};
+
+/** Creates the writer for overlays rendered inside `host`. */
+export const createOverlayWriter = (host: Element): OverlayWriter => {
+  let latest: ReadonlyArray<OverlayPlacement> = [];
+  const rewrite = (): void => {
+    for (const placement of latest) {
+      const element = host.querySelector(
+        `[${overlayData.attribute}="${CSS.escape(placement.key)}"]`,
+      );
+      if (element instanceof HTMLElement) write(element, placement);
+    }
+  };
+  return {
+    place: (placements) => {
+      latest = placements;
+      rewrite();
+    },
+    rewrite,
+  };
+};
+
+/** Makes the scene element the overlays' containing block, unless it already is one. */
+export const containOverlays = (host: Element) => (): void => {
+  if (!(host instanceof HTMLElement)) return;
+  if (getComputedStyle(host).position === 'static') host.style.position = 'relative';
+};

package/src/dom/pointer.ts

@@ -0,0 +1,163 @@
+/**
+ * DOM pointer events to the kernel's normalised device coordinates.
+ *
+ * @module
+ */
+import type { Gestures, Modifiers, PointerInput, SceneEvent } from '@opsydyn/effect-three';
+
+/** The part of `DOMRect` the conversion needs. */
+export type Rect = {
+  readonly left: number;
+  readonly top: number;
+  readonly width: number;
+  readonly height: number;
+};
+
+/** Client coordinates to NDC: x and y in [-1, 1], y up. A zero-sized rect maps to the centre. */
+export const toNdc = (
+  rect: Rect,
+  clientX: number,
+  clientY: number,
+): { readonly x: number; readonly y: number } => {
+  if (rect.width === 0 || rect.height === 0) return { x: 0, y: 0 };
+  return {
+    x: ((clientX - rect.left) / rect.width) * 2 - 1,
+    y: -(((clientY - rect.top) / rect.height) * 2 - 1),
+  };
+};
+
+const modifiersOf = (event: MouseEvent): Modifiers => ({
+  shift: event.shiftKey,
+  control: event.ctrlKey,
+  meta: event.metaKey,
+  alt: event.altKey,
+});
+
+/** The pointer's id, or 0 for mouse events that are not pointer events. */
+const pointerIdOf = (event: MouseEvent): number =>
+  event instanceof PointerEvent ? event.pointerId : 0;
+
+/**
+ * Wheel deltas in CSS pixels: line and page modes scaled as three.js's `OrbitControls`
+ * scales them (`_customWheelEvent`: 16 and 100).
+ */
+const wheelScale = [1, 16, 100] as const;
+
+/**
+ * Converts a DOM pointer, mouse or wheel event into kernel input, or `undefined` for
+ * other event types. Pointer cancel is treated as leaving the surface.
+ */
+export const toPointerInput = (event: MouseEvent, rect: Rect): PointerInput | undefined => {
+  if (event.type === 'pointerleave' || event.type === 'pointercancel') {
+    return { _tag: 'PointerLeave' };
+  }
+  const { x, y } = toNdc(rect, event.clientX, event.clientY);
+  const pointer = pointerIdOf(event);
+  switch (event.type) {
+    case 'pointermove':
+      return { _tag: 'PointerMove', x, y, pointer };
+    case 'pointerdown':
+      return {
+        _tag: 'PointerDown',
+        x,
+        y,
+        button: event.button,
+        pointer,
+        modifiers: modifiersOf(event),
+      };
+    case 'pointerup':
+      return { _tag: 'PointerUp', x, y, button: event.button, pointer };
+    case 'dblclick':
+      return { _tag: 'DoubleClick', x, y, button: event.button };
+    case 'contextmenu':
+      return { _tag: 'ContextMenu', x, y };
+    case 'wheel':
+      return event instanceof WheelEvent
+        ? {
+            _tag: 'Wheel',
+            x,
+            y,
+            deltaX: event.deltaX * (wheelScale[event.deltaMode] ?? 1),
+            deltaY: event.deltaY * (wheelScale[event.deltaMode] ?? 1),
+            modifiers: modifiersOf(event),
+          }
+        : undefined;
+    default:
+      return undefined;
+  }
+};
+
+/** True when a press landed on an interactive mesh, which then captures the pointer. */
+export const capturesPointer = (events: ReadonlyArray<SceneEvent>): boolean =>
+  events.some((event) => event._tag === 'PointerDown');
+
+/** True when the scene handled a context-menu input, so the browser menu should not open. */
+export const claimsContextMenu = (events: ReadonlyArray<SceneEvent>): boolean =>
+  events.some((event) => event._tag === 'ContextMenu');
+
+const eventTypes = [
+  'pointermove',
+  'pointerdown',
+  'pointerup',
+  'pointerleave',
+  'pointercancel',
+  'dblclick',
+  'contextmenu',
+  'wheel',
+] as const;
+
+/**
+ * Forwards pointer, mouse and wheel input from `element`. `onInput` returns the scene
+ * events it produced. By default the page keeps its gestures: wheel and touch scroll it,
+ * and the browser's menu opens except over an interactive mesh that handles it. A press
+ * on a mesh captures the pointer.
+ *
+ * While `claimsGestures()` is true the scene owns them, as three.js's `OrbitControls` does
+ * when connected: every press captures the pointer, the wheel does not scroll the page,
+ * and the context menu stays shut (the right button pans). Returns a function that
+ * removes every listener.
+ */
+export const listenForPointer = (
+  element: HTMLElement,
+  onInput: (input: PointerInput) => ReadonlyArray<SceneEvent>,
+  claimsGestures: () => boolean = () => false,
+): (() => void) => {
+  const listener = (event: Event): void => {
+    if (!(event instanceof MouseEvent)) return;
+    const input = toPointerInput(event, element.getBoundingClientRect());
+    if (input === undefined) return;
+    const events = onInput(input);
+    const claimed = claimsGestures();
+    if (claimed && (event.type === 'wheel' || event.type === 'contextmenu')) {
+      event.preventDefault();
+    }
+    if (event.type === 'contextmenu' && claimsContextMenu(events)) event.preventDefault();
+    // Keep the drag's moves and release coming here even off the canvas, as React Three
+    // Fiber's setPointerCapture does. The browser releases capture on pointer up.
+    if (
+      event instanceof PointerEvent &&
+      event.type === 'pointerdown' &&
+      (claimed || capturesPointer(events))
+    ) {
+      element.setPointerCapture(event.pointerId);
+    }
+  };
+  // Not passive, so a claimed wheel can stop the page scrolling; unclaimed wheels are
+  // left alone.
+  for (const type of eventTypes) element.addEventListener(type, listener, { passive: false });
+  return () => {
+    for (const type of eventTypes) element.removeEventListener(type, listener);
+  };
+};
+
+/** Whatever reports the scene's claim on gestures: its graph. */
+type GestureOwner = { readonly gestures: () => Gestures };
+
+/** Whether the scene currently claims the pointer's gestures. */
+export const claimsGestures = (owner: GestureOwner) => (): boolean => owner.gestures() === 'scene';
+
+/** Lets the browser pan and zoom on touch, or not while the scene claims gestures. */
+export const touchActionSync = (element: HTMLElement, owner: GestureOwner) => (): void => {
+  const touchAction = claimsGestures(owner)() ? 'none' : '';
+  if (element.style.touchAction !== touchAction) element.style.touchAction = touchAction;
+};

package/src/dom/postprocessing.ts

@@ -0,0 +1,116 @@
+/**
+ * Post-processing for the WebGL renderer: three.js's `EffectComposer`, built from the
+ * scene's `render.effects` and rebuilt only when they change. With no effects the scene
+ * renders straight to the screen and no composer exists.
+ *
+ * The composer renders into a multisampled target, so antialiasing survives, and ends
+ * with three's `OutputPass`, which applies tone mapping and the output colour space.
+ *
+ * @module
+ */
+import { effectsEqual, type PostEffect } from '@opsydyn/effect-three';
+import {
+  type Camera,
+  HalfFloatType,
+  PerspectiveCamera,
+  type Scene,
+  Scene as EmptyScene,
+  Vector2,
+  type WebGLRenderer,
+  WebGLRenderTarget,
+} from 'three';
+import { EffectComposer } from 'three/addons/postprocessing/EffectComposer.js';
+import { FilmPass } from 'three/addons/postprocessing/FilmPass.js';
+import { OutputPass } from 'three/addons/postprocessing/OutputPass.js';
+import type { Pass } from 'three/addons/postprocessing/Pass.js';
+import { RenderPass } from 'three/addons/postprocessing/RenderPass.js';
+import { ShaderPass } from 'three/addons/postprocessing/ShaderPass.js';
+import { UnrealBloomPass } from 'three/addons/postprocessing/UnrealBloomPass.js';
+import { VignetteShader } from 'three/addons/shaders/VignetteShader.js';
+
+type Size = { width: number; height: number; pixelRatio: number };
+
+const passFor = (effect: PostEffect, size: Size): Pass => {
+  switch (effect._tag) {
+    case 'Bloom':
+      return new UnrealBloomPass(
+        new Vector2(size.width, size.height),
+        effect.strength,
+        effect.radius,
+        effect.threshold,
+      );
+    case 'Vignette': {
+      const pass = new ShaderPass(VignetteShader);
+      pass.uniforms['offset'] = { value: effect.offset };
+      pass.uniforms['darkness'] = { value: effect.darkness };
+      return pass;
+    }
+    case 'Film':
+      return new FilmPass(effect.intensity, effect.grayscale);
+  }
+};
+
+export type PostProcessing = {
+  /** Rebuilds the passes when `effects` differ from the current ones. */
+  readonly configure: (effects: ReadonlyArray<PostEffect>) => void;
+  readonly setSize: (width: number, height: number, pixelRatio: number) => void;
+  /** Renders through the effects; returns false when there are none to apply. */
+  readonly render: (scene: Scene, camera: Camera) => boolean;
+  readonly dispose: () => void;
+};
+
+export const createPostProcessing = (renderer: WebGLRenderer): PostProcessing => {
+  let effects: ReadonlyArray<PostEffect> = [];
+  let composer: EffectComposer | undefined;
+  let renderPass: RenderPass | undefined;
+  const size: Size = { width: 1, height: 1, pixelRatio: 1 };
+
+  const dispose = (): void => {
+    if (composer === undefined) return;
+    for (const pass of composer.passes) pass.dispose();
+    composer.dispose();
+    composer = undefined;
+    renderPass = undefined;
+  };
+
+  const build = (): void => {
+    dispose();
+    if (effects.length === 0) return;
+    const target = new WebGLRenderTarget(size.width, size.height, {
+      type: HalfFloatType,
+      samples: 4,
+    });
+    const next = new EffectComposer(renderer, target);
+    const first = new RenderPass(new EmptyScene(), new PerspectiveCamera());
+    next.addPass(first);
+    for (const effect of effects) next.addPass(passFor(effect, size));
+    next.addPass(new OutputPass());
+    next.setPixelRatio(size.pixelRatio);
+    next.setSize(size.width, size.height);
+    composer = next;
+    renderPass = first;
+  };
+
+  return {
+    configure: (next) => {
+      if (effectsEqual(next, effects)) return;
+      effects = next;
+      build();
+    },
+    setSize: (width, height, pixelRatio) => {
+      size.width = width;
+      size.height = height;
+      size.pixelRatio = pixelRatio;
+      composer?.setPixelRatio(pixelRatio);
+      composer?.setSize(width, height);
+    },
+    render: (scene, camera) => {
+      if (composer === undefined || renderPass === undefined) return false;
+      renderPass.scene = scene;
+      renderPass.camera = camera;
+      composer.render();
+      return true;
+    },
+    dispose,
+  };
+};

package/src/dom/property.ts

@@ -0,0 +1,43 @@
+/**
+ * Intercepts the property Foldkit's CustomElement factory sets on every render, so a
+ * Mount can see new values without an update hook (ADR-002).
+ *
+ * @module
+ */
+
+export type PropertyInterception = {
+  /** The value present when interception began (set by the first render). */
+  readonly initial: unknown;
+  /** Restores a plain data property holding the latest value. */
+  readonly restore: () => void;
+};
+
+/** Calls `onSet` for every assignment to `element[key]`. */
+export const interceptProperty = (
+  element: object,
+  key: string,
+  onSet: (value: unknown) => void,
+): PropertyInterception => {
+  const initial: unknown = Reflect.get(element, key);
+  let current = initial;
+  Object.defineProperty(element, key, {
+    configurable: true,
+    enumerable: true,
+    get: () => current,
+    set: (value: unknown) => {
+      current = value;
+      onSet(value);
+    },
+  });
+  return {
+    initial,
+    restore: () => {
+      Object.defineProperty(element, key, {
+        configurable: true,
+        enumerable: true,
+        writable: true,
+        value: current,
+      });
+    },
+  };
+};

package/src/dom/reconciled.ts

@@ -0,0 +1,51 @@
+/**
+ * Summaries of scene updates, for the `scene-reconciled` event.
+ *
+ * @module
+ */
+import type { Op, ResourceStats } from '@opsydyn/effect-three';
+
+import type { ReconciledDetail } from '../element.ts';
+
+/** Counts operations by kind and snapshots resource counters. */
+export const summarise = (ops: ReadonlyArray<Op>, stats: ResourceStats): ReconciledDetail => {
+  const counts = {
+    created: 0,
+    updated: 0,
+    moved: 0,
+    removed: 0,
+    replaced: 0,
+    reordered: 0,
+    configured: 0,
+  };
+  for (const op of ops) {
+    switch (op._tag) {
+      case 'Create':
+        counts.created++;
+        break;
+      case 'Update':
+        counts.updated++;
+        break;
+      case 'Move':
+        counts.moved++;
+        break;
+      case 'Remove':
+        counts.removed++;
+        break;
+      case 'Replace':
+        counts.replaced++;
+        break;
+      case 'Order':
+        counts.reordered++;
+        break;
+      case 'SetCamera':
+      case 'DefineResources':
+        counts.configured++;
+        break;
+    }
+  }
+  return {
+    ops: counts,
+    resources: { geometries: { ...stats.geometries }, materials: { ...stats.materials } },
+  };
+};

package/src/dom/renderSettings.ts

@@ -0,0 +1,117 @@
+/**
+ * What the WebGL and WebGPU renderers share: the scene's render settings by three.js's
+ * names, recompiling materials when shadows switch, and which renderer draws each
+ * canvas, for presenting it in an immersive session.
+ *
+ * @module
+ */
+import type { RenderSettings } from '@opsydyn/effect-three';
+import {
+  ACESFilmicToneMapping,
+  AgXToneMapping,
+  BasicShadowMap,
+  CineonToneMapping,
+  type ColorSpace,
+  LinearSRGBColorSpace,
+  LinearToneMapping,
+  Material,
+  NeutralToneMapping,
+  NoToneMapping,
+  type Object3D,
+  PCFShadowMap,
+  ReinhardToneMapping,
+  type ShadowMapType,
+  SRGBColorSpace,
+  type ToneMapping,
+  VSMShadowMap,
+  type WebGLRenderer,
+} from 'three';
+import type { WebGPURenderer } from 'three/webgpu';
+
+/**
+ * Shadow map types by React Three Fiber's names (`core/configuration.ts` at `d74622e`).
+ * three 0.186 folded PCF soft into PCF (softness is per light), so `soft` maps to PCF
+ * here; R3F's PCFSoftShadowMap would only log a removal warning on this version.
+ */
+export const shadowTypes = {
+  basic: BasicShadowMap,
+  percentage: PCFShadowMap,
+  soft: PCFShadowMap,
+  variance: VSMShadowMap,
+} satisfies Record<Exclude<RenderSettings['shadows'], 'off'>, ShadowMapType>;
+
+export const toneMappings = {
+  none: NoToneMapping,
+  linear: LinearToneMapping,
+  reinhard: ReinhardToneMapping,
+  cineon: CineonToneMapping,
+  aces: ACESFilmicToneMapping,
+  agx: AgXToneMapping,
+  neutral: NeutralToneMapping,
+} satisfies Record<RenderSettings['toneMapping'], ToneMapping>;
+
+export const colorSpaces = {
+  srgb: SRGBColorSpace,
+  linear: LinearSRGBColorSpace,
+} satisfies Record<RenderSettings['colorSpace'], ColorSpace>;
+
+/**
+ * Flags every material in the scene for recompilation. three.js keeps a shader built
+ * with shadows sampling its last shadow map after `shadowMap.enabled` turns off (and
+ * without shadows after it turns on) until its material is updated.
+ */
+export const recompileMaterials = (scene: Object3D): void => {
+  scene.traverse((object) => {
+    const material: unknown = Reflect.get(object, 'material');
+    const materials = Array.isArray(material) ? material : [material];
+    for (const each of materials) if (each instanceof Material) each.needsUpdate = true;
+  });
+};
+
+/** What presenting a renderer in WebXR uses; three's WebGL and WebGPU renderers both have it. */
+export type PresentableRenderer = {
+  readonly xr: {
+    enabled: boolean;
+    readonly isPresenting: boolean;
+    setReferenceSpaceType: (type: XRReferenceSpaceType) => void;
+    setFramebufferScaleFactor: (scale: number) => void;
+    setSession: (session: XRSession) => Promise<void>;
+    getReferenceSpace: () => XRReferenceSpace | null;
+    setReferenceSpace: (space: XRReferenceSpace) => void;
+    getEnvironmentBlendMode: () => XREnvironmentBlendMode | undefined;
+  };
+  /**
+   * Hands the session's frames to `callback` (`null` stops), set before the session starts:
+   * WebGL's `xr.setAnimationLoop`, or WebGPU's `setAnimationLoop`, which its XR manager
+   * captures when the session starts. It may also be called outside the session.
+   */
+  readonly setXrLoop: (callback: ((time: number, frame?: XRFrame) => void) | null) => void;
+};
+
+/** Each canvas's three.js renderer, for presenting it in a WebXR session. */
+const presentable = new WeakMap<HTMLCanvasElement, PresentableRenderer>();
+/** Each canvas's three.js renderer itself, for tests that read three's own state. */
+const drawing = new WeakMap<HTMLCanvasElement, WebGLRenderer | WebGPURenderer>();
+
+export const registerPresentable = (
+  canvas: HTMLCanvasElement,
+  renderer: WebGLRenderer | WebGPURenderer,
+  presenting: PresentableRenderer,
+): void => {
+  presentable.set(canvas, presenting);
+  drawing.set(canvas, renderer);
+};
+
+export const forgetPresentable = (canvas: HTMLCanvasElement): void => {
+  presentable.delete(canvas);
+  drawing.delete(canvas);
+};
+
+/** The three.js renderer drawing into `canvas` (WebGL or WebGPU), if one does. */
+export const threeRendererOf = (
+  canvas: HTMLCanvasElement,
+): WebGLRenderer | WebGPURenderer | undefined => drawing.get(canvas);
+
+/** The three.js renderer drawing into `canvas`, if one does. */
+export const presentableRendererOf = (canvas: HTMLCanvasElement): PresentableRenderer | undefined =>
+  presentable.get(canvas);

package/src/dom/typedScenes.ts

@@ -0,0 +1,21 @@
+/**
+ * Scenes that reached the element through the typed `view` helper. TypeScript already
+ * checked them against `SceneDescription`, so the Mount can skip the Schema decode (about
+ * 0.6 ms per render for 1,000 meshes). Any other value assigned to the element's `scene`
+ * property is still decoded.
+ *
+ * @module
+ */
+import type { SceneDescription } from '@opsydyn/effect-three';
+
+const typed = new WeakMap<object, SceneDescription>();
+
+/** Records a compile-time-checked scene and returns it unchanged. */
+export const markTyped = (scene: SceneDescription): SceneDescription => {
+  typed.set(scene, scene);
+  return scene;
+};
+
+/** The scene, if this exact value came through `markTyped`. */
+export const typedScene = (value: unknown): SceneDescription | undefined =>
+  typeof value === 'object' && value !== null ? typed.get(value) : undefined;

package/src/dom/updates.ts

@@ -0,0 +1,14 @@
+/**
+ * What follows a scene update in the DOM.
+ *
+ * @module
+ */
+
+/** After an update: report it, then run each follow-up step in order. */
+export const afterUpdate =
+  <A>(report: (value: A) => () => void, steps: ReadonlyArray<() => void>) =>
+  (value: A) =>
+  (): void => {
+    report(value)();
+    for (const step of steps) step();
+  };

package/src/dom/viewport.ts

@@ -0,0 +1,97 @@
+/**
+ * Element size, visibility and motion preference.
+ *
+ * @module
+ */
+import type { Viewport } from '@opsydyn/effect-three';
+
+/**
+ * The drawing buffer's pixel ratio: a fixed number, or `[min, max]` to follow the device
+ * within bounds. React Three Fiber's `dpr`, with its `[1, 2]` default (`calculateDpr` in
+ * `core/utils.tsx` at `d74622e`): ratios above 2 cost GPU time for little visible gain.
+ */
+export type PixelRatio = number | readonly [min: number, max: number];
+
+export const defaultPixelRatio: PixelRatio = [1, 2];
+
+/** Resolves a pixel ratio setting against the device's ratio. */
+export const resolvePixelRatio = (devicePixelRatio: number, setting: PixelRatio): number =>
+  typeof setting === 'number'
+    ? setting
+    : Math.min(Math.max(setting[0], devicePixelRatio), setting[1]);
+
+/** The element's current viewport, with the pixel ratio resolved. */
+export const measureViewport = (
+  element: Element,
+  devicePixelRatio: number,
+  pixelRatio: PixelRatio = defaultPixelRatio,
+): Viewport => {
+  const rect = element.getBoundingClientRect();
+  return {
+    width: Math.max(1, rect.width),
+    height: Math.max(1, rect.height),
+    pixelRatio: resolvePixelRatio(devicePixelRatio, pixelRatio),
+  };
+};
+
+/** Calls `onResize` whenever the element's size changes. Returns a disconnect function. */
+export const observeSize = (element: Element, onResize: () => void): (() => void) => {
+  const observer = new ResizeObserver(onResize);
+  observer.observe(element);
+  return () => observer.disconnect();
+};
+
+/** Calls `onVisible` with whether any part of the element is on screen. */
+export const observeVisibility = (
+  element: Element,
+  onVisible: (visible: boolean) => void,
+): (() => void) => {
+  const observer = new IntersectionObserver((entries) => {
+    for (const entry of entries) onVisible(entry.isIntersecting);
+  });
+  observer.observe(element);
+  return () => observer.disconnect();
+};
+
+/** Calls `onChange` with the current reduced-motion preference, then on every change. */
+export const observeReducedMotion = (
+  view: Pick<Window, 'matchMedia'>,
+  onChange: (reduced: boolean) => void,
+): (() => void) => {
+  const query = view.matchMedia('(prefers-reduced-motion: reduce)');
+  const listener = (event: MediaQueryListEvent): void => onChange(event.matches);
+  onChange(query.matches);
+  query.addEventListener('change', listener);
+  return () => query.removeEventListener('change', listener);
+};
+
+/** The media query calls the pixel-ratio watch needs; `window` provides them. */
+type ChangeTarget = {
+  addEventListener(type: 'change', listener: () => void): void;
+  removeEventListener(type: 'change', listener: () => void): void;
+};
+
+export type PixelRatioHost = {
+  readonly devicePixelRatio: number;
+  readonly matchMedia: (query: string) => ChangeTarget;
+};
+
+/**
+ * Calls `onChange` whenever the device pixel ratio changes (moving to another display, or
+ * zooming), which resizes nothing. As React Three Fiber's `watchDpr`: a media query for
+ * the current resolution, re-armed for the new ratio after each change.
+ */
+export const observePixelRatio = (view: PixelRatioHost, onChange: () => void): (() => void) => {
+  let query: ChangeTarget | undefined;
+  const listener = (): void => {
+    query?.removeEventListener('change', listener);
+    arm();
+    onChange();
+  };
+  const arm = (): void => {
+    query = view.matchMedia(`(resolution: ${view.devicePixelRatio}dppx)`);
+    query.addEventListener('change', listener);
+  };
+  arm();
+  return () => query?.removeEventListener('change', listener);
+};