@lightningjs/blits 1.48.0 → 1.50.0

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## v1.50.0
+
+_27 feb 2026_
+
+- Fixed issue with router navigation options not properly being overriden
+- Fixed FPS counter component and made it into a separate importable component (`import { FPScounter } from @lightningjs/blits/components`)
+- Added mouse (magic wand) support (including new `hover` lifecycle hook and `isHovered` state indicator)
+- Updated template attributes for VScode extension
+
+
+## v1.49.0
+
+_20 feb 2026_
+
+- Added `data-blits-renderstate` inspector attribute
+- Fixed `data-blits-hasfocus` inspector attribute to always be available
+- Added boolean attribute to `idle` lifecycle hook to indicate `idle` or `active` state
+- Fixed type definitions for router beforeEach hooks
+- Fixed double processing of reactivity guard
 
 ## v1.48.0
 

package/index.d.ts

@@ -170,6 +170,8 @@ declare module '@lightningjs/blits' {
     * Fires when the Component is being destroyed and removed.
     */
     destroy?: () => void;
+    hover?: () => void;
+    unhover?: () => void;
     /**
     * Fires upon each frame start  (allowing you to tap directly into the renderloop)
     *
@@ -201,11 +203,14 @@ declare module '@lightningjs/blits' {
     */
     exit?: () => void;
     /**
-    * Fires when the renderer is done rendering and enters an idle state
+    * Fires when the renderer is done rendering and enters an idle state (idle = true)
+    * and when the renderer starts rendering again and leaves the idle state (idle = false)
+    *
+    * @param idle - boolean to indicate whether the renderer is in idle state or not
     *
     * Note: This event can fire multiple times
     */
-    idle?: () => void;
+    idle?: (idle: boolean) => void;
     /**
     * Fires at a predefined interval and reports the current FPS value
     *
@@ -391,6 +396,13 @@ declare module '@lightningjs/blits' {
     */
     hasFocus: boolean,
 
+    /**
+    * Indicates whether the component currently is hovered
+    *
+    * @returns Boolean
+    */
+    isHovered: boolean,
+
     /**
     * Listen to events emitted by other components
     */
@@ -666,9 +678,9 @@ declare module '@lightningjs/blits' {
 
   export interface RouterHooks {
     init?: () => Promise<void> | void;
-    beforeEach?: (to: Route, from: Route) => string | Route | Promise<string | Route> | void;
-    afterEach?: (to: Route, from: Route) => string | Route | Promise<string | Route> | void;
-    error?: (err: string) => string | Route | Promise<string | Route> | void;
+    beforeEach?: (to: Route, from: Route) => string | Route | void | boolean | Promise<string | Route | void | boolean>;
+    afterEach?: (to: Route, from: Route) => string | Route | void | boolean | Promise<string | Route | void | boolean>;
+    error?: (err: string) => string | Route | void | boolean | Promise<string | Route | void | boolean>;
   }
 
   export interface RouterConfig<P extends Props, S, M, C> {
@@ -694,13 +706,13 @@ declare module '@lightningjs/blits' {
 
     /**
      * Enable or disable RouterView history navigation on Back input
-     * 
+     *
      * @default true
-     * 
+     *
      * @remarks
      * This is an app-wide setting that affects all RouterView instances in your application.
      * The router state is global and shared across all router instances.
-     * 
+     *
      * @example
      * ```js
      * router: {
@@ -809,8 +821,8 @@ declare module '@lightningjs/blits' {
   }[keyof T]
 
   export interface RouteHooks {
-    before?: (to: Route, from: Route) => string | Route | Promise<string | Route>;
-    after?: (to: Route, from: Route) => string | Route | Promise<string | Route>;
+    before?: (to: Route, from: Route) => string | Route | void | boolean | Promise<string | Route | void | boolean>;
+    after?: (to: Route, from: Route) => string | Route | void | boolean | Promise<string | Route | void | boolean>;
   }
 
   export type Route = {
@@ -1250,6 +1262,16 @@ declare module '@lightningjs/blits' {
      * ```
      */
     announcerOptions?: AnnouncerUtteranceOptions,
+    /**
+     * Enable mouse support (hover and click-to-focus).
+     *
+     * When set to `true`, pointer movement over the canvas updates hover state on components
+     * and click dispatches focus and Enter key input to the component under the cursor.
+     * When set to `false`, no mouse or pointer listeners are registered.
+     *
+     * @default false
+     */
+    enableMouse?: boolean,
     /**
      * Maximum FPS at which the App will be rendered
      *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lightningjs/blits",
-  "version": "1.48.0",
+  "version": "1.50.0",
   "description": "Blits: The Lightning 3 App Development Framework",
   "bin": "bin/index.js",
   "exports": {
@@ -29,7 +29,8 @@
       "default": "./src/plugins/storage/storage.js"
     },
     "./symbols": "./src/lib/symbols.js",
-    "./blitsFileConverter": "./src/lib/blitsfileconverter/blitsfileconverter.js"
+    "./blitsFileConverter": "./src/lib/blitsfileconverter/blitsfileconverter.js",
+    "./components": "./src/components/FPScounter.js"
   },
   "scripts": {
     "test": "c8 node scripts/runTests.js",
@@ -74,7 +75,7 @@
   },
   "dependencies": {
     "@lightningjs/msdf-generator": "^1.2.0",
-    "@lightningjs/renderer": "^2.21.0",
+    "@lightningjs/renderer": "^2.23.0",
     "magic-string": "^0.30.21"
   },
   "repository": {

package/scripts/prepublishOnly.js

@@ -19,7 +19,7 @@ import fs from 'fs'
 import path from 'path'
 import { fileURLToPath } from 'url'
 import compiler from '../src/lib/precompiler/precompiler.js'
-import { exec } from 'child_process'
+import childProcess from 'child_process'
 
 const currentDir = process.cwd()
 const componentDirs = ['src/components']
@@ -71,7 +71,7 @@ function processFile(filePath) {
 function formatFileWithESLint(filePath) {
   const command = `eslint "${filePath}" --fix`
 
-  exec(command, (error, stdout, stderr) => {
+  childProcess.exec(command, (error, stdout, stderr) => {
     if (error) {
       console.error(`Execution Error: ${error.message}`)
       console.error(`Exit Code: ${error.code}`)

package/src/application.js

@@ -15,12 +15,14 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import Component from './component.js'
-import { default as Focus, keyUpCallbacks } from './focus.js'
-import Settings from './settings.js'
+import { default as Component, componentMap } from './component.js'
+import { default as Focus, keyUpCallbacks } from './focus/focus.js'
+import Hover from './focus/hover.js'
 
+import Settings from './settings.js'
 import symbols from './lib/symbols.js'
 import { DEFAULT_HOLD_TIMEOUT_MS, DEFAULT_KEYMAP } from './constants.js'
+import { renderer } from './launch.js'
 
 /**
  * Merged keyMap (default + custom settings).
@@ -34,13 +36,24 @@ const Application = (config) => {
 
   let keyDownHandler
   let keyUpHandler
+  let mouseMoveHandler
+  let mouseClickHandler
+  let updateCanvasRect
   let holdTimeout
   let lastInputTime = 0
   let lastInputKey = null
+  let mouseListenersAdded = false
 
   config.hooks[symbols.destroy] = function () {
     document.removeEventListener('keydown', keyDownHandler)
     document.removeEventListener('keyup', keyUpHandler)
+    if (mouseListenersAdded) {
+      document.removeEventListener('mousemove', mouseMoveHandler)
+      document.removeEventListener('click', mouseClickHandler)
+      window.removeEventListener('resize', updateCanvasRect)
+      window.removeEventListener('scroll', updateCanvasRect)
+      Hover.clear()
+    }
   }
 
   config.hooks[symbols.init] = function () {
@@ -57,6 +70,8 @@ const Application = (config) => {
     /** @type {number} Input throttle time in milliseconds (0 = disabled) */
     const throttleMs = Settings.get('inputThrottle', 0)
 
+    const mouseEnabled = Settings.get('enableMouse', false)
+
     keyDownHandler = async (e) => {
       const currentTime = performance.now()
 
@@ -89,6 +104,7 @@ const Application = (config) => {
       }
 
       Focus.input(key, e)
+      if (mouseEnabled === true) Hover.clear()
       clearTimeout(holdTimeout)
       holdTimeout = setTimeout(
         () => {
@@ -108,8 +124,84 @@ const Application = (config) => {
       Focus.hold = false
     }
 
+    let lastMoved = 0
+    let currentNode = undefined
+    let currentComponent = undefined
+    let canvasRect = null
+
+    updateCanvasRect = () => {
+      if (renderer.canvas !== undefined) {
+        canvasRect = renderer.canvas.getBoundingClientRect()
+      }
+    }
+
+    // limit the amount of move events per time frame
+    mouseMoveHandler = (e) => {
+      if (e.timeStamp - lastMoved < 100) return
+      lastMoved = e.timeStamp
+
+      this.$emit('mouse::move', e)
+
+      if (canvasRect === null && renderer.canvas != null) {
+        updateCanvasRect()
+      }
+      if (canvasRect === null) {
+        return
+      }
+
+      const stage = renderer.stage
+      if (stage == null) {
+        return
+      }
+
+      // Convert viewport → canvas display coordinates
+      const x = e.clientX - canvasRect.left
+      const y = e.clientY - canvasRect.top
+
+      const node = stage.getNodeFromPosition({ x, y })
+
+      if (node === null) {
+        currentComponent = undefined
+        Hover.clear()
+        return
+      }
+      if (node === currentNode) return
+
+      currentNode = node
+      currentComponent = componentMap.get(currentNode)
+
+      if (currentComponent === undefined) {
+        Hover.clear()
+        return
+      }
+      Hover.set(currentComponent)
+    }
+
+    mouseClickHandler = () => {
+      if (currentComponent === undefined || currentComponent.eol === true) return
+
+      const e = new KeyboardEvent('keydown', {
+        key: 'Enter',
+        code: 'Enter',
+        keyCode: 13,
+        bubbles: true,
+        cancelable: true,
+        composed: true,
+      })
+      currentComponent.$focus()
+      currentComponent.$input(e)
+    }
+
     document.addEventListener('keydown', keyDownHandler)
     document.addEventListener('keyup', keyUpHandler)
+    if (mouseEnabled === true) {
+      updateCanvasRect()
+      document.addEventListener('mousemove', mouseMoveHandler)
+      document.addEventListener('click', mouseClickHandler)
+      window.addEventListener('resize', updateCanvasRect)
+      window.addEventListener('scroll', updateCanvasRect)
+      mouseListenersAdded = true
+    }
 
     // next tick
     setTimeout(() => Focus.set(this))

package/src/component/base/methods.js

@@ -16,8 +16,7 @@
  */
 
 import symbols from '../../lib/symbols.js'
-import Focus from '../../focus.js'
-import { keyUpCallbacks, getComponentWithInputEvent } from '../../focus.js'
+import { default as Focus, keyUpCallbacks, getComponentWithInputEvent } from '../../focus/focus.js'
 import eventListeners from '../../lib/eventListeners.js'
 import { trigger } from '../../lib/reactivity/effect.js'
 import { Log } from '../../lib/log.js'

package/src/component/setup/state.js

@@ -36,6 +36,8 @@ export default (component, state = () => {}) => {
     // add built-in hasFocus key
     stateKeys.push(['hasFocus'])
   }
+  // add built-in isHovered key
+  stateKeys.push(['isHovered'])
   const stateKeysLength = stateKeys.length
 
   for (let i = 0; i < stateKeysLength; i++) {

package/src/component.js

@@ -43,6 +43,9 @@ const required = (name) => {
   throw new Error(`Parameter ${name} is required`)
 }
 
+// map that holds component to their holder node
+export const componentMap = new WeakMap()
+
 /**
  * @typedef {function} BlitsComponentFactory
  * @param {object} opts - The options for the component instance
@@ -216,6 +219,10 @@ const Component = (name = required('name'), config = required('config')) => {
     // such as rotation and scale to components)
     this[symbols.holder] = parentEl
 
+    if (parentEl !== undefined && parentEl.node !== undefined) {
+      componentMap.set(parentEl.node, this)
+    }
+
     // generate an internal id (simple counter)
     this[symbols.id] = createInternalId()
 
@@ -238,6 +245,9 @@ const Component = (name = required('name'), config = required('config')) => {
     // add hasFocus key in
     this[symbols.originalState]['hasFocus'] = false
 
+    // add isHovered key in
+    this[symbols.originalState]['isHovered'] = false
+
     // generate a reactive state (using the result of previously execute state function)
     // and store it
     this[symbols.state] = reactive(this[symbols.originalState], Settings.get('reactivityMode'))
@@ -267,35 +277,59 @@ const Component = (name = required('name'), config = required('config')) => {
     this[symbols.slots] = this[symbols.children].filter((child) => child[symbols.isSlot])
 
     this[symbols.rendererEventListeners] = []
+
+    if (this[symbols.holder] !== undefined && Settings.get('inspector', false)) {
+      this[symbols.holder].setInspectorMetadata({ 'blits-hasFocus': false })
+    }
+
+    // setup inspector data for render state
+    if (name === 'App' && Settings.get('inspector', false)) {
+      this.$setTimeout(() => {
+        const wrapperEl = this[symbols.wrapper]
+        const idleCb = () => {
+          wrapperEl.setInspectorMetadata({ 'blits-renderState': 'idle' })
+        }
+        const activeCb = () => {
+          wrapperEl.setInspectorMetadata({ 'blits-renderState': 'active' })
+        }
+        renderer.on('idle', idleCb)
+        renderer.on('active', activeCb)
+        this[symbols.rendererEventListeners].push({ event: 'idle', cb: idleCb })
+        this[symbols.rendererEventListeners].push({ event: 'active', cb: activeCb })
+      })
+    }
+
     // register hooks if component has hooks specified
     if (config.hooks) {
-      // push to next tick to ensure
-      setTimeout(() => {
-        // frame tick event
-        if (config.hooks.frameTick) {
-          const cb = (r, data) => emit('frameTick', this[symbols.identifier], this, [data])
-          this[symbols.rendererEventListeners].push({ event: 'frameTick', cb })
-          renderer.on('frameTick', cb)
-        }
+      // frame tick event
+      if (config.hooks.frameTick) {
+        const cb = (_r, data) => emit('frameTick', this[symbols.identifier], this, [data])
+        renderer.on('frameTick', cb)
+        this[symbols.rendererEventListeners].push({ event: 'frameTick', cb })
+      }
 
-        // idle event
-        if (config.hooks.idle) {
-          const cb = () => {
-            emit('idle', this[symbols.identifier], this)
-          }
-          this[symbols.rendererEventListeners].push({ event: 'idle', cb })
-          renderer.on('idle', cb)
+      // idle event
+      if (config.hooks.idle) {
+        const idleCb = () => {
+          emit('idle', this[symbols.identifier], this, [true])
         }
+        const activeCb = () => {
+          emit('idle', this[symbols.identifier], this, [false])
+        }
+        renderer.on('idle', idleCb)
+        renderer.on('active', activeCb)
+        this[symbols.rendererEventListeners].push({ event: 'idle', cb: idleCb })
+        this[symbols.rendererEventListeners].push({ event: 'active', cb: activeCb })
+      }
 
-        // fpsUpdate event
-        if (config.hooks.fpsUpdate) {
-          const cb = (r, data) => {
-            emit('fpsUpdate', this[symbols.identifier], this, [data.fps])
-          }
-          this[symbols.rendererEventListeners].push({ event: 'fpsUpdate', cb })
-          renderer.on('fpsUpdate', cb)
+      // fpsUpdate event
+      if (config.hooks.fpsUpdate) {
+        const cb = (_r, data) => {
+          emit('fpsUpdate', this[symbols.identifier], this, [data.fps])
         }
-      })
+        renderer.on('fpsUpdate', cb)
+        this[symbols.rendererEventListeners].push({ event: 'fpsUpdate', cb })
+      }
 
       // inBounds event emiting a lifecycle attach event
       if (config.hooks.attach) {