@grida/hud 0.1.0 → 0.2.1

package/dist/core/index.mjs

@@ -0,0 +1,291 @@
+//#region core/event.ts
+const NO_MODS = {
+	shift: false,
+	alt: false,
+	meta: false,
+	ctrl: false
+};
+//#endregion
+//#region core/click-tracker.ts
+var ClickTracker = class {
+	constructor(opts = {}) {
+		this.last_time = 0;
+		this.last_x = 0;
+		this.last_y = 0;
+		this.count = 0;
+		this.window_ms = opts.windowMs ?? 250;
+		this.distance_px = opts.distancePx ?? 5;
+	}
+	/**
+	* Register a click at `(x, y)` and return the current consecutive-
+	* click count (1 = single, 2 = double, etc.). `now` is in ms.
+	*/
+	register(x, y, now = nowMs()) {
+		const dt = now - this.last_time;
+		const dx = x - this.last_x;
+		const dy = y - this.last_y;
+		const dist2 = dx * dx + dy * dy;
+		const max2 = this.distance_px * this.distance_px;
+		if (dt <= this.window_ms && dist2 <= max2 && this.count > 0) this.count += 1;
+		else this.count = 1;
+		this.last_time = now;
+		this.last_x = x;
+		this.last_y = y;
+		return this.count;
+	}
+	reset() {
+		this.count = 0;
+		this.last_time = 0;
+	}
+};
+function nowMs() {
+	if (typeof performance !== "undefined" && performance.now) return performance.now();
+	return Date.now();
+}
+//#endregion
+//#region core/transform.ts
+const IDENTITY = [[
+	1,
+	0,
+	0
+], [
+	0,
+	1,
+	0
+]];
+/** Project a screen-space point into document-space. */
+function screenToDoc(t, x, y) {
+	const [[sx, , tx], [, sy, ty]] = t;
+	return [(x - tx) / (sx || 1), (y - ty) / (sy || 1)];
+}
+/** Project a document-space point into screen-space. */
+function docToScreen(t, x, y) {
+	const [[sx, , tx], [, sy, ty]] = t;
+	return [sx * x + tx, sy * y + ty];
+}
+/** Current uniform zoom. Reads `sx`. */
+function zoomOf(t) {
+	return t[0][0];
+}
+//#endregion
+//#region core/registry.ts
+/**
+* Thrown by `register` when an entity with the same `name` is already
+* registered. Consumers should `unregister` the existing one first.
+*/
+var RegistrationError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "RegistrationError";
+	}
+};
+/**
+* Generic name-keyed registry.
+*
+* @typeParam K — key type, must extend `string`.
+* @typeParam T — entity type. Must expose `readonly name: K` and an
+*               optional `detach()` method.
+*/
+var NamedRegistry = class {
+	constructor(label) {
+		this.label = label;
+		this.byName = /* @__PURE__ */ new Map();
+		this.order = [];
+	}
+	register(e) {
+		if (this.byName.has(e.name)) throw new RegistrationError(`${this.label} "${e.name}" already registered; unregister it first.`);
+		this.byName.set(e.name, e);
+		this.order.push(e);
+	}
+	unregister(e) {
+		if (this.byName.get(e.name) !== e) return;
+		this.byName.delete(e.name);
+		const i = this.order.indexOf(e);
+		if (i >= 0) this.order.splice(i, 1);
+		try {
+			e.detach?.();
+		} catch (err) {
+			console.error(`[hud] ${this.label} "${e.name}" detach() threw:`, err);
+		}
+	}
+	has(name) {
+		return this.byName.has(name);
+	}
+	get(name) {
+		return this.byName.get(name);
+	}
+	*entries() {
+		for (const e of this.order) yield e;
+	}
+	size() {
+		return this.order.length;
+	}
+	clear() {
+		for (let i = this.order.length - 1; i >= 0; i--) {
+			const e = this.order[i];
+			try {
+				e.detach?.();
+			} catch (err) {
+				console.error(`[hud] ${this.label} "${e.name}" detach() threw:`, err);
+			}
+		}
+		this.order = [];
+		this.byName.clear();
+	}
+};
+//#endregion
+//#region core/hit-registry.ts
+/**
+* Generic hit registry. One per frame (or persistent — bedrock is
+* agnostic). Add objects with `add`, clear with `clear`, query with
+* `queryPoint` / `queryAll`.
+*/
+var HitRegistry = class {
+	constructor() {
+		this.items = [];
+	}
+	/**
+	* Add an object. Objects without `hit` are accepted (they may carry
+	* paint information the consumer still wants in the registry for
+	* uniform iteration) but are filtered from point queries.
+	*/
+	add(obj) {
+		this.items.push(obj);
+	}
+	/** Drop all entries. */
+	clear() {
+		this.items = [];
+	}
+	/** Total number of stored objects (paint-only + hit-testable). */
+	size() {
+		return this.items.length;
+	}
+	/** Iterate every stored object in insertion order. */
+	*entries() {
+		for (const o of this.items) yield o;
+	}
+	/**
+	* Return the hit-testable object whose hit shape contains the
+	* given screen-space point with the lowest `priority` value
+	* (lower wins). Paint-only objects (no `hit`) are skipped.
+	*/
+	queryPoint(point_screen, transform) {
+		let best = null;
+		let best_priority = Number.POSITIVE_INFINITY;
+		for (const obj of this.items) {
+			if (!obj.hit) continue;
+			if (obj.priority > best_priority) continue;
+			if (!shapeContains(obj.hit, point_screen, transform)) continue;
+			if (obj.refine && !obj.refine(point_screen)) continue;
+			best = obj;
+			best_priority = obj.priority;
+		}
+		return best;
+	}
+	/**
+	* Return all hit-testable objects whose hit shape contains the point,
+	* winner first. Ordering is identical to `queryPoint`'s arbitration:
+	* priority ascending (lower wins), and on EQUAL priority the
+	* later-added object comes first ("later push wins on tie"). This makes
+	* `queryAll(p)[0]` always equal `queryPoint(p)` — the two query paths
+	* never disagree on the winner.
+	*/
+	queryAll(point_screen, transform) {
+		const matches = [];
+		for (let i = 0; i < this.items.length; i++) {
+			const obj = this.items[i];
+			if (!obj.hit) continue;
+			if (!shapeContains(obj.hit, point_screen, transform)) continue;
+			if (obj.refine && !obj.refine(point_screen)) continue;
+			matches.push({
+				obj,
+				i
+			});
+		}
+		matches.sort((a, b) => a.obj.priority - b.obj.priority || b.i - a.i);
+		return matches.map((m) => m.obj);
+	}
+};
+/**
+* Test whether a screen-space point lies inside a `HitShape`.
+*
+* The camera `transform` is needed for doc-anchored shapes
+* (`screen_rect_at_doc`, `screen_circle_at_doc`); pre-projected
+* shapes (`screen_aabb`, `screen_polygon`) ignore it. `screen_obb`
+* applies its own `inverse_transform`, which maps screen → shadow
+* (independent of the camera).
+*/
+function shapeContains(shape, point_screen, transform) {
+	const [px, py] = point_screen;
+	switch (shape.kind) {
+		case "screen_rect_at_doc": {
+			const [ax, ay] = docToScreen(transform, shape.anchor_doc[0], shape.anchor_doc[1]);
+			const { x, y } = anchorOrigin(ax, ay, shape.width, shape.height, shape.placement ?? "center");
+			return px >= x && px <= x + shape.width && py >= y && py <= y + shape.height;
+		}
+		case "screen_aabb": {
+			const r = shape.rect;
+			return px >= r.x && px <= r.x + r.width && py >= r.y && py <= r.y + r.height;
+		}
+		case "screen_obb": {
+			const [[a, b, e], [c, d, f]] = shape.inverse_transform;
+			const sx = a * px + b * py + e;
+			const sy = c * px + d * py + f;
+			const r = shape.rect;
+			return sx >= r.x && sx <= r.x + r.width && sy >= r.y && sy <= r.y + r.height;
+		}
+		case "screen_circle_at_doc": {
+			const [ax, ay] = docToScreen(transform, shape.anchor_doc[0], shape.anchor_doc[1]);
+			const dx = px - ax;
+			const dy = py - ay;
+			return dx * dx + dy * dy <= shape.radius * shape.radius;
+		}
+		case "screen_polygon": return pointInPolygon(point_screen, shape.points);
+	}
+}
+function anchorOrigin(ax, ay, w, h, placement) {
+	switch (placement) {
+		case "center": return {
+			x: ax - w / 2,
+			y: ay - h / 2
+		};
+		case "tl": return {
+			x: ax,
+			y: ay
+		};
+		case "tr": return {
+			x: ax - w,
+			y: ay
+		};
+		case "bl": return {
+			x: ax,
+			y: ay - h
+		};
+		case "br": return {
+			x: ax - w,
+			y: ay - h
+		};
+	}
+}
+/**
+* Standard even-odd ray-cast point-in-polygon.
+*
+* Horizontal edges (`yi === yj`) are skipped — the standard idiom for
+* the even-odd algorithm. (The previous form used `(yj - yi ||
+* Number.EPSILON)` as a divide-by-zero guard, but the guard was dead
+* code: the `yi > py !== yj > py` clause already short-circuits to
+* `false` when the edge is horizontal, so the division never runs.)
+*/
+function pointInPolygon(point, poly) {
+	const [px, py] = point;
+	let inside = false;
+	for (let i = 0, j = poly.length - 1; i < poly.length; j = i++) {
+		const [xi, yi] = poly[i];
+		const [xj, yj] = poly[j];
+		if (yi === yj) continue;
+		if (yi > py !== yj > py && px < (xj - xi) * (py - yi) / (yj - yi) + xi) inside = !inside;
+	}
+	return inside;
+}
+//#endregion
+export { ClickTracker, HitRegistry, IDENTITY, NO_MODS, NamedRegistry, RegistrationError, docToScreen, screenToDoc, shapeContains, zoomOf };

