@lightningjs/blits 2.0.0-beta.1 → 2.0.0-beta.4

package/CHANGELOG.md

@@ -1,5 +1,81 @@
 # Changelog
 
+## v1.50.0
+
+_27 feb 2026_
+
+- Fixed issue with router navigation options not properly being overriden
+- Fixed FPS counter component and made it into a separate importable component (`import { FPScounter } from @lightningjs/blits/components`)
+- Added mouse (magic wand) support (including new `hover` lifecycle hook and `isHovered` state indicator)
+- Updated template attributes for VScode extension
+
+
+## v1.49.0
+
+_20 feb 2026_
+
+- Added `data-blits-renderstate` inspector attribute
+- Fixed `data-blits-hasfocus` inspector attribute to always be available
+- Added boolean attribute to `idle` lifecycle hook to indicate `idle` or `active` state
+- Fixed type definitions for router beforeEach hooks
+- Fixed double processing of reactivity guard
+
+## v1.48.0
+
+_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_
+
+- Fixed issue with reactivity guard vite plugin failing for commented-out code
+- Fixed issue with autosizing of holder node by adding extra `eol` check
+- Added support for _variants_ to the Theme plugin
+
+## 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_
+
+- fixed issue `magic-string` package being a dev dependency
+
+## v1.45.0
+
+_29 dec 2025_
+
+- Added support for defining types for custom plugins on the Blits component definitions
+- Added importable type definitions for built-in plugins
+- Added support for JS sourcemaps
+- Added reactivity for shader props (individual shaders, not effects via dynamic shader)
+- Fixed issue with usage of Blits plugins not working in for loops
+- Improved test coverage
+
 ## v1.44.0
 
 _20 Nov 2025_

package/README.md

@@ -2,6 +2,8 @@
 
 # Blits - Lightning 3 App Development Framework
 
