@lightningjs/blits 2.9.0 → 2.11.0

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # Changelog
 
+## 2.11.0
+
+_28 sep 2026_
+
+- Improved `$select()` method by adding caching
+- Upgraded several dependencies
+- Bumped renderer to 3.5.1
+
+## 2.10.0
+
+_21 sep 2026_
+
+- Fixed / improved type definitions
+- Fixed issue with accidental sideeffect running when `$hasFocus` triggers after destroy
+- Fixed issue where an error in an effect can break execution of other effects
+- Added support for reactivity of `array.length`
+- Improved reactivity in the case of nested array operations
+- Fixed case where transition callbacks could run after destroy
+- Fixed case where keyup callback could fire after component destroy
+- Improved error handling and parse rejection for fetchJson method
+- Fixed typing of `fpsUpdate`
+- Added textCalculated listener to trigger layout changes
+- Added `mouseMoveThrottle` setting to configure responsiveness of mouse movements
+- Fixed issue where hover is not recognized after keyboard use
+- Added support for numeric rgba colors
+- Bumped renderer to 3.5.0
+
 ## 2.9.0
 
 _9 sep 2026_

package/index.d.ts

@@ -18,7 +18,7 @@
 // blits file type reference
 /// <reference path="./blits.d.ts" />
 
-import {type ShaderEffect as RendererShaderEffect, type RendererMainSettings} from '@lightningjs/renderer'
+import {type ShaderEffect as RendererShaderEffect, type RendererMainSettings, type FrameCounter} from '@lightningjs/renderer'
 import { CanvasShaderType } from '@lightningjs/renderer/canvas';
 import { WebGlShaderType } from '@lightningjs/renderer/webgl';
 
