@lightningjs/blits 1.47.0 → 1.49.0

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+
+## 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
+- Fixed double processiong of reactivity guard
+
+## v1.48.0
+
+_10 feb 2026_
+
+- Improved cleanup of for-loop effects
+- Fixed router issue with params not being reset
+- Added next tick debouncing for transitions on multiple props
+- Bumped renderer to 2.21.0
+- Added support for using function-notation in `@loaded`, `@error` and `@updated` callbacks
+- Added displaying of correct component type in inspector data when using `is`-attribute
+- Replaced `$`-prefix for automatic inspector data with `blits-` prefix (fixes fatal error in Safari)
+
+
 ## v1.47.0
 
 _26 jan 2026_

package/index.d.ts

@@ -201,11 +201,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
     *
@@ -666,9 +669,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 +697,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 +812,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 = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lightningjs/blits",
-  "version": "1.47.0",
+  "version": "1.49.0",
   "description": "Blits: The Lightning 3 App Development Framework",
   "bin": "bin/index.js",
   "exports": {
@@ -74,7 +74,7 @@
   },
   "dependencies": {
     "@lightningjs/msdf-generator": "^1.2.0",
-    "@lightningjs/renderer": "^2.20.4",
+    "@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/scripts/prepush.js

@@ -69,7 +69,6 @@ try {
   // Run ESLint on the changed files
   execSync(`npx eslint ${fileList.join(' ')}`, { stdio: 'inherit' })
   console.log('Linting passed successfully!\n')
-  process.exit(0)
 } catch (error) {
   console.log('\n==========================================================================')
   console.log('ESLint found issues in your code. Please fix them before pushing.')
@@ -79,3 +78,24 @@ try {
   console.log('==========================================================================\n')
   process.exit(1)
 }
+
+// By default, always run tests unless RUN_TEST=skip
+const runTestsFlag = process.env.RUN_TEST || ''
+
+if (runTestsFlag.toLowerCase() === 'skip') {
+  console.log('Skipping tests due to RUN_TEST=skip. Proceeding with push.')
+  process.exit(0)
+} else {
+  // For any other value (including empty or unknown), run tests
+  try {
+    console.log('Running tests...\n')
+    execSync('npm run test', { stdio: 'inherit' })
+    console.log('Tests passed successfully!\n')
+    process.exit(0)
+  } catch (error) {
+    console.log('\n==========================================================================')
+    console.log('Some tests failed. Please fix them before pushing.')
+    console.log('==========================================================================\n')
+    process.exit(1)
+  }
+}

package/src/component.js

@@ -267,33 +267,60 @@ 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(() => {
+      this.$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 })
+          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)
+          const idleCb = () => {
+            emit('idle', this[symbols.identifier], this, [true])
+          }
+          const activeCb = () => {
+            emit('idle', this[symbols.identifier], this, [false])
           }
-          this[symbols.rendererEventListeners].push({ event: 'idle', cb })
-          renderer.on('idle', cb)
+          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) => {
+          const cb = (_r, data) => {
             emit('fpsUpdate', this[symbols.identifier], this, [data.fps])
           }
-          this[symbols.rendererEventListeners].push({ event: 'fpsUpdate', cb })
           renderer.on('fpsUpdate', cb)
+          this[symbols.rendererEventListeners].push({ event: 'fpsUpdate', cb })
         }
       })
 
