Release 1.46.0

CHANGELOG.md

@@ -1,8 +1,20 @@
 # 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
 
-_29 dec 2026_
+_13 jan 2026_
 
 - Updated renderer to v2.20.2
 

docs/components/utility_methods.md

@@ -428,3 +428,73 @@ export default Blits.Component('MyComponent', {
   }
 })
 ```
+
+## Debounce
+
+Debouncing is a technique to limit the rate at which a function executes. This is particularly useful when navigating through lists or handling rapid user input, where you want to execute a method only after the user has stopped the action for a specified delay.
+
+Similar to timeouts and intervals, debounced functions can cause memory leaks if not properly cleaned up. Blits provides built-in debounce methods that automatically handle cleanup when a component is destroyed.
+
+### $debounce
+
+The `this.$debounce()`-method creates a debounced function that delays execution until after a specified delay has passed since the last invocation. If the same name is debounced again before the delay completes, the previous debounce is cancelled and a new one is created.
+
+The first argument is a `name` (string) that uniquely identifies this debounce instance within the component. The second argument is the `callback` function to execute. The third argument is the `delay` in milliseconds. Additional arguments can be passed and will be forwarded to the callback function.
+
+The method returns a `debounce id`, which can be used to manually clear the debounce.
+
+**Key Features:**
+- **Name-based**: Each debounce is identified by a unique name (unique per component instance)
+- **Automatic replacement**: Calling `$debounce` with the same name replaces the previous debounce
+- **Memory efficient**: Only stores debounce IDs internally, function is captured in closure
+- **Automatic cleanup**: All debounces are cleared when component is destroyed
+
+### $clearDebounce
+
+The `this.$clearDebounce()`-method clears a specific debounce by its name. This prevents the debounced function from executing.
+
+### $clearDebounces
+
+The `this.$clearDebounces()`-method clears all debounces registered on the component in one go. This method is automatically called when destroying a Component, preventing memory leaks due to dangling debounce timers.
+
+```js
+export default Blits.Component('ListComponent', {
+  state() {
+    return {
+      items: [],
+      currentIndex: 0
+    }
+  },
+  input: {
+    down() {
+      // Debounce navigation - only load data after 300ms of no navigation
+      this.$debounce('navigate', () => {
+        this.loadCurrentItem()
+      }, 300)
+    },
+    up() {
+      // Different debounce for different operation
+      this.$debounce('update', () => {
+        this.updateUI()
+      }, 200)
+    }
+  },
+  methods: {
+    loadCurrentItem() {
+      // This will only execute after 300ms of no navigation
+      const item = this.items[this.currentIndex]
+      // ... load item data
+    },
+    updateUI() {
+      // This will only execute after 200ms of no update calls
+      // ... update UI
+    }
+  },
+  hooks: {
+    unfocus() {
+      // Optionally clear all debounces when component loses focus
+      this.$clearDebounces()
+    }
+  }
+})
+```

docs/essentials/element_attributes.md

@@ -193,3 +193,21 @@ By default contents inside an Element (i.e. child Elements) will overflow the bo
 In order to contain / cut off the content inside an Element's `w` and `h`, you can add the `clipping="true"`-attribute. Setting `clipping` to `false` restores the default behaviour of content overflowing.
 
 Alternatively you can also use the `overflow`-attribute (and pass it `true` or `false`), which works similar to clipping just mapped inversly (i.e. `overflow="false"` ensures content that surpasses the parent dimensions is clipped-off).
+
+## Inspector Data
+
+The `inspector-data` attribute allows you to attach custom metadata to elements and components for debugging and automated testing. This data is visible in the Lightning inspector tool when enabled.
+
+```xml
+<Element inspector-data="{testId: 'button-primary', role: 'navigation'}" />
+<Button inspector-data="{testId: 'submit-button', role: 'action'}" />
+```
+
+The framework automatically provides the following inspector metadata keys for **Components only** (prefixed with `$` to prevent naming collisions):
+- `$componentType` - The component name (e.g., 'MyComponent', 'Button', etc.)
+- `$hasFocus` - Whether the component currently has focus (automatically updates on focus/unfocus events)
+- `$isTransitioning` - Whether the element is currently animating/transitioning (automatically updates)
+
+> **Note:** 
+> - The `inspector-data` attribute is only processed in development mode when the inspector is enabled. It's automatically filtered out in production builds for performance.
+> - Automatic framework metadata (`$componentType`, `$hasFocus`, `$isTransitioning`) is only set for Components, to keep the render path lightweight.

docs/plugins/text-to-speech-announcer.md

@@ -49,7 +49,7 @@ Blits.Component('MyComponent', {
 
 ### Execute logic when done
 
-The `speak()`-function returns a promise that resolves when it's done speaking, or when it's interupted or errors out. The reason of the `speak()` method resolving is passed as an argument into the resolve function.
+The `speak()`-function returns a promise that resolves when it's done speaking, or when it's interrupted or errors out. The reason of the `speak()` method resolving is passed as an argument into the resolve function.
 
 ```js
 this.$announcer.speak('Hello').then((reason) => console.log('Speaking hello finished', reason))

docs/router/basics.md

@@ -107,6 +107,8 @@ export default Blits.Component('Poster', {
 
 Whenever you navigate to a new page, the URL hash will automatically be updated. Unless specified otherwise, navigating to a new page, will add that route to the history stack. The `back` input action is automatically wired up to navigate back down the history stack.
 
+If you want to disable this automatic history navigation on Back (for example, to let a top-level navigation component handle Back), set `this.$router.backNavigation = false`. Set `this.$router.backNavigation = true` to restore the default behavior.
+
 By default, every time you navigate to a new route, the application focus will be automatically passed to the newly loaded page. If you instead want to maintain the current focus (for example in a widget that sits above your RouterView), you can use `passFocus: false` as part of the router options.
 
 ## Deeplinking

docs/router/hooks.md

@@ -77,6 +77,29 @@ In order to configure global router hooks the `routes` key in the Application co
 
 Alongside the `router.routes` key we can now define a `router.hooks` object, which can have any of the following pre-defined hook functions:
 
+### Router Settings
+
+The router configuration also supports router settings alongside `router.routes` and `router.hooks`:
+
+- `backNavigation` - Enable or disable RouterView history navigation on Back input (default: `true`). When set to `false`, the Back input will be passed to the parent component instead of navigating back through the history stack. This setting can be configured in the router config or changed at runtime via `this.$router.backNavigation`.
+
+> **Note:** `backNavigation` is an app-wide setting that affects all `RouterView` instances in your application, as the router state is global and shared.
+
+```js
+export default Blits.Application({
+  router: {
+    backNavigation: false,
+    routes: [
+      { path: '/', component: Home },
+      { path: '/details', component: Details },
+    ],
+    hooks: {
+      // router hooks can be defined here
+    }
+  }
+})
+```
+
 ### `beforeEach()`
 
 Similar to the `before`-hook, the `beforeEach`-hook will be execute for every router navigation. This can be useful if you find yourself repeating the same functionality for many routes, for example an _authentication check_ or sending _telemetry_.

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,24 +327,29 @@ declare module '@lightningjs/blits' {
     */
     back(): boolean;
 
+    /**
+     * Enable or disable RouterView history navigation on Back input
+     */
+    backNavigation: boolean;
+
     /**
      * Get the current route read-only
     */
     readonly currentRoute: Route;
 
     /**
      * 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.json

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

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 }