@lightningjs/blits 1.44.0 → 1.45.0

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # 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_

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
     *
@@ -624,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.44.0",
+  "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",

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/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/engines/L3/element.js

@@ -380,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/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