@gd-kirie/ipc 0.1.2 → 0.2.0

package/README.md

@@ -36,3 +36,45 @@ message:
 The structured data subset is limited to `null`, booleans, numbers, strings,
 arrays, and objects with string keys. JSON message shapes are a caller or
 adapter convention and should be sent with `sendText()` when needed.
+
+## Pointer input forwarding
+
+> [!IMPORTANT]
+> Kirie WebViews normally fill their native host above Godot. CSS transparency
+> does not pass native hit tests through to Godot, so visible Godot controls
+> behind the WebView cannot be clicked without pointer forwarding. Most Kirie
+> pages should import `@gd-kirie/ipc/pointer-input/auto`.
+
+Enable both sides; the browser entry registers on import:
+
+```gdscript
+$KirieNode.pointer_input_forwarding_enabled = true
+```
+
+```ts
+import "@gd-kirie/ipc/pointer-input/auto";
+```
+
+### Custom event orchestration
+
+For custom targets or lifetimes, use the explicit entry instead:
+
+```ts
+import {
+  createPointerEventsHandler,
+  phaseFromPointerEvent,
+  sendPointerEvent,
+} from "@gd-kirie/ipc/pointer-input";
+```
+
+`createPointerEventsHandler()` returns `capture`, `bubble`, and `cancel` handlers;
+the caller owns their registration and removal.
+
+`pointerdown` bubbling decides ownership: `event.stopPropagation()` keeps the
+sequence in the WebView; otherwise its move, up, and cancel events are forwarded
+to Godot.
+
+Forwarding uses Godot's
+[`Input.parse_input_event()`](https://docs.godotengine.org/en/stable/classes/class_input.html#class-input-method-parse-input-event)
+API; forwarded mouse and touch events retain their destination
+[`window_id`](https://docs.godotengine.org/en/stable/classes/class_inputeventfromwindow.html#class-inputeventfromwindow-property-window-id).

package/dist/pointer-input/auto.d.ts

@@ -0,0 +1 @@
+export { };

package/dist/pointer-input/auto.js

@@ -0,0 +1,11 @@
+import { createPointerEventsHandler } from "./index.js";
+//#region src/pointer-input/auto.ts
+const pointerEventsHandler = createPointerEventsHandler();
+document.addEventListener("pointerdown", pointerEventsHandler.bubble);
+document.addEventListener("pointermove", pointerEventsHandler.capture, true);
+document.addEventListener("pointerup", pointerEventsHandler.capture, true);
+document.addEventListener("pointercancel", pointerEventsHandler.capture, true);
+document.addEventListener("pointermove", pointerEventsHandler.bubble);
+//#endregion
+
+//# sourceMappingURL=auto.js.map

package/dist/pointer-input/auto.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auto.js","names":[],"sources":["../../src/pointer-input/auto.ts"],"sourcesContent":["import { createPointerEventsHandler } from \"./index\";\n\nconst pointerEventsHandler = createPointerEventsHandler();\n\ndocument.addEventListener(\"pointerdown\", pointerEventsHandler.bubble);\ndocument.addEventListener(\"pointermove\", pointerEventsHandler.capture, true);\ndocument.addEventListener(\"pointerup\", pointerEventsHandler.capture, true);\ndocument.addEventListener(\"pointercancel\", pointerEventsHandler.capture, true);\ndocument.addEventListener(\"pointermove\", pointerEventsHandler.bubble);\n"],"mappings":";;AAEA,MAAM,uBAAuB,2BAA2B;AAExD,SAAS,iBAAiB,eAAe,qBAAqB,MAAM;AACpE,SAAS,iBAAiB,eAAe,qBAAqB,SAAS,IAAI;AAC3E,SAAS,iBAAiB,aAAa,qBAAqB,SAAS,IAAI;AACzE,SAAS,iBAAiB,iBAAiB,qBAAqB,SAAS,IAAI;AAC7E,SAAS,iBAAiB,eAAe,qBAAqB,MAAM"}

package/dist/pointer-input/index.d.ts

@@ -0,0 +1,14 @@
+//#region src/pointer-input/index.d.ts
+type PointerPhase = "down" | "move" | "up" | "cancel";
+type PointerEventSender = (event: PointerEvent, phase?: PointerPhase) => void;
+interface PointerEventsHandler {
+  capture(event: PointerEvent): void;
+  bubble(event: PointerEvent): void;
+  cancel(): void;
+}
+declare function sendPointerEvent(event: PointerEvent, phase?: PointerPhase): void;
+declare function createPointerEventsHandler(sendPointer?: PointerEventSender): PointerEventsHandler;
+declare function phaseFromPointerEvent(event: PointerEvent): PointerPhase;
+//#endregion
+export { PointerEventSender, PointerEventsHandler, PointerPhase, createPointerEventsHandler, phaseFromPointerEvent, sendPointerEvent };
+//# sourceMappingURL=index.d.ts.map

