feat(runtime): implement focusCanvas option to LoadRuntimeOptions (#236)

Author: fraxken

.changeset/fresh-cities-love.md

@@ -0,0 +1,5 @@
+---
+"@jolly-pixel/runtime": minor
+---
+
+Add a focusCanvas to disable permanent canvas focus listener

docs/llms/runtime-llms-full.md

@@ -108,13 +108,21 @@ Bootstraps the runtime by detecting GPU capabilities, displaying a loading scree
 Returns a `Promise<void>` that resolves when loading completes, or shows an error on the loading screen if something fails.
 
 ```ts
-export interface LoadRuntimeOptions {
+interface LoadRuntimeOptions {
   /**
    * @default 850
    * Minimum delay (ms) before starting asset loading. Gives the loading UI time to render.
    */
   loadingDelay?: number;
+  /**
+   * Whether to automatically focus the game canvas when the user clicks anywhere on the page.
+   * This is important for games that require keyboard input,
+   * as it ensures that the canvas has focus and can receive keyboard events.
+   * @default true
+   */
+  focusCanvas?: boolean;
 }
+
 ```
 
 ### 🎨 Custom loader and splash screen

packages/runtime/README.md

@@ -106,13 +106,21 @@ Bootstraps the runtime by detecting GPU capabilities, displaying a loading scree
 Returns a `Promise<void>` that resolves when loading completes, or shows an error on the loading screen if something fails.
 
 ```ts
-export interface LoadRuntimeOptions {
+interface LoadRuntimeOptions {
   /**
    * @default 850
    * Minimum delay (ms) before starting asset loading. Gives the loading UI time to render.
    */
   loadingDelay?: number;
+  /**
+   * Whether to automatically focus the game canvas when the user clicks anywhere on the page.
+   * This is important for games that require keyboard input,
+   * as it ensures that the canvas has focus and can receive keyboard events.
+   * @default true
+   */
+  focusCanvas?: boolean;
 }
+
 ```
 
 ### 🎨 Custom loader and splash screen

packages/runtime/src/index.ts

@@ -15,13 +15,23 @@ export interface LoadRuntimeOptions {
    * Minimum delay (ms) before starting asset loading. Gives the loading UI time to render.
    */
   loadingDelay?: number;
+  /**
+   * Whether to automatically focus the game canvas when the user clicks anywhere on the page.
+   * This is important for games that require keyboard input,
+   * as it ensures that the canvas has focus and can receive keyboard events.
+   * @default true
+   */
+  focusCanvas?: boolean;
 }
 
 export async function loadRuntime(
   runtime: Runtime<any>,
   options: LoadRuntimeOptions = {}
 ) {
-  const { loadingDelay = 850 } = options;
+  const {
+    loadingDelay = 850,
+    focusCanvas = true
+  } = options;
 
   const gpuTierPromise = getGPUTier();
 
@@ -57,7 +67,12 @@ export async function loadRuntime(
   });
 
   // Make sure the focus is always on the game canvas wherever we click on the game window
-  document.addEventListener("click", () => runtime.canvas.focus());
+  function focusCanvasHandler() {
+    if (document.activeElement !== runtime.canvas) {
+      runtime.canvas.focus();
+    }
+  }
+  document.addEventListener("click", focusCanvasHandler);
 
   let initialized = false;
   try {
@@ -113,6 +128,11 @@ export async function loadRuntime(
   catch (error: any) {
     loadingComponent.error(error);
   }
+  finally {
+    if (!focusCanvas) {
+      document.removeEventListener("click", focusCanvasHandler);
+    }
+  }
 
   if (initialized) {
     runtime.start();