frame a photograph on the page, at the size it is printed

The panel frames a 21:9 header in a 200-pixel thumbnail while the real one is on screen six inches
away, in the layout it belongs to. Dragging the picture itself is the obvious control, and until now
it was also the expensive one: every new rectangle made the site cut a fresh ladder — nine widths, two
formats, 1.54s measured — with the preview waiting for it.

Both halves are gone. The site draws the rectangle in CSS in development (previous commit, other
repo), so a framing costs nothing to show; the drag here is inline styles on the picture, and the only
write is one PATCH when the hand stops.

Inline styles rather than the site's custom properties, because the site renders a FRAMED picture one
way and an untouched one another — and an untouched photograph is exactly the one somebody is about to
drag. Inline beats both, and beats the object-fit the unframed path leaves behind, which would
otherwise crop the picture a second time inside a box that is already the crop.

Attached to every shaped photograph rather than to the selected one. Selection would put itself in the
paint's dependencies, so choosing a block would repaint the whole page's chrome; this way onDocument
still depends on the sections alone. The cost is that a click could become a nudge, so nothing moves
until the pointer has travelled 3px — below that it is a click, it selects the block, and no crop is
written.

The panel's zoom buttons now reach the real picture too, through `onDraft`. Otherwise the thumbnail
and the page would disagree for the 600ms until the debounce lands, which reads as a broken control
rather than a delayed one.

crop.ts is new and is the reason this is safe: parseCrop had already been copied once, and a crop that
means one thing in the panel and another on the page is a bug you can only feel. MediaField now draws
its own preview through the same `rectToBox`.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

web/sections/PageBuilderPanel.tsx

@@ -8,6 +8,7 @@ import { readableError } from '../errors';
 import { SitePreview, useDevPort } from '../SitePreview';
 import { usePreviewable, useViewMode } from '../ViewMode';
 import { paintMeasure, paintSelection, type CanvasComponent, type CanvasSection } from '../canvas';
+import { paintFraming, type Framing, type FrameTarget } from '../framing';
 
 /*
   What the Spacing dialog calls a block, by kind.
@@ -269,6 +270,28 @@ export const PageBuilderPanel = () => {
     band?.scrollIntoView({ behavior: 'smooth', block: 'start' });
   }, [part]);
 
+  /*
+    Framing, driven from outside the paint.
+
+    The handle is kept in a ref rather than in state because the panel's zoom buttons have to push a
+    rectangle into the page on every press, and re-running `onDocument` for that would repaint every
+    control on the page sixty times a gesture. A ref lets one number reach one element.
+  */
+  const framingRef = useRef<Framing | null>(null);
+
+  /*
+    Which pictures can be dragged: every photograph block that has been given a shape.
+
+    Serialised into the dependency rather than passed as an array, because a new array every render is a
+    new identity every render, and `onDocument` would repaint on each one. This is the same trap the
+    theme in SitePreview hit.
+  */
+  const frameTargets: FrameTarget[] = sections
+    .flatMap((section) => section.components)
+    .filter((component) => component.kind === 'media' && typeof component.content?.ratio === 'number')
+    .map((component) => ({ id: component.id, crop: component.content?.crop ?? null }));
+  const frameKey = JSON.stringify(frameTargets);
+
   const onDocument = useCallback(
     (frameDocument: Document) => {
       frameDoc.current = frameDocument;
@@ -313,14 +336,30 @@ export const PageBuilderPanel = () => {
         onSpaceComponent: (component) => handlersRef.current.spaceComponent(component),
       });
 
+      /*
+        Dragging a photograph reframes it, at the size it is printed.
+
+        The write is one PATCH when the hand stops — the drag itself is inline styles on the picture,
+        which costs nothing. See framing.ts, and the site's PageComponent for the half that makes the
+        page draw a rectangle rather than a pan.
+      */
+      const framing = paintFraming(frameDocument, JSON.parse(frameKey) as FrameTarget[], (id, crop) => {
+        const component = sections.flatMap((section) => section.components).find((one) => one.id === id);
+        if (!component) return;
+        void handlersRef.current.setContent(component, { ...component.content, crop: crop || undefined });
+      });
+      framingRef.current = framing;
+
       return () => {
+        framingRef.current = null;
+        framing.cleanup();
         selection();
         measure();
       };
     },
     // `mode` is in here so switching to View gives SitePreview a NEW function, which runs the previous
     // paint's cleanup and then paints nothing. That is what removes the chrome without a reload.
-    [sections],
+    [sections, frameKey],
   );
 
   /*
@@ -850,6 +889,9 @@ export const PageBuilderPanel = () => {
                   onCrop={(crop) =>
                     void handlersRef.current.setContent(block, { ...block.content, crop: crop || undefined })
                   }
+                  /* Every press of a zoom button reaches the real picture too, so the thumbnail and the
+                     page are never showing two different framings of the same photograph. */
+                  onDraft={(crop) => framingRef.current?.apply(block.id, crop)}
                 />
               ) : (
                 <>