package/dist/cursor-CxS8EMvm.d.mts

@@ -0,0 +1,64 @@
+//#region event/cursor.d.ts
+/** 8 cardinal/diagonal resize directions. */
+type ResizeDirection = "n" | "ne" | "e" | "se" | "s" | "sw" | "w" | "nw";
+/** 4 corner positions for rotation handles. */
+type RotationCorner = "nw" | "ne" | "se" | "sw";
+/**
+ * Logical cursor icon names — the host maps these to CSS `cursor` values.
+ *
+ * `baseAngle` (radians) tilts the rendered arrow by an additional amount
+ * on top of the variant's canonical orientation. Set automatically by the
+ * surface for both variants:
+ *
+ * - **rotate**: `decideIdleCursor` reads the action's `initial_shape`
+ *   and sets `baseAngle` to the matrix's screen-space rotation; the
+ *   in-gesture `pointer_move` arm composes `initial_cursor_angle + delta`
+ *   so the cursor tracks the live rotation, starting from the selection's
+ *   pre-gesture orientation rather than 0.
+ * - **resize**: `decideIdleCursor` reads the action's `initial_shape`
+ *   and sets `baseAngle` to the matrix's screen-space rotation, so the
+ *   resize cursor on a rotated selection tilts to align with the rotated
+ *   edge / corner.
+ *
+ * For `kind: "rect"` selections (the common case) `baseAngle` resolves
+ * to 0 and the cursor behaves identically to the pre-rotation builds.
+ */
+type CursorIcon = "default" | "pointer" | "move" | "crosshair" | "grab" | "grabbing" | "text" | {
+  kind: "resize";
+  direction: ResizeDirection;
+  baseAngle?: number;
+} | {
+  kind: "rotate";
+  corner: RotationCorner;
+  baseAngle?: number;
+};
+/**
+ * Pluggable cursor renderer.
+ *
+ * Maps a logical `CursorIcon` to a complete CSS `cursor:` value
+ * (e.g. a native keyword like `"crosshair"` or a data-URL form like
+ * `"url(data:...) 12 12, auto"`).
+ *
+ * The Surface owns one slot. Default = the built-in `cursorToCss` below.
+ * Hosts opt into the bundled SVG renderer via
+ * `surface.setCursorRenderer(cursors.defaultRenderer())` from
+ * `@grida/hud/cursors`, or supply their own function for full control.
+ */
+type CursorRenderer = (icon: CursorIcon) => string;
+/**
+ * Map a `CursorIcon` to the standard CSS `cursor` value. Hosts can override
+ * for custom cursors.
+ */
+declare function cursorToCss(c: CursorIcon): string;
+/**
+ * Cursor-equality used to detect changes without re-emitting `cursorChanged`.
+ *
+ * Two rotate/resize icons compare equal only when both the
+ * discriminator (corner / direction) AND the bucketed `baseAngle` match.
+ * This is what lets the state machine call `setCursor` every frame
+ * during a rotate gesture and have `cursorChanged` fire only on real
+ * angle changes (≥ `CURSOR_ANGLE_BUCKET_RAD` of motion).
+ */
+declare function cursorEquals(a: CursorIcon, b: CursorIcon): boolean;
+//#endregion
+export { cursorEquals as a, RotationCorner as i, CursorRenderer as n, cursorToCss as o, ResizeDirection as r, CursorIcon as t };

