Skip to content

A local-first multi-agent app development platform, built on PenguinHarness

4.5 KB
Raw Blame
/**
 * Turning a picked image file into the data URL the profile route stores.
 *
 * Three decisions live here, and only the last of them needs a browser:
 *
 * 1. **The crop.** An avatar is drawn in a circle, so the square the centre crop keeps is the
 *    only part a viewer ever sees; cropping before scaling is what keeps a wide photo from
 *    being squeezed into it.
 * 2. **The size.** 128x128 is the largest rung any surface draws (the Profile page's preview
 *    is 64px, the nav tile 28px), doubled for a 2x screen. A bigger source buys nothing and is
 *    paid for on every page load, since the data URL travels inside `GET /api/me`.
 * 3. **The format.** PNG first, because a flat or generated image stays small and stays sharp;
 *    a photograph does not, so a PNG over its budget is re-exported as JPEG.
 *
 * Everything but `avatarDataUrlFromFile` is pure, and the format decision takes its encoder as
 * an argument rather than reaching for a canvas: this package's vitest runs in Node with no
 * DOM, so a size/format rule that could only be exercised through a real canvas could not be
 * exercised at all.
 *
 * Both budgets are measured in CHARACTERS OF THE DATA URL, which is also the unit the server's
 * cap is written in — so "fits" means the same thing on both sides of the request, with no
 * base64-expansion arithmetic in between to get wrong.
 */

/** Edge of the stored square, in pixels. */
export const AVATAR_EDGE = 128;

/**
 * Where PNG stops being worth it. Under this, the sharper lossless encoding is kept; over it,
 * the image is photographic enough that JPEG is both smaller and indistinguishable at 128px.
 */
export const AVATAR_PNG_BUDGET = 100 * 1024;

/** The hard cap, in data-URL characters — the same number `PUT /api/me/profile` enforces. */
export const AVATAR_MAX_CHARS = 128 * 1024;

/** JPEG quality for the re-export: visually clean at 128px, and roughly a third of q=1. */
export const AVATAR_JPEG_QUALITY = 0.85;

export type AvatarMimeType = "image/png" | "image/jpeg";

/** Encodes the already-drawn 128x128 surface as a data URL. `canvas.toDataURL`, injected. */
export type AvatarEncoder = (type: AvatarMimeType, quality?: number) => string;

/** The source rectangle a centre crop keeps: the largest square centred on the image. */
export function centreCropRect(
  width: number,
  height: number,
): { x: number; y: number; size: number } {
  const size = Math.min(width, height);
  return { x: Math.round((width - size) / 2), y: Math.round((height - size) / 2), size };
}

/**
 * The data URL to store, or null when even the JPEG re-export is over the cap.
 *
 * Null is a real outcome rather than an error: a 128x128 JPEG past 128 KiB means the encoder
 * produced something the server will not take, which the page reports inline instead of
 * sending a request that is certain to 400.
 */
export function fitAvatarDataUrl(encode: AvatarEncoder): string | null {
  const png = encode("image/png");
  if (png.length <= AVATAR_PNG_BUDGET) return png;
  const jpeg = encode("image/jpeg", AVATAR_JPEG_QUALITY);
  return jpeg.length <= AVATAR_MAX_CHARS ? jpeg : null;
}

/** Decodes a picked file into an element `drawImage` accepts. Rejects if it is not an image. */
function loadImage(file: File): Promise<HTMLImageElement> {
  return new Promise((resolve, reject) => {
    const url = URL.createObjectURL(file);
    const img = new Image();
    img.onload = () => {
      // The bitmap is already decoded into the element, so the blob URL has done its job.
      URL.revokeObjectURL(url);
      resolve(img);
    };
    img.onerror = () => {
      URL.revokeObjectURL(url);
      reject(new Error("The picked file could not be decoded as an image."));
    };
    img.src = url;
  });
}

/**
 * A picked file as a stored avatar: centre-cropped, drawn at AVATAR_EDGE, encoded by the rule
 * above. Null means it did not fit; it throws only when the file is not a readable image.
 */
export async function avatarDataUrlFromFile(file: File): Promise<string | null> {
  const image = await loadImage(file);
  const canvas = document.createElement("canvas");
  canvas.width = AVATAR_EDGE;
  canvas.height = AVATAR_EDGE;
  const ctx = canvas.getContext("2d");
  if (ctx === null) throw new Error("This browser did not provide a 2D canvas context.");
  const crop = centreCropRect(image.naturalWidth, image.naturalHeight);
  ctx.drawImage(image, crop.x, crop.y, crop.size, crop.size, 0, 0, AVATAR_EDGE, AVATAR_EDGE);
  return fitAvatarDataUrl((type, quality) => canvas.toDataURL(type, quality));
}