@oh-just-another/state 0.59.0 → 0.61.0

package/dist/overlay.js

@@ -1,7 +1,8 @@
-import { getAnnotationWorldPosition, getElementWorldBounds, getWorldToScreen, isGroup, } from "@oh-just-another/scene";
+import { getAnnotationWorldPosition, getElementWorldBounds, getWorldToScreen, isGroup, brushOutline, } from "@oh-just-another/scene";
 import { bounds as B, matrix } from "@oh-just-another/math";
-import { getElementRenderer, strokeRoundedPolyline, LINK_CORNER_RADIUS, } from "@oh-just-another/renderer-core";
-import { ANCHOR_DOT_ACTIVE_RADIUS, ANCHOR_DOT_RADIUS, ANCHOR_DOT_STROKE_WIDTH, ANNOTATION_PIN_BADGE_FONT_SIZE, ANNOTATION_PIN_FILL, ANNOTATION_PIN_RADIUS, ANNOTATION_PIN_RESOLVED_FILL, ANNOTATION_PIN_STROKE, CURSOR_ARROW_SIZE, CURSOR_NAME_CHIP_OFFSET, CURSOR_NAME_CHIP_PADDING_X, CURSOR_NAME_CHIP_PADDING_Y, CURSOR_NAME_FONT_SIZE, DRAW_PREVIEW_OPACITY, GHOST_PREVIEW_OPACITY, LINK_ATTACH_ANCHOR_FILL, LINK_ATTACH_ANCHOR_STROKE, LINK_ENDPOINT_HANDLE_DRAW_RADIUS, LINK_MIDPOINT_HANDLE_DRAW_RADIUS, SELECTION_HALO_PEEK_PX, LINK_START_ANCHOR_FILL, LINK_START_ANCHOR_STROKE, PEER_SELECTION_DASH, PEER_SELECTION_PADDING, PEER_SELECTION_STROKE_WIDTH, TEXT_CARET_WIDTH_PX, TEXT_SELECTION_FILL, TEXT_SELECTION_OPACITY, GIF_BADGE_W, GIF_BADGE_H, GIF_BADGE_PAD, GIF_BADGE_RADIUS, GIF_BADGE_BG_COLOR, LOCK_BADGE_SIZE, LOCK_BADGE_COLOR, LOCK_BADGE_KEYHOLE_COLOR, ROTATE_ICON_RADIUS, } from "./constants.js";
+import { getElementRenderer, resolveImageSource, strokeRoundedPolyline, LINK_CORNER_RADIUS, } from "@oh-just-another/renderer-core";
+import { ANCHOR_DOT_ACTIVE_RADIUS, ANCHOR_DOT_RADIUS, ANCHOR_DOT_STROKE_WIDTH, ANNOTATION_PIN_BADGE_FONT_SIZE, ANNOTATION_PIN_FILL, ANNOTATION_PIN_RADIUS, ANNOTATION_PIN_RESOLVED_FILL, ANNOTATION_PIN_STROKE, CURSOR_ARROW_SIZE, CURSOR_NAME_CHIP_OFFSET, CURSOR_NAME_CHIP_PADDING_X, CURSOR_NAME_CHIP_PADDING_Y, CURSOR_NAME_FONT_SIZE, CROP_BRACKET_LEN, CROP_BRACKET_WIDTH, CROP_GHOST_OPACITY, DRAW_PREVIEW_OPACITY, FLOWCHART_PREVIEW_OPACITY, GHOST_PREVIEW_OPACITY, LINK_ATTACH_ANCHOR_FILL, LINK_ATTACH_ANCHOR_STROKE, LINK_ENDPOINT_HANDLE_DRAW_RADIUS, LINK_MIDPOINT_HANDLE_DRAW_RADIUS, SELECTION_HALO_PEEK_PX, LINK_START_ANCHOR_FILL, LINK_START_ANCHOR_STROKE, PEER_SELECTION_DASH, PEER_SELECTION_PADDING, PEER_SELECTION_STROKE_WIDTH, TEXT_CARET_WIDTH_PX, TEXT_SELECTION_FILL, TEXT_SELECTION_OPACITY, GIF_BADGE_W, GIF_BADGE_H, GIF_BADGE_PAD, GIF_BADGE_RADIUS, GIF_BADGE_BG_COLOR, LOCK_BADGE_SIZE, LOCK_BADGE_COLOR, LOCK_BADGE_KEYHOLE_COLOR, ROTATE_ICON_RADIUS, LASER_COLOR, LASER_WIDTH, LASER_TRAIL_TTL_MS, ERASER_CURSOR_STROKE, ERASER_CURSOR_LINE_WIDTH, ERASER_TRAIL_TTL_MS, } from "./constants.js";
+import { smoothLaserPoints } from "./editor/public/laser.js";
 import { CORNER_HANDLES, HANDLE_SIZE, frameCorners, handlePosition, handleWorldOnFrame, rotateGripForBounds, rotateGripWorld, shapeSelectionFrame, } from "./handle.js";
 import { isResizable } from "./editor/shape-traits.js";
 import { drawHitZones, hitZoneVisibility, } from "./editor/hit-test.js";