@@ -242,7 +242,7 @@ declare module '@lightningjs/blits' {
     *
     * Note: This event fire multiple times
     */
-    fpsUpdate?: (fps: number) => void;
+    fpsUpdate?: (fps: number, frameCounter: FrameCounter) => void;
   }
 
   export interface Input {
@@ -642,7 +642,9 @@ declare module '@lightningjs/blits' {
   type InferProp<T> = T extends (...args: any[]) => any ? ReturnType<T> : T
 
   type InferProps<T extends Record<string, any>> = {
-    [K in keyof T]: InferProp<T[K]>
+    // Since InferProps is no longer used for `Computed` props,
+    // then we do not need to infer the return type of a function-typed prop in `Props`.
+    [K in keyof T]: T[K]
   }
 
   type Computed<T extends Record<string, () => any>> = {
@@ -653,7 +655,7 @@ declare module '@lightningjs/blits' {
     P extends Record<string, any>,
     S,
     M,
-    C extends Record<string, () => any>,
+    C extends Record<string, () => any> = Record<never, never>,
   > = ThisType<
     Readonly<InferProps<P>> & S & M & Computed<C> & ChildComponentBase
   >
@@ -662,14 +664,14 @@ declare module '@lightningjs/blits' {
     P extends Record<string, any>,
     S,
     M,
-    C,
+    C extends Record<string, () => any> = Record<never, never>,
   > = ThisType<Readonly<InferProps<P>> & S & M & Computed<C> & ApplicationBase>
 
   export interface ComponentConfig<
     P extends Props = {},
     S,
     M,
-    C extends Record<string, () => any>,
+    C extends Record<string, () => any> = Record<never, never>,
     W,
   > {
     components?: {
@@ -1408,6 +1410,14 @@ declare module '@lightningjs/blits' {
      */
     enableMouse?: boolean,
     /**
+     * Minimum time in milliseconds between two pointer moves that are processed for hover.
+     *
+     * Moves arriving sooner are dropped, not delayed.
+     *
+     * @default 100
+     */
+    mouseMoveThrottle?: number,
+      /**
      * Maximum FPS at which the App will be rendered
      *
      * Lowering the maximum FPS value can improve the overall experience on lower end devices.
@@ -1478,7 +1488,7 @@ declare module '@lightningjs/blits' {
       P extends Props,
       S extends State,
       M extends Methods,
-      C extends Computed,
+      C extends Computed = Record<never, never>,
       W extends Watch>(config: ApplicationConfig<P, S, M, C, W>) : ComponentFactory
       /**
      * Blits Component
@@ -1489,7 +1499,7 @@ declare module '@lightningjs/blits' {
       P extends Props,
       S extends State,
       M extends Methods,
-      C extends Computed,
+      C extends Computed = Record<never, never>,
       W extends Watch>(name: string, config: ComponentConfig<P, S, M, C, W>) : ComponentFactory
     /**
      * Blits Launch
@@ -1526,4 +1536,5 @@ declare module '@lightningjs/blits' {
   const Blits: Blits;
 
   export default Blits;
+
 }

package/package.json

@@ -1,10 +1,14 @@
 {
   "name": "@lightningjs/blits",
-  "version": "2.9.0",
+  "version": "2.11.0",
   "description": "Blits: The Lightning 3 App Development Framework",
   "bin": "bin/index.js",
   "exports": {
     ".": "./index.js",
+    "./colors": {
+      "types": "./src/lib/colors/htmlColors.d.ts",
+      "default": "./src/lib/colors/htmlColors.js"
+    },
     "./platforms": {
       "types": "./src/platforms.d.ts",
       "default": "./src/platforms.js"
@@ -70,29 +74,29 @@
   "author": "Michiel van der Geest <hello@michielvandergeest.com>",
   "license": "Apache-2.0",
   "devDependencies": {
-    "@babel/eslint-parser": "^7.26.5",
-    "@babel/plugin-syntax-import-assertions": "^7.26.0",
-    "@eslint/eslintrc": "^3.3.1",
-    "@eslint/js": "^9.33.0",
-    "c8": "^9.1.0",
-    "eslint": "^9.33.0",
+    "@babel/eslint-parser": "^7.28.6",
+    "@babel/plugin-syntax-import-assertions": "^7.28.6",
+    "@eslint/eslintrc": "^3.3.4",
+    "@eslint/js": "^9.39.3",
+    "c8": "^12.0.0",
+    "eslint": "^9.39.3",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-prettier": "^5.5.4",
     "fast-glob": "^3.3.3",
-    "global-jsdom": "24.0.0",
-    "globals": "^16.3.0",
+    "global-jsdom": "^30.0.0",
+    "globals": "^17.12.0",
     "husky": "^9.1.7",
-    "jsdom": "24.0.0",
-    "lint-staged": "^15.5.0",
+    "jsdom": "^30.1.0",
+    "lint-staged": "^15.5.2",
     "prettier": "^3.6.2",
-    "sinon": "^21.0.0",
+    "sinon": "^22.1.0",
     "tap-diff": "^0.1.1",
     "tap-filter": "^1.0.3",
-    "tape": "^5.5.0"
+    "tape": "^5.9.0"
   },
   "dependencies": {
-    "@lightningjs/renderer": "3.3.1",
-    "magic-string": "^0.30.21"
+    "@lightningjs/renderer": "3.5.1",
+    "magic-string": "^1.4.1"
   },
   "repository": {
     "type": "git",

package/src/application.js

@@ -15,7 +15,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import { default as Component, componentMap } from './component.js'
+import { componentMap, default as Component } from './component.js'
 import { default as Focus, keyUpCallbacks } from './focus/focus.js'
 import Hover from './focus/hover.js'
 
@@ -80,6 +80,7 @@ const Application = (config) => {
     const throttleMs = Settings.get('inputThrottle', 0)
 
     const mouseEnabled = Settings.get('enableMouse', false)
+    const mouseMoveThrottle = Settings.get('mouseMoveThrottle', 100)
     const { createKeyboardEvent, input, isKeyboardEvent, now = Date.now, viewport } = platform
 
     keyDownHandler = async (e) => {
@@ -114,7 +115,11 @@ const Application = (config) => {
       }
 
       Focus.input(key, e)
-      if (mouseEnabled === true) Hover.clear()
+      if (mouseEnabled === true) {
+        Hover.clear()
+        // forget the node under the pointer too, so moving on it hovers it again
+        currentNode = undefined
+      }
       clearTimeout(holdTimeout)
       holdTimeout = setTimeout(
         () => {
@@ -125,10 +130,12 @@ const Application = (config) => {
     }
 
     keyUpHandler = (e) => {
-      const cb = keyUpCallbacks.get(e.keyCode)
-      if (cb !== undefined && typeof cb === 'function') {
+      const entry = keyUpCallbacks.get(e.keyCode)
+      if (entry !== undefined) {
         keyUpCallbacks.delete(e.keyCode)
-        cb()
+        if (entry.component.eol !== true && typeof entry.callback === 'function') {
+          entry.callback()
+        }
       }
       clearTimeout(holdTimeout)
       Focus.hold = false
@@ -147,7 +154,7 @@ const Application = (config) => {
 
     // limit the amount of move events per time frame
     mouseMoveHandler = (e) => {
-      if (e.timeStamp - lastMoved < 100) return
+      if (e.timeStamp - lastMoved < mouseMoveThrottle) return
       lastMoved = e.timeStamp
 
       this.$emit('mouse::move', e)

package/src/component/base/methods.js

@@ -16,7 +16,12 @@
  */
 
 import symbols from '../../lib/symbols.js'
-import { default as Focus, keyUpCallbacks, getComponentWithInputEvent } from '../../focus/focus.js'
+import {
+  default as Focus,
+  keyUpCallbacks,
+  getComponentWithInputEvent,
+  removeKeyUpCallbacks,
+} from '../../focus/focus.js'
 import eventListeners from '../../lib/eventListeners.js'
 import { trigger } from '../../lib/reactivity/effect.js'
 import { Log } from '../../lib/log.js'
@@ -25,6 +30,8 @@ import { renderer } from '../../launch.js'
 import { keyMap } from '../../application.js'
 import { platform } from '../../platform.js'
 
+const selectCache = new WeakMap()
+
 export default {
   $focus: {
     /**
@@ -71,7 +78,7 @@ export default {
       }
 
       if (cb !== undefined && event.keyCode) {
-        keyUpCallbacks.set(event.keyCode, cb)
+        keyUpCallbacks.set(event.keyCode, { callback: cb, component: componentWithInputEvent })
       }
 
       return true
@@ -98,14 +105,16 @@ export default {
      */
     value: function () {
       this.eol = true
+      selectCache.delete(this)
+      removeKeyUpCallbacks(this)
       this[symbols.lifecycle].state = 'destroy'
 
+      removeEffects(this[symbols.effects])
+
       // when destroying a component that currently has focus
       // pass focus to the parent so we don't get lost in focus limbo
       if (this.$hasFocus === true) this[symbols.parent].$focus()
 
-      removeEffects(this[symbols.effects])
-
       // @todo - is this really necessary?
       // This cause an issue with auto sizing of parent (and required an extra eol check there)
       for (let key in this[symbols.state]) {
@@ -191,26 +200,60 @@ export default {
       // early exit when component is marked as end of life
       if (this.eol === true) return
 
-      let selected = null
-      this[symbols.children].forEach((child) => {
+      let cache = selectCache.get(this)
+      if (cache !== undefined && cache.has(ref) === true) {
+        const selected = cache.get(ref)
+        if (selected !== undefined && selected.eol !== true) return selected
+        cache.delete(ref)
+      }
+
+      for (const child of this[symbols.children]) {
+        if (child === undefined || child === null) continue
         if (Array.isArray(child)) {
-          child.forEach((c) => {
-            if (c['ref'] === ref) selected = c
-          })
+          const selected = child.find((c) => c['ref'] === ref)
+          if (selected !== undefined) {
+            if (cache === undefined) {
+              cache = new Map()
+              selectCache.set(this, cache)
+            }
+            cache.set(ref, selected)
+            return selected
+          }
         } else if (Object.getPrototypeOf(child) === Object.prototype) {
-          Object.keys(child).forEach((k) => {
-            if (child[k]['ref'] === ref) selected = child[k]
-          })
+          const selected = Object.values(child).find((c) => c['ref'] === ref)
+          if (selected !== undefined) {
+            if (cache === undefined) {
+              cache = new Map()
+              selectCache.set(this, cache)
+            }
+            cache.set(ref, selected)
+            return selected
+          }
         } else {
-          if (child['ref'] === ref) selected = child
+          if (child['ref'] === ref) {
+            if (cache === undefined) {
+              cache = new Map()
+              selectCache.set(this, cache)
+            }
+            cache.set(ref, child)
+            return child
+          }
         }
-      })
-      return selected
+      }
+      return null
     },
     writable: false,
     enumerable: true,
     configurable: false,
   },
+  [symbols.invalidateSelectCache]: {
+    value: function () {
+      selectCache.delete(this)
+    },
+    writable: false,
+    enumerable: false,
+    configurable: false,
+  },
   $trigger: {
     /**
      * @this {import('../../component').BlitsComponent}

package/src/engines/L3/element.js

@@ -275,7 +275,9 @@ const propsTransformer = {
     this.props['zIndex'] = v
   },
   set color(v) {
-    if (typeof v === 'string' && v.startsWith('{') === false) {
+    if (typeof v === 'number') {
+      this.props['color'] = v
+    } else if (typeof v === 'string' && v.startsWith('{') === false) {
       this.props['color'] = colors.normalize(v)
     } else if (typeof v === 'object' || (isObjectString(v) === true && (v = parseToObject(v)))) {
       this.props['color'] = 0
@@ -649,10 +651,11 @@ const Element = {
     if (this.props.props['color'] === undefined && '__textnode' in props === false) {
       this.props.props['color'] = 0
     }
-
-    this.node = props.__textnode
-      ? renderer.createTextNode({ ...textDefaults, ...this.props.props })
-      : renderer.createNode(this.props.props)
+    const isTextNode = props.__textnode
+    this.node =
+      isTextNode === true
+        ? renderer.createTextNode({ ...textDefaults, ...this.props.props })
+        : renderer.createNode(this.props.props)
 
     if (this.props['holder'] === true) {
       holderComponentMap.set(this.node, this.component)
@@ -680,7 +683,8 @@ const Element = {
 
     if (this.config.parent.props !== undefined && this.config.parent.props.__layout === true) {
       this.config.parent.triggerLayout(this.config.parent.props)
-      this.node.on('loaded', () => {
+
+      this.node.on(isTextNode === true ? 'textCalculated' : 'loaded', () => {
         if (this.eol === true) return
         this.config.parent.triggerLayout(this.config.parent.props)
       })
@@ -809,6 +813,20 @@ const Element = {
     // @ts-ignore
     this.props.raw[prop] = value
 
+    if (prop === 'color' && typeof value === 'number') {
+      // A gradient can share its base color with the new solid color (notably zero).
+      // The renderer skips equal base colors, so reset its sides in that case.
+      if (this.node.color === value) {
+        this.node.colorTop = value
+        this.node.colorBottom = value
+        this.node.colorLeft = value
+        this.node.colorRight = value
+      }
+      // Use the renderer setter to invalidate colors, including text colors.
+      this.node.color = value
+      return
+    }
+
     this.props.props = {}
     // @ts-ignore
     this.props[prop] = unpackTransition(value)
@@ -908,6 +926,7 @@ const Element = {
     if (transition.start !== undefined && typeof transition.start === 'function') {
       // fire transition start callback when animation really starts (depending on specified delay)
       f.once('animating', () => {
+        if (this.eol === true) return
         transition.start.call(this.component, this, prop, startValue)
       })
     }
@@ -929,6 +948,7 @@ const Element = {
     }
 
     f.once('stopped', () => {
+      if (this.eol === true) return
       if (
         this.scheduledTransitions[prop] !== undefined &&
         this.scheduledTransitions[prop].canceled === true
@@ -936,7 +956,7 @@ const Element = {
         return
       }
       // fire transition end callback when animation ends (if specified)
-      if (this.node !== undefined && transition.end && typeof transition.end === 'function') {
+      if (transition.end && typeof transition.end === 'function') {
         transition.end.call(this.component, this, prop, this.node[prop])
       }
       // remove the prop from scheduled transitions
@@ -1010,7 +1030,7 @@ const Element = {
     delete this.forComponent
 
     this.node.destroy()
-    this.node = null
+    this.node = undefined
   },
   get nodeId() {
     return this.node && this.node.id

package/src/focus/focus.js

@@ -29,6 +29,12 @@ let setFocusTimeout
 
 export const keyUpCallbacks = new Map()
 
+export const removeKeyUpCallbacks = (component) => {
+  for (const [keyCode, entry] of keyUpCallbacks) {
+    if (entry.component === component) keyUpCallbacks.delete(keyCode)
+  }
+}
+
 export default {
   _hold: false,
   set hold(v) {
@@ -99,7 +105,7 @@ export default {
     }
 
     if (cb !== undefined) {
-      keyUpCallbacks.set(event.keyCode, cb)
+      keyUpCallbacks.set(event.keyCode, { callback: cb, component: componentWithInputEvent })
     }
   },
 }

package/src/helpers/fetchJson.js

@@ -22,10 +22,18 @@ export default (file) => {
       if (xhr.readyState == XMLHttpRequest.DONE) {
         // file protocol returns 0
         // http(s) protocol returns 200
-        if (xhr.status === 0 || xhr.status === 200) resolve(JSON.parse(xhr.responseText))
-        else reject(xhr.statusText)
+        if (xhr.status === 0 || xhr.status === 200) {
+          try {
+            resolve(JSON.parse(xhr.responseText))
+          } catch (err) {
+            reject(err)
+          }
+        } else reject(xhr.statusText || xhr.status)
       }
     }
+
+    xhr.onerror = () => reject(new Error('Network request failed'))
+
     xhr.open('GET', file)
     xhr.send(null)
   })

package/src/lib/codegenerator/generator.js

@@ -223,6 +223,9 @@ const generateElementCode = function (
 
     if (key === 'key') return
 
+    // a ref on a component belongs to the component itself, not to its holder element
+    if (options.holder === true && (key === 'ref' || key === ':ref')) return
+
     // Skip inspector-data in production builds for performance optimization
     if (key === 'inspector-data' && !isDev) return
 
@@ -524,6 +527,8 @@ const generateForLoopCode = function (templateObject, parent) {
     }
   }
 
+  const invalidateSelectCache = 'ref' in templateObject
+
   ctx.renderCode.push(`
     created[${forStartCounter}] = []
     effects[${forStartCounter}] = []
@@ -532,6 +537,7 @@ const generateForLoopCode = function (templateObject, parent) {
     let to${forStartCounter}
 
     forloops[${forStartCounter}] = (collection = [], elms, created) => {
+      ${invalidateSelectCache ? "rootComponent && rootComponent[Symbol.for('invalidateSelectCache')]()" : ''}
       const rawCollection = getRaw(collection)
       const keys = new Set()
       let l = rawCollection.length

package/src/lib/colors/colors.js

@@ -15,7 +15,9 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import colorsMap from './htmlColors.js'
+import htmlColors from './htmlColors.js'
+
+const colorsMap = { ...htmlColors }
 
 const hex = /^#?([0-9a-f]{3}|[0-9a-f]{6}|[0-9a-f]{8})$/i
 const rgba =

package/src/lib/colors/htmlColors.d.ts

@@ -0,0 +1,4 @@
+/** Known HTML color names mapped to hexadecimal RGBA strings, including transparent. */
+declare const htmlColors: Readonly<Record<string, `0x${string}` | undefined>>
+
+export default htmlColors

package/src/lib/reactivity/effect.js

@@ -18,14 +18,17 @@
 let currentEffect = null
 let currentKey = null
 
-let paused = false
+// counter that tracks all pauseTracking invocations
+// to ensure nested array operations don't prematurely
+// resume before all operations have completed
+let pauseCounter = 0
 
 export const pauseTracking = () => {
-  paused = true
+  pauseCounter++
 }
 
 export const resumeTracking = () => {
-  paused = false
+  if (pauseCounter > 0) pauseCounter--
 }
 
 const objectMap = new WeakMap()
@@ -45,7 +48,7 @@ export const removeEffects = (effectsToRemove) => {
 
 export const track = (target, key) => {
   if (currentEffect !== null) {
-    if (paused) {
+    if (pauseCounter > 0) {
       return
     }
     // note: nesting the conditions like this seems to perform better ¯\_(ツ)_/¯
@@ -76,7 +79,7 @@ export const track = (target, key) => {
 }
 
 export const trigger = (target, key, force = false) => {
-  if (paused === true) return
+  if (pauseCounter > 0) return
   const effectsMap = objectMap.get(target)
   if (effectsMap === undefined) {
     return
@@ -89,10 +92,17 @@ export const trigger = (target, key, force = false) => {
   }
 }
 
-export const effect = (effect, key = null) => {
-  currentEffect = effect
+export const effect = (effectFn, key = null) => {
+  const previousEffect = currentEffect
+  const previousKey = currentKey
+
+  currentEffect = effectFn
   currentKey = key
-  currentEffect()
-  currentEffect = null
-  currentKey = null
+
+  try {
+    effectFn()
+  } finally {
+    currentEffect = previousEffect
+    currentKey = previousKey
+  }
 }

package/src/lib/reactivity/reactive.js

@@ -67,9 +67,19 @@ const reactiveProxy = (original, _parent = null, _key) => {
         // augment array path methods (that change the length of the array)
         if (arrayPatchMethods.indexOf(key) !== -1) {
           return function (...args) {
+            const oldLength = target.length
             pauseTracking()
-            const result = target[key].apply(this, args)
-            resumeTracking()
+            let result
+            try {
+              result = target[key].apply(this, args)
+            } finally {
+              resumeTracking()
+            }
+            // trigger a change when the length of the array has changed
+            // by the array operation
+            if (_parent === null && target.length !== oldLength) {
+              trigger(target, 'length')
+            }
             // trigger a change on the parent object and the key
             // i.e. when pushing a new item to `obj.data`, _parent will equal `obj`
             // and _key will equal `data`
@@ -78,6 +88,10 @@ const reactiveProxy = (original, _parent = null, _key) => {
           }
         }
         if (key === 'length') {
+          // only track root level to prevent double reactive executions
+          if (_parent === null) {
+            track(target, 'length')
+          }
           return original.length
         }
 

package/src/lib/symbols.js

@@ -144,4 +144,6 @@ export default {
   removeEffects: Symbol.for('removeEffects'),
   // Symbol 'tagContent' utilized within generated code
   tagContent: Symbol.for('tagContent'),
+  // Symbol used by generated loops to invalidate cached ref lookups
+  invalidateSelectCache: Symbol.for('invalidateSelectCache'),
 }

package/src/plugins/language.js

@@ -55,7 +55,7 @@ export default {
     }
 
     const setDict = (language) => {
-      return new Promise((resolve) => {
+      return new Promise((resolve, reject) => {
         const translationObj = translations[language]
         if (typeof translationObj === 'object') {
           dictionary = translationObj
@@ -71,6 +71,7 @@ export default {
             })
             .catch((e) => {
               Log.error(e)
+              reject(e)
             })
         }
       })

package/src/plugins/storage/storage.js

@@ -17,11 +17,11 @@
 
 import localCookie from './localCookie.js'
 
-let lc = new localCookie()
-
 export default {
   name: 'storage',
   plugin() {
+    const lc = new localCookie()
+
     return {
       get(key) {
         try {

package/src/plugins/theme.js

@@ -111,7 +111,6 @@ export default {
         if (theme in themes) {
           themeMap = {}
           state.variant = theme
-          console.log('change variant', theme)
         } else {
           Log.warn(`Variant ${theme} not found`)
         }