paseo-plugin-genui 0.0.0-stage → 0.1.0

package/server/web/address.ts

@@ -0,0 +1,57 @@
+// Which IP addresses the plugin may connect to. A URL in a spec is model
+// output, so fetching it must never reach this machine, its network or any
+// address that isn't on the public internet.
+import { BlockList, isIP } from "node:net";
+
+/** IPv4 ranges that are not public unicast (RFC 6890 and friends). */
+const PRIVATE_V4: readonly (readonly [string, number])[] = [
+  ["0.0.0.0", 8], // "this network"
+  ["10.0.0.0", 8], // private
+  ["100.64.0.0", 10], // carrier-grade NAT
+  ["127.0.0.0", 8], // loopback
+  ["169.254.0.0", 16], // link-local (cloud metadata lives here)
+  ["172.16.0.0", 12], // private
+  ["192.0.0.0", 24], // IETF protocol assignments
+  ["192.0.2.0", 24], // documentation
+  ["192.88.99.0", 24], // 6to4 relay anycast
+  ["192.168.0.0", 16], // private
+  ["198.18.0.0", 15], // benchmarking
+  ["198.51.100.0", 24], // documentation
+  ["203.0.113.0", 24], // documentation
+  ["224.0.0.0", 4], // multicast
+  ["240.0.0.0", 4], // reserved, broadcast
+];
+
+/**
+ * IPv6 is allowed only inside global unicast (2000::/3), which already
+ * excludes loopback, unspecified, IPv4-mapped, NAT64, unique-local,
+ * link-local and multicast; these special blocks inside it are refused too.
+ */
+const SPECIAL_V6: readonly (readonly [string, number])[] = [
+  ["2001::", 23], // IETF protocol assignments (Teredo, benchmarking, ORCHID)
+  ["2001:db8::", 32], // documentation
+  ["2002::", 16], // 6to4: tunnels to an embedded IPv4 address
+  ["3fff::", 20], // documentation
+];
+
+const privateV4 = new BlockList();
+for (const [network, prefix] of PRIVATE_V4) privateV4.addSubnet(network, prefix, "ipv4");
+const globalV6 = new BlockList();
+globalV6.addSubnet("2000::", 3, "ipv6");
+const specialV6 = new BlockList();
+for (const [network, prefix] of SPECIAL_V6) specialV6.addSubnet(network, prefix, "ipv6");
+
+/** True only for a literal IP address on the public internet. */
+export function isPublicAddress(address: string): boolean {
+  const bare = address.startsWith("[") && address.endsWith("]") ? address.slice(1, -1) : address;
+  // A zone index (fe80::1%en0) only exists on link-local addresses.
+  if (bare.includes("%")) return false;
+  switch (isIP(bare)) {
+    case 4:
+      return !privateV4.check(bare, "ipv4");
+    case 6:
+      return globalV6.check(bare, "ipv6") && !specialV6.check(bare, "ipv6");
+    default:
+      return false;
+  }
+}

package/server/web/cache.ts

@@ -0,0 +1,85 @@
+const ROW_OVERHEAD = 256;
+
+export interface CacheEntry {
+  readonly body: Buffer;
+  readonly meta: string;
+  readonly expired: boolean;
+}
+
+interface StoredRow {
+  body: Buffer;
+  meta: string;
+  bytes: number;
+  expiresAt: number;
+  usedAt: number;
+}
+
+export class WebCache {
+  private readonly rows = new Map<string, StoredRow>();
+  private totalBytes = 0;
+
+  constructor(
+    private readonly maxBytes: number,
+    private readonly now: () => number = Date.now,
+  ) {}
+
+  get(key: string): CacheEntry | null {
+    const row = this.rows.get(key);
+    if (row === undefined) return null;
+    const now = this.now();
+    row.usedAt = now;
+    this.rows.delete(key);
+    this.rows.set(key, row);
+    return { body: row.body, meta: row.meta, expired: row.expiresAt <= now };
+  }
+
+  put(key: string, body: Buffer, meta: string, ttlMs: number): void {
+    const existing = this.rows.get(key);
+    if (existing !== undefined) {
+      this.totalBytes -= existing.bytes;
+      this.rows.delete(key);
+    }
+    const now = this.now();
+    const bytes = body.length + meta.length + ROW_OVERHEAD;
+    this.rows.set(key, {
+      body,
+      meta,
+      bytes,
+      expiresAt: now + ttlMs,
+      usedAt: now,
+    });
+    this.totalBytes += bytes;
+    this.evict();
+  }
+
+  renew(key: string, meta: string, ttlMs: number): void {
+    const existing = this.rows.get(key);
+    if (existing === undefined) return;
+    const now = this.now();
+    this.totalBytes -= existing.bytes;
+    const bytes = existing.body.length + meta.length + ROW_OVERHEAD;
+    this.rows.delete(key);
+    this.rows.set(key, {
+      body: existing.body,
+      meta,
+      bytes,
+      expiresAt: now + ttlMs,
+      usedAt: now,
+    });
+    this.totalBytes += bytes;
+  }
+
+  size(): number {
+    return this.totalBytes;
+  }
+
+  private evict(): void {
+    if (this.totalBytes <= this.maxBytes) return;
+    const target = this.maxBytes * 0.8;
+    for (const [key, row] of this.rows.entries()) {
+      if (this.totalBytes <= target) break;
+      this.rows.delete(key);
+      this.totalBytes -= row.bytes;
+    }
+  }
+}