package/dist/cursor-CxS8EMvm.d.ts

@@ -0,0 +1,64 @@
+//#region event/cursor.d.ts
+/** 8 cardinal/diagonal resize directions. */
+type ResizeDirection = "n" | "ne" | "e" | "se" | "s" | "sw" | "w" | "nw";
+/** 4 corner positions for rotation handles. */
+type RotationCorner = "nw" | "ne" | "se" | "sw";
+/**
+ * Logical cursor icon names — the host maps these to CSS `cursor` values.
+ *
+ * `baseAngle` (radians) tilts the rendered arrow by an additional amount
+ * on top of the variant's canonical orientation. Set automatically by the
+ * surface for both variants:
+ *
+ * - **rotate**: `decideIdleCursor` reads the action's `initial_shape`
+ *   and sets `baseAngle` to the matrix's screen-space rotation; the
+ *   in-gesture `pointer_move` arm composes `initial_cursor_angle + delta`
+ *   so the cursor tracks the live rotation, starting from the selection's
+ *   pre-gesture orientation rather than 0.
+ * - **resize**: `decideIdleCursor` reads the action's `initial_shape`
+ *   and sets `baseAngle` to the matrix's screen-space rotation, so the
+ *   resize cursor on a rotated selection tilts to align with the rotated
+ *   edge / corner.
+ *
+ * For `kind: "rect"` selections (the common case) `baseAngle` resolves
+ * to 0 and the cursor behaves identically to the pre-rotation builds.
+ */
+type CursorIcon = "default" | "pointer" | "move" | "crosshair" | "grab" | "grabbing" | "text" | {
+  kind: "resize";
+  direction: ResizeDirection;
+  baseAngle?: number;
+} | {
+  kind: "rotate";
+  corner: RotationCorner;
+  baseAngle?: number;
+};
+/**
+ * Pluggable cursor renderer.
+ *
+ * Maps a logical `CursorIcon` to a complete CSS `cursor:` value
+ * (e.g. a native keyword like `"crosshair"` or a data-URL form like
+ * `"url(data:...) 12 12, auto"`).
+ *
+ * The Surface owns one slot. Default = the built-in `cursorToCss` below.
+ * Hosts opt into the bundled SVG renderer via
+ * `surface.setCursorRenderer(cursors.defaultRenderer())` from
+ * `@grida/hud/cursors`, or supply their own function for full control.
+ */
+type CursorRenderer = (icon: CursorIcon) => string;
+/**
+ * Map a `CursorIcon` to the standard CSS `cursor` value. Hosts can override
+ * for custom cursors.
+ */
+declare function cursorToCss(c: CursorIcon): string;
+/**
+ * Cursor-equality used to detect changes without re-emitting `cursorChanged`.
+ *
+ * Two rotate/resize icons compare equal only when both the
+ * discriminator (corner / direction) AND the bucketed `baseAngle` match.
+ * This is what lets the state machine call `setCursor` every frame
+ * during a rotate gesture and have `cursorChanged` fire only on real
+ * angle changes (≥ `CURSOR_ANGLE_BUCKET_RAD` of motion).
+ */
+declare function cursorEquals(a: CursorIcon, b: CursorIcon): boolean;
+//#endregion
+export { cursorEquals as a, RotationCorner as i, CursorRenderer as n, cursorToCss as o, ResizeDirection as r, CursorIcon as t };

