@grida/hud 0.2.0 → 0.2.1

package/dist/core/index.d.mts

@@ -0,0 +1,181 @@
+import { i as HitShape, t as HUDObject } from "../overlay-dsG32baA.mjs";
+import cmath from "@grida/cmath";
+
+//#region core/event.d.ts
+/** Modifier-key snapshot at the moment an event was produced. */
+interface Modifiers {
+  readonly shift: boolean;
+  readonly alt: boolean;
+  readonly meta: boolean;
+  readonly ctrl: boolean;
+}
+declare const NO_MODS: Modifiers;
+type PointerButton = "primary" | "secondary" | "middle";
+/**
+ * Synthesized input event consumed by HUD bedrock.
+ *
+ * All coordinates are **screen-space CSS pixels relative to the
+ * canvas viewport**. The consumer holds the camera and converts to
+ * document-space via {@link Transform}.
+ */
+type HUDEvent = {
+  readonly kind: "pointer_move";
+  readonly x: number;
+  readonly y: number;
+  readonly mods: Modifiers;
+} | {
+  readonly kind: "pointer_down";
+  readonly x: number;
+  readonly y: number;
+  readonly button: PointerButton;
+  readonly mods: Modifiers;
+} | {
+  readonly kind: "pointer_up";
+  readonly x: number;
+  readonly y: number;
+  readonly button: PointerButton;
+  readonly mods: Modifiers;
+} | {
+  readonly kind: "modifiers";
+  readonly mods: Modifiers;
+} | {
+  readonly kind: "wheel";
+  readonly x: number;
+  readonly y: number;
+  readonly dx: number;
+  readonly dy: number;
+  readonly mods: Modifiers;
+} | {
+  readonly kind: "key";
+  readonly phase: "down" | "up";
+  readonly code: string;
+  readonly mods: Modifiers;
+} | {
+  readonly kind: "blur";
+};
+/** Convenience re-export. */
+type Vector2 = cmath.Vector2;
+//#endregion
+//#region core/click-tracker.d.ts
+interface ClickTrackerOptions {
+  /** Max gap between clicks in ms. Default 250. */
+  readonly windowMs?: number;
+  /** Max distance between clicks in screen px. Default 5. */
+  readonly distancePx?: number;
+}
+declare class ClickTracker {
+  private window_ms;
+  private distance_px;
+  private last_time;
+  private last_x;
+  private last_y;
+  private count;
+  constructor(opts?: ClickTrackerOptions);
+  /**
+   * Register a click at `(x, y)` and return the current consecutive-
+   * click count (1 = single, 2 = double, etc.). `now` is in ms.
+   */
+  register(x: number, y: number, now?: number): number;
+  reset(): void;
+}
+//#endregion
+//#region core/transform.d.ts
+/**
+ * Axis-aligned 2×3 affine.
+ *
+ * Stored as a `cmath.Transform`:
+ *   `[[sx, 0, tx], [0, sy, ty]]`
+ *
+ * Off-diagonal components are ignored by these helpers; HUD's camera
+ * is scale + translate only.
+ */
+type Transform = cmath.Transform;
+declare const IDENTITY: Transform;
+/** Project a screen-space point into document-space. */
+declare function screenToDoc(t: Transform, x: number, y: number): cmath.Vector2;
+/** Project a document-space point into screen-space. */
+declare function docToScreen(t: Transform, x: number, y: number): cmath.Vector2;
+/** Current uniform zoom. Reads `sx`. */
+declare function zoomOf(t: Transform): number;
+//#endregion
+//#region core/registry.d.ts
+/**
+ * Thrown by `register` when an entity with the same `name` is already
+ * registered. Consumers should `unregister` the existing one first.
+ */
+declare class RegistrationError extends Error {
+  constructor(message: string);
+}
+/**
+ * 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.
+ */
+declare class NamedRegistry<K extends string, T extends {
+  readonly name: K;
+  detach?(): void;
+}> {
+  private label;
+  private byName;
+  /** Explicit insertion-ordered array for cheap reverse-walk on clear. */
+  private order;
+  constructor(label: string);
+  register(e: T): void;
+  unregister(e: T): void;
+  has(name: K): boolean;
+  get(name: K): T | undefined;
+  entries(): IterableIterator<T>;
+  size(): number;
+  clear(): void;
+}
+//#endregion
+//#region core/hit-registry.d.ts
+/**
+ * Generic hit registry. One per frame (or persistent — bedrock is
+ * agnostic). Add objects with `add`, clear with `clear`, query with
+ * `queryPoint` / `queryAll`.
+ */
+declare class HitRegistry<I = unknown> {
+  private 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: HUDObject<I>): void;
+  /** Drop all entries. */
+  clear(): void;
+  /** Total number of stored objects (paint-only + hit-testable). */
+  size(): number;
+  /** Iterate every stored object in insertion order. */
+  entries(): IterableIterator<HUDObject<I>>;
+  /**
+   * 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: cmath.Vector2, transform: Transform): HUDObject<I> | null;
+  /**
+   * 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: cmath.Vector2, transform: Transform): HUDObject<I>[];
+}
+/**
+ * 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).
+ */
+declare function shapeContains(shape: HitShape, point_screen: cmath.Vector2, transform: Transform): boolean;
+//#endregion
+export { ClickTracker, type ClickTrackerOptions, type HUDEvent, HitRegistry, IDENTITY, type Modifiers, NO_MODS, NamedRegistry, type PointerButton, RegistrationError, type Transform, type Vector2, docToScreen, screenToDoc, shapeContains, zoomOf };

