@grida/hud 0.1.0 → 0.2.1

package/dist/cursors/index.d.ts

@@ -0,0 +1,98 @@
+import { n as CursorRenderer } from "../cursor-CxS8EMvm.js";
+
+//#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 };

package/dist/cursors/index.js

@@ -0,0 +1,188 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_cursor = require("../cursor-FGiJBdU-.js");
+//#region cursors/encode.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,...`. */
+function svgDataUrl(svg) {
+	return `data:image/svg+xml;base64,${btoa(svg)}`;
+}
+//#endregion
+//#region cursors/templates.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). */
+function template_rotate(angle_deg) {
+	return `<svg xmlns="http://www.w3.org/2000/svg" width="26" height="24" fill="none"><g filter="url(#a)" transform="rotate(${angle_deg}, 13, 12), scale(0.75)"><path fill="#000" fill-rule="evenodd" d="M23 15.5h-6.43l2.65-2.79A7.72 7.72 0 0 0 13 9.5a7.72 7.72 0 0 0-6.22 3.21l2.65 2.79H3V8.75l1.74 1.83A10.5 10.5 0 0 1 13 6.5c3.32 0 6.3 1.59 8.26 4.08L23 8.75v6.75Z" clip-rule="evenodd"/><path stroke="#fff" stroke-width=".75" d="M23 15.88h.38V7.8l-.65.68-1.45 1.52A10.85 10.85 0 0 0 13 6.13c-3.3 0-6.25 1.5-8.28 3.88L3.27 8.5l-.64-.68v8.07h7.67l-.6-.64-2.43-2.55A7.32 7.32 0 0 1 13 9.88c2.3 0 4.36 1.08 5.73 2.8l-2.43 2.56-.6.63H23Z"/></g><defs><filter id="a" width="25.1" height="14.1" x=".45" y="4.95" color-interpolation-filters="sRGB" filterUnits="userSpaceOnUse"><feFlood flood-opacity="0" result="BackgroundImageFix"/><feColorMatrix in="SourceAlpha" result="hardAlpha" values="0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 127 0"/><feOffset dy="1"/><feGaussianBlur stdDeviation=".9"/><feComposite in2="hardAlpha" operator="out"/><feColorMatrix values="0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0.65 0"/><feBlend in2="BackgroundImageFix" result="effect1_dropShadow_443_204"/><feBlend in="SourceGraphic" in2="effect1_dropShadow_443_204" result="shape"/></filter></defs></svg>`;
+}
+/** Hotspot for `template_rotate` — CSS-px offset from SVG top-left. */
+const ROTATE_HOTSPOT = [12, 12];
+/**
+* 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`.
+*/
+function template_resize(angle_deg) {
+	return `<svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" fill="none"><g filter="url(#b)" transform="rotate(${angle_deg}, 16, 16)"><path fill="#000" stroke="#fff" stroke-width="1" stroke-linejoin="round" d="M7 16 L11 12 L11 14.5 L21 14.5 L21 12 L25 16 L21 20 L21 17.5 L11 17.5 L11 20 Z"/></g><defs><filter id="b" width="22" height="13" x="5" y="10" color-interpolation-filters="sRGB" filterUnits="userSpaceOnUse"><feFlood flood-opacity="0" result="BackgroundImageFix"/><feColorMatrix in="SourceAlpha" result="hardAlpha" values="0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 127 0"/><feOffset dy="1"/><feGaussianBlur stdDeviation=".8"/><feComposite in2="hardAlpha" operator="out"/><feColorMatrix values="0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0.55 0"/><feBlend in2="BackgroundImageFix" result="effect1_dropShadow_resize"/><feBlend in="SourceGraphic" in2="effect1_dropShadow_resize" result="shape"/></filter></defs></svg>`;
+}
+/** Hotspot for `template_resize` — CSS-px offset from SVG top-left. */
+const RESIZE_HOTSPOT = [16, 16];
+//#endregion
+//#region cursors/renderer.ts
+/**
+* Default cursor renderer — maps `CursorIcon` → CSS `cursor:` value.
+*
+* Two responsibilities:
+*
+* 1. **Static-keyword passthrough** for cursors that don't need angle
+*    info (text, grab, crosshair, etc.) — defer to the canonical
+*    `cursorToCss` mapping shipped from `event/cursor.ts` so the
+*    fallback keyword stays the single source of truth.
+*
+* 2. **SVG generation** for rotation-sensitive cursors (rotate +
+*    8 resize directions). Each cardinal direction maps to a fixed
+*    base angle; when the icon carries a `baseAngle` (radians), it
+*    composes with the base. The renderer is stateless — the upstream
+*    `SurfaceState.setCursor` already gates re-emit at the
+*    `CURSOR_ANGLE_BUCKET_RAD` level via `cursorEquals`, so this
+*    function is invoked at most once per real change.
+*
+* Output shape per icon:
+*
+*     "url(data:image/svg+xml;base64,...) HOTSPOT_X HOTSPOT_Y, FALLBACK_KEYWORD"
+*
+* `FALLBACK_KEYWORD` is what `cursorToCss` would have returned. This
+* means a browser that fails to load the data URL (truly impossible for
+* inline base64, but the spec requires a fallback) lands on the
+* existing native cursor — never on `auto`.
+*/
+const RESIZE_BASE_ANGLE_DEG = {
+	e: 0,
+	w: 0,
+	n: 90,
+	s: 90,
+	ne: -45,
+	sw: -45,
+	nw: 45,
+	se: 45
+};
+const ROTATE_BASE_ANGLE_DEG = {
+	nw: -45,
+	ne: 45,
+	se: 135,
+	sw: -135
+};
+const RAD_TO_DEG = 180 / Math.PI;
+/**
+* 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());
+*/
+function defaultRenderer() {
+	return function render(icon) {
+		if (typeof icon === "string") return require_cursor.cursorToCss(icon);
+		if (icon.kind === "rotate") return build_rotate_css(icon.corner, bucket_to_deg(require_cursor.angleBucket(icon.baseAngle)));
+		return build_resize_css(icon.direction, bucket_to_deg(require_cursor.angleBucket(icon.baseAngle)));
+	};
+}
+function bucket_to_deg(bucket) {
+	return bucket * require_cursor.CURSOR_ANGLE_BUCKET_RAD * RAD_TO_DEG;
+}
+function build_cursor_css(template, hotspot, fallback, base_deg, extra_deg) {
+	return `url(${svgDataUrl(template(base_deg + extra_deg))}) ${hotspot[0]} ${hotspot[1]}, ${fallback}`;
+}
+function build_rotate_css(corner, extra_angle_deg) {
+	return build_cursor_css(template_rotate, ROTATE_HOTSPOT, "crosshair", ROTATE_BASE_ANGLE_DEG[corner], extra_angle_deg);
+}
+function build_resize_css(direction, extra_angle_deg) {
+	return build_cursor_css(template_resize, RESIZE_HOTSPOT, `${direction}-resize`, RESIZE_BASE_ANGLE_DEG[direction], extra_angle_deg);
+}
+//#endregion
+//#region cursors/index.ts
+/**
+* `@grida/hud/cursors` — opt-in default cursor renderer.
+*
+* Hosts wire it once at construction:
+*
+*     import { cursors } from "@grida/hud/cursors";
+*     surface.setCursorRenderer(cursors.defaultRenderer());
+*
+* Tree-shake invariant: nothing in `surface/`, `event/`, or
+* `primitives/` may import from this directory. Hosts that don't import
+* the subpath pay zero bundle cost. See `__tests__/cursors.test.ts` for
+* the import-graph assertion that enforces this.
+*
+* Templates and the encoder are re-exported for hosts that want to
+* render cursor previews in sidebar UI without going through the Surface.
+*/
+/**
+* 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.
+*/
+const cursors = {
+	defaultRenderer,
+	svgDataUrl,
+	templates: {
+		rotate: template_rotate,
+		resize: template_resize
+	},
+	hotspots: {
+		rotate: ROTATE_HOTSPOT,
+		resize: RESIZE_HOTSPOT
+	}
+};
+//#endregion
+exports.cursors = cursors;
+exports.defaultRenderer = defaultRenderer;
+exports.svgDataUrl = svgDataUrl;

