@grida/hud 0.1.0 → 0.2.0

package/dist/{surface-hUEeEVdL.mjs → surface-BvMmXoEl.mjs}

@@ -1,5 +1,38 @@
+import { i as cursorToCss, r as cursorEquals } from "./cursor-BieMVb71.mjs";
 import { auxiliary_line_xylr, guide_line_xylr } from "@grida/cmath/_measurement";
 import cmath from "@grida/cmath";
+//#region primitives/pixel-grid.ts
+const DEFAULT_PIXEL_GRID_COLOR = "rgba(150, 150, 150, 0.15)";
+const DEFAULT_PIXEL_GRID_STEPS = [1, 1];
+function drawPixelGrid(p) {
+	const { ctx, transform, width, height, dpr, color = DEFAULT_PIXEL_GRID_COLOR, steps = DEFAULT_PIXEL_GRID_STEPS } = p;
+	ctx.save();
+	const [[sx, , tx], [, sy, ty]] = transform;
+	ctx.setTransform(sx * dpr, 0, 0, sy * dpr, tx * dpr, ty * dpr);
+	ctx.strokeStyle = color;
+	ctx.lineWidth = 1 / Math.max(Math.abs(sx * dpr), Math.abs(sy * dpr));
+	const minUserX = (0 - tx * dpr) / (sx * dpr);
+	const maxUserX = (width * dpr - tx * dpr) / (sx * dpr);
+	const minUserY = (0 - ty * dpr) / (sy * dpr);
+	const maxUserY = (height * dpr - ty * dpr) / (sy * dpr);
+	const [stepX, stepY] = steps;
+	const startX = Math.floor(minUserX / stepX) * stepX - 2 * stepX;
+	const endX = Math.ceil(maxUserX / stepX) * stepX + 2 * stepX;
+	const startY = Math.floor(minUserY / stepY) * stepY - 2 * stepY;
+	const endY = Math.ceil(maxUserY / stepY) * stepY + 2 * stepY;
+	ctx.beginPath();
+	for (let x = startX; x <= endX; x += stepX) {
+		ctx.moveTo(x, startY);
+		ctx.lineTo(x, endY);
+	}
+	for (let y = startY; y <= endY; y += stepY) {
+		ctx.moveTo(startX, y);
+		ctx.lineTo(endX, y);
+	}
+	ctx.stroke();
+	ctx.restore();
+}
+//#endregion
 //#region primitives/canvas.ts
 const DEFAULT_COLOR = "#f44336";
 const DEFAULT_LABEL_FG = "#ffffff";
@@ -37,6 +70,7 @@ var HUDCanvas = class {
 		]];
 		this.width = 0;
 		this.height = 0;
+		this.pixelGrid = null;
 		this.ctx = canvas.getContext("2d");
 		this.dpr = typeof window !== "undefined" ? window.devicePixelRatio || 1 : 1;
 		this.color = options?.color ?? DEFAULT_COLOR;
@@ -59,6 +93,31 @@ var HUDCanvas = class {
 		this.transform = transform;
 	}
 	/**
+	* Configure the back-most pixel-grid layer. Pass `null` to disable.
+	* Drawn before any HUD primitive, gated by `zoomThreshold`. See
+	* `PixelGridConfig.transform` for the two-transform contract.
+	*/
+	setPixelGrid(config) {
+		if (config === null) {
+			this.pixelGrid = null;
+			return;
+		}
+		this.pixelGrid = {
+			...config,
+			transform: config.transform ?? this.pixelGrid?.transform
+		};
+	}
+	/**
+	* Update only the pixel grid's transform, without replacing the rest of
+	* the config. Cheap to call per camera tick.
+	*/
+	setPixelGridTransform(transform) {
+		if (this.pixelGrid) this.pixelGrid = {
+			...this.pixelGrid,
+			transform
+		};
+	}
+	/**
 	* Clear the canvas and draw all primitives in `commands`.
 	* Pass `undefined` to clear without drawing (e.g. when no overlay is active).
 	*/
