@nulib/clover 0.0.0-stage → 4.0.0-beta.0

package/dist/lib/renderer/CanvasRenderer.mjs

@@ -0,0 +1,857 @@
+"use client";
+var __defProp = Object.defineProperty;
+var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
+import { claimContext, returnContext } from "./backends/contexts.mjs";
+import { WebGL2Backend } from "./backends/webgl2/WebGL2Backend.mjs";
+import { fitCamera, visibleWorldRect, screenPointToWorld, anchoredCenter, worldPointToScreen, sameCamera } from "./camera/Camera.mjs";
+import { CameraAnimator } from "./camera/CameraAnimator.mjs";
+import { GestureController, DEFAULT_GESTURES } from "./input/GestureController.mjs";
+import { TileCache } from "./io/TileCache.mjs";
+import { loadImage } from "./io/decode.mjs";
+import { FrameLoop } from "./loop/FrameLoop.mjs";
+import { uploadBudget } from "./scene/uploadBudget.mjs";
+import { apply, compose, rotate, scale } from "./math/affine.mjs";
+import { union, clamp } from "./math/rect.mjs";
+import { planFrame } from "./scene/planFrame.mjs";
+import { sameSpec, prepareItem, layoutItems, pixelsToWorld, MEDIA_KEY_PREFIX } from "./scene/sceneItem.mjs";
+const DEFAULTS = {
+  maxZoomPixelRatio: 1.1,
+  minZoomImageRatio: 0.9,
+  animationTime: 0.09,
+  request: void 0,
+  byteBudget: 192 * 1024 * 1024,
+  maxInFlight: 6,
+  releaseAfterMs: 2e3
+};
+const MAX_PIXEL_RATIO = 2;
+const MAX_CONTEXT_LOSSES = 3;
+const ANNOTATION_PADDING = 0.1;
+const ZOOM_EPSILON = 1e-6;
+const NO_INSET = { top: 0, right: 0, bottom: 0, left: 0 };
+function readInset(host) {
+  if (typeof getComputedStyle !== "function") return NO_INSET;
+  const style = getComputedStyle(host);
+  const px = (value) => parseFloat(value) || 0;
+  return {
+    top: px(style.paddingTop),
+    right: px(style.paddingRight),
+    bottom: px(style.paddingBottom),
+    left: px(style.paddingLeft)
+  };
+}
+const sameInset = (a, b) => a.top === b.top && a.right === b.right && a.bottom === b.bottom && a.left === b.left;
+let canvas2d;
+class CanvasRenderer {
+  constructor(host, options = {}) {
+    __publicField(this, "host");
+    /**
+     * Annotation hotspots and anything else pinned to a world rectangle: made by the first
+     * thing pinned (`overlaysOf`, in the hotspots' chunk), so a Canvas with none never
+     * loads it.
+     */
+    __publicField(this, "overlays", null);
+    __publicField(this, "options");
+    __publicField(this, "backend", null);
+    __publicField(this, "backendPreference");
+    __publicField(this, "contextLosses", 0);
+    /** Its place among the page's WebGL contexts (`backends/contexts`). */
+    __publicField(this, "holder", {
+      hiddenSince: null,
+      release: () => this.giveBack()
+    });
+    /** In the window, as last seen: only then does it hold a context. */
+    __publicField(this, "visible", true);
+    /**
+     * Elements the backend does not draw (`dom` video, pixels WebGL may not read): made,
+     * its code loaded, the first time a frame holds one.
+     */
+    __publicField(this, "dom", null);
+    __publicField(this, "domAsked", false);
+    /** A canvas waiting for Canvas2D's code, the host's background showing meanwhile. */
+    __publicField(this, "pending", null);
+    __publicField(this, "camera");
+    __publicField(this, "loop");
+    __publicField(this, "gestures");
+    /** The gesture options the renderer was created with; `setGestures` layers on these. */
+    __publicField(this, "gestureOptions", {});
+    __publicField(this, "cache");
+    __publicField(this, "navigator", null);
+    /** Counts `attachNavigator` calls, so only the latest one's navigator is made. */
+    __publicField(this, "navigatorAsked", 0);
+    __publicField(this, "viewport", { width: 1, height: 1 });
+    /** The host's padding: the space the home view keeps clear around the picture. */
+    __publicField(this, "inset", NO_INSET);
+    __publicField(this, "pixelRatio", 1);
+    __publicField(this, "items", []);
+    __publicField(this, "worldBounds", null);
+    /** Bumped when the scene or its loaded tiles change: the navigator redraws on it. */
+    __publicField(this, "contentVersion", 0);
+    /** Tiles WebGL refused (no CORS): shown as DOM layers from then on. */
+    __publicField(this, "opaqueUrls", /* @__PURE__ */ new Set());
+    /** Media items' elements, by their one tile's key. Never in the tile cache. */
+    __publicField(this, "mediaByKey", /* @__PURE__ */ new Map());
+    __publicField(this, "detachMedia", []);
+    __publicField(this, "opened", false);
+    /** True until the reader moves the camera; a resize then refits rather than crops. */
+    __publicField(this, "atHome", true);
+    __publicField(this, "lastEmitted", null);
+    __publicField(this, "generation", 0);
+    __publicField(this, "listeners", /* @__PURE__ */ new Map());
+    __publicField(this, "resizeObserver", null);
+    __publicField(this, "intersectionObserver", null);
+    __publicField(this, "releaseTimer", null);
+    __publicField(this, "dprQuery", null);
+    __publicField(this, "disposed", false);
+    __publicField(this, "dismisser", null);
+    // ─── Frame ────────────────────────────────────────────────────────────────
+    __publicField(this, "tick", (dt) => {
+      var _a, _b;
+      if (this.disposed) return false;
+      const animating = this.camera.step(dt, this.viewport);
+      const camera = this.camera.current;
+      const backend = this.backend;
+      const uploads = uploadBudget(
+        this.getTile,
+        (url) => backend ? backend.has(url) : true
+      );
+      const plan = planFrame({
+        items: this.items,
+        camera,
+        viewport: this.viewport,
+        pixelRatio: this.pixelRatio,
+        getTile: uploads.getTile,
+        wantOverview: Boolean(this.navigator),
+        // Fetch for where the camera lands, not for each view on the way.
+        destination: animating ? this.camera.destination : void 0
+      });
+      this.cache.update(
+        plan.wants.filter((want) => !want.url.startsWith(MEDIA_KEY_PREFIX))
+      );
+      this.paint(plan.draws);
+      (_a = this.overlays) == null ? void 0 : _a.position(camera, this.viewport);
+      (_b = this.navigator) == null ? void 0 : _b.render(
+        this.items.filter((item) => !item.spec.hidden),
+        this.worldBounds,
+        visibleWorldRect(camera, this.viewport),
+        this.pixelRatio,
+        this.getTile,
+        this.contentVersion
+      );
+      if (!this.lastEmitted || !sameCamera(this.lastEmitted, camera)) {
+        this.lastEmitted = { ...camera };
+        if (this.opened) this.emit("viewport");
+      }
+      return animating || uploads.deferred;
+    });
+    __publicField(this, "getTile", (url) => this.mediaByKey.get(url) ?? this.cache.get(url));
+    /*
+     * The browser took the context (too many on the page, a GPU reset). Its canvas goes at
+     * once, so the browser's picture of a lost context never shows, only the host's
+     * background; Canvas2D draws on from the decoded tiles, nothing refetched, and WebGL is
+     * tried again when it next comes into view (a GPU that keeps dropping it, never).
+     */
+    __publicField(this, "onContextLost", () => {
+      this.contextLosses += 1;
+      this.releaseBackend();
+      if (this.visible) this.acquireBackend(false);
+      else this.host.dataset.backend = "released";
+    });
+    __publicField(this, "onPixelRatioChange", () => {
+      this.measure();
+      this.watchPixelRatio();
+    });
+    this.host = host;
+    this.backendPreference = options.backend ?? "auto";
+    this.options = {
+      ...DEFAULTS,
+      ...stripUndefined(options)
+    };
+    if (prefersReducedMotion()) this.options.animationTime = 0;
+    this.camera = new CameraAnimator(
+      { x: 0, y: 0, zoom: 1, rotation: 0 },
+      this.options.animationTime
+    );
+    this.loop = new FrameLoop(this.tick);
+    this.gestureOptions = stripUndefined(options.gestures ?? {});
+    this.gestures = new GestureController(host, this, {
+      ...DEFAULT_GESTURES,
+      ...this.gestureOptions
+    });
+    this.cache = new TileCache({
+      load: (url, signal) => this.loadTile(url, signal),
+      onSettled: () => {
+        this.contentVersion++;
+        this.invalidate();
+      },
+      onEvict: (url) => {
+        var _a;
+        return (_a = this.backend) == null ? void 0 : _a.release(url);
+      },
+      byteBudget: this.options.byteBudget,
+      maxInFlight: this.options.maxInFlight
+    });
+    this.visible = inWindow(host);
+    if (this.visible) this.acquireBackend();
+    else this.holder.hiddenSince = now();
+    this.measure();
+    this.observe();
+  }
+  // ─── Public API ────────────────────────────────────────────────────────────
+  get backendKind() {
+    var _a;
+    return ((_a = this.backend) == null ? void 0 : _a.kind) ?? "none";
+  }
+  get isOpen() {
+    return this.opened;
+  }
+  /** Whether the camera is at home: false once the reader zooms, pans or turns it. */
+  get isAtHome() {
+    return this.atHome;
+  }
+  on(event, listener) {
+    let set = this.listeners.get(event);
+    if (!set) {
+      set = /* @__PURE__ */ new Set();
+      this.listeners.set(event, set);
+    }
+    set.add(listener);
+    return () => set == null ? void 0 : set.delete(listener);
+  }
+  /**
+   * Replace the scene.
+   *
+   * New items are resolved — `info.json` fetched, coarsest tiles decoded — before they
+   * replace the old ones, so a swap never flashes empty. Items whose description is
+   * unchanged are kept as they are, and tiles are cached by URL, so swapping between two
+   * regions of one image costs nothing at all.
+   */
+  async setImages(images, {
+    world,
+    fit = false
+  } = {}) {
+    const generation = ++this.generation;
+    const previous = new Map(this.items.map((item) => [item.id, item]));
+    const results = await Promise.allSettled(
+      images.map((spec) => {
+        const kept = previous.get(spec.id);
+        if (kept && sameSpec(kept.spec, spec)) {
+          kept.spec = spec;
+          return Promise.resolve(kept);
+        }
+        return prepareItem(spec, {
+          cache: this.cache,
+          loadStatic: (url) => this.loadTile(url),
+          infoOptions: { request: this.options.request }
+        });
+      })
+    );
+    if (generation !== this.generation || this.disposed) return;
+    const items = results.filter(
+      (r) => r.status === "fulfilled"
+    ).map((r) => r.value);
+    const errors = results.filter((r) => r.status === "rejected").map((r) => r.reason);
+    this.items = items;
+    this.watchMedia(items);
+    const laidOut = layoutItems(items);
+    this.worldBounds = world ? laidOut ? union([world, laidOut]) : world : laidOut;
+    this.contentVersion++;
+    if (errors.length) this.emit("error", errors);
+    if (!this.worldBounds) {
+      this.invalidate();
+      return;
+    }
+    if (!this.opened) {
+      this.opened = true;
+      this.home(true);
+      this.emit("open");
+    } else if (fit) {
+      this.home(true);
+      this.emit("change");
+    } else {
+      this.camera.set(this.constrain(this.camera.current));
+      this.emit("change");
+    }
+    this.invalidate();
+  }
+  /**
+   * Put the scene away at once: from the next frame nothing of it is drawn, and a swap
+   * still preparing is dropped. For moving to a different resource, whose pictures should
+   * never show beside the last one's while they load; `setImages` then draws the new
+   * scene, framed afresh. A swap within one resource keeps the old scene up instead.
+   */
+  clear() {
+    this.generation++;
+    this.items = [];
+    this.watchMedia([]);
+    this.worldBounds = null;
+    this.contentVersion++;
+    this.invalidate();
+  }
+  /**
+   * Show only some of the scene's images, keeping the others loaded: the frames of an
+   * animation. Nothing is prepared, laid out or reported; the next frame draws the change.
+   */
+  setHidden(ids) {
+    const hidden = new Set(ids);
+    let changed = false;
+    for (const item of this.items) {
+      const next = hidden.has(item.id);
+      if (Boolean(item.spec.hidden) === next) continue;
+      item.spec = { ...item.spec, hidden: next };
+      changed = true;
+    }
+    if (changed) this.invalidate();
+  }
+  /**
+   * Whether an image can be drawn now: it is in the scene and its coarsest level is
+   * loaded. An animation waits on this before showing a frame, rather than blink empty.
+   */
+  isReady(id) {
+    const item = this.items.find((candidate) => candidate.id === id);
+    if (!item) return false;
+    if (item.spec.media) return true;
+    const level = item.pyramid.levels[0];
+    if (!level) return false;
+    for (let row = 0; row < level.rows; row++) {
+      for (let col = 0; col < level.cols; col++) {
+        if (!this.getTile(item.pyramid.tile({ level: 0, col, row }).url)) {
+          return false;
+        }
+      }
+    }
+    return true;
+  }
+  /** Frame `bounds` (world units) in the viewport. */
+  fitBounds(bounds, immediate = false) {
+    const target = fitCamera(
+      bounds,
+      this.viewport,
+      this.camera.destination.rotation,
+      0
+    );
+    this.atHome = false;
+    this.animateTo(
+      this.constrain(target, { allowBeyondLimits: true }),
+      immediate
+    );
+  }
+  /**
+   * Zoom to a rectangle in item `index`'s own coordinates — an annotation's `xywh` — with
+   * OpenSeadragon's padding.
+   */
+  fitItemRect(index, rect, immediate = false) {
+    const world = this.itemRectToWorld(index, rect);
+    if (world) this.fitAnnotation(world, immediate);
+  }
+  /** Zoom to a world rectangle with OpenSeadragon's annotation padding. */
+  fitAnnotation(world, immediate = false) {
+    const first = this.items[0];
+    if (!first) return;
+    const pad = first.rect.width * ANNOTATION_PADDING;
+    this.fitBounds(
+      {
+        x: world.x - pad,
+        y: world.y - pad,
+        width: world.width + pad * 2,
+        height: world.height + pad * 2
+      },
+      immediate
+    );
+  }
+  /** The world rectangle currently visible (its bounding box when rotated). */
+  getBounds() {
+    return visibleWorldRect(this.camera.current, this.viewport);
+  }
+  getHomeBounds() {
+    return this.worldBounds ? { ...this.worldBounds } : null;
+  }
+  getCamera() {
+    return { ...this.camera.current };
+  }
+  getZoomLimits() {
+    var _a;
+    const home = ((_a = this.homeCamera()) == null ? void 0 : _a.zoom) ?? 1;
+    const worldPerPixel = this.items.length ? Math.min(...this.items.map((item) => pixelsToWorld(item).x)) : 1;
+    return {
+      home,
+      min: home * this.options.minZoomImageRatio,
+      max: Math.max(home, this.options.maxZoomPixelRatio / worldPerPixel)
+    };
+  }
+  home(immediate = false) {
+    const home = this.homeCamera();
+    if (!home) return;
+    this.atHome = true;
+    this.animateTo(home, immediate);
+  }
+  /** Zoomed in as far as it goes, or on the way there. */
+  atMaxZoom() {
+    return this.camera.destination.zoom >= this.getZoomLimits().max * (1 - ZOOM_EPSILON);
+  }
+  zoomBy(factor, at, animate = true) {
+    const base = animate ? this.camera.destination : this.camera.current;
+    const screen = at ?? {
+      x: this.viewport.width / 2,
+      y: this.viewport.height / 2
+    };
+    const world = screenPointToWorld(base, this.viewport, screen);
+    const { min, max } = this.getZoomLimits();
+    const zoom = clamp(base.zoom * factor, min, max);
+    const center = anchoredCenter(
+      world,
+      screen,
+      zoom,
+      base.rotation,
+      this.viewport
+    );
+    const target = this.constrain({ ...base, ...center, zoom });
+    this.atHome = false;
+    if (animate) {
+      this.camera.animateTo(
+        { state: target, anchor: { world, screen } },
+        this.viewport
+      );
+    } else {
+      this.camera.set(target);
+    }
+    this.invalidate();
+  }
+  panBy(dx, dy, animate = false) {
+    const base = animate ? this.camera.destination : this.camera.current;
+    const shift = apply(compose(scale(1 / base.zoom), rotate(-base.rotation)), {
+      x: dx,
+      y: dy
+    });
+    const target = this.constrain({
+      ...base,
+      x: base.x - shift.x,
+      y: base.y - shift.y
+    });
+    this.atHome = false;
+    if (animate) this.camera.animateTo({ state: target }, this.viewport);
+    else this.camera.set(target);
+    this.invalidate();
+  }
+  /** Center the view on a world point. */
+  panTo(point, immediate = false) {
+    const base = immediate ? this.camera.current : this.camera.destination;
+    this.atHome = false;
+    this.animateTo(this.constrain({ ...base, ...point }), immediate);
+  }
+  flick(vx, vy) {
+    this.panBy(vx * 0.25, vy * 0.25, true);
+  }
+  rotateBy(degrees) {
+    const base = this.camera.destination;
+    this.setRotation(base.rotation * 180 / Math.PI + degrees);
+  }
+  /** Rotate about the viewport center. Degrees, clockwise, like OpenSeadragon. */
+  setRotation(degrees, immediate = false) {
+    const base = this.camera.destination;
+    const rotation = degrees * Math.PI / 180;
+    this.animateTo(this.constrain({ ...base, rotation }), immediate);
+  }
+  getRotation() {
+    return this.camera.destination.rotation * 180 / Math.PI;
+  }
+  tap(at) {
+    this.emit("tap", at);
+  }
+  /**
+   * What a tap off every control and hotspot puts away first: the handler returns whether
+   * it put anything away, and if it did, the tap neither zooms nor is reported.
+   */
+  setDismiss(handler) {
+    this.dismisser = handler;
+  }
+  dismiss() {
+    var _a;
+    return ((_a = this.dismisser) == null ? void 0 : _a.call(this)) ?? false;
+  }
+  /** Change how pointer, wheel and keyboard drive the camera. */
+  setGestures(gestures) {
+    this.gestures.setOptions({
+      ...DEFAULT_GESTURES,
+      ...this.gestureOptions,
+      ...stripUndefined(gestures)
+    });
+  }
+  setInteracting(interacting) {
+    if (interacting) this.camera.stop();
+  }
+  worldToScreenPoint(point) {
+    return worldPointToScreen(this.camera.current, this.viewport, point);
+  }
+  screenToWorldPoint(point) {
+    return screenPointToWorld(this.camera.current, this.viewport, point);
+  }
+  /**
+   * A rectangle in item `index`'s own coordinates (its declared size — what an
+   * annotation's `xywh` targets) → world units.
+   */
+  itemRectToWorld(index, rect) {
+    const item = this.items[index];
+    if (!item) return null;
+    const { contentClip } = item;
+    const kx = item.rect.width / contentClip.width;
+    const ky = item.rect.height / contentClip.height;
+    return {
+      x: item.rect.x + (rect.x - contentClip.x) * kx,
+      y: item.rect.y + (rect.y - contentClip.y) * ky,
+      width: rect.width * kx,
+      height: rect.height * ky
+    };
+  }
+  /**
+   * Show an overview of the scene in `element`. Returns a function that removes it. It is
+   * off by default, so its code loads the first time one is asked for, and draws then.
+   */
+  attachNavigator(element) {
+    var _a;
+    (_a = this.navigator) == null ? void 0 : _a.dispose();
+    this.navigator = null;
+    const asked = ++this.navigatorAsked;
+    let navigator = null;
+    let removed = false;
+    void import("./overlays/Navigator.mjs").then((module) => {
+      if (removed || this.disposed || asked !== this.navigatorAsked) return;
+      navigator = new module.Navigator(
+        element,
+        (point, immediate) => this.panTo(point, immediate)
+      );
+      this.navigator = navigator;
+      this.invalidate();
+    });
+    return () => {
+      removed = true;
+      navigator == null ? void 0 : navigator.dispose();
+      if (navigator && this.navigator === navigator) this.navigator = null;
+    };
+  }
+  invalidate() {
+    this.loop.invalidate();
+  }
+  dispose() {
+    var _a, _b, _c, _d, _e, _f, _g;
+    if (this.disposed) return;
+    this.disposed = true;
+    this.generation++;
+    this.loop.dispose();
+    this.gestures.dispose();
+    (_a = this.resizeObserver) == null ? void 0 : _a.disconnect();
+    (_b = this.intersectionObserver) == null ? void 0 : _b.disconnect();
+    (_d = (_c = this.dprQuery) == null ? void 0 : _c.removeEventListener) == null ? void 0 : _d.call(_c, "change", this.onPixelRatioChange);
+    if (this.releaseTimer) clearTimeout(this.releaseTimer);
+    (_e = this.navigator) == null ? void 0 : _e.dispose();
+    this.navigator = null;
+    this.releaseBackend();
+    this.cache.dispose();
+    (_f = this.dom) == null ? void 0 : _f.dispose();
+    (_g = this.overlays) == null ? void 0 : _g.dispose();
+    this.items = [];
+    this.detachMedia.forEach((detach) => detach());
+    this.mediaByKey.clear();
+    this.listeners.clear();
+    delete this.host.dataset.backend;
+  }
+  /**
+   * Track the scene's media elements: redraw when one has a new frame to show (it
+   * started, seeked, or loaded), and drop the listeners when the scene changes.
+   */
+  watchMedia(items) {
+    this.detachMedia.forEach((detach) => detach());
+    this.detachMedia = [];
+    this.mediaByKey.clear();
+    for (const item of items) {
+      if (!item.media || item.media.kind !== "media") continue;
+      const key = item.pyramid.tile({ level: 0, col: 0, row: 0 }).url;
+      this.mediaByKey.set(key, item.media);
+      const element = item.media.source;
+      const redraw = () => this.invalidate();
+      const events = ["play", "seeked", "loadeddata", "resize"];
+      events.forEach((type) => element.addEventListener(type, redraw));
+      this.detachMedia.push(
+        () => events.forEach((type) => element.removeEventListener(type, redraw))
+      );
+    }
+  }
+  paint(draws) {
+    const backend = this.backend;
+    const domItems = [];
+    const webgl = (backend == null ? void 0 : backend.kind) === "webgl2";
+    backend == null ? void 0 : backend.begin();
+    for (const draw of draws) {
+      const { image } = draw;
+      const asDom = image.kind === "media" || image.kind === "element" && webgl && (image.opaque || this.opaqueUrls.has(draw.url));
+      if (!asDom && backend) {
+        const result = backend.draw({
+          key: draw.url,
+          source: image.source,
+          width: image.width,
+          height: image.height,
+          transform: draw.transform,
+          crop: draw.crop,
+          opacity: 1,
+          bleed: draw.bleed
+        });
+        if (result !== "tainted" || image.kind === "bitmap") continue;
+        this.opaqueUrls.add(draw.url);
+      }
+      if (image.kind === "element" || image.kind === "media") {
+        domItems.push({
+          key: `${draw.item.id}|${draw.url}`,
+          element: image.source,
+          width: image.width,
+          height: image.height,
+          transform: draw.transform,
+          crop: draw.crop,
+          opacity: 1
+        });
+      }
+    }
+    backend == null ? void 0 : backend.end();
+    if (this.dom) this.dom.sync(domItems);
+    else if (domItems.length && !this.domAsked) {
+      this.domAsked = true;
+      void import("./backends/dom/DomLayers.mjs").then(({ DomLayers }) => {
+        if (this.disposed) return;
+        const dom = new DomLayers(this.host);
+        if (this.overlays)
+          this.host.insertBefore(dom.container, this.overlays.container);
+        this.dom = dom;
+        this.invalidate();
+      });
+    }
+  }
+  loadTile(url, signal) {
+    return loadImage(url, {
+      signal,
+      request: this.options.request,
+      maxTextureSize: this.backend instanceof WebGL2Backend ? this.backend.maxTextureSize : void 0
+    });
+  }
+  // ─── Camera helpers ───────────────────────────────────────────────────────
+  animateTo(state, immediate) {
+    this.camera.animateTo({ state }, this.viewport, immediate);
+    this.invalidate();
+  }
+  /**
+   * Home is the whole world, upright — Clover's home control also resets rotation. Upright
+   * is the whole turn nearest where the camera is heading, so four quarter turns right then
+   * home does not spin a full turn back, and three come upright by one more quarter.
+   */
+  homeCamera() {
+    if (!this.worldBounds) return null;
+    const turn = 2 * Math.PI;
+    const upright = Math.round(this.camera.destination.rotation / turn) * turn || 0;
+    const { top, right, bottom, left } = this.inset;
+    const camera = fitCamera(
+      this.worldBounds,
+      {
+        width: Math.max(1, this.viewport.width - left - right),
+        height: Math.max(1, this.viewport.height - top - bottom)
+      },
+      upright
+    );
+    camera.x -= (left - right) / 2 / camera.zoom;
+    camera.y -= (top - bottom) / 2 / camera.zoom;
+    return camera;
+  }
+  /**
+   * Keep the camera usable: zoom within limits, and the center over the world so the
+   * picture cannot be flung out of sight.
+   */
+  constrain(state, { allowBeyondLimits = false } = {}) {
+    const bounds = this.worldBounds;
+    if (!bounds) return state;
+    const { min, max } = this.getZoomLimits();
+    const zoom = allowBeyondLimits ? clamp(state.zoom, min, Math.max(max, state.zoom)) : clamp(state.zoom, min, max);
+    return {
+      ...state,
+      zoom,
+      x: clamp(state.x, bounds.x, bounds.x + bounds.width),
+      y: clamp(state.y, bounds.y, bounds.y + bounds.height)
+    };
+  }
+  // ─── Backend lifecycle ────────────────────────────────────────────────────
+  /** @param webgl false to draw with Canvas2D whatever the preference, as after a loss. */
+  acquireBackend(webgl = true) {
+    var _a, _b;
+    if (this.backend || this.pending || this.disposed) return;
+    const canvas = document.createElement("canvas");
+    canvas.className = "clover-canvas-surface";
+    canvas.setAttribute("aria-hidden", "true");
+    Object.assign(canvas.style, {
+      position: "absolute",
+      inset: "0",
+      width: "100%",
+      height: "100%",
+      display: "block",
+      pointerEvents: "none"
+    });
+    this.host.insertBefore(
+      canvas,
+      ((_a = this.dom) == null ? void 0 : _a.container) ?? ((_b = this.overlays) == null ? void 0 : _b.container) ?? null
+    );
+    const tryWebGL = webgl && (this.backendPreference === "webgl2" || this.backendPreference === "auto" && this.contextLosses < MAX_CONTEXT_LOSSES);
+    let backend = null;
+    if (tryWebGL && (claimContext(this.holder) || this.backendPreference === "webgl2")) {
+      backend = WebGL2Backend.create(canvas, { onLost: this.onContextLost });
+      if (!backend) returnContext(this.holder);
+    }
+    if (backend) this.install(backend);
+    else if (this.backendPreference === "webgl2") this.none(canvas);
+    else {
+      this.pending = canvas;
+      void (canvas2d ?? (canvas2d = import("./backends/canvas2d/Canvas2DBackend.mjs"))).then(
+        ({ Canvas2DBackend }) => {
+          if (this.pending !== canvas) return;
+          this.pending = null;
+          const made = Canvas2DBackend.create(canvas);
+          if (made) this.install(made);
+          else this.none(canvas);
+        }
+      );
+    }
+  }
+  none(canvas) {
+    canvas.remove();
+    this.host.dataset.backend = "none";
+  }
+  install(backend) {
+    this.backend = backend;
+    this.host.dataset.backend = backend.kind;
+    backend.resize(this.viewport.width, this.viewport.height, this.pixelRatio);
+    if (backend.kind === "canvas2d") this.opaqueUrls.clear();
+    this.emit("backend", backend.kind);
+    this.invalidate();
+  }
+  releaseBackend() {
+    var _a;
+    returnContext(this.holder);
+    (_a = this.pending) == null ? void 0 : _a.remove();
+    this.pending = null;
+    if (!this.backend) return;
+    const canvas = this.backend.canvas;
+    this.backend.dispose();
+    canvas.remove();
+    this.backend = null;
+  }
+  /** Its context given back, out of view or to make room for one in view. */
+  giveBack() {
+    if (this.releaseTimer) clearTimeout(this.releaseTimer);
+    this.releaseTimer = null;
+    this.releaseBackend();
+    this.host.dataset.backend = "released";
+  }
+  // ─── Observation ──────────────────────────────────────────────────────────
+  observe() {
+    if (typeof ResizeObserver !== "undefined") {
+      this.resizeObserver = new ResizeObserver(() => this.measure(true));
+      this.resizeObserver.observe(this.host);
+    }
+    if (typeof IntersectionObserver !== "undefined") {
+      this.intersectionObserver = new IntersectionObserver((entries) => {
+        const visible = entries.some((entry) => entry.isIntersecting);
+        this.setVisible(visible);
+      });
+      this.intersectionObserver.observe(this.host);
+    }
+    this.watchPixelRatio();
+  }
+  /**
+   * Browsers cap live WebGL contexts per page and silently kill the oldest beyond it.
+   * An instance scrolled out of view gives its context back after a grace period, or at
+   * once when one in view needs it (`backends/contexts`), and takes a fresh one on
+   * return; decoded tiles stay in memory, so nothing is refetched.
+   */
+  setVisible(visible) {
+    var _a;
+    this.visible = visible;
+    if (visible) {
+      this.holder.hiddenSince = null;
+      if (this.releaseTimer) clearTimeout(this.releaseTimer);
+      this.releaseTimer = null;
+      if (!this.backend) this.acquireBackend();
+      return;
+    }
+    (_a = this.holder).hiddenSince ?? (_a.hiddenSince = now());
+    if (!this.backend || this.releaseTimer) return;
+    this.releaseTimer = setTimeout(
+      () => this.giveBack(),
+      this.options.releaseAfterMs
+    );
+  }
+  /**
+   * @param now draw at once, for a ResizeObserver: resizing the canvas clears it, and
+   *   the observer runs too late in the frame for the next frame to be in time. Without
+   *   it, dragging a pane's edge blinks the picture on every step.
+   */
+  measure(now2 = false) {
+    var _a;
+    const rect = this.host.getBoundingClientRect();
+    const width = Math.max(1, rect.width);
+    const height = Math.max(1, rect.height);
+    const inset = readInset(this.host);
+    const pixelRatio = Math.min(
+      typeof window !== "undefined" ? window.devicePixelRatio || 1 : 1,
+      MAX_PIXEL_RATIO
+    );
+    if (width === this.viewport.width && height === this.viewport.height && pixelRatio === this.pixelRatio && sameInset(inset, this.inset)) {
+      return;
+    }
+    const previous = this.viewport;
+    this.viewport = { width, height };
+    this.inset = inset;
+    this.pixelRatio = pixelRatio;
+    (_a = this.backend) == null ? void 0 : _a.resize(width, height, pixelRatio);
+    if (this.opened) {
+      if (this.atHome) {
+        this.home(true);
+      } else {
+        const current = this.camera.current;
+        const ratio = width / Math.max(previous.width, 1);
+        this.camera.set(
+          this.constrain({ ...current, zoom: current.zoom * ratio })
+        );
+      }
+    }
+    if (now2) this.loop.drawNow();
+    else this.invalidate();
+  }
+  watchPixelRatio() {
+    var _a, _b, _c, _d;
+    if (typeof window === "undefined" || typeof window.matchMedia !== "function") {
+      return;
+    }
+    (_b = (_a = this.dprQuery) == null ? void 0 : _a.removeEventListener) == null ? void 0 : _b.call(_a, "change", this.onPixelRatioChange);
+    this.dprQuery = window.matchMedia(
+      `(resolution: ${window.devicePixelRatio || 1}dppx)`
+    );
+    (_d = (_c = this.dprQuery).addEventListener) == null ? void 0 : _d.call(_c, "change", this.onPixelRatioChange);
+  }
+  emit(event, detail) {
+    var _a;
+    (_a = this.listeners.get(event)) == null ? void 0 : _a.forEach((listener) => listener(detail));
+  }
+}
+const now = () => typeof performance !== "undefined" ? performance.now() : Date.now();
+function inWindow(host) {
+  if (typeof IntersectionObserver === "undefined" || typeof window === "undefined") {
+    return true;
+  }
+  const { top, left, width, height } = host.getBoundingClientRect();
+  return top + height >= 0 && left + width >= 0 && top <= window.innerHeight && left <= window.innerWidth;
+}
+function prefersReducedMotion() {
+  return typeof window !== "undefined" && typeof window.matchMedia === "function" && window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+}
+function stripUndefined(value) {
+  return Object.fromEntries(
+    Object.entries(value).filter(([, v]) => v !== void 0)
+  );
+}
+export {
+  CanvasRenderer
+};