@oh-just-another/state 0.58.0 → 0.60.0

package/dist/overlay.js

@@ -1,16 +1,12 @@
-import { getAnnotationWorldPosition, getElementWorldBounds, getWorldToScreen, } 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, } from "./constants.js";
-import { CORNER_HANDLES, HANDLE_SIZE, handlePosition } from "./handle.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";
-/** Index-access helper: throws on out-of-range instead of returning `undefined`. */
-const req = (v) => {
-    if (v === undefined)
-        throw new Error("packages/state: index out of range");
-    return v;
-};
+import { req } from "./util.js";
 /**
  * Union AABB of every direct child of `groupId` (recursive). Returns
  * `null` for empty groups so callers can skip the outline pass. Used
@@ -21,7 +17,7 @@ const groupWorldBounds = (scene, groupId) => {
     for (const shape of scene.elements.values()) {
         if (shape.parentId !== groupId)
             continue;
-        const inner = shape.type === "group" ? groupWorldBounds(scene, shape.id) : getElementWorldBounds(shape);
+        const inner = isGroup(shape) ? groupWorldBounds(scene, shape.id) : getElementWorldBounds(shape);
         if (!inner)
             continue;
         acc = acc ? B.union(acc, inner) : inner;
@@ -85,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();
@@ -93,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,
@@ -112,41 +135,96 @@ 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);
         if (!shape)
             continue;
         // Groups have no intrinsic geometry — outline the union of their
-        // descendants instead. Otherwise the selection chrome would collapse
-        // to a zero-size point at the group's origin.
-        const worldBounds = shape.type === "group" ? groupWorldBounds(scene, id) : getElementWorldBounds(shape);
-        if (!worldBounds)
+        // descendants as an axis-aligned box. A single shape gets an oriented
+        // frame that turns with its rotation, so the selection box hugs the body
+        // instead of its (larger, axis-aligned) AABB.
+        if (isGroup(shape)) {
+            const worldBounds = groupWorldBounds(scene, id);
+            if (!worldBounds)
+                continue;
+            const screenBounds = projectBounds(worldBounds, w2s);
+            drawOutline(target, screenBounds, style);
+            if (shape.locked === true) {
+                drawLockBadge(target, screenBounds);
+                continue;
+            }
+            // Read-only: outline only — no resize/rotate affordances to grab.
+            if (multiSelect || !isResizable(shape) || options.readOnly === true)
+                continue;
+            for (const handle of CORNER_HANDLES) {
+                const worldPoint = handlePosition(handle, worldBounds, zoom);
+                drawHandle(target, matrix.applyToPoint(w2s, worldPoint), style);
+            }
+            drawRotateGripForBounds(target, worldBounds, zoom, w2s, style);
             continue;
-        const screenBounds = projectBounds(worldBounds, w2s);
-        drawOutline(target, screenBounds, style);
+        }
+        const frame = shapeSelectionFrame(shape);
+        // Unrotated → the plain AABB rect (unchanged rendering); rotated → a quad
+        // through the frame's corners so the box turns with the shape.
+        if (frame.rotation === 0) {
+            drawOutline(target, projectBounds(frame.bounds, w2s), style);
+        }
+        else {
+            drawFrameOutline(target, frame, w2s, style);
+        }
         // Locked element: no resize handles; show a small lock badge instead so
         // the user sees why it won't move/resize (click still selects → unlock).
         if (shape.locked === true) {
-            drawLockBadge(target, screenBounds);
+            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)
             continue;
-        // Draw only the four CORNER dots. The edge-midpoint handles are gone from
-        // the chrome — edge resize is done by dragging the selection-box side
-        // (see `hitHandle`), so no midpoint dot is needed. `resizeHandlesFor`
-        // (ALL_HANDLES) still drives hit-test capability.
+        // 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
+        // dot is needed; the edge handles stay hit-testable via `hitHandleOnFrame`.
         for (const handle of CORNER_HANDLES) {
-            const worldPoint = handlePosition(handle, worldBounds, zoom);
-            const screenPoint = matrix.applyToPoint(w2s, worldPoint);
-            drawHandle(target, screenPoint, style);
+            const worldPoint = handleWorldOnFrame(handle, frame, zoom);
+            drawHandle(target, matrix.applyToPoint(w2s, worldPoint), style);
         }
+        // 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) {
@@ -174,6 +252,47 @@ export const renderOverlay = (scene, selection, target, options = {}) => {
             target.restore();
         }
     }
+    // 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();
+        }
+    }
+    // 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. Link-drawing preview — dashed line in screen space. An elbow preview
     //    carries the full orthogonal polyline (`points`); otherwise a straight
     //    from→to segment.
@@ -236,6 +355,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) {
@@ -246,7 +373,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);
             }
         }
     }
@@ -256,7 +383,7 @@ export const renderOverlay = (scene, selection, target, options = {}) => {
     if (options.selectedLinkPaths && options.selectedLinkPaths.length > 0) {
         target.setTransform(w2s);
         target.setStroke(style.selectionStroke);
-        target.setOpacity(0.32);
+        target.setOpacity(SELECTION_HALO_OPACITY);
         target.setDashArray(null);
         target.setLineJoin("round");
         target.setLineCap("round");
@@ -279,7 +406,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) {
         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).
@@ -292,9 +421,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) {
@@ -303,6 +437,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
@@ -311,6 +453,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;
@@ -323,35 +466,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)");
@@ -364,23 +625,41 @@ 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: combined-bounds outline only — no resize/rotate handles.
+        if (options.readOnly === true)
+            return;
         const handleSet = CORNER_HANDLES;
         for (const handle of handleSet) {
             const worldPoint = handlePosition(handle, options.groupBounds, zoom);
             const screenPoint = matrix.applyToPoint(w2s, worldPoint);
             drawHandle(target, screenPoint, style);
         }
+        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);
@@ -388,25 +667,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) {
@@ -429,21 +722,12 @@ export const renderOverlay = (scene, selection, target, options = {}) => {
             target.fill();
         }
     }
-    target.restore();
 };
-/** Rounded "gif" chip in a shape's top-left corner — signals a paused
- *  GIF the user can click (or hover) to resume. */
-const GIF_BADGE_W = 30;
-const GIF_BADGE_H = 16;
-const GIF_BADGE_PAD = 4;
-const GIF_BADGE_RADIUS = 4;
-/** Small padlock badge at a selected locked element's top-right corner. */
-const LOCK_BADGE_SIZE = 16;
 const drawLockBadge = (target, b) => {
     const s = LOCK_BADGE_SIZE;
     const x = b.x + b.width - s - 2;
     const y = b.y + 2;
-    const color = "#1a73e8";
+    const color = LOCK_BADGE_COLOR;
     // Shackle — a ring above the body; its lower half is hidden by the body so
     // the visible top arc reads as the lock's bow.
     target.setStroke(color);
@@ -461,7 +745,7 @@ const drawLockBadge = (target, b) => {
     target.rect(x + s * 0.2, y + s * 0.44, s * 0.6, s * 0.48);
     target.fill();
     // Keyhole.
-    target.setFill("#fff");
+    target.setFill(LOCK_BADGE_KEYHOLE_COLOR);
     target.beginPath();
     target.ellipse(x + s / 2, y + s * 0.64, s * 0.07, s * 0.07);
     target.fill();
@@ -474,7 +758,7 @@ const drawGifBadge = (target, screen) => {
     const r = GIF_BADGE_RADIUS;
     // Rounded-rect background.
     target.setStroke(null);
-    target.setFill("rgba(0,0,0,0.65)");
+    target.setFill(GIF_BADGE_BG_COLOR);
     target.beginPath();
     target.moveTo(x + r, y);
     target.lineTo(x + w - r, y);
@@ -509,19 +793,121 @@ const drawOutline = (target, b, style) => {
     target.rect(b.x, b.y, b.width, b.height);
     target.stroke();
 };
+/** Selection outline as a (possibly rotated) quad through the frame's corners. */
+const drawFrameOutline = (target, frame, w2s, style) => {
+    const [wnw, wne, wse, wsw] = frameCorners(frame);
+    const nw = matrix.applyToPoint(w2s, wnw);
+    const ne = matrix.applyToPoint(w2s, wne);
+    const se = matrix.applyToPoint(w2s, wse);
+    const sw = matrix.applyToPoint(w2s, wsw);
+    target.setStroke(style.selectionStroke);
+    target.setStrokeWidth(style.selectionStrokeWidth);
+    target.setDashArray(null);
+    target.beginPath();
+    target.moveTo(nw.x, nw.y);
+    target.lineTo(ne.x, ne.y);
+    target.lineTo(se.x, se.y);
+    target.lineTo(sw.x, sw.y);
+    target.closePath();
+    target.stroke();
+};
+/** Screen-space AABB enclosing the frame's (rotated) corners — for badges. */
+const frameScreenBounds = (frame, w2s) => {
+    const pts = frameCorners(frame).map((c) => matrix.applyToPoint(w2s, c));
+    let minX = Infinity;
+    let minY = Infinity;
+    let maxX = -Infinity;
+    let maxY = -Infinity;
+    for (const p of pts) {
+        if (p.x < minX)
+            minX = p.x;
+        if (p.y < minY)
+            minY = p.y;
+        if (p.x > maxX)
+            maxX = p.x;
+        if (p.y > maxY)
+            maxY = p.y;
+    }
+    return { x: minX, y: minY, width: maxX - minX, height: maxY - minY };
+};
+/**
+ * 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, radius, radius);
+    target.fill();
+    target.stroke();
+    if (s.opacity !== undefined)
+        target.setOpacity(1);
+};
 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);
+    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
+ * at `grip` (screen px), with no connector line back to the shape. Authored in
+ * lucide's 24×24 space — a near-full circle (radius 9) opening on the right plus
+ * an `L`-shaped arrowhead at the opening — scaled so the circle radius is
+ * `ROTATE_ICON_RADIUS` screen px.
+ */
+const drawRotateIcon = (target, grip, style) => {
+    const s = ROTATE_ICON_RADIUS / 9; // icon radius 9 (in its 24×24 box) → screen px
+    // Map a point from the icon's 24×24 space (centre 12,12) to screen.
+    const tx = (px, py) => ({
+        x: grip.x + (px - 12) * s,
+        y: grip.y + (py - 12) * s,
+    });
     target.setStroke(style.handleStroke);
-    target.setStrokeWidth(1);
+    target.setFill(null);
+    target.setStrokeWidth(2 * s); // lucide strokeWidth 2
+    target.setLineCap("round");
+    target.setLineJoin("round");
     target.setDashArray(null);
+    // Arc: centre (12,12), radius 9, from 0° (east tail) clockwise to (21,8)
+    // (≈ 336° swept) — a polyline is smooth enough at this size.
+    const END_DEG = 336;
+    const STEPS = 30;
     target.beginPath();
-    target.ellipse(center.x, center.y, HANDLE_SIZE, HANDLE_SIZE);
-    target.fill();
+    for (let i = 0; i <= STEPS; i++) {
+        const a = ((END_DEG * i) / STEPS) * (Math.PI / 180);
+        const p = tx(12 + 9 * Math.cos(a), 12 + 9 * Math.sin(a));
+        if (i === 0)
+            target.moveTo(p.x, p.y);
+        else
+            target.lineTo(p.x, p.y);
+    }
     target.stroke();
+    // Arrowhead at the arc's end (lucide `M21 3 v5 h-5`): a right-angle chevron.
+    const a1 = tx(21, 3);
+    const a2 = tx(21, 8);
+    const a3 = tx(16, 8);
+    target.beginPath();
+    target.moveTo(a1.x, a1.y);
+    target.lineTo(a2.x, a2.y);
+    target.lineTo(a3.x, a3.y);
+    target.stroke();
+    target.setLineCap("butt");
+    target.setLineJoin("miter");
+};
+/** Project the rotate grip to screen and draw the icon for AABB `b`. */
+const drawRotateGripForBounds = (target, b, zoom, w2s, style) => {
+    const grip = rotateGripForBounds(b, zoom);
+    drawRotateIcon(target, matrix.applyToPoint(w2s, grip), style);
 };
 const drawDrawingPreview = (target, b, style) => {
     target.setStroke(style.drawingStroke);
@@ -541,6 +927,93 @@ const drawLinkPreview = (target, from, to, style) => {
     target.stroke();
 };
 /** Dashed polyline preview (elbow) in screen space. */
+/**
+ * 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();
+    const first = req(pts[0]);
+    target.moveTo(first.x, first.y);
+    for (let i = 1; i < pts.length; i++) {
+        const p = req(pts[i]);
+        target.lineTo(p.x, p.y);
+    }
+    target.lineTo(first.x, first.y);
+    target.stroke();
+    target.setDashArray(null);
+};
+/**
+ * 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 drawLinkPreviewPath = (target, pts, style) => {
     target.setStroke(style.drawingStroke);
     target.setStrokeWidth(1.5);
@@ -554,7 +1027,7 @@ const drawLinkPreviewPath = (target, pts, style) => {
     }
     target.stroke();
 };
-const drawPortDot = (target, center, style, active, role = "link-start", activeRadius) => {
+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
@@ -567,41 +1040,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;