@@ -450,6 +477,9 @@ const Component = (name = required('name'), config = required('config')) => {
   // during the code generation step
   factory[Symbol.for('config')] = config
 
+  // Display name for inspector
+  factory[Symbol.for('componentType')] = name
+
   // To determine whether dynamic component is actual Blits component or not
   factory[symbols.isComponent] = true
 

package/src/engines/L3/element.js

@@ -602,7 +602,7 @@ const Element = {
       this.props.props['data'] = {}
     }
 
-    // Merge framework data (with $ prefix to prevent collisions)
+    // Merge framework data (blits-* keys data attributes)
     Object.assign(this.props['data'], data)
     Object.assign(this.props.props['data'], data)
 
@@ -656,13 +656,31 @@ const Element = {
     }
   },
   animate(prop, value, transition) {
+    // Clear any existing debounce timeout for this property
+    if (this.debounceTimeouts[prop] !== undefined) {
+      clearTimeout(this.debounceTimeouts[prop])
+      Log.debug(`Cleared debounce timeout for property "${prop}"`)
+    }
+
+    // Debounce the animation execution
+    this.debounceTimeouts[prop] = setTimeout(() => {
+      delete this.debounceTimeouts[prop]
+      this._executeAnimation(prop, value, transition)
+    }, 0)
+  },
+  _executeAnimation(prop, value, transition) {
     // check if a transition is already scheduled to run on the same prop
     // and cancels it if it does
+    const stateOfAnimation =
+      this.scheduledTransitions[prop] !== undefined
+        ? this.scheduledTransitions[prop].f.state
+        : undefined
+
     if (
-      this.scheduledTransitions[prop] !== undefined &&
-      this.scheduledTransitions[prop].f.state === 'scheduled'
+      stateOfAnimation !== undefined &&
+      (stateOfAnimation === 'scheduled' || stateOfAnimation === 'running')
     ) {
-      this.scheduledTransitions[prop].f.stop()
+      this.scheduledTransitions[prop].f.stop(stateOfAnimation === 'running' ? false : true)
     }
 
     // if current value is the same as the value to animate to, instantly resolve
@@ -700,7 +718,7 @@ const Element = {
 
     // Update inspector metadata when transition starts
     if (inspectorEnabled === true) {
-      this.setInspectorMetadata({ $isTransitioning: true })
+      this.setInspectorMetadata({ 'blits-isTransitioning': true })
     }
 
     if (transition.start !== undefined && typeof transition.start === 'function') {
@@ -740,7 +758,7 @@ const Element = {
       // Update inspector metadata when transition ends
       if (inspectorEnabled === true) {
         this.setInspectorMetadata({
-          $isTransitioning: Object.keys(this.scheduledTransitions).length > 0,
+          'blits-isTransitioning': Object.keys(this.scheduledTransitions).length > 0,
         })
       }
     })
@@ -752,6 +770,14 @@ const Element = {
     if (this.node === null) return
 
     Log.debug('Deleting Node', this.nodeId)
+
+    // Clear all pending debounce timeouts
+    const debounceProps = Object.keys(this.debounceTimeouts)
+    for (let i = 0; i < debounceProps.length; i++) {
+      clearTimeout(this.debounceTimeouts[debounceProps[i]])
+    }
+    this.debounceTimeouts = null
+
     // Clearing transition end callback functions
     const transitionProps = Object.keys(this.scheduledTransitions)
     for (let i = 0; i < transitionProps.length; i++) {
@@ -834,6 +860,7 @@ export default (config, component) => {
   return Object.assign(Object.create(Element), {
     props: Object.assign(Object.create(propsTransformer), { props: {} }),
     scheduledTransitions: {},
+    debounceTimeouts: {},
     config,
     component,
   })

package/src/lib/codegenerator/generator.js

@@ -360,17 +360,17 @@ const generateComponentCode = function (
     }
   `)
 
-  // For forloops, this code runs per instance, setting metadata for each component instance
   if (isDev === true) {
-    const componentType = templateObject[Symbol.for('componentType')]
+    const templateTagName = templateObject[Symbol.for('componentType')]
     const holderElm = options.key
       ? `elms[${holderCounter}][${options.key}]`
       : `elms[${holderCounter}]`
+    const componentDisplayName = `typeof componentType === 'string'
+      ? componentType
+      : (componentType?.[Symbol.for('componentType')] || '${templateTagName}')`
     renderCode.push(`
       if (${holderElm} !== undefined && typeof ${holderElm}.setInspectorMetadata === 'function') {
-        ${holderElm}.setInspectorMetadata({
-          $componentType: '${componentType}'
-        })
+        ${holderElm}.setInspectorMetadata({ 'blits-componentType': ${componentDisplayName} })
       }
     `)
   }
@@ -503,10 +503,16 @@ const generateForLoopCode = function (templateObject, parent) {
 
       component !== null && component[Symbol.for('removeGlobalEffects')](effects[${forStartCounter}])
 
-      for(let i = 0; i < effects[${forStartCounter}].length; i++) {
-        const value = effects[${forStartCounter}][i]
-        const index = component[Symbol.for('effects')].indexOf(value)
-        if (index > -1) component[Symbol.for('effects')].splice(index, 1)
+     const effectsToRemove = new Set(effects[${forStartCounter}].slice(0))
+      if (effectsToRemove.size > 0) {
+        const componentEffects = component?.[Symbol.for('effects')] || []
+        let writeIndex = 0
+        for (let readIndex = 0; readIndex < componentEffects.length; readIndex++) {
+          if (!effectsToRemove.has(componentEffects[readIndex])) {
+            componentEffects[writeIndex++] = componentEffects[readIndex]
+          }
+        }
+        componentEffects.length = writeIndex
       }
 
       effects[${forStartCounter}].length = 0
@@ -804,8 +810,13 @@ const cast = (val = '', key = false, component = 'component.') => {
   }
   // @-listener
   else if (key.startsWith('@') && val) {
-    const c = component.slice(0, -1)
-    castedValue = `${c}['${val.replace('$', '')}'] && ${c}['${val.replace('$', '')}'].bind(${c})`
+    const trimmed = val.trim()
+    if (/^\$?\w+$/.test(trimmed)) {
+      const c = component.slice(0, -1)
+      castedValue = `${c}['${trimmed.replace('$', '')}'] && ${c}['${trimmed.replace('$', '')}'].bind(${c})`
+    } else {
+      castedValue = interpolate(trimmed, component)
+    }
   }
   // dynamic value
   else if (val.startsWith('$')) {

package/src/lib/lifecycle.js

@@ -97,7 +97,7 @@ export default {
           this.component[symbols.holder] &&
           typeof this.component[symbols.holder].setInspectorMetadata === 'function'
         ) {
-          this.component[symbols.holder].setInspectorMetadata({ $hasFocus: true })
+          this.component[symbols.holder].setInspectorMetadata({ 'blits-hasFocus': true })
         }
       }
       if (v === 'unfocus') {
@@ -107,7 +107,7 @@ export default {
           this.component[symbols.holder] &&
           typeof this.component[symbols.holder].setInspectorMetadata === 'function'
         ) {
-          this.component[symbols.holder].setInspectorMetadata({ $hasFocus: false })
+          this.component[symbols.holder].setInspectorMetadata({ 'blits-hasFocus': false })
         }
       }
     }

package/src/lib/reactivity/effect.js

@@ -32,9 +32,10 @@ const objectMap = new WeakMap()
 const globalEffectsMap = new Map()
 
 export const removeGlobalEffects = (effectsToRemove) => {
-  if (globalEffectsMap.size === 0) return
+  if (globalEffectsMap.size === 0 || effectsToRemove.length === 0) return
+  const effectsToRemoveSet = new Set(effectsToRemove)
   for (const [effect, target] of globalEffectsMap) {
-    if (effectsToRemove.indexOf(effect) === -1) continue
+    if (!effectsToRemoveSet.has(effect)) continue
     const effectsSet = objectMap.get(target)
     if (effectsSet === undefined) continue
     for (const set of effectsSet.values()) {

package/src/lib/reactivityguard/computedprops.js

@@ -195,7 +195,7 @@ export default (code) => {
           if (thisRefs.size > 0) {
             // Skip if already modified
             if (
-              prop.body.includes(commentText) ||
+              prop.body.includes(commentText.trim()) ||
               Array.from(thisRefs).some((ref) => prop.body.startsWith(ref))
             ) {
               continue

package/src/router/router.js

@@ -403,7 +403,7 @@ export const navigate = async function () {
       // Update router state after announcements and final route resolution,
       // right before initializing or restoring the view
       state.path = route.path
-      state.params = route.params || {}
+      state.params = Object.keys(route.params).length === 0 ? null : route.params
       state.hash = route.hash
       state.data = null
       state.data = route.data || {}