package/server/web/commons.ts

@@ -0,0 +1,126 @@
+// Image search on Wikimedia Commons. Chosen over Openverse after comparing
+// both on everyday queries ("slow roasted lamb shoulder", "Lisbon tram 28"):
+// Commons ranked on-topic photos first where Openverse mixed in salads and an
+// art edit, holds only free licences (Openverse's top hits were mostly
+// NonCommercial/NoDerivs Flickr photos), has no 200-requests-a-day anonymous
+// cap, and scales thumbnails server-side to the width asked for.
+import { z } from "zod";
+
+/** A photo found for a description, with what its licence asks to be credited. */
+export const foundImageSchema = z.object({
+  /** https URL of a scaled rendition (≤ THUMB_WIDTH wide). */
+  url: z.string(),
+  width: z.number(),
+  height: z.number(),
+  title: z.string(),
+  creator: z.string(),
+  /** Short licence name ("CC BY-SA 4.0", "Public domain"). */
+  license: z.string(),
+  licenseUrl: z.string().nullable(),
+  /** The file's page on Commons, which holds the full attribution. */
+  sourceUrl: z.string(),
+});
+
+export type FoundImage = z.infer<typeof foundImageSchema>;
+
+const API = "https://commons.wikimedia.org/w/api.php";
+/** A standard Wikimedia thumbnail step, sharp at chat width on a 2× screen. */
+export const THUMB_WIDTH = 1280;
+const CANDIDATES = 12;
+const MIN_WIDTH = 480;
+
+/** The API request for `query`: bitmap files only, with the metadata a credit needs. */
+export function searchUrl(query: string): string {
+  const params = new URLSearchParams({
+    action: "query",
+    format: "json",
+    formatversion: "2",
+    generator: "search",
+    gsrsearch: `${query} filetype:bitmap`,
+    gsrnamespace: "6",
+    gsrlimit: String(CANDIDATES),
+    prop: "imageinfo",
+    iiprop: "url|size|mime|extmetadata",
+    iiurlwidth: String(THUMB_WIDTH),
+    iiextmetadatafilter: "Artist|LicenseShortName|LicenseUrl|ObjectName",
+    maxlag: "5",
+  });
+  return `${API}?${params}`;
+}
+
+/** Plain text from an extmetadata HTML fragment (artist links, spans). */
+function plain(html: unknown): string {
+  if (typeof html !== "string") return "";
+  const entities: Record<string, string> = { amp: "&", lt: "<", gt: ">", quot: '"', "#39": "'", nbsp: " " };
+  return html
+    .replace(/<[^>]*>/g, " ")
+    .replace(/&(amp|lt|gt|quot|#39|nbsp);/g, (_, name: string) => entities[name])
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+function record(value: unknown): Readonly<Record<string, unknown>> {
+  return typeof value === "object" && value !== null && !Array.isArray(value) ? (value as Record<string, unknown>) : {};
+}
+
+function metadata(fields: Readonly<Record<string, unknown>>, name: string): string {
+  return plain(record(fields[name]).value);
+}
+
+function https(value: unknown): string | null {
+  if (typeof value !== "string") return null;
+  try {
+    const url = new URL(value, "https://commons.wikimedia.org");
+    // Commons now appends utm_ tracking parameters to thumbnail URLs.
+    for (const key of [...url.searchParams.keys()]) if (key.startsWith("utm_")) url.searchParams.delete(key);
+    return url.protocol === "https:" ? url.href : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The best photo in a search response: in search order, the first JPEG wide
+ * enough to fill a chat column (PNGs on Commons are mostly diagrams and
+ * screenshots, so one is taken only when no JPEG qualifies). Null when none fits.
+ */
+export function pickImage(response: unknown): FoundImage | null {
+  const pages = record(record(response).query).pages;
+  if (!Array.isArray(pages)) return null;
+  const candidates = pages
+    .map(record)
+    .sort((a, b) => Number(a.index ?? 0) - Number(b.index ?? 0))
+    .flatMap((page): (FoundImage & { mime: string })[] => {
+      const info = record(Array.isArray(page.imageinfo) ? page.imageinfo[0] : undefined);
+      const mime = typeof info.mime === "string" ? info.mime : "";
+      const width = Number(info.width);
+      const height = Number(info.height);
+      const url = https(info.thumburl) ?? https(info.url);
+      const sourceUrl = https(info.descriptionurl);
+      if (url === null || sourceUrl === null || !Number.isFinite(width) || !Number.isFinite(height)) return [];
+      if (width < MIN_WIDTH || height < MIN_WIDTH * 0.5) return [];
+      if (mime !== "image/jpeg" && mime !== "image/png" && mime !== "image/webp") return [];
+      const fields = record(info.extmetadata);
+      const fileTitle = typeof page.title === "string" ? page.title.replace(/^File:/, "").replace(/\.[a-z0-9]+$/i, "") : "";
+      const thumbWidth = Number(info.thumbwidth);
+      const thumbHeight = Number(info.thumbheight);
+      const scaled = Number.isFinite(thumbWidth) && Number.isFinite(thumbHeight) && thumbWidth > 0;
+      return [
+        {
+          mime,
+          url,
+          width: scaled ? thumbWidth : width,
+          height: scaled ? thumbHeight : height,
+          title: (metadata(fields, "ObjectName") || fileTitle).slice(0, 200),
+          creator: (metadata(fields, "Artist") || "Unknown author").slice(0, 120),
+          license: metadata(fields, "LicenseShortName") || "See source page",
+          licenseUrl: https(record(fields.LicenseUrl).value),
+          sourceUrl,
+        },
+      ];
+    });
+  const chosen = candidates.find((candidate) => candidate.mime === "image/jpeg") ?? candidates[0];
+  if (chosen === undefined) return null;
+  const { mime: _mime, ...image } = chosen;
+  return image;
+}

package/server/web/geocode.ts

@@ -0,0 +1,40 @@
+// Place names to coordinates with Photon (photon.komoot.io), OpenStreetMap
+// data under the ODbL. Not Nominatim: its usage policy forbids the public API
+// being offered through or generated by AI coding tools, which is exactly how
+// Map's place names arrive. Photon asks for fair use; we keep to one request
+// a second (see lookups.ts), identify ourselves and cache every answer.
+import { z } from "zod";
+
+export const locatedSchema = z.object({ lat: z.number().min(-90).max(90), lng: z.number().min(-180).max(180) });
+
+export type Located = z.infer<typeof locatedSchema>;
+
+const API = "https://photon.komoot.io/api/";
+
+/** The request for `name`, nudged toward `near` (the places already on the map) when given. */
+export function geocodeUrl(name: string, near: Located | null): string {
+  const params = new URLSearchParams({ q: name, limit: "1" });
+  if (near !== null) {
+    params.set("lat", near.lat.toFixed(3));
+    params.set("lon", near.lng.toFixed(3));
+    // A regional nudge: it breaks ties between same-named places without
+    // overriding a clearly named one far away.
+    params.set("zoom", "8");
+    params.set("location_bias_scale", "0.3");
+  }
+  return `${API}?${params}`;
+}
+
+const photonResponse = z.object({
+  features: z
+    .array(z.object({ geometry: z.object({ coordinates: z.tuple([z.number(), z.number()]).rest(z.number()) }) }))
+    .min(1),
+});
+
+/** The first feature's position in a Photon GeoJSON response, or null. */
+export function pickLocation(response: unknown): Located | null {
+  const parsed = photonResponse.safeParse(response);
+  if (!parsed.success) return null;
+  const [lng, lat] = parsed.data.features[0].geometry.coordinates;
+  return Math.abs(lat) > 90 || Math.abs(lng) > 180 ? null : { lat, lng };
+}

package/server/web/image.ts

@@ -0,0 +1,35 @@
+// What a fetched body really is. A server's Content-Type is a claim; the
+// bytes decide which image type the page is told to decode.
+
+/** Image types the proxy passes on, by MIME type. */
+export const IMAGE_MIME_TYPES = ["image/png", "image/jpeg", "image/gif", "image/webp", "image/avif", "image/svg+xml"] as const;
+
+export type ImageMime = (typeof IMAGE_MIME_TYPES)[number];
+
+function startsWith(body: Uint8Array, bytes: readonly number[], at = 0): boolean {
+  return body.length >= at + bytes.length && bytes.every((byte, index) => body[at + index] === byte);
+}
+
+function ascii(text: string): number[] {
+  return [...text].map((char) => char.charCodeAt(0));
+}
+
+const SVG_START = /^(?:<\?xml[^>]*>\s*)?(?:<!--[\s\S]*?-->\s*)*(?:<!DOCTYPE[^>]*>\s*)?(?:<!--[\s\S]*?-->\s*)*<svg[\s>/]/i;
+
+/** The image type `body` holds, from its leading bytes; null when it is not one of IMAGE_MIME_TYPES. */
+export function sniffImage(body: Uint8Array): ImageMime | null {
+  if (startsWith(body, [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a])) return "image/png";
+  if (startsWith(body, [0xff, 0xd8, 0xff])) return "image/jpeg";
+  if (startsWith(body, ascii("GIF87a")) || startsWith(body, ascii("GIF89a"))) return "image/gif";
+  if (startsWith(body, ascii("RIFF")) && startsWith(body, ascii("WEBP"), 8)) return "image/webp";
+  if (startsWith(body, ascii("ftyp"), 4) && (startsWith(body, ascii("avif"), 8) || startsWith(body, ascii("avis"), 8))) {
+    return "image/avif";
+  }
+  const head = new TextDecoder("utf-8", { fatal: false }).decode(body.subarray(0, 4096)).replace(/^\uFEFF/, "").trimStart();
+  return SVG_START.test(head) ? "image/svg+xml" : null;
+}
+
+/** True when a Content-Type header names an image type (parameters ignored). */
+export function declaresImage(contentType: string | undefined): boolean {
+  return contentType !== undefined && /^image\/[a-z0-9.+-]+\s*(;|$)/i.test(contentType.trim());
+}

package/server/web/lookups.ts

@@ -0,0 +1,248 @@
+import { setTimeout as sleep } from "node:timers/promises";
+import { WebCache, type CacheEntry } from "./cache";
+import { foundImageSchema, pickImage, searchUrl, type FoundImage } from "./commons";
+import { geocodeUrl, locatedSchema, pickLocation, type Located } from "./geocode";
+import { declaresImage, sniffImage } from "./image";
+import { safeGet, type Fetched, type GetOptions } from "./net";
+
+export const MAX_REMOTE_IMAGE_BYTES = 5 * 1024 * 1024;
+const CACHE_BYTES = 64 * 1024 * 1024;
+const DAY_MS = 86_400_000;
+const TILE_TTL_MS = 7 * DAY_MS;
+const IMAGE_TTL_MS = 7 * DAY_MS;
+const FOUND_TTL_MS = 30 * DAY_MS;
+const MISS_TTL_MS = DAY_MS;
+const GEOCODE_SPACING_MS = 1_100;
+export const MAX_TILE_ZOOM = 19;
+
+export type WebFailure = { readonly ok: false; readonly error: string; readonly off?: boolean };
+export type WebImage = { readonly ok: true; readonly dataUrl: string } | WebFailure;
+export type WebSearch = { readonly ok: true; readonly image: FoundImage } | WebFailure;
+export type WebPlace = ({ readonly ok: true } & Located) | WebFailure;
+
+const OFF: WebFailure = {
+  ok: false,
+  off: true,
+  error: "Web lookups are off in the Generative UI plugin settings",
+};
+
+function limiter(max: number): <T>(task: () => Promise<T>) => Promise<T> {
+  let active = 0;
+  const waiting: (() => void)[] = [];
+  return async (task) => {
+    if (active >= max) await new Promise<void>((resolve) => waiting.push(resolve));
+    active += 1;
+    try {
+      return await task();
+    } finally {
+      active -= 1;
+      waiting.shift()?.();
+    }
+  };
+}
+
+function dataUrl(mime: string, body: Buffer): string {
+  return `data:${mime};base64,${body.toString("base64")}`;
+}
+
+function parseJson(body: Buffer): unknown {
+  try {
+    return JSON.parse(body.toString("utf8"));
+  } catch {
+    return undefined;
+  }
+}
+
+function metaOf(entry: CacheEntry): Record<string, unknown> {
+  const meta = parseJson(Buffer.from(entry.meta, "utf8"));
+  return typeof meta === "object" && meta !== null && !Array.isArray(meta)
+    ? Object.fromEntries(Object.entries(meta))
+    : {};
+}
+
+function normalize(text: string): string {
+  return text.trim().replace(/\s+/g, " ").toLowerCase();
+}
+
+export interface WebLookups {
+  image(url: string): Promise<WebImage>;
+  search(query: string): Promise<WebSearch>;
+  geocode(name: string, near: Located | null): Promise<WebPlace>;
+  tile(z: number, x: number, y: number): Promise<WebImage>;
+  isOn(): boolean;
+}
+
+export function createWebLookups(isEnabled: () => Promise<boolean>, isOnSync: () => boolean): WebLookups {
+  const cache = new WebCache(CACHE_BYTES);
+  const inFlight = new Map<string, Promise<unknown>>();
+
+  function once<T>(key: string, task: () => Promise<T>): Promise<T> {
+    const running = inFlight.get(key);
+    if (running !== undefined) return running as Promise<T>;
+    const started = task().finally(() => inFlight.delete(key));
+    inFlight.set(key, started);
+    return started;
+  }
+
+  function cached(key: string): CacheEntry | null {
+    try {
+      return cache.get(key);
+    } catch {
+      return null;
+    }
+  }
+
+  function store(write: () => void): void {
+    try {
+      write();
+    } catch {
+      // Ignore cache write errors
+    }
+  }
+
+  const images = limiter(4);
+  const tiles = limiter(2);
+  const api = limiter(2);
+  let nextGeocodeAt = 0;
+
+  const imageRequest: GetOptions = {
+    accept: "image/avif,image/webp,image/png,image/jpeg,image/gif,image/svg+xml;q=0.8",
+    maxBytes: MAX_REMOTE_IMAGE_BYTES,
+    timeoutMs: 20_000,
+  };
+  const jsonRequest: GetOptions = {
+    accept: "application/json",
+    maxBytes: 2 * 1024 * 1024,
+    timeoutMs: 15_000,
+  };
+
+  async function image(input: string): Promise<WebImage> {
+    if (!(await isEnabled())) return OFF;
+    let url: string;
+    try {
+      url = new URL(input).href;
+    } catch {
+      return { ok: false, error: "not a valid URL" };
+    }
+    const key = `img:${url}`;
+    return once(key, async (): Promise<WebImage> => {
+      const hit = cached(key);
+      const hitMime = hit === null ? null : metaOf(hit).mime;
+      if (hit !== null && !hit.expired && typeof hitMime === "string") {
+        return { ok: true, dataUrl: dataUrl(hitMime, hit.body) };
+      }
+      const fetched = await images(() => safeGet(url, imageRequest));
+      if (!fetched.ok) {
+        return hit !== null && typeof hitMime === "string"
+          ? { ok: true, dataUrl: dataUrl(hitMime, hit.body) }
+          : fetched;
+      }
+      const mime = sniffImage(fetched.body);
+      if (mime === null || !declaresImage(fetched.headers["content-type"])) {
+        return { ok: false, error: "the link is not a png, jpeg, gif, webp, avif or svg image" };
+      }
+      store(() => cache.put(key, fetched.body, JSON.stringify({ mime }), IMAGE_TTL_MS));
+      return { ok: true, dataUrl: dataUrl(mime, fetched.body) };
+    });
+  }
+
+  async function search(query: string): Promise<WebSearch> {
+    if (!(await isEnabled())) return OFF;
+    const normalized = normalize(query);
+    if (normalized === "") return { ok: false, error: "the search is empty" };
+    const key = `search:${normalized}`;
+    const notFound: WebFailure = { ok: false, error: `no photo found for “${query.trim()}”` };
+    return once(key, async (): Promise<WebSearch> => {
+      const hit = cached(key);
+      const parsed = hit === null ? null : foundImageSchema.nullable().safeParse(metaOf(hit).image);
+      const remembered = parsed?.success ? parsed.data : null;
+      if (hit !== null && !hit.expired && parsed?.success) {
+        return remembered === null ? notFound : { ok: true, image: remembered };
+      }
+      const fetched: Fetched = await api(() => safeGet(searchUrl(normalized), jsonRequest));
+      if (!fetched.ok) return remembered !== null ? { ok: true, image: remembered } : fetched;
+      const found: FoundImage | null = pickImage(parseJson(fetched.body));
+      store(() =>
+        cache.put(
+          key,
+          Buffer.alloc(0),
+          JSON.stringify({ image: found }),
+          found === null ? MISS_TTL_MS : FOUND_TTL_MS,
+        ),
+      );
+      return found === null ? notFound : { ok: true, image: found };
+    });
+  }
+
+  async function geocode(name: string, near: Located | null): Promise<WebPlace> {
+    if (!(await isEnabled())) return OFF;
+    const normalized = normalize(name);
+    if (normalized === "") return { ok: false, error: "the place has no name" };
+    const bias = near === null ? "" : `${near.lat.toFixed(1)},${near.lng.toFixed(1)}`;
+    const key = `geo:${normalized}|${bias}`;
+    const notFound: WebFailure = { ok: false, error: `couldn't find “${name.trim()}” on the map` };
+    return once(key, async (): Promise<WebPlace> => {
+      const hit = cached(key);
+      const parsed = hit === null ? null : locatedSchema.nullable().safeParse(metaOf(hit).place);
+      const remembered = parsed?.success ? parsed.data : null;
+      if (hit !== null && !hit.expired && parsed?.success) {
+        return remembered === null ? notFound : { ok: true, ...remembered };
+      }
+      const now = Date.now();
+      const slot = Math.max(now, nextGeocodeAt);
+      nextGeocodeAt = slot + GEOCODE_SPACING_MS;
+      if (slot > now) await sleep(slot - now);
+      const fetched = await safeGet(geocodeUrl(normalized, near), jsonRequest);
+      if (!fetched.ok) return remembered !== null ? { ok: true, ...remembered } : fetched;
+      const found = pickLocation(parseJson(fetched.body));
+      store(() =>
+        cache.put(
+          key,
+          Buffer.alloc(0),
+          JSON.stringify({ place: found }),
+          found === null ? MISS_TTL_MS : FOUND_TTL_MS,
+        ),
+      );
+      return found === null ? notFound : { ok: true, ...found };
+    });
+  }
+
+  async function tile(z: number, x: number, y: number): Promise<WebImage> {
+    if (!(await isEnabled())) return OFF;
+    const span = 2 ** z;
+    if (![z, x, y].every(Number.isInteger) || z < 0 || z > MAX_TILE_ZOOM || x < 0 || y < 0 || x >= span || y >= span) {
+      return { ok: false, error: "no such tile" };
+    }
+    const key = `tile:${z}/${x}/${y}`;
+    return once(key, async (): Promise<WebImage> => {
+      const hit = cached(key);
+      const meta = hit === null ? {} : metaOf(hit);
+      if (hit !== null && !hit.expired) return { ok: true, dataUrl: dataUrl("image/png", hit.body) };
+      const validators: Record<string, string> = {};
+      if (hit !== null && typeof meta.etag === "string") validators["if-none-match"] = meta.etag;
+      if (hit !== null && typeof meta.lastModified === "string") validators["if-modified-since"] = meta.lastModified;
+      const fetched = await tiles(() =>
+        safeGet(`https://tile.openstreetmap.org/${z}/${x}/${y}.png`, {
+          accept: "image/png",
+          maxBytes: 1024 * 1024,
+          timeoutMs: 15_000,
+          headers: validators,
+        }),
+      );
+      if (!fetched.ok) return hit !== null ? { ok: true, dataUrl: dataUrl("image/png", hit.body) } : fetched;
+      if (fetched.status === 304 && hit !== null) {
+        store(() => cache.renew(key, hit.meta, TILE_TTL_MS));
+        return { ok: true, dataUrl: dataUrl("image/png", hit.body) };
+      }
+      if (sniffImage(fetched.body) !== "image/png") {
+        return { ok: false, error: "the tile server sent something other than a png" };
+      }
+      const etag = fetched.headers.etag;
+      const lastModified = fetched.headers["last-modified"];
+      store(() => cache.put(key, fetched.body, JSON.stringify({ etag, lastModified }), TILE_TTL_MS));
+      return { ok: true, dataUrl: dataUrl("image/png", fetched.body) };
+    });
+  }
+
+  return { image, search, geocode, tile, isOn: isOnSync };
+}