@lightningjs/blits 1.43.2 → 1.45.0

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## 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_
+
+- Added `$input` method to facilitate key handling _without_ also passing focus
+- Added support for passing `type` of image in the `src`-attribute (`regular`, `svg`, `compressed` for cases the file type can't be derived from the file name)
+- Bumped Lightning renderer to v2.20.0 with improved support for compressed textures
+
+
 ## v1.43.2
 
 _13 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

@@ -18,10 +18,10 @@
 // blits file type reference
 /// <reference path="./blits.d.ts" />
 
-import {type ShaderEffect as RendererShaderEffect, type WebGlCoreShader, type RendererMainSettings} from '@lightningjs/renderer'
-
 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 {
     /**
@@ -209,7 +209,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
      *
@@ -362,7 +362,39 @@ 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 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 {
     /**
     * Indicates whether the component currently has focus
     *
@@ -431,6 +463,12 @@ declare module '@lightningjs/blits' {
     * Set focus to the Component, optionally pass a KeyboardEvent for instant event bubbling
     */
     $focus: (event?: KeyboardEvent) => void
+    /**
+     * Handle a keyboard event on this component without changing focus
+     * @param event - The keyboard event to handle
+     * @returns Returns true if this component or a parent component handled the event, false otherwise
+     */
+    $input: (event: KeyboardEvent) => boolean
     /**
      * @deprecated
      * Deprecated:  use `this.$focus()` instead
@@ -618,7 +656,7 @@ declare module '@lightningjs/blits' {
   }
 
   export interface RouterHooks {
-    init?: () => Promise<> | void;
+    init?: () => Promise<void> | void;
     beforeEach?: (to: Route, from: Route) => string | Route | Promise<string | Route> | void;
     error?: (err: string) => string | Route | Promise<string | Route> | void;
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lightningjs/blits",
-  "version": "1.43.2",
+  "version": "1.45.0",
   "description": "Blits: The Lightning 3 App Development Framework",
   "bin": "bin/index.js",
   "exports": {
@@ -8,7 +8,26 @@
     "./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"
   },
@@ -48,6 +67,7 @@
     "husky": "^9.1.7",
     "jsdom": "24.0.0",
     "lint-staged": "^15.5.0",
+    "magic-string": "^0.30.21",
     "prettier": "^3.6.2",
     "sinon": "^21.0.0",
     "tap-diff": "^0.1.1",
@@ -55,7 +75,7 @@
   },
   "dependencies": {
     "@lightningjs/msdf-generator": "^1.2.0",
-    "@lightningjs/renderer": "^2.19.1"
+    "@lightningjs/renderer": "^2.20.0"
   },
   "repository": {
     "type": "git",

package/scripts/prepublishOnly.js

@@ -55,7 +55,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

package/src/application.js

@@ -20,28 +20,16 @@ import { default as Focus, keyUpCallbacks } from './focus.js'
 import Settings from './settings.js'
 
 import symbols from './lib/symbols.js'
-import { DEFAULT_HOLD_TIMEOUT_MS } from './constants.js'
+import { DEFAULT_HOLD_TIMEOUT_MS, DEFAULT_KEYMAP } from './constants.js'
 
-const Application = (config) => {
-  const defaultKeyMap = {
-    ArrowLeft: 'left',
-    ArrowRight: 'right',
-    ArrowUp: 'up',
-    ArrowDown: 'down',
-    Enter: 'enter',
-    ' ': 'space',
-    Backspace: 'back',
-    Escape: 'escape',
-    37: 'left',
-    39: 'right',
-    38: 'up',
-    40: 'down',
-    13: 'enter',
-    32: 'space',
-    8: 'back',
-    27: 'escape',
-  }
+/**
+ * Merged keyMap (default + custom settings).
+ * Initialized once during application init.
+ * @type {Object<string, string>}
+ */
+export let keyMap = {}
 
+const Application = (config) => {
   config.hooks = config.hooks || {}
 
   let keyDownHandler
@@ -63,7 +51,8 @@ const Application = (config) => {
     if (announcerOptions && typeof announcerOptions === 'object') {
       this.$announcer.configure(announcerOptions)
     }
-    const keyMap = { ...defaultKeyMap, ...Settings.get('keymap', {}) }
+    // Initialize merged keyMap once during application init
+    keyMap = { ...DEFAULT_KEYMAP, ...Settings.get('keymap', {}) }
 
     /** @type {number} Input throttle time in milliseconds (0 = disabled) */
     const throttleMs = Settings.get('inputThrottle', 0)

package/src/component/base/methods.js

@@ -17,11 +17,13 @@
 
 import symbols from '../../lib/symbols.js'
 import Focus from '../../focus.js'
+import { keyUpCallbacks, getComponentWithInputEvent } from '../../focus.js'
 import eventListeners from '../../lib/eventListeners.js'
 import { trigger } from '../../lib/reactivity/effect.js'
 import { Log } from '../../lib/log.js'
 import { removeGlobalEffects } from '../../lib/reactivity/effect.js'
 import { renderer } from '../../launch.js'
+import { keyMap } from '../../application.js'
 
 export default {
   focus: {
@@ -51,6 +53,41 @@ export default {
     enumerable: true,
     configurable: false,
   },
+  $input: {
+    /**
+     * Handle a keyboard event on this component without changing focus
+     * @this {import('../../component').BlitsComponent}
+     * @param {KeyboardEvent} event - The keyboard event to handle
+     * @returns {boolean} - Returns true if this component or a parent component handled the event, false otherwise
+     */
+    value: function (event) {
+      if (event === null || event === undefined || event instanceof KeyboardEvent === false)
+        return false
+
+      const key = keyMap[event.key] || keyMap[event.keyCode] || event.key || event.keyCode
+
+      const componentWithInputEvent = getComponentWithInputEvent(this, key)
+      if (componentWithInputEvent === null) return false
+
+      const inputEvents = componentWithInputEvent[symbols.inputEvents] || {}
+
+      let cb
+      if (inputEvents[key]) {
+        cb = inputEvents[key].call(componentWithInputEvent, event)
+      } else if (inputEvents.any) {
+        cb = inputEvents.any.call(componentWithInputEvent, event)
+      }
+
+      if (cb !== undefined && event.code) {
+        keyUpCallbacks.set(event.code, cb)
+      }
+
+      return true
+    },
+    writable: false,
+    enumerable: true,
+    configurable: false,
+  },
   unfocus: {
     /**
      * @this {import('../../component').BlitsComponent}

package/src/components/Sprite.js

@@ -121,15 +121,20 @@ export default () =>
         // Resolve frame data from sprite map
         let options = null
         if (
-          this.map !== undefined &&
           this.map !== null &&
-          this.frame !== undefined &&
-          this.frame !== null
+          this.map !== undefined &&
+          this.frame !== null &&
+          this.frame !== undefined
         ) {
-          options =
-            'frames' in this.map
-              ? Object.assign({}, this.map.defaults || {}, this.map.frames[this.frame])
-              : this.map[this.frame]
+          if (
+            this.map.frames !== null &&
+            this.map.frames !== undefined &&
+            this.frame in this.map.frames
+          ) {
+            options = Object.assign({}, this.map.defaults || {}, this.map.frames[this.frame])
+          } else if (this.frame in this.map) {
+            options = this.map[this.frame]
+          }
         }
 
         // If no map but frame is object (manual subtexture)

package/src/constants.js

@@ -1,5 +1,24 @@
 export const DEFAULT_HOLD_TIMEOUT_MS = 50
 
+export const DEFAULT_KEYMAP = {
+  ArrowLeft: 'left',
+  ArrowRight: 'right',
+  ArrowUp: 'up',
+  ArrowDown: 'down',
+  Enter: 'enter',
+  ' ': 'space',
+  Backspace: 'back',
+  Escape: 'escape',
+  37: 'left',
+  39: 'right',
+  38: 'up',
+  40: 'down',
+  13: 'enter',
+  32: 'space',
+  8: 'back',
+  27: 'escape',
+}
+
 export const SCREEN_RESOLUTIONS = {
   hd: 0.66666667,
   '720p': 0.66666667,

package/src/engines/L3/element.js

@@ -168,7 +168,7 @@ const isObjectString = (str) => {
  * @returns {object} The parsed object.
  */
 const parseToObject = (str) => {
-  return JSON.parse(str.replace(/'/g, '"').replace(/([\w-_]+)\s*:/g, '"$1":'))
+  return JSON.parse(str.replace(/'/g, '"').replace(/([{,]\s*)([\w-_]+)(\s*:)/g, '$1"$2"$3'))
 }
 
 /**
@@ -276,7 +276,13 @@ const propsTransformer = {
     }
   },
   set src(v) {
-    this.props['src'] = v
+    if (typeof v === 'object' || (isObjectString(v) === true && (v = parseToObject(v)))) {
+      this.props['src'] = v.src
+      this.props['imageType'] = v.type
+    } else {
+      this.props['src'] = v
+    }
+
     if (this.raw['color'] === undefined) {
       this.props['color'] = this.props['src'] ? 0xffffffff : 0x00000000
     }
@@ -374,10 +380,21 @@ const propsTransformer = {
     }
   },
   set shader(v) {
-    if (v !== null) {
-      this.props['shader'] = renderer.createShader(v.type, v.props)
-    } else {
-      this.props['shader'] = renderer.createShader('DefaultShader')
+    const target = this.element.node !== undefined ? this.element.node : this.props
+
+    if (v === null) {
+      target['shader'] = null
+      return
+    }
+
+    if (typeof v === 'object' || (isObjectString(v) === true && (v = parseToObject(v)))) {
+      if (target.shader !== undefined && target.shader.type === v.type) {
+        for (const prop in v.props) {
+          target.shader.props[prop] = v.props[prop]
+        }
+        return
+      }
+      target['shader'] = renderer.createShader(v.type, v.props)
     }
   },
   set effects(v) {

package/src/focus.js

@@ -118,7 +118,7 @@ const getAncestors = (components) => {
  * @param {String} key
  * @returns component
  */
-const getComponentWithInputEvent = (component, key) => {
+export const getComponentWithInputEvent = (component, key) => {
   if (
     component[symbols.inputEvents] &&
     (typeof component[symbols.inputEvents][key] === 'function' ||

package/src/lib/codegenerator/generator.js

@@ -409,7 +409,7 @@ const generateForLoopCode = function (templateObject, parent) {
     .replace(')', '')
     .split(/\s*,\s*/)
 
-  const scopeRegex = new RegExp(`(scope\\.(?!${item}\\.|${index}|key)(\\w+))`, 'gi')
+  const scopeRegex = new RegExp(`(scope\\.(?!${item}\\.|${index}|key)([\\w$]+))`, 'gi')
 
   // local context
   const ctx = {

package/src/lib/precompiler/precompiler.js

@@ -17,6 +17,7 @@
 
 import parser from '../templateparser/parser.js'
 import generator from '../codegenerator/generator.js'
+import MagicString from 'magic-string'
 
 export default (source, filePath, mode) => {
   if (
@@ -26,12 +27,9 @@ export default (source, filePath, mode) => {
     /\{.*?template\s*:\s*(['"`])((?:\\?.)*?)\1.*?\}/s.test(source) // object with template key
   ) {
     const templates = source.matchAll(/(?<!\/\/\s*)template\s*:\s*(['"`])((?:\\?.)*?)\1/gs)
-    let newSource = source
-    /*
-      if there are multiple templates in the file, we need to keep
-      track of the offset caused by the previous replacements
-    */
-    let offset = 0
+
+    // Use MagicString to track changes
+    const s = new MagicString(source)
 
     for (const template of templates) {
       if (template[2]) {
@@ -39,7 +37,8 @@ export default (source, filePath, mode) => {
 
         // Only process if it looks like a Blits template
         if (templateContent.match(/^\s*(<!--[\s\S]*?-->|<[A-Za-z][^>]*>)/s)) {
-          const templateStartIndex = template.index + offset
+          // Use original indices - MagicString handles position tracking automatically
+          const templateStartIndex = template.index
           const templateEndIndex = templateStartIndex + template[0].length
 
           // Parse the template
@@ -58,16 +57,26 @@ export default (source, filePath, mode) => {
             (fn) => fn.toString()
           )}], context: {}}`
 
-          offset += replacement.length - template[0].length
-
-          newSource =
-            newSource.substring(0, templateStartIndex) +
-            replacement +
-            newSource.substring(templateEndIndex)
+          // MagicString tracks all changes automatically, no offset needed
+          s.overwrite(templateStartIndex, templateEndIndex, replacement)
         }
       }
     }
-    return newSource
+
+    const newSource = s.toString()
+
+    if (newSource !== source) {
+      const fileName = filePath.split(/[\\/]/).pop()
+      return {
+        code: newSource,
+        map: s.generateMap({
+          hires: true,
+          source: fileName,
+          includeContent: true,
+          file: fileName,
+        }),
+      }
+    }
   }
   return source
 }

package/src/lib/reactivityguard/computedprops.js

@@ -213,7 +213,12 @@ export default (code) => {
       modifiedCode = modifiedCode.replace(mod.original, mod.replacement)
     }
 
-    return { code: modifiedCode }
+    // Returning code without a source map
+    // Vite will automatically chain this with the next plugin's source map (preCompiler)
+    return {
+      code: modifiedCode,
+      map: { mappings: '' },
+    }
   }
 
   return null

package/src/plugins/appstate.d.ts

@@ -0,0 +1,29 @@
+/*
+ * Copyright 2024 Comcast Cable Communications Management, LLC
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type { AppStatePlugin } from '@lightningjs/blits'
+
+// Re-export AppStatePlugin for direct imports
+export type { AppStatePlugin }
+
+declare const appState: {
+  readonly name: 'appState'
+  plugin: <TState extends Record<string, unknown>>(state?: TState) => AppStatePlugin<TState>
+}
+
+export default appState
+

package/src/plugins/index.d.ts

@@ -0,0 +1,29 @@
+/*
+ * Copyright 2024 Comcast Cable Communications Management, LLC
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+export { default as language } from './language.js'
+export { default as theme } from './theme.js'
+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'
+

package/src/plugins/language.d.ts

@@ -0,0 +1,34 @@
+/*
+ * Copyright 2024 Comcast Cable Communications Management, LLC
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type { LanguagePlugin } from '@lightningjs/blits'
+
+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
+}
+
+export default language
+

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

@@ -0,0 +1,29 @@
+/*
+ * Copyright 2024 Comcast Cable Communications Management, LLC
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type { StoragePlugin } from '@lightningjs/blits'
+
+// Re-export StoragePlugin for direct imports
+export type { StoragePlugin }
+
+declare const storage: {
+  readonly name: 'storage'
+  plugin: () => StoragePlugin
+}
+
+export default storage
+

package/src/plugins/theme.d.ts

@@ -0,0 +1,35 @@
+/*
+ * Copyright 2024 Comcast Cable Communications Management, LLC
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type { ThemePlugin } from '@lightningjs/blits'
+
+export interface ThemePluginConfig {
+  themes?: Record<string, Record<string, unknown>>
+  current?: string
+  base?: string
+}
+
+// Re-export ThemePlugin for direct imports
+export type { ThemePlugin }
+
+declare const theme: {
+  readonly name: 'theme'
+  plugin: (config?: ThemePluginConfig | Record<string, unknown>) => ThemePlugin
+}
+
+export default theme
+

package/vite/preCompiler.js

@@ -32,12 +32,22 @@ export default function () {
 
       // we should only precompile .blits, .js and .ts files
       if (
-        fileExtension === '.js' ||
-        fileExtension === '.ts' ||
-        fileExtension === '.blits' ||
-        fileExtension === '.mjs'
+        filePath.indexOf('node_modules') === -1 &&
+        (fileExtension === '.js' ||
+          fileExtension === '.ts' ||
+          fileExtension === '.blits' ||
+          fileExtension === '.mjs')
       ) {
-        return compiler(source, filePath, config.mode)
+        const result = compiler(source, filePath, config.mode)
+
+        if (typeof result === 'object') {
+          return {
+            code: result.code,
+            map: result.map,
+          }
+        }
+        // No transformation needed - return null so Vite knows no changes were made
+        return null
       }
 
       // vite expects null if there is no modification