package/dist/pointer-input/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/pointer-input/index.ts"],"mappings":";KAGY,YAAA;AAAA,KAmBA,kBAAA,IAAsB,KAAA,EAAO,YAAA,EAAc,KAAA,GAAQ,YAAA;AAAA,UAE9C,oBAAA;EACf,OAAA,CAAQ,KAAA,EAAO,YAAA;EACf,MAAA,CAAO,KAAA,EAAO,YAAA;EACd,MAAA;AAAA;AAAA,iBAGc,gBAAA,CACd,KAAA,EAAO,YAAA,EACP,KAAA,GAAO,YAAA;AAAA,iBAwBO,0BAAA,CACd,WAAA,GAAa,kBAAA,GACZ,oBAAA;AAAA,iBA8Fa,qBAAA,CAAsB,KAAA,EAAO,YAAA,GAAe,YAAA"}

package/dist/pointer-input/index.js

@@ -0,0 +1,105 @@
+import { sendData } from "../index.js";
+//#region src/pointer-input/index.ts
+function sendPointerEvent(event, phase = phaseFromPointerEvent(event)) {
+	const view = event.view ?? window;
+	const pointerType = event.pointerType;
+	if (pointerType !== "mouse" && pointerType !== "pen" && pointerType !== "touch") throw new TypeError(`Kirie cannot forward pointer type: ${pointerType}`);
+	sendData({ __gd_kirie_control: {
+		kind: "pointer",
+		phase,
+		pointer_id: event.pointerId,
+		pointer_type: pointerType,
+		normalized_x: event.clientX / view.innerWidth,
+		normalized_y: event.clientY / view.innerHeight,
+		button: event.button,
+		buttons: event.buttons,
+		pressure: event.pressure
+	} });
+}
+function createPointerEventsHandler(sendPointer = sendPointerEvent) {
+	const claimedPointers = /* @__PURE__ */ new Map();
+	/**
+	* Completes events for pointer sequences previously claimed during bubbling.
+	*
+	* Triggering workflow:
+	*
+	* {@link EventTarget.addEventListener}
+	*   -> `pointermove|pointerup|pointercancel`
+	*     -> {@link capture}
+	*
+	* Upstream:
+	* - {@link EventTarget.addEventListener}
+	*
+	* Downstream:
+	* - {@link sendPointerEvent}
+	*/
+	const capture = (event) => {
+		if (!claimedPointers.has(event.pointerId) || event.type !== "pointermove" && event.type !== "pointerup" && event.type !== "pointercancel") return;
+		sendPointer(event);
+		if (event.type === "pointerup" || event.type === "pointercancel") {
+			claimedPointers.delete(event.pointerId);
+			return;
+		}
+		claimedPointers.set(event.pointerId, event);
+	};
+	/**
+	* Claims bubbled pointer downs and forwards unpressed mouse hover.
+	*
+	* Triggering workflow:
+	*
+	* {@link EventTarget.addEventListener}
+	*   -> `pointerdown|pointermove`
+	*     -> {@link bubble}
+	*
+	* Upstream:
+	* - {@link EventTarget.addEventListener}
+	*
+	* Downstream:
+	* - {@link sendPointerEvent}
+	*/
+	const bubble = (event) => {
+		if (event.type === "pointerdown") {
+			sendPointer(event);
+			claimedPointers.set(event.pointerId, event);
+			return;
+		}
+		if (event.type !== "pointermove" || claimedPointers.has(event.pointerId) || event.pointerType !== "mouse" || event.buttons !== 0) return;
+		sendPointer(event);
+	};
+	/**
+	* Cancels every pointer sequence currently claimed by this handler.
+	*
+	* Triggering workflow:
+	*
+	* {@link createPointerEventsHandler}
+	*   -> {@link PointerEventsHandler.cancel}
+	*
+	* Upstream:
+	* - caller of {@link PointerEventsHandler.cancel}
+	*
+	* Downstream:
+	* - {@link sendPointerEvent}
+	*/
+	const cancel = () => {
+		for (const pointerEvent of claimedPointers.values()) sendPointer(pointerEvent, "cancel");
+		claimedPointers.clear();
+	};
+	return {
+		capture,
+		bubble,
+		cancel
+	};
+}
+function phaseFromPointerEvent(event) {
+	switch (event.type) {
+		case "pointerdown": return "down";
+		case "pointermove": return "move";
+		case "pointerup": return "up";
+		case "pointercancel": return "cancel";
+		default: throw new TypeError(`Kirie cannot forward pointer event type: ${event.type}`);
+	}
+}
+//#endregion
+export { createPointerEventsHandler, phaseFromPointerEvent, sendPointerEvent };
+
+//# sourceMappingURL=index.js.map