package/dist/cursor-DW-uAPVE.mjs

@@ -0,0 +1,57 @@
+//#region event/cursor.ts
+/**
+* Angle-comparison bucket — radians. 0.5° in radians. Two icons are
+* considered equal when their `baseAngle`s round to the same bucket;
+* this is what prevents unnecessary `cursorChanged` re-emit during a
+* smooth rotate gesture, so the host repaints only on real motion.
+*
+* 0.5° is below human perception for cursor orientation, so the
+* quantization is visually free.
+*/
+const CURSOR_ANGLE_BUCKET_RAD = Math.PI / 360;
+/**
+* Quantize an angle (radians) to its `CURSOR_ANGLE_BUCKET_RAD` bucket.
+* Used by `cursorEquals` to decide whether two cursors with the same
+* variant differ visibly.
+*/
+function angleBucket(rad) {
+	if (rad === void 0 || rad === 0) return 0;
+	return Math.round(rad / CURSOR_ANGLE_BUCKET_RAD);
+}
+/**
+* Map a `CursorIcon` to the standard CSS `cursor` value. Hosts can override
+* for custom cursors.
+*/
+function cursorToCss(c) {
+	if (typeof c === "string") switch (c) {
+		case "default": return "default";
+		case "pointer": return "pointer";
+		case "move": return "move";
+		case "crosshair": return "crosshair";
+		case "grab": return "grab";
+		case "grabbing": return "grabbing";
+		case "text": return "text";
+	}
+	if (c.kind === "resize") return `${c.direction}-resize`;
+	return "crosshair";
+}
+/**
+* Cursor-equality used to detect changes without re-emitting `cursorChanged`.
+*
+* Two rotate/resize icons compare equal only when both the
+* discriminator (corner / direction) AND the bucketed `baseAngle` match.
+* This is what lets the state machine call `setCursor` every frame
+* during a rotate gesture and have `cursorChanged` fire only on real
+* angle changes (≥ `CURSOR_ANGLE_BUCKET_RAD` of motion).
+*/
+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 && angleBucket(a.baseAngle) === angleBucket(b.baseAngle);
+		if (a.kind === "rotate" && b.kind === "rotate") return a.corner === b.corner && angleBucket(a.baseAngle) === angleBucket(b.baseAngle);
+		return false;
+	}
+	return false;
+}
+//#endregion
+export { cursorToCss as i, angleBucket as n, cursorEquals as r, CURSOR_ANGLE_BUCKET_RAD as t };