package/dist/cursors/index.mjs

@@ -0,0 +1,185 @@
+import { i as cursorToCss, n as angleBucket, t as CURSOR_ANGLE_BUCKET_RAD } from "../cursor-DW-uAPVE.mjs";
+//#region cursors/encode.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,...`. */
+function svgDataUrl(svg) {
+	return `data:image/svg+xml;base64,${btoa(svg)}`;
+}
+//#endregion
+//#region cursors/templates.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). */
+function template_rotate(angle_deg) {
+	return `<svg xmlns="http://www.w3.org/2000/svg" width="26" height="24" fill="none"><g filter="url(#a)" transform="rotate(${angle_deg}, 13, 12), scale(0.75)"><path fill="#000" fill-rule="evenodd" d="M23 15.5h-6.43l2.65-2.79A7.72 7.72 0 0 0 13 9.5a7.72 7.72 0 0 0-6.22 3.21l2.65 2.79H3V8.75l1.74 1.83A10.5 10.5 0 0 1 13 6.5c3.32 0 6.3 1.59 8.26 4.08L23 8.75v6.75Z" clip-rule="evenodd"/><path stroke="#fff" stroke-width=".75" d="M23 15.88h.38V7.8l-.65.68-1.45 1.52A10.85 10.85 0 0 0 13 6.13c-3.3 0-6.25 1.5-8.28 3.88L3.27 8.5l-.64-.68v8.07h7.67l-.6-.64-2.43-2.55A7.32 7.32 0 0 1 13 9.88c2.3 0 4.36 1.08 5.73 2.8l-2.43 2.56-.6.63H23Z"/></g><defs><filter id="a" width="25.1" height="14.1" x=".45" y="4.95" color-interpolation-filters="sRGB" filterUnits="userSpaceOnUse"><feFlood flood-opacity="0" result="BackgroundImageFix"/><feColorMatrix in="SourceAlpha" result="hardAlpha" values="0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 127 0"/><feOffset dy="1"/><feGaussianBlur stdDeviation=".9"/><feComposite in2="hardAlpha" operator="out"/><feColorMatrix values="0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0.65 0"/><feBlend in2="BackgroundImageFix" result="effect1_dropShadow_443_204"/><feBlend in="SourceGraphic" in2="effect1_dropShadow_443_204" result="shape"/></filter></defs></svg>`;
+}
+/** Hotspot for `template_rotate` — CSS-px offset from SVG top-left. */
+const ROTATE_HOTSPOT = [12, 12];
+/**
+* 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`.
+*/
+function template_resize(angle_deg) {
+	return `<svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" fill="none"><g filter="url(#b)" transform="rotate(${angle_deg}, 16, 16)"><path fill="#000" stroke="#fff" stroke-width="1" stroke-linejoin="round" d="M7 16 L11 12 L11 14.5 L21 14.5 L21 12 L25 16 L21 20 L21 17.5 L11 17.5 L11 20 Z"/></g><defs><filter id="b" width="22" height="13" x="5" y="10" color-interpolation-filters="sRGB" filterUnits="userSpaceOnUse"><feFlood flood-opacity="0" result="BackgroundImageFix"/><feColorMatrix in="SourceAlpha" result="hardAlpha" values="0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 127 0"/><feOffset dy="1"/><feGaussianBlur stdDeviation=".8"/><feComposite in2="hardAlpha" operator="out"/><feColorMatrix values="0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0.55 0"/><feBlend in2="BackgroundImageFix" result="effect1_dropShadow_resize"/><feBlend in="SourceGraphic" in2="effect1_dropShadow_resize" result="shape"/></filter></defs></svg>`;
+}
+/** Hotspot for `template_resize` — CSS-px offset from SVG top-left. */
+const RESIZE_HOTSPOT = [16, 16];
+//#endregion
+//#region cursors/renderer.ts
+/**
+* Default cursor renderer — maps `CursorIcon` → CSS `cursor:` value.
+*
+* Two responsibilities:
+*
+* 1. **Static-keyword passthrough** for cursors that don't need angle
+*    info (text, grab, crosshair, etc.) — defer to the canonical
+*    `cursorToCss` mapping shipped from `event/cursor.ts` so the
+*    fallback keyword stays the single source of truth.
+*
+* 2. **SVG generation** for rotation-sensitive cursors (rotate +
+*    8 resize directions). Each cardinal direction maps to a fixed
+*    base angle; when the icon carries a `baseAngle` (radians), it
+*    composes with the base. The renderer is stateless — the upstream
+*    `SurfaceState.setCursor` already gates re-emit at the
+*    `CURSOR_ANGLE_BUCKET_RAD` level via `cursorEquals`, so this
+*    function is invoked at most once per real change.
+*
+* Output shape per icon:
+*
+*     "url(data:image/svg+xml;base64,...) HOTSPOT_X HOTSPOT_Y, FALLBACK_KEYWORD"
+*
+* `FALLBACK_KEYWORD` is what `cursorToCss` would have returned. This
+* means a browser that fails to load the data URL (truly impossible for
+* inline base64, but the spec requires a fallback) lands on the
+* existing native cursor — never on `auto`.
+*/
+const RESIZE_BASE_ANGLE_DEG = {
+	e: 0,
+	w: 0,
+	n: 90,
+	s: 90,
+	ne: -45,
+	sw: -45,
+	nw: 45,
+	se: 45
+};
+const ROTATE_BASE_ANGLE_DEG = {
+	nw: -45,
+	ne: 45,
+	se: 135,
+	sw: -135
+};
+const RAD_TO_DEG = 180 / Math.PI;
+/**
+* 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());
+*/
+function defaultRenderer() {
+	return function render(icon) {
+		if (typeof icon === "string") return cursorToCss(icon);
+		if (icon.kind === "rotate") return build_rotate_css(icon.corner, bucket_to_deg(angleBucket(icon.baseAngle)));
+		return build_resize_css(icon.direction, bucket_to_deg(angleBucket(icon.baseAngle)));
+	};
+}
+function bucket_to_deg(bucket) {
+	return bucket * CURSOR_ANGLE_BUCKET_RAD * RAD_TO_DEG;
+}
+function build_cursor_css(template, hotspot, fallback, base_deg, extra_deg) {
+	return `url(${svgDataUrl(template(base_deg + extra_deg))}) ${hotspot[0]} ${hotspot[1]}, ${fallback}`;
+}
+function build_rotate_css(corner, extra_angle_deg) {
+	return build_cursor_css(template_rotate, ROTATE_HOTSPOT, "crosshair", ROTATE_BASE_ANGLE_DEG[corner], extra_angle_deg);
+}
+function build_resize_css(direction, extra_angle_deg) {
+	return build_cursor_css(template_resize, RESIZE_HOTSPOT, `${direction}-resize`, RESIZE_BASE_ANGLE_DEG[direction], extra_angle_deg);
+}
+//#endregion
+//#region cursors/index.ts
+/**
+* `@grida/hud/cursors` — opt-in default cursor renderer.
+*
+* Hosts wire it once at construction:
+*
+*     import { cursors } from "@grida/hud/cursors";
+*     surface.setCursorRenderer(cursors.defaultRenderer());
+*
+* Tree-shake invariant: nothing in `surface/`, `event/`, or
+* `primitives/` may import from this directory. Hosts that don't import
+* the subpath pay zero bundle cost. See `__tests__/cursors.test.ts` for
+* the import-graph assertion that enforces this.
+*
+* Templates and the encoder are re-exported for hosts that want to
+* render cursor previews in sidebar UI without going through the Surface.
+*/
+/**
+* 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.
+*/
+const cursors = {
+	defaultRenderer,
+	svgDataUrl,
+	templates: {
+		rotate: template_rotate,
+		resize: template_resize
+	},
+	hotspots: {
+		rotate: ROTATE_HOTSPOT,
+		resize: RESIZE_HOTSPOT
+	}
+};
+//#endregion
+export { cursors, defaultRenderer, svgDataUrl };