package/dist/pointer-input/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../../src/pointer-input/index.ts"],"sourcesContent":["import type { KirieData } from \"../index\";\nimport { sendData } from \"../index\";\n\nexport type PointerPhase = \"down\" | \"move\" | \"up\" | \"cancel\";\ntype PointerType = \"mouse\" | \"pen\" | \"touch\";\n\ninterface PointerInputRecord extends Record<string, KirieData> {\n  kind: \"pointer\";\n  phase: PointerPhase;\n  pointer_id: number;\n  pointer_type: PointerType;\n  normalized_x: number;\n  normalized_y: number;\n  button: number;\n  buttons: number;\n  pressure: number;\n}\n\ninterface PointerControlRecord extends Record<string, KirieData> {\n  __gd_kirie_control: PointerInputRecord;\n}\n\nexport type PointerEventSender = (event: PointerEvent, phase?: PointerPhase) => void;\n\nexport interface PointerEventsHandler {\n  capture(event: PointerEvent): void;\n  bubble(event: PointerEvent): void;\n  cancel(): void;\n}\n\nexport function sendPointerEvent(\n  event: PointerEvent,\n  phase: PointerPhase = phaseFromPointerEvent(event),\n): void {\n  const view = event.view ?? window;\n\n  const pointerType = event.pointerType;\n  if (pointerType !== \"mouse\" && pointerType !== \"pen\" && pointerType !== \"touch\") {\n    throw new TypeError(`Kirie cannot forward pointer type: ${pointerType}`);\n  }\n\n  sendData({\n    __gd_kirie_control: {\n      kind: \"pointer\",\n      phase,\n      pointer_id: event.pointerId,\n      pointer_type: pointerType,\n      normalized_x: event.clientX / view.innerWidth,\n      normalized_y: event.clientY / view.innerHeight,\n      button: event.button,\n      buttons: event.buttons,\n      pressure: event.pressure,\n    },\n  } satisfies PointerControlRecord);\n}\n\nexport function createPointerEventsHandler(\n  sendPointer: PointerEventSender = sendPointerEvent,\n): PointerEventsHandler {\n  // A sequence is claimed only when its down event reaches the document bubble phase.\n  const claimedPointers = new Map<number, PointerEvent>();\n\n  /**\n   * Completes events for pointer sequences previously claimed during bubbling.\n   *\n   * Triggering workflow:\n   *\n   * {@link EventTarget.addEventListener}\n   *   -> `pointermove|pointerup|pointercancel`\n   *     -> {@link capture}\n   *\n   * Upstream:\n   * - {@link EventTarget.addEventListener}\n   *\n   * Downstream:\n   * - {@link sendPointerEvent}\n   */\n  const capture = (event: PointerEvent): void => {\n    if (\n      !claimedPointers.has(event.pointerId) ||\n      (event.type !== \"pointermove\" && event.type !== \"pointerup\" && event.type !== \"pointercancel\")\n    ) {\n      return;\n    }\n\n    sendPointer(event);\n    if (event.type === \"pointerup\" || event.type === \"pointercancel\") {\n      claimedPointers.delete(event.pointerId);\n      return;\n    }\n\n    claimedPointers.set(event.pointerId, event);\n  };\n\n  /**\n   * Claims bubbled pointer downs and forwards unpressed mouse hover.\n   *\n   * Triggering workflow:\n   *\n   * {@link EventTarget.addEventListener}\n   *   -> `pointerdown|pointermove`\n   *     -> {@link bubble}\n   *\n   * Upstream:\n   * - {@link EventTarget.addEventListener}\n   *\n   * Downstream:\n   * - {@link sendPointerEvent}\n   */\n  const bubble = (event: PointerEvent): void => {\n    if (event.type === \"pointerdown\") {\n      sendPointer(event);\n      claimedPointers.set(event.pointerId, event);\n      return;\n    }\n\n    if (\n      event.type !== \"pointermove\" ||\n      claimedPointers.has(event.pointerId) ||\n      event.pointerType !== \"mouse\" ||\n      event.buttons !== 0\n    ) {\n      return;\n    }\n\n    sendPointer(event);\n  };\n\n  /**\n   * Cancels every pointer sequence currently claimed by this handler.\n   *\n   * Triggering workflow:\n   *\n   * {@link createPointerEventsHandler}\n   *   -> {@link PointerEventsHandler.cancel}\n   *\n   * Upstream:\n   * - caller of {@link PointerEventsHandler.cancel}\n   *\n   * Downstream:\n   * - {@link sendPointerEvent}\n   */\n  const cancel = (): void => {\n    for (const pointerEvent of claimedPointers.values()) {\n      sendPointer(pointerEvent, \"cancel\");\n    }\n    claimedPointers.clear();\n  };\n\n  return { capture, bubble, cancel };\n}\n\nexport function phaseFromPointerEvent(event: PointerEvent): PointerPhase {\n  switch (event.type) {\n    case \"pointerdown\":\n      return \"down\";\n    case \"pointermove\":\n      return \"move\";\n    case \"pointerup\":\n      return \"up\";\n    case \"pointercancel\":\n      return \"cancel\";\n    default:\n      throw new TypeError(`Kirie cannot forward pointer event type: ${event.type}`);\n  }\n}\n"],"mappings":";;AA8BA,SAAgB,iBACd,OACA,QAAsB,sBAAsB,KAAK,GAC3C;CACN,MAAM,OAAO,MAAM,QAAQ;CAE3B,MAAM,cAAc,MAAM;CAC1B,IAAI,gBAAgB,WAAW,gBAAgB,SAAS,gBAAgB,SACtE,MAAM,IAAI,UAAU,sCAAsC,aAAa;CAGzE,SAAS,EACP,oBAAoB;EAClB,MAAM;EACN;EACA,YAAY,MAAM;EAClB,cAAc;EACd,cAAc,MAAM,UAAU,KAAK;EACnC,cAAc,MAAM,UAAU,KAAK;EACnC,QAAQ,MAAM;EACd,SAAS,MAAM;EACf,UAAU,MAAM;CAClB,EACF,CAAgC;AAClC;AAEA,SAAgB,2BACd,cAAkC,kBACZ;CAEtB,MAAM,kCAAkB,IAAI,IAA0B;;;;;;;;;;;;;;;;CAiBtD,MAAM,WAAW,UAA8B;EAC7C,IACE,CAAC,gBAAgB,IAAI,MAAM,SAAS,KACnC,MAAM,SAAS,iBAAiB,MAAM,SAAS,eAAe,MAAM,SAAS,iBAE9E;EAGF,YAAY,KAAK;EACjB,IAAI,MAAM,SAAS,eAAe,MAAM,SAAS,iBAAiB;GAChE,gBAAgB,OAAO,MAAM,SAAS;GACtC;EACF;EAEA,gBAAgB,IAAI,MAAM,WAAW,KAAK;CAC5C;;;;;;;;;;;;;;;;CAiBA,MAAM,UAAU,UAA8B;EAC5C,IAAI,MAAM,SAAS,eAAe;GAChC,YAAY,KAAK;GACjB,gBAAgB,IAAI,MAAM,WAAW,KAAK;GAC1C;EACF;EAEA,IACE,MAAM,SAAS,iBACf,gBAAgB,IAAI,MAAM,SAAS,KACnC,MAAM,gBAAgB,WACtB,MAAM,YAAY,GAElB;EAGF,YAAY,KAAK;CACnB;;;;;;;;;;;;;;;CAgBA,MAAM,eAAqB;EACzB,KAAK,MAAM,gBAAgB,gBAAgB,OAAO,GAChD,YAAY,cAAc,QAAQ;EAEpC,gBAAgB,MAAM;CACxB;CAEA,OAAO;EAAE;EAAS;EAAQ;CAAO;AACnC;AAEA,SAAgB,sBAAsB,OAAmC;CACvE,QAAQ,MAAM,MAAd;EACE,KAAK,eACH,OAAO;EACT,KAAK,eACH,OAAO;EACT,KAAK,aACH,OAAO;EACT,KAAK,iBACH,OAAO;EACT,SACE,MAAM,IAAI,UAAU,4CAA4C,MAAM,MAAM;CAChF;AACF"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gd-kirie/ipc",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "type": "module",
   "repository": {
     "type": "git",
@@ -13,6 +13,14 @@
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
+    },
+    "./pointer-input": {
+      "types": "./dist/pointer-input/index.d.ts",
+      "import": "./dist/pointer-input/index.js"
+    },
+    "./pointer-input/auto": {
+      "types": "./dist/pointer-input/auto.d.ts",
+      "import": "./dist/pointer-input/auto.js"
     }
   },
   "files": [
@@ -23,7 +31,8 @@
   },
   "devDependencies": {
     "tsdown": "^0.22.2",
-    "typescript": "^6.0.3"
+    "typescript": "^6.0.3",
+    "vitest": "^4.0.15"
   },
   "publishConfig": {
     "access": "public",
@@ -31,6 +40,7 @@
   },
   "scripts": {
     "build": "tsdown",
+    "test:run": "vitest run",
     "typecheck": "tsc -p tsconfig.json --noEmit"
   }
 }