package/dist/cursor-FGiJBdU-.js

@@ -0,0 +1,80 @@
+//#region event/cursor.ts
+/**
+* Angle-comparison bucket — radians. 0.5° in radians. Two icons are
+* considered equal when their `baseAngle`s round to the same bucket;
+* this is what prevents unnecessary `cursorChanged` re-emit during a
+* smooth rotate gesture, so the host repaints only on real motion.
+*
+* 0.5° is below human perception for cursor orientation, so the
+* quantization is visually free.
+*/
+const CURSOR_ANGLE_BUCKET_RAD = Math.PI / 360;
+/**
+* Quantize an angle (radians) to its `CURSOR_ANGLE_BUCKET_RAD` bucket.
+* Used by `cursorEquals` to decide whether two cursors with the same
+* variant differ visibly.
+*/
+function angleBucket(rad) {
+	if (rad === void 0 || rad === 0) return 0;
+	return Math.round(rad / CURSOR_ANGLE_BUCKET_RAD);
+}
+/**
+* Map a `CursorIcon` to the standard CSS `cursor` value. Hosts can override
+* for custom cursors.
+*/
+function cursorToCss(c) {
+	if (typeof c === "string") switch (c) {
+		case "default": return "default";
+		case "pointer": return "pointer";
+		case "move": return "move";
+		case "crosshair": return "crosshair";
+		case "grab": return "grab";
+		case "grabbing": return "grabbing";
+		case "text": return "text";
+	}
+	if (c.kind === "resize") return `${c.direction}-resize`;
+	return "crosshair";
+}
+/**
+* Cursor-equality used to detect changes without re-emitting `cursorChanged`.
+*
+* Two rotate/resize icons compare equal only when both the
+* discriminator (corner / direction) AND the bucketed `baseAngle` match.
+* This is what lets the state machine call `setCursor` every frame
+* during a rotate gesture and have `cursorChanged` fire only on real
+* angle changes (≥ `CURSOR_ANGLE_BUCKET_RAD` of motion).
+*/
+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 && angleBucket(a.baseAngle) === angleBucket(b.baseAngle);
+		if (a.kind === "rotate" && b.kind === "rotate") return a.corner === b.corner && angleBucket(a.baseAngle) === angleBucket(b.baseAngle);
+		return false;
+	}
+	return false;
+}
+//#endregion
+Object.defineProperty(exports, "CURSOR_ANGLE_BUCKET_RAD", {
+	enumerable: true,
+	get: function() {
+		return CURSOR_ANGLE_BUCKET_RAD;
+	}
+});
+Object.defineProperty(exports, "angleBucket", {
+	enumerable: true,
+	get: function() {
+		return angleBucket;
+	}
+});
+Object.defineProperty(exports, "cursorEquals", {
+	enumerable: true,
+	get: function() {
+		return cursorEquals;
+	}
+});
+Object.defineProperty(exports, "cursorToCss", {
+	enumerable: true,
+	get: function() {
+		return cursorToCss;
+	}
+});

package/dist/cursors/index.d.mts

