@lightningjs/blits 1.45.1 → 1.46.0

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## v1.46.0
+
+_22 jan 2026_
+
+- Improved Announcer on Comcast devices
+- Added new `afterEach` router hook
+- Added router option to dynamically disable `back`-key handling by the router
+- Added `this.$debounce`-method
+- Added automatic inspector data items (`$componentType`, `$hasFocus` and `$isTransitioning`)
+- Added functionality to auto size the holder node of a Component when the wrapper Element has dimensions
+- Bumped Lightning renderer to v2.20.4 with correct handling of failed textures
+
+## v1.45.2
+
+_13 jan 2026_
+
+- Updated renderer to v2.20.2
+
 ## v1.45.1
 
 _29 dec 2025_

package/index.d.ts

@@ -54,6 +54,12 @@ declare module '@lightningjs/blits' {
      * @default 1
      */
     volume?: number,
+    /**
+     * Whether to enable utterance keep-alive (prevents pausing on some platforms)
+     *
+     * @default undefined
+     */
+    enableUtteranceKeepAlive?: boolean
   }
 
   export interface AnnouncerUtterance<T = any> extends Promise<T> {
@@ -321,6 +327,11 @@ declare module '@lightningjs/blits' {
     */
     back(): boolean;
 
+    /**
+     * Enable or disable RouterView history navigation on Back input
+     */
+    backNavigation: boolean;
+
     /**
      * Get the current route read-only
     */
@@ -328,17 +339,17 @@ declare module '@lightningjs/blits' {
 
     /**
      * Get the list of all routes
-     */
+    */
     readonly routes: Route[];
 
     /**
      * Get navigating state
-     */
+    */
     readonly navigating: boolean;
 
     /**
      * Reactive router state
-     */
+    */
     state: {
       /**
        * Path of the current route
@@ -371,28 +382,6 @@ declare module '@lightningjs/blits' {
     // Empty by design: extend in your app via TypeScript module augmentation.
   }
 
-  export interface LanguagePlugin {
-    translate(key: string, ...replacements: any[]): string
-    readonly language: string
-    set(language: string): void
-    translations(translationsObject: Record<string, unknown>): void
-    load(file: string): Promise<void>
-  }
-
-  export interface ThemePlugin {
-    get<T = unknown>(key: string): T | undefined
-    get<T>(key: string, fallback: T): T
-    set(theme: string): void
-  }
-
-  export interface StoragePlugin {
-    get<T = unknown>(key: string): T | null
-    set(key: string, value: unknown): boolean
-    remove(key: string): void
-    clear(): void
-  }
-
-  export type AppStatePlugin<TState extends Record<string, unknown> = Record<string, unknown>> = TState
 
   export interface ComponentBase extends CustomComponentProperties {
     /**
@@ -444,6 +433,26 @@ declare module '@lightningjs/blits' {
     */
     $clearTimeout: (id: ReturnType<typeof setTimeout>) => void
 
+    /**
+    * Debounce a function execution, preventing memory leaks and function re-allocation
+    * @param name - Unique identifier for this debounce instance (unique per component instance)
+    * @param callback - Function to debounce
+    * @param ms - Delay in milliseconds
+    * @param args - Arguments to pass to the callback
+    */
+    $debounce: (name: string, callback: (...args: any[]) => void, ms?: number, ...args: any[]) => ReturnType<typeof setTimeout>
+
+    /**
+    * Clear a specific debounce by name
+    * @param name - The name of the debounce to clear
+    */
+    $clearDebounce: (name: string) => void
+
+    /**
+    * Clear all debounces registered on the component (automatically called on component destroy)
+    */
+    $clearDebounces: () => void
+
     /**
     * Set an interval that is automatically cleaned upon component destroy
     */
@@ -658,6 +667,7 @@ 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;
   }
 
@@ -681,6 +691,25 @@ declare module '@lightningjs/blits' {
      * ```
      */
     routes?: Route[]
+
+    /**
+     * 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: {
+     *   backNavigation: false, // Disable automatic back navigation
+     *   routes: [...]
+     * }
+     * ```
+     */
+    backNavigation?: boolean
   }
 
   export type ApplicationConfig<P extends Props, S, M, C, W> = ComponentConfig<P, S, M, C, W> & (
@@ -781,6 +810,7 @@ declare module '@lightningjs/blits' {
 
   export interface RouteHooks {
     before?: (to: Route, from: Route) => string | Route | Promise<string | Route>;
+    after?: (to: Route, from: Route) => string | Route | Promise<string | Route>;
   }
 
   export type Route = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lightningjs/blits",
-  "version": "1.45.1",
+  "version": "1.46.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.0",
+    "@lightningjs/renderer": "^2.20.4",
     "magic-string": "^0.30.21"
   },
   "repository": {

package/scripts/prepublishOnly.js

@@ -17,6 +17,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'
 
@@ -84,4 +85,9 @@ function formatFileWithESLint(filePath) {
   })
 }
 
-precompileComponents()
+// Only run if this file is executed directly (not imported)
+if (fileURLToPath(import.meta.url) === process.argv[1]) {
+  precompileComponents()
+}
+
+export { precompileComponents, processDirectory, processFile, formatFileWithESLint }

package/src/announcer/announcer.js

@@ -26,7 +26,9 @@ let currentId = null
 let debounce = null
 
 // Global default utterance options
-let globalDefaultOptions = {}
+let globalDefaultOptions = {
+  enableUtteranceKeepAlive: !/android/i.test((window.navigator || {}).userAgent || ''),
+}
 
 const noopAnnouncement = {
   then() {},
@@ -50,7 +52,6 @@ const toggle = (v) => {
 
 const speak = (message, politeness = 'off', options = {}) => {
   if (active === false) return noopAnnouncement
-
   return addToQueue(message, politeness, false, options)
 }
 
@@ -106,6 +107,8 @@ const addToQueue = (message, politeness, delay = false, options = {}) => {
   return done
 }
 
+let currentResolveFn = null
+
 const processQueue = async () => {
   if (isProcessing === true || queue.length === 0) return
   isProcessing = true
@@ -113,11 +116,13 @@ const processQueue = async () => {
   const { message, resolveFn, delay, id, options = {} } = queue.shift()
 
   currentId = id
+  currentResolveFn = resolveFn
 
   if (delay) {
     setTimeout(() => {
       isProcessing = false
       currentId = null
+      currentResolveFn = null
       resolveFn('finished')
       processQueue()
     }, delay)
@@ -138,19 +143,21 @@ const processQueue = async () => {
           Log.debug(`Announcer - finished speaking: "${message}" (id: ${id})`)
 
           currentId = null
+          currentResolveFn = null
           isProcessing = false
           resolveFn('finished')
           processQueue()
         })
         .catch((e) => {
           currentId = null
+          currentResolveFn = null
           isProcessing = false
           Log.debug(`Announcer - error ("${e.error}") while speaking: "${message}" (id: ${id})`)
           resolveFn(e.error)
           processQueue()
         })
       debounce = null
-    }, 200)
+    }, 300)
   }
 }
 
@@ -158,13 +165,52 @@ const polite = (message, options = {}) => speak(message, 'polite', options)
 
 const assertive = (message, options = {}) => speak(message, 'assertive', options)
 
+// Clear debounce timer
+const clearDebounceTimer = () => {
+  if (debounce !== null) {
+    clearTimeout(debounce)
+    debounce = null
+  }
+}
+
 const stop = () => {
+  // Clear debounce timer if speech hasn't started yet
+  clearDebounceTimer()
+
+  // Always cancel speech synthesis to ensure clean state
   speechSynthesis.cancel()
+
+  // Store resolve function before resetting state
+  const resolveFn = currentResolveFn
+
+  // Reset state
+  currentId = null
+  currentResolveFn = null
+  isProcessing = false
+
+  // Resolve promise if there was an active utterance
+  if (resolveFn !== null) {
+    resolveFn('interrupted')
+  }
 }
 
 const clear = () => {
+  // Clear debounce timer
+  clearDebounceTimer()
+
+  // Resolve all pending items in queue
+  while (queue.length > 0) {
+    const item = queue.shift()
+    if (item.resolveFn) {
+      Log.debug(`Announcer - clearing queued item: "${item.message}" (id: ${item.id})`)
+      item.resolveFn('cleared')
+    }
+  }
+
+  // Reset state
+  currentId = null
+  currentResolveFn = null
   isProcessing = false
-  queue.length = 0
 }
 
 const configure = (options = {}) => {

package/src/announcer/speechSynthesis.js

@@ -19,33 +19,61 @@ import { Log } from '../lib/log.js'
 
 const syn = window.speechSynthesis
 
-const isAndroid = /android/i.test((window.navigator || {}).userAgent || '')
-
-const utterances = new Map() // Strong references with unique keys
+const utterances = new Map() // id -> { utterance, timer, ignoreResume }
 
 let initialized = false
-let infinityTimer = null
 
-const clear = () => {
-  if (infinityTimer) {
-    clearTimeout(infinityTimer)
-    infinityTimer = null
+const clear = (id) => {
+  const state = utterances.get(id)
+  if (state === undefined) {
+    return
+  }
+  if (state.timer !== null) {
+    clearTimeout(state.timer)
+    state.timer = null
   }
+  utterances.delete(id)
 }
 
-const resumeInfinity = (target) => {
-  if (!target || infinityTimer) {
-    return clear()
+const startKeepAlive = (id) => {
+  const state = utterances.get(id)
+
+  // utterance status: utterance was removed (cancelled or finished)
+  if (state == undefined) {
+    return
+  }
+
+  // Clear existing timer for this specific utterance
+  if (state.timer !== null) {
+    clearTimeout(state.timer)
+    state.timer = null
+  }
+
+  // syn status: syn might be undefined or cancelled
+  if (!syn) {
+    clear(id)
+    return
   }
 
   syn.pause()
   setTimeout(() => {
-    syn.resume()
+    // utterance status: utterance might have been removed during setTimeout
+    const currentState = utterances.get(id)
+    if (currentState) {
+      currentState.ignoreResume = true
+      syn.resume()
+    }
   }, 0)
 
-  infinityTimer = setTimeout(() => {
-    resumeInfinity(target)
-  }, 5000)
+  // Check if utterance still exists before scheduling next cycle
+  if (utterances.has(id) === true) {
+    state.timer = setTimeout(() => {
+      // Double-check utterance still exists before resuming
+      if (utterances.has(id) === true) {
+        startKeepAlive(id)
+      }
+    }, 5000)
+  }
 }
 
 const defaultUtteranceProps = {
@@ -57,45 +85,124 @@ const defaultUtteranceProps = {
 }
 
 const initialize = () => {
+  // syn api check: syn might not have getVoices method
+  if (!syn || typeof syn.getVoices !== 'function') {
+    initialized = false
+    return
+  }
+
   const voices = syn.getVoices()
   defaultUtteranceProps.voice = voices[0] || null
   initialized = true
 }
 
-const speak = (options) => {
-  const utterance = new SpeechSynthesisUtterance(options.message)
+const waitForSynthReady = (timeoutMs = 2000, checkIntervalMs = 100) => {
+  return new Promise((resolve) => {
+    if (!syn) {
+      Log.debug('SpeechSynthesis - syn unavailable')
+      resolve()
+      return
+    }
+
+    if (!syn.speaking && !syn.pending) {
+      Log.debug('SpeechSynthesis - ready immediately')
+      resolve()
+      return
+    }
+
+    Log.debug('SpeechSynthesis - waiting for ready state...')
+
+    const startTime = Date.now()
+
+    const intervalId = setInterval(() => {
+      const elapsed = Date.now() - startTime
+      const isReady = !syn.speaking && !syn.pending
+
+      if (isReady) {
+        Log.debug(`SpeechSynthesis - ready after ${elapsed}ms`)
+        clearInterval(intervalId)
+        resolve()
+      } else if (elapsed >= timeoutMs) {
+        Log.debug(`SpeechSynthesis - timeout after ${elapsed}ms, forcing ready`, {
+          speaking: syn.speaking,
+          pending: syn.pending,
+        })
+        clearInterval(intervalId)
+        resolve()
+      }
+    }, checkIntervalMs)
+  })
+}
+
+const speak = async (options) => {
+  // options check: missing required options
+  if (!options || !options.message) {
+    return Promise.reject({ error: 'Missing message' })
+  }
+
+  // options check: missing or invalid id
   const id = options.id
+  if (id === undefined || id === null) {
+    return Promise.reject({ error: 'Missing id' })
+  }
+
+  // utterance status: utterance with same id already exists
+  if (utterances.has(id)) {
+    clear(id)
+  }
+
+  // Wait for engine to be ready
+  await waitForSynthReady()
+
+  const utterance = new SpeechSynthesisUtterance(options.message)
   utterance.lang = options.lang || defaultUtteranceProps.lang
   utterance.pitch = options.pitch || defaultUtteranceProps.pitch
   utterance.rate = options.rate || defaultUtteranceProps.rate
   utterance.voice = options.voice || defaultUtteranceProps.voice
   utterance.volume = options.volume || defaultUtteranceProps.volume
-  utterances.set(id, utterance) // Strong reference
-
-  if (isAndroid === false) {
-    utterance.onstart = () => {
-      resumeInfinity(utterance)
-    }
 
-    utterance.onresume = () => {
-      resumeInfinity(utterance)
-    }
-  }
+  utterances.set(id, { utterance, timer: null, ignoreResume: false })
 
   return new Promise((resolve, reject) => {
-    utterance.onend = () => {
-      clear()
-      utterances.delete(id) // Cleanup
-      resolve()
+    utterance.onend = (result) => {
+      clear(id)
+      resolve(result)
     }
 
     utterance.onerror = (e) => {
-      clear()
-      utterances.delete(id) // Cleanup
-      reject(e)
+      Log.warn('SpeechSynthesisUtterance error:', e)
+      clear(id)
+      resolve()
     }
 
-    syn.speak(utterance)
+    if (options.enableUtteranceKeepAlive === true) {
+      utterance.onstart = () => {
+        // utterances status: check if utterance still exists
+        if (utterances.has(id)) {
+          startKeepAlive(id)
+        }
+      }
+
+      utterance.onresume = () => {
+        const state = utterances.get(id)
+        // utterance status: utterance might have been removed
+        if (!state) return
+
+        if (state.ignoreResume === true) {
+          state.ignoreResume = false
+          return
+        }
+
+        startKeepAlive(id)
+      }
+    }
+    // handle error: syn.speak might throw
+    try {
+      syn.speak(utterance)
+    } catch (error) {
+      clear(id)
+      reject(error)
+    }
   })
 }
 
@@ -113,8 +220,20 @@ export default {
   },
   cancel() {
     if (syn !== undefined) {
-      syn.cancel()
-      clear()
+      // timers: clear all timers before cancelling
+      for (const id of utterances.keys()) {
+        clear(id)
+      }
+
+      // handle errors: syn.cancel might throw
+      try {
+        syn.cancel()
+      } catch (error) {
+        Log.error('Error cancelling speech synthesis:', error)
+      }
+
+      // utterances status: ensure all utterances are cleaned up
+      utterances.clear()
     }
   },
   // @todo

package/src/component/base/methods.js

@@ -120,6 +120,8 @@ export default {
 
       this.$clearTimeouts()
       this.$clearIntervals()
+      this.$clearDebounces()
+
       eventListeners.removeListeners(this)
 
       const rendererEventListenersLength = this[symbols.rendererEventListeners].length

package/src/component/base/router.js

@@ -23,6 +23,12 @@ export default {
     value: {
       to,
       back,
+      get backNavigation() {
+        return state.backNavigation !== false
+      },
+      set backNavigation(enabled) {
+        state.backNavigation = enabled !== false
+      },
       get currentRoute() {
         return currentRoute
       },

package/src/component/base/timeouts_intervals.js

@@ -96,4 +96,60 @@ export default {
     enumerable: true,
     configurable: false,
   },
+  $debounce: {
+    value: function (name, fn, ms, ...params) {
+      // early exit when component is marked as end of life
+      if (this.eol === true) return
+
+      // clear existing debounce for this name if it exists
+      const existing = this[symbols.debounces].get(name)
+      if (existing !== undefined) {
+        this.$clearTimeout(existing)
+        this[symbols.debounces].delete(name)
+      }
+
+      // create new timeout
+      const timeoutId = setTimeout(() => {
+        this[symbols.debounces].delete(name)
+        this.$clearTimeout(timeoutId)
+        fn.apply(this, params)
+      }, ms)
+
+      // track timeout in timeouts array for automatic cleanup
+      this[symbols.timeouts].push(timeoutId)
+
+      // store timeoutId per name to enable replace behavior and lifecycle cleanup
+      this[symbols.debounces].set(name, timeoutId)
+
+      return timeoutId
+    },
+    writable: false,
+    enumerable: true,
+    configurable: false,
+  },
+  $clearDebounce: {
+    value: function (name) {
+      const existing = this[symbols.debounces].get(name)
+      if (existing !== undefined) {
+        this.$clearTimeout(existing)
+        this[symbols.debounces].delete(name)
+      }
+    },
+    writable: false,
+    enumerable: true,
+    configurable: false,
+  },
+  $clearDebounces: {
+    value: function () {
+      // clear all timeouts associated with debounces
+      const timeoutIds = Array.from(this[symbols.debounces].values())
+      for (let i = 0; i < timeoutIds.length; i++) {
+        this.$clearTimeout(timeoutIds[i])
+      }
+      this[symbols.debounces].clear()
+    },
+    writable: false,
+    enumerable: true,
+    configurable: false,
+  },
 }

package/src/component/setup/routes.js

@@ -16,12 +16,17 @@
  */
 
 import symbols from '../../lib/symbols.js'
+import { state as routerState } from '../../router/router.js'
 
 export default (component, data) => {
   let routes = data
   if (Array.isArray(data) === false) {
     component[symbols.routerHooks] = data.hooks
     routes = data.routes
+    // Set initial backNavigation value if provided in router config
+    if (data.backNavigation !== undefined) {
+      routerState.backNavigation = data.backNavigation !== false
+    }
   }
   component[symbols.routes] = []
 

package/src/component.js

@@ -228,6 +228,9 @@ const Component = (name = required('name'), config = required('config')) => {
     // create an empty array for storing intervals created by this component (via this.$setInterval)
     this[symbols.intervals] = []
 
+    // create a Map for storing debounced functions (via this.$debounce)
+    this[symbols.debounces] = new Map()
+
     // apply the state function (passing in the this reference to utilize configured props)
     // and store a reference to this original state
     this[symbols.originalState] =

package/src/components/Circle.js

@@ -37,6 +37,7 @@ export default () =>
         let slotChildCounter = 0
         let cmps = []
         elementConfigs[0] = {}
+        elementConfigs[0]['___wrapper'] = true
 
         elms[0] = this.element(
           { parent: parent || 'root' },

package/src/components/FPScounter.js

@@ -39,6 +39,7 @@ export default () =>
         let slotChildCounter = 0
         let cmps = []
         elementConfigs[0] = {}
+        elementConfigs[0]['___wrapper'] = true
 
         elms[0] = this.element(
           { parent: parent || 'root' },

package/src/components/RouterView.js

@@ -16,96 +16,106 @@
  */
 
 import Component from '../component.js'
-import Router from '../router/router.js'
+import Router, { state as routerState } from '../router/router.js'
 import symbols from '../lib/symbols.js'
 import Focus from '../focus.js'
 
 let hashchangeHandler = null
 
+/** @typedef {{ $input?: (event: any) => boolean, $focus?: (event: any) => void }} RouterViewParent */
+
 export default () =>
-  Component('RouterView', {
-    /* eslint-disable no-unused-vars */
-    code: {
-      render: function anonymous(parent, component, context, components, effect, getRaw, Log) {
-        const elms = []
-        const elementConfigs = []
-        const forloops = []
-        const props = []
-        const created = []
-        const effects = {}
-        const skips = []
-        let componentType
-        let rootComponent = component
-        let propData
-        let slotComponent
-        let inSlot = false
-        let slotChildCounter = 0
-        let cmps = []
-        elementConfigs[0] = {}
+  Component(
+    'RouterView',
+    /** @type {any} */ ({
+      /* eslint-disable no-unused-vars */
+      code: {
+        render: function anonymous(parent, component, context, components, effect, getRaw, Log) {
+          const elms = []
+          const elementConfigs = []
+          const forloops = []
+          const props = []
+          const created = []
+          const effects = {}
+          const skips = []
+          let componentType
+          let rootComponent = component
+          let propData
+          let slotComponent
+          let inSlot = false
+          let slotChildCounter = 0
+          let cmps = []
+          elementConfigs[0] = {}
+          elementConfigs[0]['___wrapper'] = true
 
-        elms[0] = this.element(
-          { parent: parent || 'root' },
-          inSlot === true ? slotComponent : component
-        )
+          elms[0] = this.element(
+            { parent: parent || 'root' },
+            inSlot === true ? slotComponent : component
+          )
 
-        elementConfigs[0]['w'] = parent.node.width * (100 / 100)
-        elementConfigs[0]['height'] = parent.node.height * (100 / 100)
-        elms[0].populate(elementConfigs[0])
+          elementConfigs[0]['w'] = parent.node.width * (100 / 100)
+          elementConfigs[0]['height'] = parent.node.height * (100 / 100)
+          elms[0].populate(elementConfigs[0])
 
-        if (inSlot === true) {
-          slotChildCounter -= 1
-        }
+          if (inSlot === true) {
+            slotChildCounter -= 1
+          }
 
-        return {
-          elms,
-          cleanup: () => {
-            rootComponent = null
-            propData = null
-            slotComponent = null
-            parent = null
-            component = null
-            cmps.length = 0
-            elms.length = 0
-            components.length = 0
-            elementConfigs.length = 0
-            forloops.length = 0
-            props.length = 0
-            skips.length = 0
-          },
-        }
+          return {
+            elms,
+            cleanup: () => {
+              rootComponent = null
+              propData = null
+              slotComponent = null
+              parent = null
+              component = null
+              cmps.length = 0
+              elms.length = 0
+              components.length = 0
+              elementConfigs.length = 0
+              forloops.length = 0
+              props.length = 0
+              skips.length = 0
+            },
+          }
+        },
+        effects: [],
+        context: {},
       },
-      effects: [],
-      context: {},
-    },
-    state() {
-      return {
-        activeView: null,
-      }
-    },
-    hooks: {
-      async ready() {
-        if (this.parent[symbols.routerHooks] && this.parent[symbols.routerHooks].init) {
-          await this.parent[symbols.routerHooks].init.apply(this.parent)
+      state() {
+        return {
+          activeView: null,
         }
-        hashchangeHandler = () => Router.navigate.apply(this)
-        Router.navigate.apply(this)
-        window.addEventListener('hashchange', hashchangeHandler)
-      },
-      destroy() {
-        window.removeEventListener('hashchange', hashchangeHandler, false)
       },
-      focus() {
-        if (this.activeView && Focus.get() === this) {
-          this.activeView.$focus()
-        }
+      hooks: {
+        async ready() {
+          if (this.parent[symbols.routerHooks] && this.parent[symbols.routerHooks].init) {
+            await this.parent[symbols.routerHooks].init.apply(this.parent)
+          }
+          hashchangeHandler = () => Router.navigate.apply(this)
+          Router.navigate.apply(this)
+          window.addEventListener('hashchange', hashchangeHandler)
+        },
+        destroy() {
+          window.removeEventListener('hashchange', hashchangeHandler, false)
+        },
+        focus() {
+          if (this.activeView && Focus.get() === this) {
+            this.activeView.$focus()
+          }
+        },
       },
-    },
-    input: {
-      back(e) {
-        const navigating = Router.back.call(this)
-        if (navigating === false) {
-          this.parent.$focus(e)
-        }
+      input: {
+        back(e) {
+          if (routerState.backNavigation === false) {
+            this.parent.$input(e)
+            return
+          }
+          const navigating = Router.back.call(this)
+          if (navigating === false) {
+            this.parent.$focus(e)
+          }
+        },
       },
-    },
-  })
+    })
+  )

package/src/components/Sprite.js

@@ -39,6 +39,7 @@ export default () =>
         let slotChildCounter = 0
         let cmps = []
         elementConfigs[0] = {}
+        elementConfigs[0]['___wrapper'] = true
 
         elms[0] = this.element(
           { parent: parent || 'root' },

package/src/engines/L3/element.js

@@ -243,15 +243,21 @@ const propsTransformer = {
   },
   set w(v) {
     this.props['width'] = parsePercentage.call(this, v, 'width')
+    if (this.___wrapper === true && this.element.component[symbols.holder] !== undefined) {
+      this.element.component[symbols.holder].set('w', this.props['width'])
+    }
   },
   set width(v) {
-    this.props['width'] = parsePercentage.call(this, v, 'width')
+    this.w = v
   },
   set h(v) {
     this.props['height'] = parsePercentage.call(this, v, 'height')
+    if (this.___wrapper === true && this.element.component[symbols.holder] !== undefined) {
+      this.element.component[symbols.holder].set('h', this.props['height'])
+    }
   },
   set height(v) {
-    this.props['height'] = parsePercentage.call(this, v, 'height')
+    this.h = v
   },
   set x(v) {
     this.props['x'] = parsePercentage.call(this, v, 'width')
@@ -564,6 +570,39 @@ const Element = {
       })
     }
   },
+  /**
+   * Sets framework-provided inspector metadata
+   * Only sets if inspector is enabled and in dev mode
+   * @param {Object} data - Framework inspector metadata to merge
+   */
+  setInspectorMetadata(data) {
+    // Early return if inspector not enabled (performance optimization)
+    if (inspectorEnabled !== true) {
+      return
+    }
+
+    // Early return if element is destroyed (props.props is null)
+    if (this.props.props === undefined || this.props.props === null) {
+      return
+    }
+
+    // Initialize data object if it doesn't exist
+    if (this.props['data'] === undefined) {
+      this.props['data'] = {}
+    }
+    if (this.props.props['data'] === undefined) {
+      this.props.props['data'] = {}
+    }
+
+    // Merge framework data (with $ prefix to prevent collisions)
+    Object.assign(this.props['data'], data)
+    Object.assign(this.props.props['data'], data)
+
+    // Sync to renderer node so inspector can see it
+    if (this.node !== undefined && this.node !== null) {
+      this.node.data = { ...this.props.props['data'] }
+    }
+  },
   /**
    * Set an individual property on the node
    *
@@ -651,6 +690,11 @@ const Element = {
       f,
     }
 
+    // Update inspector metadata when transition starts
+    if (inspectorEnabled === true) {
+      this.setInspectorMetadata({ $isTransitioning: true })
+    }
+
     if (transition.start !== undefined && typeof transition.start === 'function') {
       // fire transition start callback when animation really starts (depending on specified delay)
       f.once('animating', () => {
@@ -685,6 +729,12 @@ const Element = {
       }
       // remove the prop from scheduled transitions
       delete this.scheduledTransitions[prop]
+      // Update inspector metadata when transition ends
+      if (inspectorEnabled === true) {
+        this.setInspectorMetadata({
+          $isTransitioning: Object.keys(this.scheduledTransitions).length > 0,
+        })
+      }
     })
 
     // start animation

package/src/lib/codegenerator/generator.js

@@ -151,6 +151,10 @@ const generateElementCode = function (
 
   renderCode.push(`elementConfigs[${counter}] = {}`)
 
+  if (counter === 0) {
+    renderCode.push(`elementConfigs[${counter}]['___wrapper'] = true `)
+  }
+
   if (options.forloop) {
     renderCode.push(`if(${elm} === undefined) {`)
   }
@@ -283,9 +287,11 @@ const generateComponentCode = function (
 
   const children = templateObject.children
   delete templateObject.children
+  // Capture holder counter before generating element code (which may process children and increment counter)
+  const holderCounter = counter
   generateElementCode.call(this, templateObject, parent, { ...options, ...{ holder: true } })
 
-  parent = options.key ? `elms[${counter}][${options.key}]` : `elms[${counter}]`
+  parent = options.key ? `elms[${holderCounter}][${options.key}]` : `elms[${holderCounter}]`
 
   counter++
 
@@ -354,6 +360,21 @@ 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 holderElm = options.key
+      ? `elms[${holderCounter}][${options.key}]`
+      : `elms[${holderCounter}]`
+    renderCode.push(`
+      if (${holderElm} !== undefined && typeof ${holderElm}.setInspectorMetadata === 'function') {
+        ${holderElm}.setInspectorMetadata({
+          $componentType: '${componentType}'
+        })
+      }
+    `)
+  }
+
   this.cleanupCode.push(`components[${counter}] = null`)
 
   if (options.forloop) {

package/src/lib/lifecycle.js

@@ -18,6 +18,9 @@
 import { Log } from './log.js'
 import { emit, privateEmit } from './hooks.js'
 import symbols from './symbols.js'
+import Settings from '../settings.js'
+
+let inspectorEnabled = null
 
 /**
  * List of valid lifecycle states for a component.
@@ -82,8 +85,31 @@ export default {
       // emit 'public' hook
       emit(v, this.component[symbols.identifier], this.component)
       // update the built-in hasFocus state variable
-      if (v === 'focus') this.component[symbols.state].hasFocus = true
-      if (v === 'unfocus') this.component[symbols.state].hasFocus = false
+      if (v === 'focus' || v === 'unfocus') {
+        if (inspectorEnabled === null) {
+          inspectorEnabled = Settings.get('inspector', false)
+        }
+      }
+      if (v === 'focus') {
+        this.component[symbols.state].hasFocus = true
+        if (
+          inspectorEnabled === true &&
+          this.component[symbols.holder] &&
+          typeof this.component[symbols.holder].setInspectorMetadata === 'function'
+        ) {
+          this.component[symbols.holder].setInspectorMetadata({ $hasFocus: true })
+        }
+      }
+      if (v === 'unfocus') {
+        this.component[symbols.state].hasFocus = false
+        if (
+          inspectorEnabled === true &&
+          this.component[symbols.holder] &&
+          typeof this.component[symbols.holder].setInspectorMetadata === 'function'
+        ) {
+          this.component[symbols.holder].setInspectorMetadata({ $hasFocus: false })
+        }
+      }
     }
   },
 }

package/src/lib/symbols.js

@@ -17,6 +17,7 @@
  * @property {symbol} inputEvents
  * @property {symbol} internalEvent
  * @property {symbol} intervals
+ * @property {symbol} debounces
  * @property {symbol} isProxy
  * @property {symbol} launched
  * @property {symbol} level
@@ -70,6 +71,7 @@ export default {
   inputEvents: Symbol('inputEvents'),
   internalEvent: Symbol('internalEvent'),
   intervals: Symbol('intervals'),
+  debounces: Symbol('debounces'),
   isProxy: Symbol('isProxy'),
   launched: Symbol('launched'),
   level: Symbol('level'),

package/src/plugins/appstate.d.ts

@@ -15,10 +15,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import type { AppStatePlugin } from '@lightningjs/blits'
-
-// Re-export AppStatePlugin for direct imports
-export type { AppStatePlugin }
+export type AppStatePlugin<TState extends Record<string, unknown> = Record<string, unknown>> = TState
 
 declare const appState: {
   readonly name: 'appState'

package/src/plugins/index.d.ts

@@ -21,9 +21,8 @@ export { default as appState } from './appstate.js'
 export { default as storage } from './storage/storage.js'
 
 // Re-export plugin interfaces for convenience
-export type { LanguagePlugin, ThemePlugin, StoragePlugin, AppStatePlugin } from '@lightningjs/blits'
-
-// Re-export option types
-export type { LanguagePluginOptions } from './language.js'
-export type { ThemePluginConfig } from './theme.js'
+export type { LanguagePlugin, LanguagePluginOptions } from './language.js'
+export type { ThemePlugin, ThemePluginConfig } from './theme.js'
+export type { StoragePlugin } from './storage/storage.js'
+export type { AppStatePlugin } from './appstate.js'
 

package/src/plugins/language.d.ts

@@ -15,16 +15,19 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import type { LanguagePlugin } from '@lightningjs/blits'
+export interface LanguagePlugin {
+  translate(key: string, ...replacements: any[]): string
+  readonly language: string
+  set(language: string): void
+  translations(translationsObject: Record<string, unknown>): void
+  load(file: string): Promise<void>
+}
 
 export interface LanguagePluginOptions {
   file?: string
   language?: string
 }
 
-// Re-export LanguagePlugin for direct imports
-export type { LanguagePlugin }
-
 declare const language: {
   readonly name: 'language'
   plugin: (options?: LanguagePluginOptions) => LanguagePlugin

package/src/plugins/storage/storage.d.ts

@@ -15,10 +15,12 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import type { StoragePlugin } from '@lightningjs/blits'
-
-// Re-export StoragePlugin for direct imports
-export type { StoragePlugin }
+export interface StoragePlugin {
+  get<T = unknown>(key: string): T | null
+  set(key: string, value: unknown): boolean
+  remove(key: string): void
+  clear(): void
+}
 
 declare const storage: {
   readonly name: 'storage'

package/src/plugins/theme.d.ts

@@ -15,7 +15,11 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import type { ThemePlugin } from '@lightningjs/blits'
+export interface ThemePlugin {
+  get<T = unknown>(key: string): T | undefined
+  get<T>(key: string, fallback: T): T
+  set(theme: string): void
+}
 
 export interface ThemePluginConfig {
   themes?: Record<string, Record<string, unknown>>
@@ -23,9 +27,6 @@ export interface ThemePluginConfig {
   base?: string
 }
 
-// Re-export ThemePlugin for direct imports
-export type { ThemePlugin }
-
 declare const theme: {
   readonly name: 'theme'
   plugin: (config?: ThemePluginConfig | Record<string, unknown>) => ThemePlugin

package/src/router/router.js

@@ -30,6 +30,9 @@ import Settings from '../settings.js'
  * @typedef {import('../component.js').BlitsComponent} BlitsComponent - The element of the route
  * @typedef {import('../engines/L3/element.js').BlitsElement} BlitsElement - The element of the route
  *
+ * @typedef {BlitsComponent|BlitsComponentFactory} RouteView
+ * @typedef {RouteView & { default?: BlitsComponentFactory }} RouteViewWithOptionalDefault
+ *
  * @typedef {Object} Route
  * @property {string} path - The path of the route
  * @property {string} hash - The hash of the route
@@ -57,6 +60,7 @@ export const state = reactive(
     data: null,
     params: null,
     hash: '',
+    backNavigation: true,
   },
   Settings.get('reactivityMode'),
   true
@@ -335,6 +339,7 @@ export const navigate = async function () {
           return
         }
       }
+
       // add the previous route (technically still the current route at this point)
       // into the history stack when inHistory is true and we're not navigating back
       if (
@@ -354,6 +359,7 @@ export const navigate = async function () {
       /** @type {import('../engines/L3/element.js').BlitsElement} */
       let holder
 
+      /** @type {RouteViewWithOptionalDefault|undefined|null} */
       let view
       let focus
       // when navigating back let's see if we're navigating back to a route that was kept alive
@@ -476,15 +482,17 @@ export const navigate = async function () {
       }
 
       let shouldAnimate = false
+      // Declare oldView in broader scope so it can be used in hooks below
+      let oldView = null
 
       // apply out out transition on previous view if available, unless
       // we're reusing the prvious page component
       if (previousRoute !== undefined && reuse === false) {
         // only animate when there is a previous route
         shouldAnimate = true
-        const oldView = this[symbols.children].splice(1, 1).pop()
+        oldView = this[symbols.children].splice(1, 1).pop()
         if (oldView) {
-          removeView(previousRoute, oldView, route.transition.out, navigatingBack)
+          await removeView(previousRoute, oldView, route.transition.out, navigatingBack)
         }
       }
 
@@ -492,7 +500,7 @@ export const navigate = async function () {
       if (route.transition.in) {
         if (Array.isArray(route.transition.in)) {
           for (let i = 0; i < route.transition.in.length; i++) {
-            i === route.transition.length - 1
+            i === route.transition.in.length - 1
               ? await setOrAnimate(holder, route.transition.in[i], shouldAnimate)
               : setOrAnimate(holder, route.transition.in[i], shouldAnimate)
           }
@@ -500,6 +508,33 @@ export const navigate = async function () {
           await setOrAnimate(holder, route.transition.in, shouldAnimate)
         }
       }
+
+      if (this.parent[symbols.routerHooks]) {
+        const hooks = this.parent[symbols.routerHooks]
+        if (hooks.afterEach) {
+          try {
+            await hooks.afterEach.call(
+              this.parent,
+              route, // to
+              previousRoute // from
+            )
+          } catch (error) {
+            Log.error('Error in "AfterEach" Hook', error)
+          }
+        }
+      }
+
+      if (route.hooks.after) {
+        try {
+          await route.hooks.after.call(
+            this.parent,
+            route, // to
+            previousRoute // from
+          )
+        } catch (error) {
+          Log.error('Error or Rejected Promise in "After" Hook', error)
+        }
+      }
     } else {
       Log.error(`Route ${route.hash} not found`)
       const routerHooks = this.parent[symbols.routerHooks]