@@ -66,6 +125,17 @@ var HUDCanvas = class {
 		const ctx = this.ctx;
 		ctx.setTransform(1, 0, 0, 1, 0, 0);
 		ctx.clearRect(0, 0, this.canvas.width, this.canvas.height);
+		const pg = this.pixelGrid;
+		const pgTransform = pg?.transform ?? this.transform;
+		if (pg?.enabled && pgTransform[0][0] > pg.zoomThreshold) drawPixelGrid({
+			ctx,
+			transform: pgTransform,
+			width: this.width,
+			height: this.height,
+			dpr: this.dpr,
+			color: pg.color,
+			steps: pg.steps
+		});
 		if (!commands) return;
 		const { lines, rules, points, rects, polylines, screenRects } = commands;
 		if (rules && rules.length > 0) this.drawRules(rules);
@@ -91,12 +161,12 @@ var HUDCanvas = class {
 	drawRules(rules) {
 		const ctx = this.ctx;
 		this.applyScreenTransform();
-		ctx.strokeStyle = this.color;
 		ctx.lineWidth = DEFAULT_LINE_WIDTH;
-		for (const { axis, offset } of rules) {
-			const screenOffset = this.deltaToScreen(offset, axis);
+		for (const rule of rules) {
+			const screenOffset = this.deltaToScreen(rule.offset, rule.axis);
+			ctx.strokeStyle = rule.color ?? this.color;
 			ctx.beginPath();
-			if (axis === "x") {
+			if (rule.axis === "x") {
 				ctx.moveTo(screenOffset, 0);
 				ctx.lineTo(screenOffset, this.height);
 			} else {
@@ -150,17 +220,29 @@ var HUDCanvas = class {
 			const midY = (line.y1 + line.y2) / 2;
 			const lx = sx * midX + tx;
 			const ly = sy * midY + ty;
+			const angle = line.labelAngle ?? 0;
 			const isVertical = Math.abs(line.x2 - line.x1) < Math.abs(line.y2 - line.y1);
-			const labelX = isVertical ? lx + LABEL_OFFSET : lx;
-			const labelY = isVertical ? ly : ly + LABEL_OFFSET;
+			const baseOffsetX = isVertical ? LABEL_OFFSET : 0;
+			const baseOffsetY = isVertical ? 0 : LABEL_OFFSET;
+			const cos = Math.cos(angle);
+			const sin = Math.sin(angle);
+			const labelX = lx + baseOffsetX * cos - baseOffsetY * sin;
+			const labelY = ly + baseOffsetX * sin + baseOffsetY * cos;
 			const tw = ctx.measureText(line.label).width + LABEL_PADDING_X * 2;
 			const th = LABEL_FONT_HEIGHT + LABEL_PADDING_Y * 2;
+			if (angle !== 0) {
+				ctx.save();
+				ctx.translate(labelX, labelY);
+				ctx.rotate(angle);
+				ctx.translate(-labelX, -labelY);
+			}
 			ctx.fillStyle = line.color ?? this.color;
 			ctx.beginPath();
 			ctx.roundRect(labelX - tw / 2, labelY - th / 2, tw, th, LABEL_BORDER_RADIUS);
 			ctx.fill();
 			ctx.fillStyle = DEFAULT_LABEL_FG;
 			ctx.fillText(line.label, labelX, labelY);
+			if (angle !== 0) ctx.restore();
 		}
 	}
 	drawRects(rects) {
@@ -223,20 +305,29 @@ var HUDCanvas = class {
 	drawPoints(points) {
 		const ctx = this.ctx;
 		this.applyScreenTransform();
-		ctx.strokeStyle = this.color;
 		ctx.lineWidth = DEFAULT_LINE_WIDTH;
 		const half = CROSSHAIR_SIZE / 2;
 		const [[sx, , tx], [, sy, ty]] = this.transform;
-		ctx.beginPath();
-		for (const [px, py] of points) {
-			const scrX = sx * px + tx;
-			const scrY = sy * py + ty;
-			ctx.moveTo(scrX - half, scrY - half);
-			ctx.lineTo(scrX + half, scrY + half);
-			ctx.moveTo(scrX + half, scrY - half);
-			ctx.lineTo(scrX - half, scrY + half);
+		const buckets = /* @__PURE__ */ new Map();
+		for (const p of points) {
+			const c = p.color ?? this.color;
+			const arr = buckets.get(c);
+			if (arr) arr.push(p);
+			else buckets.set(c, [p]);
+		}
+		for (const [color, group] of buckets) {
+			ctx.strokeStyle = color;
+			ctx.beginPath();
+			for (const p of group) {
+				const scrX = sx * p.x + tx;
+				const scrY = sy * p.y + ty;
+				ctx.moveTo(scrX - half, scrY - half);
+				ctx.lineTo(scrX + half, scrY + half);
+				ctx.moveTo(scrX + half, scrY - half);
+				ctx.lineTo(scrX - half, scrY + half);
+			}
+			ctx.stroke();
 		}
-		ctx.stroke();
 	}
 	/**
 	* Draw rects whose **size is in screen-space** but whose **anchor is in
@@ -283,6 +374,15 @@ var HUDCanvas = class {
 			}
 			const doFill = r.fill !== false;
 			const doStroke = r.stroke !== false;
+			const angle = r.angle ?? 0;
+			if (angle !== 0) {
+				const cx = x + w / 2;
+				const cy = y + h / 2;
+				ctx.save();
+				ctx.translate(cx, cy);
+				ctx.rotate(angle);
+				ctx.translate(-cx, -cy);
+			}
 			if (doFill) {
 				ctx.fillStyle = r.fillColor ?? this.color;
 				ctx.fillRect(x, y, w, h);
@@ -291,28 +391,67 @@ var HUDCanvas = class {
 				ctx.strokeStyle = r.strokeColor ?? this.color;
 				ctx.strokeRect(x, y, w, h);
 			}
+			if (angle !== 0) ctx.restore();
 		}
 	}
 };
 //#endregion
+//#region primitives/draw.ts
+/**
+* Filter a draw command list by semantic group.
+*
+* Ungrouped primitives are always kept. The function is intentionally shallow:
+* primitives are immutable command objects on the hot draw path, so preserving
+* object identity keeps this as a visibility pass rather than a rewrite.
+*/
+function filterHUDDrawByGroup(draw, filter) {
+	if (!draw) return void 0;
+	const hidden = new Set(filter.hidden ?? []);
+	if (hidden.size === 0) return draw;
+	const out = {};
+	out.lines = keepVisible(draw.lines, hidden);
+	out.rules = keepVisible(draw.rules, hidden);
+	out.points = keepVisible(draw.points, hidden);
+	out.rects = keepVisible(draw.rects, hidden);
+	out.polylines = keepVisible(draw.polylines, hidden);
+	out.screenRects = keepVisible(draw.screenRects, hidden);
+	return hasAny(out) ? out : void 0;
+}
+function keepVisible(items, hidden) {
+	if (!items || items.length === 0) return void 0;
+	const kept = items.filter((item) => !item.group || !hidden.has(item.group));
+	return kept.length > 0 ? kept : void 0;
+}
+function hasAny(draw) {
+	return (draw.lines?.length ?? 0) > 0 || (draw.rules?.length ?? 0) > 0 || (draw.points?.length ?? 0) > 0 || (draw.rects?.length ?? 0) > 0 || (draw.polylines?.length ?? 0) > 0 || (draw.screenRects?.length ?? 0) > 0;
+}
+//#endregion
 //#region primitives/snap-guide.ts
 /**
 * Convert a `guide.SnapGuide` (the output of `guide.plot()`) into a
 * generic {@link HUDDraw} command list.
 *
-* Lines pass through directly (HUDLine extends cmath.ui.Line).
-* Points pass through directly (both are cmath.Vector2).
-* Rules are destructured from tuples to objects.
+* `color`, when supplied, is applied as the per-item stroke override
+* for every emitted line, rule, and point. When absent, the HUD
+* canvas's current color is used.
 */
-function snapGuideToHUDDraw(sg) {
+function snapGuideToHUDDraw(sg, color) {
 	if (!sg) return void 0;
 	return {
-		lines: sg.lines,
+		lines: sg.lines.map((l) => ({
+			...l,
+			color
+		})),
 		rules: sg.rules.map(([axis, offset]) => ({
 			axis,
-			offset
+			offset,
+			color
 		})),
-		points: sg.points
+		points: sg.points.map(([x, y]) => ({
+			x,
+			y,
+			color
+		}))
 	};
 }
 //#endregion
@@ -449,15 +588,53 @@ function rectFromPoints(a, b) {
 	return cmath.rect.fromPoints([a, b]);
 }
 /**
-* Apply a resize handle drag to an initial rect and return the new rect.
+* Apply a resize-handle drag to a `SelectionShape` and return the new shape.
 *
-* `dx, dy` is the total drag delta in document-space, measured from
+* `dx, dy` is the total drag delta in **document-space**, measured from
 * `anchor_doc` (the pointer-down point) to the current pointer.
 *
+* - For `kind: "rect"` shapes, the delta applies directly to the doc-space
+*   bbox. Same math as the legacy `Rect`-only `applyResize`; no behavior
+*   change for axis-aligned hosts.
+* - For `kind: "transformed"` shapes, the doc-space delta is rotated into
+*   the shape's **local** frame via the matrix's linear part (the rotation
+*   component, translation dropped), then applied to `local`. The matrix
+*   itself is preserved — only `local.x/y/width/height` change. Net effect:
+*   dragging a corner of a rotated rect extends the artwork along its
+*   rotation axis, not along world axes.
+* - For `kind: "line"` and `kind: "unresolved"` the shape is returned
+*   unchanged (lines have endpoint-knob gestures, not corner-resize).
+*
 * No constraints: width/height can go negative — host is responsible for
 * normalizing if it cares (most callers clamp to a min-size).
 */
 function applyResize(initial, direction, dx, dy) {
+	if (initial.kind === "rect") return {
+		kind: "rect",
+		rect: applyResizeRect(initial.rect, direction, dx, dy)
+	};
+	if (initial.kind === "transformed") {
+		const m = initial.matrix;
+		const linear = [[
+			m[0][0],
+			m[0][1],
+			0
+		], [
+			m[1][0],
+			m[1][1],
+			0
+		]];
+		const inv_linear = cmath.transform.invert(linear);
+		const [ldx, ldy] = cmath.vector2.transform([dx, dy], inv_linear);
+		return {
+			kind: "transformed",
+			local: applyResizeRect(initial.local, direction, ldx, ldy),
+			matrix: m
+		};
+	}
+	return initial;
+}
+function applyResizeRect(initial, direction, dx, dy) {
 	let { x, y, width, height } = initial;
 	switch (direction) {
 		case "n":
@@ -503,16 +680,19 @@ function applyResize(initial, direction, dx, dy) {
 	};
 }
 //#endregion
-//#region event/cursor.ts
-/** Cursor-equality used to detect changes without object allocations. */
-function cursorEquals(a, b) {
-	if (typeof a === "string" && typeof b === "string") return a === b;
-	if (typeof a !== "string" && typeof b !== "string") {
-		if (a.kind === "resize" && b.kind === "resize") return a.direction === b.direction;
-		if (a.kind === "rotate" && b.kind === "rotate") return a.corner === b.corner;
-		return false;
-	}
-	return false;
+//#region event/shape.ts
+/**
+* Compute the axis-aligned bounding box of a `SelectionShape` in doc-space.
+* Used for layout math the chrome builder needs (e.g. handle positions).
+*
+* Throws on `kind: "unresolved"` — the chrome builder must resolve those
+* via `shapeOf` first.
+*/
+function shapeBounds(shape) {
+	if (shape.kind === "rect") return shape.rect;
+	if (shape.kind === "transformed") return cmath.rect.transform(shape.local, shape.matrix);
+	if (shape.kind === "line") return cmath.rect.fromPoints([shape.p1, shape.p2]);
+	throw new Error(`shapeBounds: cannot bound unresolved shape (id=${shape.id})`);
 }
 //#endregion
 //#region event/click-tracker.ts
@@ -556,9 +736,10 @@ function nowMs() {
 /**
 * Registry of overlay UI hit regions.
 *
-* Regions are appended in draw order (back-to-front). `hitTest` iterates
-* in reverse so the topmost region wins — matching how the chrome is
-* visually layered.
+* Regions are appended in declaration order. `hitTest` resolves by
+* **lowest priority value** at the hit point; declaration order
+* serves as tie-break only (later push wins on equal priorities,
+* preserving the prior "topmost wins on overlap" feel).
 */
 var HitRegions = class {
 	constructor() {
@@ -571,11 +752,18 @@ var HitRegions = class {
 		this.regions.push(region);
 	}
 	hitTest(point) {
-		for (let i = this.regions.length - 1; i >= 0; i--) {
-			const r = this.regions[i];
-			if (cmath.rect.containsPoint(r.rect, point)) return r.action;
+		return this.hitTestRegion(point)?.action ?? null;
+	}
+	/** Returns the full region (label + priority) — used by tests and
+	*  debug tooling that want to assert on `label`. `hitTest` delegates here. */
+	hitTestRegion(point) {
+		let best = null;
+		for (const r of this.regions) {
+			const test_point = r.inverse_transform ? cmath.vector2.transform(point, r.inverse_transform) : point;
+			if (!cmath.rect.containsPoint(r.rect, test_point)) continue;
+			if (best === null || r.priority <= best.priority) best = r;
 		}
-		return null;
+		return best;
 	}
 	isEmpty() {
 		return this.regions.length === 0;
@@ -588,6 +776,44 @@ var HitRegions = class {
 //#endregion
 //#region event/decision.ts
 /**
+* Selection-intent decision module — pure functions, ZERO side effects.
+*
+* Mental model:
+*
+*   The HUD is an event router over real overlay layers. The host creates
+*   overlays (resize knob, rotate region, endpoint knob, translate body,
+*   etc.); the router decides what each one does on pointer-down by overlay
+*   type, falling back to a scene-content pick when no overlay claims.
+*   Pointer events are synthesized on top of raw pointer input — no native
+*   `click`, no DOM ordering.
+*
+*   Architecture:
+*
+*     PointerDownInput  ─►  classifyScenario()  ─►  Scenario  ─►  dispatch()  ─►  PointerDownDecision
+*                           (recognizer)                          (declarative table)
+*
+*   The `Scenario` enum is a **descriptive label** for each `(overlay hit,
+*   pick result, selection, modifiers)` combination — useful for tests and
+*   readable dispatch — NOT a contract the HUD imposes on hosts. The
+*   contract is per-overlay routing semantics (e.g. resize knob always
+*   starts a gesture; translate body always defers) and the Tier-1 → Tier-2
+*   fallback when no overlay claims the point.
+*
+* Adding a new UX rule:
+*
+*   1. Add a new `Scenario` constant (or reuse one).
+*   2. Add/update the recognizer branch in {@link classifyScenario}.
+*   3. Add/update the dispatch branch in {@link decidePointerDown}.
+*   4. Add tests pinning the classification and the dispatch.
+*   5. Update the working-group doc.
+*
+* Working-group spec (implementation-agnostic):
+*   https://grida.co/docs/wg/feat-editor/ux-surface/selection-intent
+*
+* UX-narrative sibling:
+*   https://grida.co/docs/wg/feat-editor/ux-surface/selection
+*/
+/**
 * Recognize which scenario a pointer-down belongs to. Total over inputs.
 * Pure, no I/O. The single source of truth for "which atomic intent did the
 * user just express?"
@@ -654,7 +880,7 @@ function dispatch(scenario, input) {
 				kind: "start_resize",
 				ids: a.ids,
 				direction: a.direction,
-				initial_rect: a.initial_rect
+				initial_shape: a.initial_shape
 			};
 		}
 		case "HandleRotate": {
@@ -663,7 +889,7 @@ function dispatch(scenario, input) {
 				kind: "start_rotate",
 				ids: a.ids,
 				corner: a.corner,
-				initial_rect: a.initial_rect
+				initial_shape: a.initial_shape
 			};
 		}
 		case "HandleEndpoint": {
@@ -764,11 +990,13 @@ function decideIdleCursor(input) {
 	if (ui_action) switch (ui_action.kind) {
 		case "resize_handle": return {
 			kind: "resize",
-			direction: ui_action.direction
+			direction: ui_action.direction,
+			baseAngle: shape_screen_angle_rad(ui_action.initial_shape)
 		};
 		case "rotate_handle": return {
 			kind: "rotate",
-			corner: ui_action.corner
+			corner: ui_action.corner,
+			baseAngle: shape_screen_angle_rad(ui_action.initial_shape)
 		};
 		case "translate_handle": return "move";
 		case "select_node":
@@ -777,6 +1005,24 @@ function decideIdleCursor(input) {
 	if (hovered_id && selection_ids.includes(hovered_id)) return "move";
 	return "default";
 }
+/**
+* Doc-space rotation of a `SelectionShape` in radians. For `transformed`
+* shapes this is the angle baked into `matrix`; for `rect`/`line` it's 0.
+*
+* Used by `decideIdleCursor` and by the rotate-gesture cursor compositor
+* so the resize / rotate cursor always tilts to match the selection's
+* orientation — without requiring the HUD's camera to be axis-aligned
+* for the doc-space angle to be the right thing to render (the renderer
+* draws the cursor in screen px, and in svg-editor the camera contributes
+* scale + translate only, so doc-space == screen-space rotation).
+*
+* For hosts that ROTATE the HUD camera, this should compose with the
+* camera's angle at consume time. Not relevant for svg-editor.
+*/
+function shape_screen_angle_rad(shape) {
+	if (shape.kind !== "transformed") return 0;
+	return cmath.transform.angle(shape.matrix) * Math.PI / 180;
+}
 //#endregion
 //#region event/transform.ts
 const IDENTITY = [[
@@ -981,16 +1227,17 @@ var SurfaceState = class {
 				const g = this.gesture;
 				const dx = point_doc[0] - g.anchor_doc[0];
 				const dy = point_doc[1] - g.anchor_doc[1];
-				const next_rect = applyResize(g.initial_rect, g.direction, dx, dy);
+				const next_shape = applyResize(g.initial_shape, g.direction, dx, dy);
 				this.gesture = {
 					...g,
-					current_rect: next_rect
+					current_shape: next_shape
 				};
 				deps.emitIntent({
 					kind: "resize",
 					ids: g.ids,
 					anchor: g.direction,
-					rect: next_rect,
+					rect: shapeBounds(next_shape),
+					shape: next_shape,
 					phase: "preview"
 				});
 				response.needsRedraw = true;
@@ -1003,12 +1250,18 @@ var SurfaceState = class {
 					...g,
 					current_angle: angle
 				};
+				const delta = angle - g.anchor_angle;
 				deps.emitIntent({
 					kind: "rotate",
 					ids: g.ids,
-					angle: angle - g.anchor_angle,
+					angle: delta,
 					phase: "preview"
 				});
+				this.setCursor({
+					kind: "rotate",
+					corner: g.corner,
+					baseAngle: g.initial_cursor_angle + delta
+				}, response);
 				response.needsRedraw = true;
 				return response;
 			}
@@ -1060,23 +1313,30 @@ var SurfaceState = class {
 					kind: "resize",
 					ids: [...decision.ids],
 					direction: decision.direction,
-					initial_rect: decision.initial_rect,
+					initial_shape: decision.initial_shape,
 					anchor_doc: point_doc,
-					current_rect: decision.initial_rect
+					current_shape: decision.initial_shape
 				};
 				response.needsRedraw = true;
 				return response;
 			case "start_rotate": {
-				const [cx, cy] = cmath.rect.getCenter(decision.initial_rect);
+				const [cx, cy] = cmath.rect.getCenter(shapeBounds(decision.initial_shape));
 				const angle = Math.atan2(point_doc[1] - cy, point_doc[0] - cx);
+				const initial_cursor_angle = decision.initial_shape.kind === "transformed" ? cmath.transform.angle(decision.initial_shape.matrix) * Math.PI / 180 : 0;
 				this.gesture = {
 					kind: "rotate",
 					ids: [...decision.ids],
 					corner: decision.corner,
 					center_doc: [cx, cy],
 					anchor_angle: angle,
-					current_angle: angle
+					current_angle: angle,
+					initial_cursor_angle
 				};
+				this.setCursor({
+					kind: "rotate",
+					corner: decision.corner,
+					baseAngle: initial_cursor_angle
+				}, response);
 				response.needsRedraw = true;
 				return response;
 			}
@@ -1182,7 +1442,8 @@ var SurfaceState = class {
 					kind: "resize",
 					ids: g.ids,
 					anchor: g.direction,
-					rect: g.current_rect,
+					rect: shapeBounds(g.current_shape),
+					shape: g.current_shape,
 					phase: "commit"
 				});
 				this.gesture = IDLE;
@@ -1279,20 +1540,6 @@ function mergeStyle(base, partial) {
 	};
 }
 //#endregion
-//#region event/shape.ts
-/**
-* Compute the axis-aligned bounding box of a `SelectionShape` in doc-space.
-* Used for layout math the chrome builder needs (e.g. handle positions).
-*
-* Throws on `kind: "unresolved"` — the chrome builder must resolve those
-* via `shapeOf` first.
-*/
-function shapeBounds(shape) {
-	if (shape.kind === "rect") return shape.rect;
-	if (shape.kind === "line") return cmath.rect.fromPoints([shape.p1, shape.p2]);
-	throw new Error(`shapeBounds: cannot bound unresolved shape (id=${shape.id})`);
-}
-//#endregion
 //#region event/overlay.ts
 /**
 * Minimum hit-target size in screen-px.
@@ -1308,25 +1555,237 @@ const MIN_HIT_SIZE = 16;
 */
 const MIN_CHROME_VISIBLE_SIZE = 12;
 //#endregion
-//#region surface/chrome.ts
-const CORNER_RESIZE_DIRECTIONS = [
+//#region event/selection-controls.ts
+const CORNER_DIRS = [
 	"nw",
 	"ne",
 	"se",
 	"sw"
 ];
-const EDGE_RESIZE_DIRECTIONS = [
+const EDGE_DIRS = [
 	"n",
 	"e",
 	"s",
 	"w"
 ];
-const ROTATION_CORNERS = [
-	"nw",
-	"ne",
-	"se",
-	"sw"
-];
+const CORNER_LABEL = {
+	nw: "resize_handle:nw",
+	ne: "resize_handle:ne",
+	se: "resize_handle:se",
+	sw: "resize_handle:sw"
+};
+const EDGE_LABEL = {
+	n: "resize_edge:n",
+	e: "resize_edge:e",
+	s: "resize_edge:s",
+	w: "resize_edge:w"
+};
+const ROTATE_LABEL = {
+	nw: "rotate:nw",
+	ne: "rotate:ne",
+	se: "rotate:se",
+	sw: "rotate:sw"
+};
+const HUDHitPriority = {
+	ENDPOINT_HANDLE: 10,
+	RESIZE_HANDLE_EDGE_SMALL: 22,
+	TRANSLATE_BODY_SMALL: 25,
+	RESIZE_HANDLE_EDGE: 30,
+	RESIZE_HANDLE_CORNER: 31,
+	TRANSLATE_BODY: 40,
+	ROTATE_HANDLE: 50
+};
+/** The principle constant — the minimum guaranteed length for the body
+*  interior on each axis AND for each side strip along its parallel
+*  axis. Tunable; everything else derives. */
+const MIN_GUARANTEED_INTERACTIVE_DIM = 20;
+/** Below this axis dim, body promotes above corner. Derived from the
+*  principle. */
+const BODY_FLIP_THRESHOLD = 36;
+/**
+* @returns { corner, edge } — lengths in screen-px summing to `total`
+* (corner * 2 + edge === total). Each is `>= 0`.
+*
+* Three phases:
+*  - **comfortable** (`total >= 2 * corner_preferred + edge_min`):
+*    corners at preferred, edge takes the surplus.
+*  - **squeezed** (`total >= edge_min`): edge at its min, corners share
+*    the remainder.
+*  - **tiny** (`total < edge_min`): edge takes everything, corners 0.
+*/
+function negotiateAxis(total, corner_preferred, edge_min) {
+	if (total <= 0) return {
+		corner: 0,
+		edge: 0
+	};
+	if (total >= corner_preferred * 2 + edge_min) return {
+		corner: corner_preferred,
+		edge: total - corner_preferred * 2
+	};
+	if (total >= edge_min) return {
+		corner: (total - edge_min) / 2,
+		edge: edge_min
+	};
+	return {
+		corner: 0,
+		edge: total
+	};
+}
+/**
+* Compute the selection control layout for a screen-space rect.
+*
+* Pure: no DOM, no global state. Same inputs → same zones.
+*
+* The perimeter ring straddles the bbox edge with `extension =
+* hit_size / 2` overhang outside. Along each axis the run of length
+* `axis_dim + 2 * extension` is split via {@link negotiateAxis} into
+* `[corner | edge | corner]`. The 4 corners and 4 edges in 2D then tile
+* the ring as a strict 3×3 grid of cells — **non-overlapping**. Body
+* sits at rect_screen and may overlap with the ring's inside-bbox half
+* in comfortable mode; priority resolves those overlaps.
+*
+* See the comment block in this file for the full principle.
+*/
+function computeSelectionControlLayout(rect_screen, opts) {
+	const zones = [];
+	const w_violated = rect_screen.width < BODY_FLIP_THRESHOLD;
+	const h_violated = rect_screen.height < BODY_FLIP_THRESHOLD;
+	const small_mode = w_violated || h_violated;
+	const controls_visible = rect_screen.width >= 12 && rect_screen.height >= 12;
+	if (rect_screen.width >= 1 || rect_screen.height >= 1) zones.push({
+		rect: rect_screen,
+		priority: small_mode ? HUDHitPriority.TRANSLATE_BODY_SMALL : HUDHitPriority.TRANSLATE_BODY,
+		role: { kind: "translate" },
+		label: "translate"
+	});
+	if (!controls_visible) return {
+		zones,
+		controls_visible,
+		small_mode
+	};
+	const hit_size = Math.max(opts.handle_size + 4, 16);
+	const extension = hit_size / 2;
+	const total_x = rect_screen.width + extension * 2;
+	const total_y = rect_screen.height + extension * 2;
+	const { corner: cx, edge: ex } = negotiateAxis(total_x, hit_size, 20);
+	const { corner: cy, edge: ey } = negotiateAxis(total_y, hit_size, 20);
+	const left = rect_screen.x - extension;
+	const top = rect_screen.y - extension;
+	const mid_x = left + cx;
+	const mid_y = top + cy;
+	const right_x = mid_x + ex;
+	const right_y = mid_y + ey;
+	const cornerRects = {
+		nw: {
+			x: left,
+			y: top,
+			width: cx,
+			height: cy
+		},
+		ne: {
+			x: right_x,
+			y: top,
+			width: cx,
+			height: cy
+		},
+		sw: {
+			x: left,
+			y: right_y,
+			width: cx,
+			height: cy
+		},
+		se: {
+			x: right_x,
+			y: right_y,
+			width: cx,
+			height: cy
+		}
+	};
+	const edgeRects = {
+		n: {
+			x: mid_x,
+			y: top,
+			width: ex,
+			height: cy
+		},
+		s: {
+			x: mid_x,
+			y: right_y,
+			width: ex,
+			height: cy
+		},
+		w: {
+			x: left,
+			y: mid_y,
+			width: cx,
+			height: ey
+		},
+		e: {
+			x: right_x,
+			y: mid_y,
+			width: cx,
+			height: ey
+		}
+	};
+	for (const dir of CORNER_DIRS) {
+		const rect = cornerRects[dir];
+		if (rect.width <= 0 || rect.height <= 0) continue;
+		zones.push({
+			rect,
+			priority: HUDHitPriority.RESIZE_HANDLE_CORNER,
+			role: {
+				kind: "resize_corner",
+				direction: dir
+			},
+			label: CORNER_LABEL[dir]
+		});
+	}
+	const edge_priority = {
+		n: w_violated ? HUDHitPriority.RESIZE_HANDLE_EDGE_SMALL : HUDHitPriority.RESIZE_HANDLE_EDGE,
+		s: w_violated ? HUDHitPriority.RESIZE_HANDLE_EDGE_SMALL : HUDHitPriority.RESIZE_HANDLE_EDGE,
+		e: h_violated ? HUDHitPriority.RESIZE_HANDLE_EDGE_SMALL : HUDHitPriority.RESIZE_HANDLE_EDGE,
+		w: h_violated ? HUDHitPriority.RESIZE_HANDLE_EDGE_SMALL : HUDHitPriority.RESIZE_HANDLE_EDGE
+	};
+	for (const dir of EDGE_DIRS) {
+		const rect = edgeRects[dir];
+		if (rect.width <= 0 || rect.height <= 0) continue;
+		zones.push({
+			rect,
+			priority: edge_priority[dir],
+			role: {
+				kind: "resize_edge",
+				direction: dir
+			},
+			label: EDGE_LABEL[dir]
+		});
+	}
+	if (opts.show_rotation) for (const dir of CORNER_DIRS) {
+		const resize = cornerRects[dir];
+		if (resize.width <= 0 || resize.height <= 0) continue;
+		const [dx, dy] = cmath.compass.cardinal_direction_vector[dir];
+		zones.push({
+			rect: {
+				x: resize.x + (dx > 0 ? 0 : -16),
+				y: resize.y + (dy > 0 ? 0 : -16),
+				width: resize.width + 16,
+				height: resize.height + 16
+			},
+			priority: HUDHitPriority.ROTATE_HANDLE,
+			role: {
+				kind: "rotate",
+				corner: dir
+			},
+			label: ROTATE_LABEL[dir]
+		});
+	}
+	return {
+		zones,
+		controls_visible,
+		small_mode
+	};
+}
+//#endregion
+//#region surface/chrome.ts
 /**
 * Build the per-frame surface chrome.
 *
@@ -1336,34 +1795,44 @@ const ROTATION_CORNERS = [
 * - `decoration` — pure visual `HUDDraw` (selection outlines, hover outline,
 *   marquee, line outlines). Not interactable.
 *
+* Priority is data, not iteration order. Each `OverlayElement` carries its
+* own `priority` (lower wins) and a stable `label`. The `HitRegions`
+* registry resolves overlapping regions by priority, not push order. See
+* `event/selection-controls.ts` for the canonical priority ladder.
+*
 * The Surface fans `overlays` into `HitRegions` (for events) and merges
 * their render shapes into `decoration` (for the canvas draw call).
 */
 function buildChrome(input) {
-	const { state, shapeOf, style } = input;
+	const { state, shapeOf, style, groups } = input;
 	const transform = state.getTransform();
 	const overlays = [];
 	const decoration_rects = [];
 	const decoration_lines = [];
-	const in_gesture = state.gesture.kind !== "idle";
-	const hover_id = in_gesture ? null : state.getEffectiveHover();
+	const decoration_polylines = [];
+	const hover_id = state.gesture.kind === "idle" ? state.getEffectiveHover() : null;
 	if (hover_id) {
 		const shape = shapeOf(hover_id);
-		if (shape) pushShapeOutline(shape, decoration_rects, decoration_lines, {
+		if (shape) pushShapeOutline(shape, decoration_rects, decoration_lines, decoration_polylines, {
 			dashed: false,
-			strokeWidth: style.hoverOutlineWidth
+			strokeWidth: style.hoverOutlineWidth,
+			group: groups?.hover
 		});
 	}
-	if (!in_gesture) for (const group of state.getSelectionGroups()) {
+	for (const group of state.getSelectionGroups()) {
 		const shape = resolveGroupShape(group, shapeOf);
 		if (!shape) continue;
-		pushShapeOutline(shape, decoration_rects, decoration_lines, {
+		pushShapeOutline(shape, decoration_rects, decoration_lines, decoration_polylines, {
 			dashed: false,
-			strokeWidth: style.selectionOutlineWidth
+			strokeWidth: style.selectionOutlineWidth,
+			group: groups?.selection
 		});
-		pushBodyHandle(shape, group.ids, transform, overlays);
-		if (shape.kind === "rect") pushRectGroupHandles(shape.rect, group.ids, transform, style, overlays);
-		else if (shape.kind === "line") pushLineEndpoints(group.ids[0], shape.p1, shape.p2, style, overlays);
+		if (shape.kind === "rect") pushRectChrome(shape.rect, group.ids, transform, style, groups?.selectionControls, overlays);
+		else if (shape.kind === "transformed") pushTransformedChrome(shape.local, shape.matrix, group.ids, transform, style, groups?.selectionControls, overlays);
+		else if (shape.kind === "line") {
+			pushLineBody(shape, group.ids, transform, groups?.selectionControls, overlays);
+			pushLineEndpoints(group.ids[0], shape.p1, shape.p2, style, groups?.selectionControls, overlays);
+		}
 	}
 	if (state.gesture.kind === "marquee") {
 		const g = state.gesture;
@@ -1372,20 +1841,35 @@ function buildChrome(input) {
 			...mr,
 			stroke: true,
 			fill: true,
-			fillOpacity: .15
+			fillOpacity: .15,
+			group: groups?.marquee
+		});
+	}
+	if (state.gesture.kind === "resize") {
+		const shape = state.gesture.current_shape;
+		if (shape.kind === "transformed") {
+			const corners = cmath.rect.toCorners(shape.local).map((p) => cmath.vector2.transform(p, shape.matrix));
+			decoration_polylines.push({
+				points: [...corners, corners[0]],
+				stroke: true,
+				fill: false,
+				dashed: true,
+				group: groups?.transformPreview
+			});
+		} else decoration_rects.push({
+			...shapeBounds(shape),
+			stroke: true,
+			fill: false,
+			dashed: true,
+			group: groups?.transformPreview
 		});
 	}
-	if (state.gesture.kind === "resize") decoration_rects.push({
-		...state.gesture.current_rect,
-		stroke: true,
-		fill: false,
-		dashed: true
-	});
 	return {
 		overlays,
 		decoration: {
 			rects: decoration_rects.length > 0 ? decoration_rects : void 0,
-			lines: decoration_lines.length > 0 ? decoration_lines : void 0
+			lines: decoration_lines.length > 0 ? decoration_lines : void 0,
+			polylines: decoration_polylines.length > 0 ? decoration_polylines : void 0
 		}
 	};
 }
@@ -1393,168 +1877,262 @@ function resolveGroupShape(group, shapeOf) {
 	if (group.shape.kind === "unresolved") return shapeOf(group.shape.id);
 	return group.shape;
 }
-function pushBodyHandle(shape, ids, transform, out) {
-	const bounds_doc = shapeBounds(shape);
-	const rect_screen = cmath.rect.transform(bounds_doc, transform);
-	if (rect_screen.width < 1 && rect_screen.height < 1) return;
-	out.push({
-		action: {
-			kind: "translate_handle",
-			ids
-		},
-		hit: {
-			kind: "screen_aabb",
-			rect: rect_screen
-		},
-		cursor: "move"
+function pushRectChrome(rect_doc, ids, transform, style, group, out) {
+	const layout = computeSelectionControlLayout(cmath.rect.transform(rect_doc, transform), {
+		handle_size: style.handleSize,
+		show_rotation: style.showRotationHandles && ids.length >= 1
 	});
+	for (const zone of layout.zones) {
+		const el = zoneToOverlay(zone, rect_doc, ids, style, group, layout.controls_visible);
+		if (el) out.push(el);
+	}
 }
-function pushRectGroupHandles(rect_doc, ids, transform, style, out) {
-	const rect_screen = cmath.rect.transform(rect_doc, transform);
-	if (rect_screen.width < 12 && rect_screen.height < 12) return;
-	const size = style.handleSize;
-	const hit_size = Math.max(size + 4, 16);
-	const anchors_doc = cornerAnchors(rect_doc);
-	for (const dir of CORNER_RESIZE_DIRECTIONS) {
-		const anchor_doc = anchors_doc[dir];
-		out.push({
+function zoneToOverlay(zone, rect_doc, ids, style, group, controls_visible) {
+	switch (zone.role.kind) {
+		case "translate": return {
+			label: zone.label,
+			group,
+			action: {
+				kind: "translate_handle",
+				ids
+			},
+			hit: {
+				kind: "screen_aabb",
+				rect: zone.rect
+			},
+			priority: zone.priority,
+			cursor: "move"
+		};
+		case "resize_corner": {
+			const dir = zone.role.direction;
+			const size = style.handleSize;
+			const anchor_doc = cmath.rect.getCardinalPoint(rect_doc, dir);
+			return {
+				label: zone.label,
+				group,
+				action: {
+					kind: "resize_handle",
+					direction: dir,
+					ids,
+					initial_shape: {
+						kind: "rect",
+						rect: rect_doc
+					}
+				},
+				hit: {
+					kind: "screen_aabb",
+					rect: zone.rect
+				},
+				render: controls_visible ? {
+					kind: "screen_rect",
+					anchor_doc,
+					width: size,
+					height: size,
+					placement: "center",
+					fill: true,
+					stroke: true,
+					fillColor: style.handleFill,
+					strokeColor: style.handleStroke
+				} : void 0,
+				priority: zone.priority,
+				cursor: {
+					kind: "resize",
+					direction: dir
+				}
+			};
+		}
+		case "resize_edge": return {
+			label: zone.label,
+			group,
 			action: {
 				kind: "resize_handle",
-				direction: dir,
+				direction: zone.role.direction,
 				ids,
-				initial_rect: rect_doc
+				initial_shape: {
+					kind: "rect",
+					rect: rect_doc
+				}
 			},
 			hit: {
-				kind: "screen_rect_at_doc",
-				anchor_doc,
-				width: hit_size,
-				height: hit_size,
-				placement: "center"
-			},
-			render: {
-				kind: "screen_rect",
-				anchor_doc,
-				width: size,
-				height: size,
-				placement: "center",
-				fill: true,
-				stroke: true,
-				fillColor: style.handleFill,
-				strokeColor: style.handleStroke
+				kind: "screen_aabb",
+				rect: zone.rect
 			},
+			priority: zone.priority,
 			cursor: {
 				kind: "resize",
-				direction: dir
+				direction: zone.role.direction
 			}
-		});
-	}
-	const edge_strips = edgeStripsScreen(rect_screen, hit_size);
-	for (const dir of EDGE_RESIZE_DIRECTIONS) {
-		const strip = edge_strips[dir];
-		out.push({
+		};
+		case "rotate": return {
+			label: zone.label,
+			group,
 			action: {
-				kind: "resize_handle",
-				direction: dir,
+				kind: "rotate_handle",
+				corner: zone.role.corner,
 				ids,
-				initial_rect: rect_doc
+				initial_shape: {
+					kind: "rect",
+					rect: rect_doc
+				}
 			},
 			hit: {
 				kind: "screen_aabb",
-				rect: strip
+				rect: zone.rect
 			},
+			priority: zone.priority,
 			cursor: {
-				kind: "resize",
-				direction: dir
+				kind: "rotate",
+				corner: zone.role.corner
 			}
-		});
+		};
 	}
-	if (style.showRotationHandles && ids.length === 1) {
-		const rot_size = 16;
-		for (const corner of ROTATION_CORNERS) {
-			const anchor_doc = anchors_doc[corner];
-			const offset_screen = rotationOffsetScreen(corner);
-			const [ax, ay] = docToScreen(transform, anchor_doc[0], anchor_doc[1]);
-			out.push({
-				action: {
-					kind: "rotate_handle",
-					corner,
-					ids,
-					initial_rect: rect_doc
-				},
-				hit: {
-					kind: "screen_aabb",
-					rect: {
-						x: ax + offset_screen[0] - rot_size / 2,
-						y: ay + offset_screen[1] - rot_size / 2,
-						width: rot_size,
-						height: rot_size
+}
+function pushTransformedChrome(local, matrix, ids, camera, style, group, out) {
+	const local_to_screen = cmath.transform.multiply(camera, matrix);
+	const scale_xy = cmath.transform.getScale(local_to_screen);
+	const angle_deg = cmath.transform.angle(local_to_screen);
+	const angle_rad = angle_deg * Math.PI / 180;
+	const screen_w = local.width * scale_xy[0];
+	const screen_h = local.height * scale_xy[1];
+	const local_center = [local.x + local.width / 2, local.y + local.height / 2];
+	const screen_center = cmath.vector2.transform(local_center, local_to_screen);
+	const layout = computeSelectionControlLayout({
+		x: screen_center[0] - screen_w / 2,
+		y: screen_center[1] - screen_h / 2,
+		width: screen_w,
+		height: screen_h
+	}, {
+		handle_size: style.handleSize,
+		show_rotation: style.showRotationHandles && ids.length >= 1
+	});
+	const inverse_transform = cmath.transform.rotate(cmath.transform.identity, -angle_deg, screen_center);
+	const initial_shape = {
+		kind: "transformed",
+		local,
+		matrix
+	};
+	for (const zone of layout.zones) {
+		const hit = {
+			kind: "screen_obb",
+			rect: zone.rect,
+			inverse_transform
+		};
+		switch (zone.role.kind) {
+			case "translate":
+				out.push({
+					label: zone.label,
+					group,
+					action: {
+						kind: "translate_handle",
+						ids
+					},
+					hit,
+					priority: zone.priority,
+					cursor: "move"
+				});
+				break;
+			case "resize_corner": {
+				const dir = zone.role.direction;
+				const size = style.handleSize;
+				const cardinal_local = cmath.rect.getCardinalPoint(local, dir);
+				const anchor_doc = cmath.vector2.transform(cardinal_local, matrix);
+				out.push({
+					label: zone.label,
+					group,
+					action: {
+						kind: "resize_handle",
+						direction: dir,
+						ids,
+						initial_shape
+					},
+					hit,
+					render: layout.controls_visible ? {
+						kind: "screen_rect",
+						anchor_doc,
+						width: size,
+						height: size,
+						placement: "center",
+						fill: true,
+						stroke: true,
+						fillColor: style.handleFill,
+						strokeColor: style.handleStroke,
+						angle: angle_rad
+					} : void 0,
+					priority: zone.priority,
+					cursor: {
+						kind: "resize",
+						direction: dir
 					}
-				},
-				cursor: {
-					kind: "rotate",
-					corner
-				}
-			});
+				});
+				break;
+			}
+			case "resize_edge":
+				out.push({
+					label: zone.label,
+					group,
+					action: {
+						kind: "resize_handle",
+						direction: zone.role.direction,
+						ids,
+						initial_shape
+					},
+					hit,
+					priority: zone.priority,
+					cursor: {
+						kind: "resize",
+						direction: zone.role.direction
+					}
+				});
+				break;
+			case "rotate":
+				out.push({
+					label: zone.label,
+					group,
+					action: {
+						kind: "rotate_handle",
+						corner: zone.role.corner,
+						ids,
+						initial_shape
+					},
+					hit,
+					priority: zone.priority,
+					cursor: {
+						kind: "rotate",
+						corner: zone.role.corner
+					}
+				});
+				break;
 		}
 	}
 }
-function cornerAnchors(r) {
-	return {
-		nw: [r.x, r.y],
-		n: [r.x + r.width / 2, r.y],
-		ne: [r.x + r.width, r.y],
-		e: [r.x + r.width, r.y + r.height / 2],
-		se: [r.x + r.width, r.y + r.height],
-		s: [r.x + r.width / 2, r.y + r.height],
-		sw: [r.x, r.y + r.height],
-		w: [r.x, r.y + r.height / 2]
+function pushLineBody(shape, ids, transform, group, out) {
+	const bounds_doc = shapeBounds(shape);
+	const rect_screen = cmath.rect.transform(bounds_doc, transform);
+	if (rect_screen.width < 1 && rect_screen.height < 1) return;
+	const hitW = Math.max(rect_screen.width, 16);
+	const hitH = Math.max(rect_screen.height, 16);
+	const hitRect = {
+		x: rect_screen.x - (hitW - rect_screen.width) / 2,
+		y: rect_screen.y - (hitH - rect_screen.height) / 2,
+		width: hitW,
+		height: hitH
 	};
-}
-/**
-* Compute the 4 screen-space AABB strips between corner knobs for virtual
-* edge resize regions. Each strip is `thickness` thick, inset from the
-* corners by half the strip thickness so it doesn't overlap corner hits.
-*/
-function edgeStripsScreen(rect_screen, thickness) {
-	const { x, y, width, height } = rect_screen;
-	const inset = thickness / 2;
-	const half = thickness / 2;
-	return {
-		n: {
-			x: x + inset,
-			y: y - half,
-			width: Math.max(0, width - inset * 2),
-			height: thickness
-		},
-		s: {
-			x: x + inset,
-			y: y + height - half,
-			width: Math.max(0, width - inset * 2),
-			height: thickness
+	out.push({
+		label: "translate",
+		group,
+		action: {
+			kind: "translate_handle",
+			ids
 		},
-		e: {
-			x: x + width - half,
-			y: y + inset,
-			width: thickness,
-			height: Math.max(0, height - inset * 2)
+		hit: {
+			kind: "screen_aabb",
+			rect: hitRect
 		},
-		w: {
-			x: x - half,
-			y: y + inset,
-			width: thickness,
-			height: Math.max(0, height - inset * 2)
-		}
-	};
-}
-function rotationOffsetScreen(corner) {
-	switch (corner) {
-		case "nw": return [-12, -12];
-		case "ne": return [12, -12];
-		case "se": return [12, 12];
-		case "sw": return [-12, 12];
-	}
+		priority: HUDHitPriority.TRANSLATE_BODY,
+		cursor: "move"
+	});
 }
-function pushLineEndpoints(id, p1, p2, style, out) {
+function pushLineEndpoints(id, p1, p2, style, group, out) {
 	const size = style.handleSize;
 	const hit_size = Math.max(size + 4, 16);
 	const endpoints = [{
@@ -1565,6 +2143,8 @@ function pushLineEndpoints(id, p1, p2, style, out) {
 		pos: p2
 	}];
 	for (const ep of endpoints) out.push({
+		label: `endpoint:${ep.which}`,
+		group,
 		action: {
 			kind: "endpoint_handle",
 			endpoint: ep.which,
@@ -1590,38 +2170,57 @@ function pushLineEndpoints(id, p1, p2, style, out) {
 			fillColor: style.handleFill,
 			strokeColor: style.handleStroke
 		},
+		priority: HUDHitPriority.ENDPOINT_HANDLE,
 		cursor: "pointer"
 	});
 }
-function pushShapeOutline(shape, rects, lines, opts) {
+function pushShapeOutline(shape, rects, lines, polylines, opts) {
 	if (shape.kind === "rect") rects.push({
 		...shape.rect,
 		stroke: true,
 		fill: false,
 		dashed: opts.dashed,
-		strokeWidth: opts.strokeWidth
+		strokeWidth: opts.strokeWidth,
+		group: opts.group
 	});
-	else if (shape.kind === "line") lines.push({
+	else if (shape.kind === "transformed") {
+		const corners_doc = cmath.rect.toCorners(shape.local).map((p) => cmath.vector2.transform(p, shape.matrix));
+		polylines.push({
+			points: [...corners_doc, corners_doc[0]],
+			stroke: true,
+			fill: false,
+			dashed: opts.dashed,
+			group: opts.group
+		});
+	} else if (shape.kind === "line") lines.push({
 		x1: shape.p1[0],
 		y1: shape.p1[1],
 		x2: shape.p2[0],
 		y2: shape.p2[1],
 		dashed: opts.dashed,
-		strokeWidth: opts.strokeWidth
+		strokeWidth: opts.strokeWidth,
+		group: opts.group
 	});
 }
 /**
 * Fan a list of `OverlayElement`s into per-primitive render arrays and into
 * the hit-region registry. Returns the additional render primitives that
 * should be merged with the decoration `HUDDraw`.
+*
+* Priority and label are forwarded verbatim from each overlay element to
+* the registered HitRegion — the registry resolves overlaps by priority.
 */
 function fanOverlays(overlays, transform, regions) {
 	regions.clear();
 	const screenRects = [];
 	for (const el of overlays) {
+		const projected = projectHit(el.hit, transform);
 		regions.push({
-			rect: projectHitAABB(el.hit, transform),
-			action: el.action
+			rect: projected.rect,
+			inverse_transform: projected.inverse_transform,
+			action: el.action,
+			priority: el.priority,
+			label: el.label
 		});
 		if (!el.render) continue;
 		if (el.render.kind === "screen_rect") screenRects.push({
@@ -1633,13 +2232,19 @@ function fanOverlays(overlays, transform, regions) {
 			fill: el.render.fill,
 			stroke: el.render.stroke,
 			fillColor: el.render.fillColor,
-			strokeColor: el.render.strokeColor
+			strokeColor: el.render.strokeColor,
+			angle: el.render.angle,
+			group: el.group
 		});
 	}
 	return { screenRects };
 }
-function projectHitAABB(hit, transform) {
-	if (hit.kind === "screen_aabb") return hit.rect;
+function projectHit(hit, transform) {
+	if (hit.kind === "screen_aabb") return { rect: hit.rect };
+	if (hit.kind === "screen_obb") return {
+		rect: hit.rect,
+		inverse_transform: hit.inverse_transform
+	};
 	const [sx, sy] = docToScreen(transform, hit.anchor_doc[0], hit.anchor_doc[1]);
 	const placement = hit.placement ?? "center";
 	let x = sx;
@@ -1666,12 +2271,12 @@ function projectHitAABB(hit, transform) {
 			y = sy - hit.height;
 			break;
 	}
-	return {
+	return { rect: {
 		x,
 		y,
 		width: hit.width,
 		height: hit.height
-	};
+	} };
 }
 /**
 * Merge a base `HUDDraw` (chrome decoration) with optional host-fed extras
@@ -1710,11 +2315,25 @@ var Surface = class {
 	constructor(canvas, options) {
 		this.width = 0;
 		this.height = 0;
+		this.cursor_renderer = null;
 		this.opts = options;
 		this.style = mergeStyle(DEFAULT_STYLE, options.style);
-		this.hudCanvas = new HUDCanvas(canvas, { color: options.color ?? this.style.chromeColor });
+		this.colorOverride = options.color;
+		this.hudCanvas = new HUDCanvas(canvas, { color: this.colorOverride ?? this.style.chromeColor });
 		this.state = new SurfaceState();
 		if (options.readonly !== void 0) this.state.setReadonly(options.readonly);
+		if (options.pixelGrid) this.hudCanvas.setPixelGrid(options.pixelGrid);
+	}
+	/** Configure / disable the back-most pixel-grid layer. */
+	setPixelGrid(config) {
+		this.hudCanvas.setPixelGrid(config);
+	}
+	/**
+	* Update just the pixel grid's transform. Cheap to call per camera tick.
+	* No-op when no pixel-grid config is set.
+	*/
+	setPixelGridTransform(transform) {
+		this.hudCanvas.setPixelGridTransform(transform);
 	}
 	setSize(w, h) {
 		this.width = w;
@@ -1740,7 +2359,15 @@ var Surface = class {
 	}
 	setStyle(partial) {
 		this.style = mergeStyle(this.style, partial);
-		this.hudCanvas.setColor(this.style.chromeColor);
+		this.hudCanvas.setColor(this.colorOverride ?? this.style.chromeColor);
+	}
+	/**
+	* Set or clear the host color override. `null` clears the override and
+	* lets `style.chromeColor` win on the next paint.
+	*/
+	setColor(color) {
+		this.colorOverride = color ?? void 0;
+		this.hudCanvas.setColor(this.colorOverride ?? this.style.chromeColor);
 	}
 	setReadonly(v) {
 		this.state.setReadonly(v);
@@ -1777,11 +2404,13 @@ var Surface = class {
 			state: this.state,
 			shapeOf: this.opts.shapeOf,
 			style: this.style,
+			groups: this.opts.groups,
 			width: this.width,
 			height: this.height
 		});
-		const { screenRects } = fanOverlays(overlays, this.state.getTransform(), this.state.hitRegions());
-		this.hudCanvas.draw(mergeDraws(decoration, extra, screenRects));
+		const hidden = this.opts.visibility?.({ gesture: this.state.gesture })?.hidden;
+		const { screenRects } = fanOverlays(filterOverlaysByGroup(overlays, hidden), this.state.getTransform(), this.state.hitRegions());
+		this.hudCanvas.draw(filterHUDDrawByGroup(mergeDraws(decoration, extra, screenRects), { hidden }));
 	}
 	/** Convenience: clear the canvas (e.g. when the host stops the surface). */
 	clear() {
@@ -1800,9 +2429,43 @@ var Surface = class {
 	cursor() {
 		return this.state.cursor;
 	}
+	/**
+	* Resolve the current cursor to a CSS `cursor:` value. Runs the
+	* installed renderer (or the built-in `cursorToCss` if none installed).
+	*
+	* Host wires it like:
+	*
+	*     const r = surface.dispatch(event);
+	*     if (r.cursorChanged) el.style.cursor = surface.cursorCss();
+	*
+	* Saves the host from re-importing `cursorToCss` after every dispatch
+	* and gives one place to change behavior when a renderer is swapped in.
+	*/
+	cursorCss() {
+		return (this.cursor_renderer ?? cursorToCss)(this.state.cursor);
+	}
+	/**
+	* Install (or clear) a custom cursor renderer.
+	*
+	* `null` restores the built-in `cursorToCss` behavior (native CSS
+	* keywords for every variant). Pass `cursors.defaultRenderer()` from
+	* `@grida/hud/cursors` for the bundled SVG cursor set.
+	*
+	* Re-callable mid-session; the next `cursorCss()` reads the new value.
+	*/
+	setCursorRenderer(fn) {
+		this.cursor_renderer = fn;
+	}
 	modifiers() {
 		return this.state.modifiers;
 	}
 };
+function filterOverlaysByGroup(overlays, hidden) {
+	const hidden_set = new Set(hidden ?? []);
+	if (hidden_set.size === 0) return overlays;
+	return overlays.filter((overlay) => {
+		return !overlay.group || !hidden_set.has(overlay.group);
+	});
+}
 //#endregion
-export { lassoToHUDDraw as a, snapGuideToHUDDraw as c, NO_MODS as i, HUDCanvas as l, MIN_CHROME_VISIBLE_SIZE as n, marqueeToHUDDraw as o, MIN_HIT_SIZE as r, measurementToHUDDraw as s, Surface as t };
+export { DEFAULT_PIXEL_GRID_STEPS as _, computeSelectionControlLayout as a, MIN_HIT_SIZE as c, marqueeToHUDDraw as d, measurementToHUDDraw as f, DEFAULT_PIXEL_GRID_COLOR as g, HUDCanvas as h, MIN_GUARANTEED_INTERACTIVE_DIM as i, NO_MODS as l, filterHUDDrawByGroup as m, BODY_FLIP_THRESHOLD as n, negotiateAxis as o, snapGuideToHUDDraw as p, HUDHitPriority as r, MIN_CHROME_VISIBLE_SIZE as s, Surface as t, lassoToHUDDraw as u, drawPixelGrid as v };