package/dist/core/index.d.ts

@@ -0,0 +1,181 @@
+import { i as HitShape, t as HUDObject } from "../overlay-CVV4s3IL.js";
+import cmath from "@grida/cmath";
+
+//#region core/event.d.ts
+/** Modifier-key snapshot at the moment an event was produced. */
+interface Modifiers {
+  readonly shift: boolean;
+  readonly alt: boolean;
+  readonly meta: boolean;
+  readonly ctrl: boolean;
+}
+declare const NO_MODS: Modifiers;
+type PointerButton = "primary" | "secondary" | "middle";
+/**
+ * Synthesized input event consumed by HUD bedrock.
+ *
+ * All coordinates are **screen-space CSS pixels relative to the
+ * canvas viewport**. The consumer holds the camera and converts to
+ * document-space via {@link Transform}.
+ */
+type HUDEvent = {
+  readonly kind: "pointer_move";
+  readonly x: number;
+  readonly y: number;
+  readonly mods: Modifiers;
+} | {
+  readonly kind: "pointer_down";
+  readonly x: number;
+  readonly y: number;
+  readonly button: PointerButton;
+  readonly mods: Modifiers;
+} | {
+  readonly kind: "pointer_up";
+  readonly x: number;
+  readonly y: number;
+  readonly button: PointerButton;
+  readonly mods: Modifiers;
+} | {
+  readonly kind: "modifiers";
+  readonly mods: Modifiers;
+} | {
+  readonly kind: "wheel";
+  readonly x: number;
+  readonly y: number;
+  readonly dx: number;
+  readonly dy: number;
+  readonly mods: Modifiers;
+} | {
+  readonly kind: "key";
+  readonly phase: "down" | "up";
+  readonly code: string;
+  readonly mods: Modifiers;
+} | {
+  readonly kind: "blur";
+};
+/** Convenience re-export. */
+type Vector2 = cmath.Vector2;
+//#endregion
+//#region core/click-tracker.d.ts
+interface ClickTrackerOptions {
+  /** Max gap between clicks in ms. Default 250. */
+  readonly windowMs?: number;
+  /** Max distance between clicks in screen px. Default 5. */
+  readonly distancePx?: number;
+}
+declare class ClickTracker {
+  private window_ms;
+  private distance_px;
+  private last_time;
+  private last_x;
+  private last_y;
+  private count;
+  constructor(opts?: ClickTrackerOptions);
+  /**
+   * Register a click at `(x, y)` and return the current consecutive-
+   * click count (1 = single, 2 = double, etc.). `now` is in ms.
+   */
+  register(x: number, y: number, now?: number): number;
+  reset(): void;
+}
+//#endregion
+//#region core/transform.d.ts
+/**
+ * Axis-aligned 2×3 affine.
+ *
+ * Stored as a `cmath.Transform`:
+ *   `[[sx, 0, tx], [0, sy, ty]]`
+ *
+ * Off-diagonal components are ignored by these helpers; HUD's camera
+ * is scale + translate only.
+ */
+type Transform = cmath.Transform;
+declare const IDENTITY: Transform;
+/** Project a screen-space point into document-space. */
+declare function screenToDoc(t: Transform, x: number, y: number): cmath.Vector2;
+/** Project a document-space point into screen-space. */
+declare function docToScreen(t: Transform, x: number, y: number): cmath.Vector2;
+/** Current uniform zoom. Reads `sx`. */
+declare function zoomOf(t: Transform): number;
+//#endregion
+//#region core/registry.d.ts
+/**
+ * Thrown by `register` when an entity with the same `name` is already
+ * registered. Consumers should `unregister` the existing one first.
+ */
+declare class RegistrationError extends Error {
+  constructor(message: string);
+}
+/**
+ * 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.
+ */
+declare class NamedRegistry<K extends string, T extends {
+  readonly name: K;
+  detach?(): void;
+}> {
+  private label;
+  private byName;
+  /** Explicit insertion-ordered array for cheap reverse-walk on clear. */
+  private order;
+  constructor(label: string);
+  register(e: T): void;
+  unregister(e: T): void;
+  has(name: K): boolean;
+  get(name: K): T | undefined;
+  entries(): IterableIterator<T>;
+  size(): number;
+  clear(): void;
+}
+//#endregion
+//#region core/hit-registry.d.ts
+/**
+ * Generic hit registry. One per frame (or persistent — bedrock is
+ * agnostic). Add objects with `add`, clear with `clear`, query with
+ * `queryPoint` / `queryAll`.
+ */
+declare class HitRegistry<I = unknown> {
+  private 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: HUDObject<I>): void;
+  /** Drop all entries. */
+  clear(): void;
+  /** Total number of stored objects (paint-only + hit-testable). */
+  size(): number;
+  /** Iterate every stored object in insertion order. */
+  entries(): IterableIterator<HUDObject<I>>;
+  /**
+   * 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: cmath.Vector2, transform: Transform): HUDObject<I> | null;
+  /**
+   * 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: cmath.Vector2, transform: Transform): HUDObject<I>[];
+}
+/**
+ * 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).
+ */
+declare function shapeContains(shape: HitShape, point_screen: cmath.Vector2, transform: Transform): boolean;
+//#endregion
+export { ClickTracker, type ClickTrackerOptions, type HUDEvent, HitRegistry, IDENTITY, type Modifiers, NO_MODS, NamedRegistry, type PointerButton, RegistrationError, type Transform, type Vector2, docToScreen, screenToDoc, shapeContains, zoomOf };

package/dist/core/index.js

@@ -0,0 +1,301 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#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
+exports.ClickTracker = ClickTracker;
+exports.HitRegistry = HitRegistry;
+exports.IDENTITY = IDENTITY;
+exports.NO_MODS = NO_MODS;
+exports.NamedRegistry = NamedRegistry;
+exports.RegistrationError = RegistrationError;
+exports.docToScreen = docToScreen;
+exports.screenToDoc = screenToDoc;
+exports.shapeContains = shapeContains;
+exports.zoomOf = zoomOf;