@@ -0,0 +1,98 @@
+import { n as CursorRenderer } from "../cursor-CxS8EMvm.mjs";
+
+//#region cursors/renderer.d.ts
+/**
+ * Build the default cursor renderer.
+ *
+ * Stateless — every call regenerates the data URL from scratch. This is
+ * cheap (`template_*` is a string-concat, `btoa` of ~600 B is
+ * sub-millisecond) AND the upstream `SurfaceState.setCursor` already
+ * gates re-emit via `cursorEquals`, which buckets `baseAngle` to
+ * `CURSOR_ANGLE_BUCKET_RAD`. Net result: this function is invoked at
+ * most once per real bucket change — caching here would be redundant
+ * and, sized wrong (the previous 64-entry LRU thrashed after ~32° of
+ * drag), actively harmful.
+ *
+ * Hosts install via `surface.setCursorRenderer(...)`.
+ *
+ * @example
+ *   import { cursors } from "@grida/hud/cursors";
+ *   surface.setCursorRenderer(cursors.defaultRenderer());
+ */
+declare function defaultRenderer(): CursorRenderer;
+//#endregion
+//#region cursors/encode.d.ts
+/**
+ * SVG → `data:` URL encoding for CSS `cursor:` values.
+ *
+ * Uses base64 (`btoa`) for two reasons:
+ * - Cross-browser support is universal; URL-encoded SVG has historically had
+ *   parser inconsistencies on `#` and `<`.
+ * - It's what the main editor's `cursor-data.ts` uses, so cursor visuals
+ *   compare byte-identical when we A/B during the eventual migration.
+ *
+ * Browser-only — `btoa` is part of the WHATWG HTML spec, available on
+ * Worker / Window. The package's `platform: "neutral"` tsdown config means
+ * we don't pull a Node polyfill; consumers using SSR must avoid evaluating
+ * the renderer on the server (the Surface itself is client-side).
+ */
+/** Encode an SVG string as `data:image/svg+xml;base64,...`. */
+declare function svgDataUrl(svg: string): string;
+//#endregion
+//#region cursors/templates.d.ts
+/**
+ * SVG cursor templates — pure string templates parameterized by angle.
+ *
+ * Two families:
+ *
+ * 1. **Rotate arrow** — a curved double-arrow. Built from one template
+ *    (`template_rotate`) rotated by `angle_deg` around the SVG's
+ *    hotspot. Per-corner orientation comes from caller-supplied
+ *    initial offsets (NW: −45°, NE: +45°, SW: −135°, SE: +135°), in
+ *    Phase A. In Phase B, the host's selection rotation is added on
+ *    top of that.
+ *
+ * 2. **Resize arrow** — a straight double-arrow, also built from one
+ *    template (`template_resize`) rotated per cardinal direction. The
+ *    8 standard directions (N/NE/E/SE/S/SW/W/NW) map to multiples of
+ *    45° from the canonical horizontal arrow.
+ *
+ * **Fixed Grida palette** — black fill, white stroke. Cursors are not
+ * color-themed; hosts wanting custom colors install a custom
+ * `CursorRenderer` (see `renderer.ts`).
+ *
+ * **Hotspots** are documented per template — the click point inside
+ * the SVG that the OS aligns with the actual pointer position. Hotspots
+ * are fixed (SVG center) because the SVG rotates around the same point;
+ * the cursor stays anchored to the pointer regardless of angle.
+ */
+/** Rotate cursor SVG. `angle_deg` rotates the arrow around (13, 12). */
+declare function template_rotate(angle_deg: number): string;
+/**
+ * Resize cursor SVG. `angle_deg` rotates the arrow around (16, 16).
+ *
+ * For the canonical horizontal arrow pass `0`. For the 8 standard
+ * cardinal directions, see `DIRECTION_ANGLE_DEG` in `renderer.ts`.
+ */
+declare function template_resize(angle_deg: number): string;
+//#endregion
+//#region cursors/index.d.ts
+/**
+ * Convenience namespace export. All cursor utilities are also available
+ * as named imports — but `cursors.defaultRenderer()` reads more cleanly
+ * at host call sites, mirroring the main editor's `cursors.*` style.
+ */
+declare const cursors: {
+  readonly defaultRenderer: typeof defaultRenderer;
+  readonly svgDataUrl: typeof svgDataUrl;
+  readonly templates: {
+    readonly rotate: typeof template_rotate;
+    readonly resize: typeof template_resize;
+  };
+  readonly hotspots: {
+    readonly rotate: readonly [number, number];
+    readonly resize: readonly [number, number];
+  };
+};
+//#endregion
+export { type CursorRenderer, cursors, defaultRenderer, svgDataUrl };