Before highseam had a focal point, PawScapes had a file called toomuc-hero_16x9_1.jpg: a hero image exported at one shape and named after it. When the hero frame changed shape (it's 16:7 now), the file was wrong and nothing knew it. The presentation had been stored as content.

highseam's fix is to keep presentation out of the pixels. The media document holds one original and a hotspot: the point that has to survive any crop. Each place the image appears decides its own shape.

Tell the editor what shapes you render

The aspect registry lists the ratios the site actually uses, so an editor can judge the hotspot against real crops instead of guessing:

pawscapes-cms/src/cms.config.ts
aspects: [
  { name: "hero", ratio: "16:7", contexts: ["preview"] },
  { name: "card", ratio: "3:2", contexts: ["preview"] },
  { name: "og", ratio: "1200:630", contexts: ["preview"] },
  { name: "wide", ratio: "16:9", contexts: ["placement"] },
  { name: "standard", ratio: "4:3", contexts: ["placement"] },
  { name: "square", ratio: "1:1", contexts: ["placement"] },
],

preview entries become crop strips under the image in the media editor: the venue page hero, the venue card, the social card. Drag the hotspot and all three update. placement entries are the choices an editor gets when dropping an image into rich text, where one use might want a square and another a 16:9 band. The node stores the ratio; the original is untouched.

The site's side is one line of CSS

PawScapes doesn't resize images at the edge. It renders the original with object-fit: cover and turns the stored hotspot into object-position:

pawscapes/src/lib/server/media.ts
const fp = normalizeFocalPoint(d.focalPoint);
return {
  url,
  focus: fp ? focalObjectPosition(fp) : null,

Every card and hero on the site reads focus. highseam also ships mediaSrc(), which builds Cloudflare Image Resizing URLs with the hotspot as gravity, for sites that want smaller files from the edge. PawScapes hasn't needed it yet, and the CSS route works with no zone settings at all.

Editing without leaving the page

Since 1.5.0, image chips in the editor (upload fields and images in rich text; images inside blocks followed in 1.5.2) have an Edit button that opens the media document in a modal over the page you're on: hotspot, crop previews, alt text, caption, credit. Saving it doesn't touch the form underneath. Fixing an image's alt text used to mean opening the media library in another tab and finding the file again.

The release that half-landed

The first version of this, 1.3.0, shipped to PawScapes and half worked. The hotspot picker appeared; the crop previews didn't. The admin's doc-page file is copied into each project at setup (a stub the project owns and can customise), and PawScapes' copy predated 1.3.0, so it never passed the aspect list to the form. No error, valid config, green deploy, missing feature.

That's what npx highseam-init --check-stubs is for. Shipped in 1.4.0, it compares each project's stubs with the installed templates and lists the template lines a copy is missing, without flagging the project's own customisations. It exits non-zero on drift, so it can gate a deploy.