+![npm](https://img.shields.io/npm/v/@lightningjs/blits?label=Version&color=blue) ![License](https://img.shields.io/github/license/lightning-js/blits?label=License&color=blue) ![Tests](https://github.com/lightning-js/blits/workflows/Tests/badge.svg) ![Coverage](https://img.shields.io/codecov/c/github/lightning-js/blits/master?label=Coverage) ![npm](https://img.shields.io/npm/dm/@lightningjs/blits?label=Downloads&color=blue)
+
 With Blits, the App Development Framework for Lightning 3, it becomes a breeze to build great Lightning 3 applications.
 
 Blits is built on top of the Lightning 3 Rendererer and aims to provide a **great developer experience**, making it fun and easy to build your apps!

package/index.d.ts

@@ -23,7 +23,9 @@ import { CanvasShaderType } from '@lightningjs/renderer/canvas';
 import { WebGlShaderType } from '@lightningjs/renderer/webgl';
 
 declare module '@lightningjs/blits' {
-
+  type RendererShaderEffect = import('@lightningjs/renderer').ShaderEffect
+  type WebGlCoreShader = import('@lightningjs/renderer').WebGlCoreShader
+  type RendererMainSettings = import('@lightningjs/renderer').RendererMainSettings
 
   export interface AnnouncerUtteranceOptions {
     /**
@@ -56,6 +58,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> {
@@ -166,6 +174,8 @@ declare module '@lightningjs/blits' {
     * Fires when the Component is being destroyed and removed.
     */
     destroy?: () => void;
+    hover?: () => void;
+    unhover?: () => void;
     /**
     * Fires upon each frame start  (allowing you to tap directly into the renderloop)
     *
@@ -197,11 +207,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
     *
@@ -211,7 +224,7 @@ declare module '@lightningjs/blits' {
   }
 
   export interface Input {
-    [key: string]: (event: KeyboardEvent) => void | undefined | unknown,
+    [key: string]: ((event: KeyboardEvent) => unknown) | undefined,
     /**
      * Catch all input function
      *
@@ -323,6 +336,11 @@ declare module '@lightningjs/blits' {
     */
     back(): boolean;
 
+    /**
+     * Enable or disable RouterView history navigation on Back input
+     */
+    backNavigation: boolean;
+
     /**
      * Get the current route read-only
     */
@@ -330,17 +348,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
@@ -364,7 +382,17 @@ declare module '@lightningjs/blits' {
     }
   }
 
-  export type ComponentBase = {
+  // Extension point for app- and plugin-specific fields on the component `this`.
+  // Add your own properties (e.g., `$telemetry`, `componentName`) via TypeScript
+  // module augmentation in your app, without changing core types.
+  // Note: `ComponentBase` extends this interface, so augmented fields appear in all
+  // hooks, methods, input, computed, and watch.
+  export interface CustomComponentProperties {
+    // Empty by design: extend in your app via TypeScript module augmentation.
+  }
+
+
+  export interface ComponentBase extends CustomComponentProperties {
     /**
     * Indicates whether the component currently has focus
     *
@@ -372,6 +400,13 @@ declare module '@lightningjs/blits' {
     */
     readonly $hasFocus: boolean,
 
+    /**
+    * Indicates whether the component currently is hovered
+    *
+    * @returns Boolean
+    */
+    isHovered: boolean,
+
     /**
     * Listen to events emitted by other components
     */
@@ -414,6 +449,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
     */
@@ -609,9 +664,10 @@ declare module '@lightningjs/blits' {
   }
 
   export interface RouterHooks {
-    init?: () => Promise<> | void;
-    beforeEach?: (to: Route, from: Route) => string | Route | Promise<string | Route> | void;
-    error?: (err: string) => string | Route | Promise<string | Route> | void;
+    init?: () => Promise<void> | 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> {
@@ -634,6 +690,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> & (
@@ -733,7 +808,8 @@ declare module '@lightningjs/blits' {
   }[keyof T]
 
   export interface RouteHooks {
-    before?: (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 = {
@@ -1157,6 +1233,16 @@ declare module '@lightningjs/blits' {
      * ```
      */
     announcerOptions?: AnnouncerUtteranceOptions,
+    /**
+     * Enable mouse support (hover and click-to-focus).
+     *
+     * When set to `true`, pointer movement over the canvas updates hover state on components
+     * and click dispatches focus and Enter key input to the component under the cursor.
+     * When set to `false`, no mouse or pointer listeners are registered.
+     *
+     * @default false
+     */
+    enableMouse?: boolean,
     /**
      * Maximum FPS at which the App will be rendered
      *
@@ -1165,7 +1251,14 @@ declare module '@lightningjs/blits' {
      *
      * Defaults to `0` which means no maximum
      */
-    maxFPS?: number
+    maxFPS?: number,
+    /**
+     * Custom platform layer to be used by the App (experimental)
+     *
+     * Defaults to `null` which will be resolved internally to WebPlatform
+     */
+    platform?: any
+
   }
 
   interface State {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lightningjs/blits",
-  "version": "2.0.0-beta.1",
+  "version": "2.0.0-beta.4",
   "description": "Blits: The Lightning 3 App Development Framework",
   "bin": "bin/index.js",
   "exports": {
@@ -8,9 +8,29 @@
     "./vite": "./vite/index.js",
     "./transitions": "./src/router/transitions/index.js",
     "./precompiler": "./src/lib/precompiler/precompiler.js",
-    "./plugins": "./src/plugins/index.js",
+    "./plugins": {
+      "types": "./src/plugins/index.d.ts",
+      "default": "./src/plugins/index.js"
+    },
+    "./plugins/language": {
+      "types": "./src/plugins/language.d.ts",
+      "default": "./src/plugins/language.js"
+    },
+    "./plugins/theme": {
+      "types": "./src/plugins/theme.d.ts",
+      "default": "./src/plugins/theme.js"
+    },
+    "./plugins/appstate": {
+      "types": "./src/plugins/appstate.d.ts",
+      "default": "./src/plugins/appstate.js"
+    },
+    "./plugins/storage": {
+      "types": "./src/plugins/storage/storage.d.ts",
+      "default": "./src/plugins/storage/storage.js"
+    },
     "./symbols": "./src/lib/symbols.js",
-    "./blitsFileConverter": "./src/lib/blitsfileconverter/blitsfileconverter.js"
+    "./blitsFileConverter": "./src/lib/blitsfileconverter/blitsfileconverter.js",
+    "./components": "./src/components/FPScounter.js"
   },
   "scripts": {
     "test": "c8 node scripts/runTests.js",
@@ -56,7 +76,8 @@
     "tape": "^5.5.0"
   },
   "dependencies": {
-    "@lightningjs/renderer": "3.0.0-beta18"
+    "@lightningjs/renderer": "3.0.0-beta22",
+    "magic-string": "^0.30.21"
   },
   "repository": {
     "type": "git",

package/scripts/prepublishOnly.js

@@ -17,8 +17,9 @@
 
 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']
@@ -55,7 +56,10 @@ function processFile(filePath) {
   fs.copyFileSync(filePath, backupFilePath)
 
   const source = fs.readFileSync(filePath, 'utf-8')
-  const newSource = compiler(source, filePath)
+  const result = compiler(source, filePath)
+
+  // Handle both string and object return types
+  const newSource = typeof result === 'object' && result.code ? result.code : result
   fs.writeFileSync(filePath, newSource)
 
   // only format the file if it was changed
@@ -67,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}`)
@@ -81,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/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/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 = {}) => {