@@ -80,6 +81,12 @@ export const paintElementSelectionHalo = (target, w2s, halos, zoom, style = DEFA
     target.setOpacity(1);
     target.setTransform(matrix.IDENTITY);
 };
+/**
+ * Draws selection outlines, resize handles, previews, peer chrome and other
+ * affordances on the overlay layer. Pure draw — does not alter scene or state.
+ * A thin dispatcher: each numbered layer lives in its own `render*` helper,
+ * called here in strict back-to-front paint order.
+ */
 export const renderOverlay = (scene, selection, target, options = {}) => {
     const style = { ...DEFAULT_OVERLAY_STYLE, ...options.style };
     target.clear();
@@ -88,8 +95,29 @@ export const renderOverlay = (scene, selection, target, options = {}) => {
     const zoom = scene.viewport.zoom;
     target.save();
     target.setTransform(matrix.IDENTITY);
-    // 0. Debug hit-zones — drawn first so the real selection chrome sits
-    //    on top. Visualises every element's mouse hit-targets.
+    const ctx = { scene, selection, target, options, style, w2s, zoom };
+    renderDebugHitZones(ctx);
+    renderSelectionHandles(ctx);
+    renderPreviews(ctx);
+    renderLinkHandles(ctx);
+    renderPeerSelections(ctx);
+    renderBrushPreview(ctx);
+    renderLaserTrails(ctx);
+    renderEraserCursor(ctx);
+    renderContainerDropZone(ctx);
+    renderGroupBounds(ctx);
+    renderAnnotations(ctx);
+    renderPeerCursors(ctx);
+    renderGifBadges(ctx);
+    renderTextEditing(ctx);
+    target.restore();
+};
+/**
+ * Section 0 — debug hit-zones. Drawn first so the real selection chrome sits
+ * on top. Visualises every element's mouse hit-targets.
+ */
+const renderDebugHitZones = (ctx) => {
+    const { scene, selection, target, options, w2s, zoom } = ctx;
     if (options.debugHitZones) {
         drawHitZones(target, {
             scene,
@@ -107,11 +135,20 @@ export const renderOverlay = (scene, selection, target, options = {}) => {
                 : {}),
         });
     }
-    // 1. Selection outlines (+ handles only when a single shape is
-    //    selected). Multi-selection skips per-shape handles in favour of
-    //    the combined group bbox handles drawn later — otherwise the
-    //    overlay would look like a forest of corner squares and the user
-    //    could grab a child handle, which `hitTest` also blocks.
+};
+/**
+ * Section 1 — per-shape selection outlines (+ resize/rotate handles only when a
+ * single shape is selected). Multi-selection skips per-shape handles in favour
+ * of the combined group bbox handles (section 7) — otherwise the overlay would
+ * look like a forest of corner squares and the user could grab a child handle,
+ * which `hitTest` also blocks.
+ */
+const renderSelectionHandles = (ctx) => {
+    const { scene, selection, target, options, style, w2s, zoom } = ctx;
+    // Crop mode owns the chrome: the crop frame + handles replace the normal
+    // per-shape resize/rotate affordances (drawn by renderPreviews).
+    if (options.cropFrame)
+        return;
     const multiSelect = selection.size > 1;
     for (const id of selection) {
         const shape = scene.elements.get(id);
@@ -131,7 +168,11 @@ export const renderOverlay = (scene, selection, target, options = {}) => {
                 drawLockBadge(target, screenBounds);
                 continue;
             }
-            if (multiSelect || !isResizable(shape))
+            // Read-only: outline only — no resize/rotate affordances to grab.
+            if (multiSelect ||
+                !isResizable(shape) ||
+                options.readOnly === true ||
+                options.suppressHandles === true)
                 continue;
             for (const handle of CORNER_HANDLES) {
                 const worldPoint = handlePosition(handle, worldBounds, zoom);
@@ -155,7 +196,11 @@ export const renderOverlay = (scene, selection, target, options = {}) => {
             drawLockBadge(target, frameScreenBounds(frame, w2s));
             continue;
         }
-        if (multiSelect || !isResizable(shape))
+        // Read-only: outline only — no resize/rotate affordances to grab.
+        if (multiSelect ||
+            !isResizable(shape) ||
+            options.readOnly === true ||
+            options.suppressHandles === true)
             continue;
         // Draw only the four CORNER dots — at the rotated frame corners. Edge
         // resize is done by dragging the selection-box side itself, so no midpoint
@@ -167,6 +212,26 @@ export const renderOverlay = (scene, selection, target, options = {}) => {
         // Rotate grip from the shape's template anchor (default bottom-left).
         drawRotateIcon(target, matrix.applyToPoint(w2s, rotateGripWorld(shape, zoom)), style);
     }
+};
+/**
+ * Sections 2–3.5 — the transient draw/create previews and their landing
+ * highlights: the rubber-band rect, the WYSIWYG shape preview, the link
+ * preview, the click-create ghost, and the float-attach target outline.
+ */
+const renderPreviews = (ctx) => {
+    const { target, options, style, w2s } = ctx;
+    // 0. Crop-mode ghost — the faint full bitmap behind the crop chrome, so the
+    //    pixels hidden by the window stay visible. Drawn first (under the frame).
+    if (options.cropGhost) {
+        drawCropGhost(target, options.cropGhost, w2s);
+    }
+    // 1. Image-crop frame: dashed accent quad + L-shaped corner brackets (the
+    //    edge midpoints stay grabbable but aren't drawn, Excalidraw-style).
+    if (options.cropFrame && options.cropFrame.length >= 4) {
+        const cornersScreen = options.cropFrame.map((p) => matrix.applyToPoint(w2s, p));
+        drawCropFrame(target, cornersScreen, style);
+        drawCropCornerBrackets(target, cornersScreen, style);
+    }
     // 2. Rubber-band drawing preview (already in world coords if drawn before transform reset)
     if (options.drawingPreview) {
         const screenBounds = projectBounds(options.drawingPreview, w2s);
@@ -193,18 +258,45 @@ export const renderOverlay = (scene, selection, target, options = {}) => {
             target.restore();
         }
     }
-    // 3. Link-drawing preview — dashed line in screen space. An elbow preview
-    //    carries the full orthogonal polyline (`points`); otherwise a straight
-    //    from→to segment.
-    if (options.edgePreview) {
-        const pts = options.edgePreview.points;
-        if (pts && pts.length >= 2) {
-            drawLinkPreviewPath(target, pts.map((p) => matrix.applyToPoint(w2s, p)), style);
+    // 2.6 Flowchart-create node preview — the pending nodes of a Cmd/Ctrl+Arrow
+    //     grow session, each through its real renderer (faded). The connecting
+    //     links are drawn by the orchestrator at the same opacity.
+    if (options.flowchartPreviewElements && options.flowchartPreviewElements.length > 0) {
+        for (const el of options.flowchartPreviewElements) {
+            const renderer = getElementRenderer(el.type);
+            if (!renderer)
+                continue;
+            target.save();
+            target.setTransform(w2s);
+            target.setOpacity(FLOWCHART_PREVIEW_OPACITY);
+            target.setDashArray(null);
+            target.translate(el.position.x, el.position.y);
+            if (el.rotation !== 0)
+                target.rotate(el.rotation);
+            if (el.scale.x !== 1 || el.scale.y !== 1)
+                target.scale(el.scale.x, el.scale.y);
+            renderer(el, target);
+            target.restore();
         }
-        else {
-            const from = matrix.applyToPoint(w2s, options.edgePreview.from);
-            const to = matrix.applyToPoint(w2s, options.edgePreview.to);
-            drawLinkPreview(target, from, to, style);
+    }
+    // Stroke-erase live fragments — full opacity (the originals are hidden), drawn
+    // per-element so the overlay's cursor / trail chrome survive underneath.
+    if (options.strokeErasePreviewElements && options.strokeErasePreviewElements.length > 0) {
+        for (const el of options.strokeErasePreviewElements) {
+            const renderer = getElementRenderer(el.type);
+            if (!renderer)
+                continue;
+            target.save();
+            target.setTransform(w2s);
+            target.setOpacity(1);
+            target.setDashArray(null);
+            target.translate(el.position.x, el.position.y);
+            if (el.rotation !== 0)
+                target.rotate(el.rotation);
+            if (el.scale.x !== 1 || el.scale.y !== 1)
+                target.scale(el.scale.x, el.scale.y);
+            renderer(el, target);
+            target.restore();
         }
     }
     // 3.4 Ghost preview for "click a start dot → create element". Just the
@@ -255,6 +347,14 @@ export const renderOverlay = (scene, selection, target, options = {}) => {
         target.rect(b.x - pad, b.y - pad, b.width + pad * 2, b.height + pad * 2);
         target.stroke();
     }
+};
+/**
+ * Sections 4–5 — link chrome: port-dot attach affordances, the persistent
+ * selection halo around every selected link, and the selected-edge endpoint /
+ * waypoint / midpoint handles.
+ */
+const renderLinkHandles = (ctx) => {
+    const { target, options, style, w2s, zoom } = ctx;
     // 4. Port dots — hover affordance in draw-edge mode. May be one set or
     //    several (source start-anchors + target attach-anchors at once).
     if (options.ports) {
@@ -265,7 +365,7 @@ export const renderOverlay = (scene, selection, target, options = {}) => {
             for (let i = 0; i < set.worldPoints.length; i++) {
                 const screen = matrix.applyToPoint(w2s, req(set.worldPoints[i]));
                 const active = set.activeIndex === i;
-                drawPortDot(target, screen, style, active, set.role, active ? set.activeRadius : undefined);
+                drawPortDot(target, screen, active, set.role, active ? set.activeRadius : undefined);
             }
         }
     }
@@ -298,7 +398,9 @@ export const renderOverlay = (scene, selection, target, options = {}) => {
         target.setTransform(matrix.IDENTITY);
     }
     // 5. Selected-edge endpoint handles + bend-point (waypoint) handles.
-    if (options.edgeSelection) {
+    //    Read-only: the halo above still marks the selected link, but the
+    //    endpoint/bend grips are suppressed (nothing to re-bind or drag).
+    if (options.edgeSelection && options.readOnly !== true && options.suppressHandles !== true) {
         const from = matrix.applyToPoint(w2s, options.edgeSelection.from);
         const to = matrix.applyToPoint(w2s, options.edgeSelection.to);
         // Segment-midpoint "add waypoint" handles (drawn first, under the rest).
@@ -311,9 +413,14 @@ export const renderOverlay = (scene, selection, target, options = {}) => {
             drawLinkEndpointHandle(target, matrix.applyToPoint(w2s, w), style);
         }
     }
-    // 6. Peer selection halos — dashed outline around shapes selected
-    // by remote users, painted in their colour. Drawn before own-
-    // selection outlines so own selection stays on top.
+};
+/**
+ * Section 6 — peer selection halos. Dashed outline around shapes selected by
+ * remote users, painted in their colour. Drawn before own-selection outlines
+ * so own selection stays on top.
+ */
+const renderPeerSelections = (ctx) => {
+    const { target, options, w2s } = ctx;
     if (options.peerSelections) {
         for (const peer of options.peerSelections) {
             for (const wb of peer.bounds) {
@@ -322,6 +429,14 @@ export const renderOverlay = (scene, selection, target, options = {}) => {
             }
         }
     }
+};
+/**
+ * Section 6.5 — live brush stroke preview. Quad-strip with interpolated
+ * widths, same render path as the committed BrushElement. Runs in world coords
+ * so the stroke stays anchored to the cursor as the user zooms / pans mid-stroke.
+ */
+const renderBrushPreview = (ctx) => {
+    const { target, options, w2s } = ctx;
     // 6.5. Live brush stroke preview — quad-strip with interpolated
     //      widths, same render path as the committed BrushElement. Runs
     //      in world coords so the stroke stays anchored to the cursor
@@ -330,6 +445,7 @@ export const renderOverlay = (scene, selection, target, options = {}) => {
         const bp = options.brushPreview;
         target.save();
         target.setTransform(w2s);
+        target.setOpacity(bp.opacity);
         target.setFill(bp.fill);
         target.setStroke(null);
         const pts = bp.points;
@@ -342,35 +458,153 @@ export const renderOverlay = (scene, selection, target, options = {}) => {
             target.fill();
         }
         else {
-            for (let i = 0; i < pts.length - 1; i++) {
-                const a = req(pts[i]);
-                const b = req(pts[i + 1]);
-                const ax = ox + a.x;
-                const ay = oy + a.y;
-                const bx = ox + b.x;
-                const by = oy + b.y;
-                const dx = bx - ax;
-                const dy = by - ay;
-                const len = Math.hypot(dx, dy) || 1;
-                const nx = -dy / len;
-                const ny = dx / len;
+            // Same single-outline fill as the committed stroke (see `brushOutline` /
+            // `drawBrush`), so the preview matches the result and honours `opacity`
+            // without the per-segment double-blend at joins.
+            const outline = brushOutline(pts);
+            if (outline.length >= 3) {
                 target.beginPath();
-                target.moveTo(ax + nx * a.width, ay + ny * a.width);
-                target.lineTo(bx + nx * b.width, by + ny * b.width);
-                target.lineTo(bx - nx * b.width, by - ny * b.width);
-                target.lineTo(ax - nx * a.width, ay - ny * a.width);
+                const first = req(outline[0]);
+                target.moveTo(ox + first.x, oy + first.y);
+                for (let i = 1; i < outline.length; i++) {
+                    const p = req(outline[i]);
+                    target.lineTo(ox + p.x, oy + p.y);
+                }
                 target.closePath();
                 target.fill();
-                target.beginPath();
-                target.ellipse(bx, by, b.width, b.width);
-                target.fill();
             }
         }
         target.restore();
     }
-    // 7.0. Container drop-zone highlight — drawn under selection chrome
-    //      so handles stay legible. Dashed rect + soft fill — same
-    //      visual language as the drawing preview.
+};
+/**
+ * Section 6.6 — laser-pointer trails. Each segment is stroked in screen space
+ * (constant on-screen width at any zoom) with an opacity that decays from the
+ * newer endpoint's age: fresh points are opaque, older ones fade out, so a
+ * released stroke melts away tail-first. Read-only — never mutates state.
+ */
+const renderLaserTrails = (ctx) => {
+    const { target, options, w2s } = ctx;
+    drawFadingTrail(target, w2s, options.laserStrokes, LASER_COLOR, LASER_WIDTH, LASER_TRAIL_TTL_MS);
+    // Eraser drag trail — identical fade mechanics, neutral grey (not laser red).
+    // Its width matches the cursor ring's DIAMETER (2 × the panel radius) so the
+    // wake is exactly as wide as the eraser; a much shorter TTL than the laser
+    // keeps it a tight wake, not a long comet.
+    const eraserWidth = (options.eraserCursor?.radius ?? LASER_WIDTH / 2) * 2;
+    drawFadingTrail(target, w2s, options.eraserTrail, ERASER_CURSOR_STROKE, eraserWidth, ERASER_TRAIL_TTL_MS);
+};
+/**
+ * Paint a trail (shared by the laser pointer and the eraser wake) the way
+ * Excalidraw does: ONE filled outline per stroke, not a stack of alpha-blended
+ * segments. The smoothed centreline is offset by a half-width that tapers from
+ * `width/2` at the head to 0 at the tail, giving a single comet shape with a
+ * pointed tail — no overlapping round caps beading at the joints. The whole
+ * stroke fills at one opacity that ramps down by the NEWEST point's age over
+ * `ttl` ms, so after release the comet dissolves as its tail is pruned. Drawn in
+ * screen space (constant on-screen width at any zoom). Read-only.
+ */
+const drawFadingTrail = (target, w2s, strokes, color, width, ttl) => {
+    if (!strokes || strokes.length === 0)
+        return;
+    const now = typeof performance !== "undefined" ? performance.now() : Date.now();
+    const maxHalf = width / 2;
+    target.setStroke(null);
+    target.setDashArray(null);
+    target.setFill(color);
+    for (const stroke of strokes) {
+        const pts = smoothLaserPoints(stroke.points);
+        if (pts.length === 0)
+            continue;
+        // One opacity for the whole shape (Excalidraw fills a single path once);
+        // ramps by the freshest point's age so a released stroke fades as a whole.
+        const newest = req(pts[pts.length - 1]);
+        const op = 1 - (now - newest.t) / ttl;
+        if (op <= 0)
+            continue;
+        target.setOpacity(op);
+        const screen = pts.map((p) => matrix.applyToPoint(w2s, { x: p.x, y: p.y }));
+        if (screen.length === 1) {
+            const s = req(screen[0]);
+            target.beginPath();
+            target.ellipse(s.x, s.y, maxHalf, maxHalf);
+            target.fill();
+            continue;
+        }
+        const outline = taperedTrailOutline(screen, maxHalf);
+        const first = req(outline[0]);
+        target.beginPath();
+        target.moveTo(first.x, first.y);
+        for (let i = 1; i < outline.length; i++) {
+            const p = req(outline[i]);
+            target.lineTo(p.x, p.y);
+        }
+        target.closePath();
+        target.fill();
+    }
+    target.setOpacity(1);
+};
+/**
+ * Build the closed outline polygon of a variable-width ribbon around the screen
+ * polyline `pts` (tail → head order). Each vertex is offset by ±`hw` along the
+ * local normal, where the half-width tapers linearly from 0 at the tail (index
+ * 0) to `maxHalf` at the head (last index). Returns the left side forward then
+ * the right side backward — one closed loop to fill in a single pass.
+ */
+export const taperedTrailOutline = (pts, maxHalf) => {
+    const n = pts.length;
+    const left = [];
+    const right = [];
+    for (let i = 0; i < n; i++) {
+        const p = req(pts[i]);
+        const prev = req(pts[Math.max(0, i - 1)]);
+        const next = req(pts[Math.min(n - 1, i + 1)]);
+        let tx = next.x - prev.x;
+        let ty = next.y - prev.y;
+        const len = Math.hypot(tx, ty) || 1;
+        tx /= len;
+        ty /= len;
+        // Normal (perpendicular) × the tapered half-width.
+        const hw = maxHalf * (n > 1 ? i / (n - 1) : 1);
+        const nx = -ty * hw;
+        const ny = tx * hw;
+        left.push({ x: p.x + nx, y: p.y + ny });
+        right.push({ x: p.x - nx, y: p.y - ny });
+    }
+    right.reverse();
+    return [...left, ...right];
+};
+/**
+ * Section 6.7 — eraser cursor ring. A grey circle following the pointer while
+ * the erase tool is active, its radius the panel's eraser width in SCREEN px
+ * (so it matches the slider number, unscaled by zoom). Replaces the hidden OS
+ * cursor. Read-only — never mutates state.
+ */
+const renderEraserCursor = (ctx) => {
+    const { target, options, w2s } = ctx;
+    const cursor = options.eraserCursor;
+    if (!cursor || cursor.radius <= 0)
+        return;
+    const s = matrix.applyToPoint(w2s, cursor.center);
+    target.setDashArray(null);
+    target.setOpacity(1);
+    target.beginPath();
+    target.ellipse(s.x, s.y, cursor.radius, cursor.radius);
+    // Solid disc in the trail colour (fully opaque), with the ring on top for a
+    // crisp radius edge.
+    target.setFill(ERASER_CURSOR_STROKE);
+    target.fill();
+    target.setFill(null);
+    target.setStroke(ERASER_CURSOR_STROKE);
+    target.setStrokeWidth(ERASER_CURSOR_LINE_WIDTH);
+    target.stroke();
+};
+/**
+ * Section 7.0 — container drop-zone highlight. Drawn under selection chrome so
+ * handles stay legible. Dashed rect + soft fill — same visual language as the
+ * drawing preview.
+ */
+const renderContainerDropZone = (ctx) => {
+    const { target, options, w2s } = ctx;
     if (options.containerDropZone) {
         const zoneScreen = projectBounds(options.containerDropZone, w2s);
         target.setFill("rgba(26, 115, 232, 0.10)");
@@ -383,13 +617,25 @@ export const renderOverlay = (scene, selection, target, options = {}) => {
         target.stroke();
         target.setDashArray(null);
     }
-    // 7. Multi-selection / group-typed combined bounds — outline + handles.
-    //    Only CORNER dots are drawn (edge resize = drag the box side); the
-    //    edge handles stay hit-testable via `hitHandle` for non-aspect-locked
-    //    groups.
+};
+/**
+ * Section 7 — multi-selection / group-typed combined bounds: outline + handles.
+ * Only CORNER dots are drawn (edge resize = drag the box side); the edge
+ * handles stay hit-testable via `hitHandle` for non-aspect-locked groups.
+ */
+const renderGroupBounds = (ctx) => {
+    const { target, options, style, w2s, zoom } = ctx;
+    // Crop mode owns the chrome: an image is aspect-locked, so its selection
+    // reports `groupBounds` — but its resize/rotate handles must not show on top
+    // of the crop brackets. Suppress them exactly like the per-shape handles.
+    if (options.cropFrame)
+        return;
     if (options.groupBounds) {
         const groupScreen = projectBounds(options.groupBounds, w2s);
         drawOutline(target, groupScreen, style);
+        // Read-only / non-select tool: combined-bounds outline only — no handles.
+        if (options.readOnly === true || options.suppressHandles === true)
+            return;
         const handleSet = CORNER_HANDLES;
         for (const handle of handleSet) {
             const worldPoint = handlePosition(handle, options.groupBounds, zoom);
@@ -398,9 +644,14 @@ export const renderOverlay = (scene, selection, target, options = {}) => {
         }
         drawRotateGripForBounds(target, options.groupBounds, zoom, w2s, style);
     }
-    // 7.5. Annotation pins — drawn before peer cursors so cursors stay
-    // on top, but on top of selection handles. Each pin shows a comment
-    // count badge when the thread has > 0 replies.
+};
+/**
+ * Section 7.5 — annotation pins. Drawn before peer cursors so cursors stay on
+ * top, but on top of selection handles. Each pin shows a comment-count badge
+ * when the thread has > 0 replies.
+ */
+const renderAnnotations = (ctx) => {
+    const { scene, target, options, w2s } = ctx;
     if (options.annotations && options.annotations.length > 0) {
         for (const ann of options.annotations) {
             const world = getAnnotationWorldPosition(scene, ann);
@@ -408,25 +659,39 @@ export const renderOverlay = (scene, selection, target, options = {}) => {
             drawAnnotationPin(target, screen, ann, options.selectedAnnotation ?? null);
         }
     }
-    // 8. Remote peer cursors — drawn last so they sit on top of every
-    // other overlay element (including own selection handles).
+};
+/**
+ * Section 8 — remote peer cursors. Drawn near-last so they sit on top of every
+ * other overlay element (including own selection handles).
+ */
+const renderPeerCursors = (ctx) => {
+    const { target, options, w2s } = ctx;
     if (options.peerCursors) {
         for (const cursor of options.peerCursors) {
             const screen = matrix.applyToPoint(w2s, cursor.position);
             drawPeerCursor(target, screen, cursor.color, cursor.name);
         }
     }
-    // 9. GIF "play" badges on paused animated shapes — drawn last
-    //    so they sit above selection chrome.
+};
+/**
+ * Section 9 — GIF "play" badges on paused animated shapes. Drawn late so they
+ * sit above selection chrome.
+ */
+const renderGifBadges = (ctx) => {
+    const { target, options, w2s } = ctx;
     if (options.gifBadges) {
         for (const b of options.gifBadges) {
             drawGifBadge(target, projectBounds(b, w2s));
         }
     }
-    // 10. In-canvas text editing: translucent selection highlight, then
-    //     the caret bar on top. Both backends draw this via the shared
-    //     RenderTarget primitives (rect + fill), so it's identical on
-    //     Canvas2D and WebGL2.
+};
+/**
+ * Section 10 — in-canvas text editing: translucent selection highlight, then
+ * the caret bar on top. Both backends draw this via the shared RenderTarget
+ * primitives (rect + fill), so it's identical on Canvas2D and WebGL2.
+ */
+const renderTextEditing = (ctx) => {
+    const { target, options, w2s, zoom } = ctx;
     if (options.editingText) {
         const et = options.editingText;
         if (et.selectionRects.length > 0) {
@@ -449,7 +714,6 @@ export const renderOverlay = (scene, selection, target, options = {}) => {
             target.fill();
         }
     }
-    target.restore();
 };
 const drawLockBadge = (target, b) => {
     const s = LOCK_BADGE_SIZE;
@@ -558,19 +822,33 @@ const frameScreenBounds = (frame, w2s) => {
     }
     return { x: minX, y: minY, width: maxX - minX, height: maxY - minY };
 };
-const drawHandle = (target, center, style) => {
-    // Circle of radius HANDLE_SIZE — visually equivalent to a rounded
-    // square with maximum corner radius, but renders via `ellipse`
-    // which every RenderTarget already supports (canvas, svg). A rounded
-    // shape reads as "draggable handle" more clearly than a sharp rectangle.
-    target.setFill(style.handleFill);
-    target.setStroke(style.handleStroke);
-    target.setStrokeWidth(1);
+/**
+ * Shared draw for every "filled circle with an outline" handle affordance —
+ * resize handles, port dots, link endpoint / waypoint / midpoint grabs. A
+ * circle reads as "draggable handle" more clearly than a sharp rectangle, and
+ * `ellipse` is supported by every RenderTarget (canvas, svg). State-setter
+ * order is irrelevant to output; only the state at `fill()`/`stroke()` matters.
+ */
+const drawHandleDot = (target, center, radius, s) => {
+    if (s.opacity !== undefined)
+        target.setOpacity(s.opacity);
+    target.setStroke(s.stroke);
+    target.setStrokeWidth(s.strokeWidth);
     target.setDashArray(null);
+    target.setFill(s.fill);
     target.beginPath();
-    target.ellipse(center.x, center.y, HANDLE_SIZE, HANDLE_SIZE);
+    target.ellipse(center.x, center.y, radius, radius);
     target.fill();
     target.stroke();
+    if (s.opacity !== undefined)
+        target.setOpacity(1);
+};
+const drawHandle = (target, center, style) => {
+    drawHandleDot(target, center, HANDLE_SIZE, {
+        fill: style.handleFill,
+        stroke: style.handleStroke,
+        strokeWidth: 1,
+    });
 };
 /**
  * Rotate grip: a clockwise circular-arrow glyph (the `rotate-cw` icon) centred
@@ -631,18 +909,13 @@ const drawDrawingPreview = (target, b, style) => {
     target.rect(b.x, b.y, b.width, b.height);
     target.stroke();
 };
-const drawLinkPreview = (target, from, to, style) => {
-    target.setStroke(style.drawingStroke);
-    target.setStrokeWidth(1.5);
-    target.setDashArray(style.drawingDash);
-    target.beginPath();
-    target.moveTo(from.x, from.y);
-    target.lineTo(to.x, to.y);
-    target.stroke();
-};
-/** Dashed polyline preview (elbow) in screen space. */
-const drawLinkPreviewPath = (target, pts, style) => {
-    target.setStroke(style.drawingStroke);
+/**
+ * Dashed accent quad for the image-crop window. `pts` are already in screen
+ * space (4 corners, clockwise). The grab handles are drawn separately (all 8
+ * corner + edge nubs) by the caller.
+ */
+const drawCropFrame = (target, pts, style) => {
+    target.setStroke(style.selectionStroke);
     target.setStrokeWidth(1.5);
     target.setDashArray(style.drawingDash);
     target.beginPath();
@@ -652,9 +925,78 @@ const drawLinkPreviewPath = (target, pts, style) => {
         const p = req(pts[i]);
         target.lineTo(p.x, p.y);
     }
+    target.lineTo(first.x, first.y);
     target.stroke();
+    target.setDashArray(null);
 };
-const drawPortDot = (target, center, style, active, role = "link-start", activeRadius) => {
+/**
+ * L-shaped corner brackets on the crop frame (Excalidraw-style), replacing the
+ * round resize-nubs. `corners` are the 4 window corners in SCREEN space,
+ * clockwise (nw, ne, se, sw); each bracket's two arms run along the adjacent
+ * edges, so the marks stay aligned when the image is rotated. Only the corners
+ * are drawn — the edge midpoints remain grabbable via hit-testing.
+ */
+const drawCropCornerBrackets = (target, corners, style) => {
+    if (corners.length < 4)
+        return;
+    target.setStroke(style.selectionStroke);
+    target.setStrokeWidth(CROP_BRACKET_WIDTH);
+    target.setDashArray(null);
+    target.setLineCap("round");
+    target.setLineJoin("round");
+    const armTo = (from, to) => {
+        const dx = to.x - from.x;
+        const dy = to.y - from.y;
+        const len = Math.hypot(dx, dy) || 1;
+        const t = Math.min(CROP_BRACKET_LEN, len) / len;
+        return { x: from.x + dx * t, y: from.y + dy * t };
+    };
+    for (let i = 0; i < 4; i++) {
+        const c = req(corners[i]);
+        const prev = req(corners[(i + 3) % 4]);
+        const next = req(corners[(i + 1) % 4]);
+        const a = armTo(c, prev);
+        const b = armTo(c, next);
+        target.beginPath();
+        target.moveTo(a.x, a.y);
+        target.lineTo(c.x, c.y);
+        target.lineTo(b.x, b.y);
+        target.stroke();
+    }
+    target.setLineCap("butt");
+    target.setLineJoin("miter");
+};
+/**
+ * Paint the faint full-image ghost behind the crop chrome. Replicates the main
+ * image renderer's transform path: apply the element's local→world transform,
+ * then draw the whole bitmap over the virtual full-image LOCAL rect at
+ * {@link CROP_GHOST_OPACITY}. Resolves the live handle exactly as the built-in
+ * image renderer (`metadata.image`, else `resolveImageSource`); skips silently
+ * when no handle is available (async decode in flight / headless).
+ */
+const drawCropGhost = (target, ghost, w2s) => {
+    const el = ghost.element;
+    const handle = el.animationKind !== undefined
+        ? resolveImageSource(el, undefined)
+        : (el.metadata?.image ?? resolveImageSource(el, undefined));
+    if (handle === null || handle === undefined)
+        return;
+    const dynamic = el.metadata?.animated === true || el.animationKind !== undefined;
+    const { fullRect } = ghost;
+    target.save();
+    target.setTransform(w2s);
+    target.setDashArray(null);
+    target.translate(el.position.x, el.position.y);
+    if (el.rotation !== 0)
+        target.rotate(el.rotation);
+    if (el.scale.x !== 1 || el.scale.y !== 1)
+        target.scale(el.scale.x, el.scale.y);
+    target.setOpacity(CROP_GHOST_OPACITY);
+    target.drawImage(handle, fullRect.x, fullRect.y, fullRect.width, fullRect.height, dynamic);
+    target.setOpacity(1);
+    target.restore();
+};
+const drawPortDot = (target, center, active, role = "link-start", activeRadius) => {
     const radius = active ? (activeRadius ?? ANCHOR_DOT_ACTIVE_RADIUS) : ANCHOR_DOT_RADIUS;
     const isStart = role === "link-start";
     // When active (snapped), use the inverse fill of the resting state
@@ -667,41 +1009,25 @@ const drawPortDot = (target, center, style, active, role = "link-start", activeR
             ? LINK_START_ANCHOR_FILL
             : LINK_ATTACH_ANCHOR_FILL;
     const stroke = isStart ? LINK_START_ANCHOR_STROKE : LINK_ATTACH_ANCHOR_STROKE;
-    target.setStroke(stroke);
-    target.setStrokeWidth(ANCHOR_DOT_STROKE_WIDTH);
-    target.setDashArray(null);
-    target.setFill(fill);
-    target.beginPath();
-    target.ellipse(center.x, center.y, radius, radius);
-    target.fill();
-    target.stroke();
+    drawHandleDot(target, center, radius, { fill, stroke, strokeWidth: ANCHOR_DOT_STROKE_WIDTH });
 };
 const drawLinkEndpointHandle = (target, center, style) => {
-    const radius = LINK_ENDPOINT_HANDLE_DRAW_RADIUS;
-    target.setStroke(style.selectionStroke);
-    target.setStrokeWidth(2);
-    target.setDashArray(null);
-    target.setFill(style.handleFill);
-    target.beginPath();
-    target.ellipse(center.x, center.y, radius, radius);
-    target.fill();
-    target.stroke();
+    drawHandleDot(target, center, LINK_ENDPOINT_HANDLE_DRAW_RADIUS, {
+        fill: style.handleFill,
+        stroke: style.selectionStroke,
+        strokeWidth: 2,
+    });
 };
 // Smaller, semi-transparent dot on a segment midpoint — the "drag to add a
 // bend point" affordance. Lighter than a real waypoint handle so it reads
 // as secondary.
 const drawLinkMidpointHandle = (target, center, style) => {
-    const radius = LINK_MIDPOINT_HANDLE_DRAW_RADIUS;
-    target.setOpacity(0.55);
-    target.setStroke(style.selectionStroke);
-    target.setStrokeWidth(1.5);
-    target.setDashArray(null);
-    target.setFill(style.handleFill);
-    target.beginPath();
-    target.ellipse(center.x, center.y, radius, radius);
-    target.fill();
-    target.stroke();
-    target.setOpacity(1);
+    drawHandleDot(target, center, LINK_MIDPOINT_HANDLE_DRAW_RADIUS, {
+        fill: style.handleFill,
+        stroke: style.selectionStroke,
+        strokeWidth: 1.5,
+        opacity: 0.55,
+    });
 };
 const drawPeerSelection = (target, b, color) => {
     const pad = PEER_SELECTION_PADDING;