@lightningjs/blits 1.45.1 → 2.0.0-beta.1

package/CHANGELOG.md

@@ -1,22 +1,5 @@
 # Changelog
 
-## 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,8 +2,6 @@
 
 # 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,12 @@
 // blits file type reference
 /// <reference path="./blits.d.ts" />
 
+import {type ShaderEffect as RendererShaderEffect, type RendererMainSettings} from '@lightningjs/renderer'
+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 {
     /**
@@ -209,7 +211,7 @@ declare module '@lightningjs/blits' {
   }
 
   export interface Input {
-    [key: string]: ((event: KeyboardEvent) => unknown) | undefined,
+    [key: string]: (event: KeyboardEvent) => void | undefined | unknown,
     /**
      * Catch all input function
      *
@@ -362,45 +364,13 @@ declare module '@lightningjs/blits' {
     }
   }
 
-  // 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 {
+  export type ComponentBase = {
     /**
     * Indicates whether the component currently has focus
     *
     * @returns Boolean
     */
-    hasFocus: boolean,
+    readonly $hasFocus: boolean,
 
     /**
     * Listen to events emitted by other components
@@ -469,12 +439,6 @@ declare module '@lightningjs/blits' {
      * @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
-     */
-    focus: (event?: KeyboardEvent) => void
-
     /**
     * Select a child Element or Component by ref
     *
@@ -492,12 +456,6 @@ declare module '@lightningjs/blits' {
     */
     $select: (ref: string) => ComponentBase
 
-    /**
-     * @deprecated
-     * Deprecated: use `this.$select()` instead
-     */
-    select: (ref: string) => ComponentBase
-
     /**
      * Announcer methods for screen reader support
      */
@@ -507,13 +465,6 @@ declare module '@lightningjs/blits' {
      * Triggers a forced update on state variables.
      */
     $trigger: (key: string) => void
-    /**
-     * @deprecated
-     *
-     * Triggers a forced update on state variables.
-     * Deprecated: use `this.$trigger()` instead
-     */
-    trigger: (key: string) => void
     /**
      * Router instance
      */
@@ -563,20 +514,22 @@ declare module '@lightningjs/blits' {
     cast?: () => any
   };
 
-  // Props Array
-  export type Props = (string | PropObject)[];
+  export type Props = Record<string, any>
 
-  // Extract the prop names from the props array
-  type ExtractPropNames<P extends Props> = {
-      readonly [K in P[number] as K extends string ? K : K extends { key: infer Key } ? Key : never]: any;
-  };
+  type InferProp<T> = T extends (...args: any[]) => any ? ReturnType<T> : T
 
-  // Update the PropsDefinition to handle props as strings or objects
-  export type PropsDefinition<P extends Props> = ExtractPropNames<P>;
+  type InferProps<T extends Record<string, any>> = {
+    [K in keyof T]: InferProp<T[K]>
+  }
 
-  export type ComponentContext<P extends Props, S, M, C> = ThisType<PropsDefinition<P> & S & M & C & ComponentBase>
+  export type ComponentContext<
+    P extends Record<string, any>,
+    S,
+    M,
+    C
+  > = ThisType<Readonly<InferProps<P>> & S & M & Readonly<C> & ComponentBase>
 
-  export interface ComponentConfig<P extends Props, S, M, C, W> {
+  export interface ComponentConfig<P extends Props = {}, S, M, C, W> {
     components?: {
         [key: string]: ComponentFactory,
     },
@@ -632,7 +585,7 @@ declare module '@lightningjs/blits' {
      * }
      * ```
      */
-    state?: (this: PropsDefinition<P>) => S;
+    state?: (this: InferProps<P>) => S;
     /**
      * Methods for abstracting more complex business logic into separate function
      */
@@ -656,7 +609,7 @@ declare module '@lightningjs/blits' {
   }
 
   export interface RouterHooks {
-    init?: () => Promise<void> | void;
+    init?: () => Promise<> | void;
     beforeEach?: (to: Route, from: Route) => string | Route | Promise<string | Route> | void;
     error?: (err: string) => string | Route | Promise<string | Route> | void;
   }
@@ -900,7 +853,7 @@ declare module '@lightningjs/blits' {
 
   type Shader = {
     name: string,
-    type: WebGlCoreShader
+    type: WebGlShaderType | CanvasShaderType
   }
 
   type ScreenResolutions = 'hd' | '720p' | 720 | 'fhd' | 'fullhd' | '1080p' | 1080 | '4k' | '2160p' | 2160
@@ -936,10 +889,6 @@ declare module '@lightningjs/blits' {
      * Fonts to be used in the Application
      */
     fonts?: Font[],
-    /**
-     * Effects to be used by DynamicShader
-     */
-    effects?: ShaderEffect[],
     /**
      * Shaders to be used in the application
      */
@@ -1072,18 +1021,6 @@ declare module '@lightningjs/blits' {
      * Defaults to `0`
      */
     viewportMargin?: number | [number, number, number, number],
-    /**
-     * Threshold in `Megabytes` after which all the textures that are currently not visible
-     * within the configured viewport margin will be be freed and cleaned up
-     *
-     * When passed `0` the threshold is disabled and textures will not be actively freed
-     * and cleaned up
-     *
-     * Defaults to `200` (mb)
-     * @deprecated
-     * Deprecated:  use `gpuMemory` launch setting instead
-     */
-    gpuMemoryLimit?: number,
     /**
      * Configures the gpu memory settings used by the renderer
      */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lightningjs/blits",
-  "version": "1.45.1",
+  "version": "2.0.0-beta.1",
   "description": "Blits: The Lightning 3 App Development Framework",
   "bin": "bin/index.js",
   "exports": {
@@ -8,26 +8,7 @@
     "./vite": "./vite/index.js",
     "./transitions": "./src/router/transitions/index.js",
     "./precompiler": "./src/lib/precompiler/precompiler.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"
-    },
+    "./plugins": "./src/plugins/index.js",
     "./symbols": "./src/lib/symbols.js",
     "./blitsFileConverter": "./src/lib/blitsfileconverter/blitsfileconverter.js"
   },
@@ -35,6 +16,7 @@
     "test": "c8 node scripts/runTests.js",
     "test:ci": "c8 npm run test:run",
     "test:run": "node -r global-jsdom/register ./node_modules/.bin/tape '{,!(node_modules|packages)/**/}*.test.js' | tap-diff",
+    "test:run:failures": "node -r global-jsdom/register ./node_modules/.bin/tape '{,!(node_modules|packages)/**/}*.test.js' |  tap-filter test-fail | tap-diff",
     "lint": "node scripts/lint.js",
     "lint:fix": "node scripts/lint.js fix",
     "prepublishOnly": "node scripts/prepublishOnly.js",
@@ -70,12 +52,11 @@
     "prettier": "^3.6.2",
     "sinon": "^21.0.0",
     "tap-diff": "^0.1.1",
+    "tap-filter": "^1.0.3",
     "tape": "^5.5.0"
   },
   "dependencies": {
-    "@lightningjs/msdf-generator": "^1.2.0",
-    "@lightningjs/renderer": "^2.20.0",
-    "magic-string": "^0.30.21"
+    "@lightningjs/renderer": "3.0.0-beta18"
   },
   "repository": {
     "type": "git",

package/scripts/prepublishOnly.js

@@ -55,10 +55,7 @@ function processFile(filePath) {
   fs.copyFileSync(filePath, backupFilePath)
 
   const source = fs.readFileSync(filePath, 'utf-8')
-  const result = compiler(source, filePath)
-
-  // Handle both string and object return types
-  const newSource = typeof result === 'object' && result.code ? result.code : result
+  const newSource = compiler(source, filePath)
   fs.writeFileSync(filePath, newSource)
 
   // only format the file if it was changed

package/src/component/base/methods.js

@@ -26,26 +26,14 @@ import { renderer } from '../../launch.js'
 import { keyMap } from '../../application.js'
 
 export default {
-  focus: {
-    /**
-     * @this {import('../../component').BlitsComponent}
-     */
-    value: function (e) {
-      Log.warn('this.focus is deprecated, use this.$focus instead')
-      return this.$focus(e)
-    },
-    writable: false,
-    enumerable: true,
-    configurable: false,
-  },
   $focus: {
     /**
      * @this {import('../../component').BlitsComponent}
      */
     value: function (e) {
       // force refocus when the component is already in focused state
-      if (this.lifecycle.state === 'focus') {
-        this.lifecycle.state = 'refocus'
+      if (this[symbols.lifecycle].state === 'focus') {
+        this[symbols.lifecycle].state = 'refocus'
       }
       Focus.set(this, e)
     },
@@ -93,8 +81,8 @@ export default {
      * @this {import('../../component').BlitsComponent}
      */
     value: function () {
-      this[symbols.state].hasFocus = false
-      this.lifecycle.state = 'unfocus'
+      this[symbols.state].$hasFocus = false
+      this[symbols.lifecycle].state = 'unfocus'
     },
     writable: false,
     enumerable: true,
@@ -106,11 +94,11 @@ export default {
      */
     value: function () {
       this.eol = true
-      this.lifecycle.state = 'destroy'
+      this[symbols.lifecycle].state = 'destroy'
 
       // when destroying a component that currently has focus
       // pass focus to the parent so we don't get lost in focus limbo
-      if (this.hasFocus === true) this.parent.$focus()
+      if (this.$hasFocus === true) this[symbols.parent].$focus()
 
       for (let key in this[symbols.state]) {
         if (Array.isArray(this[symbols.state][key])) {
@@ -139,26 +127,25 @@ export default {
       this[symbols.state] = {}
 
       this[symbols.props] = {}
-      this[symbols.computed] = null
-      this.lifecycle = {}
+      this[symbols.computedKeys] = null
+      this[symbols.lifecycle] = {}
       this[symbols.effects].length = 0
-      this.parent = null
-      this.rootParent = null
+      this[symbols.parent] = null
+      this[symbols.rootParent] = null
       this[symbols.wrapper] = null
       this[symbols.originalState] = null
       this[symbols.slots].length = 0
 
-      delete this[symbols.computed]
-      delete this.parent
-      delete this.rootParent
+      delete this[symbols.computedKeys]
+      delete this[symbols.parent]
+      delete this[symbols.rootParent]
       delete this[symbols.wrapper]
       delete this[symbols.originalState]
       delete this[symbols.children]
       delete this[symbols.slots]
-      delete this.componentId
       delete this[symbols.id]
       delete this.ref
-      delete this[symbols.state].hasFocus
+      delete this[symbols.state].$hasFocus
 
       this[symbols.holder].destroy()
       this[symbols.holder] = null
@@ -169,7 +156,8 @@ export default {
 
       delete this[symbols.effects]
 
-      Log.debug(`Destroyed component ${this.componentId}`)
+      Log.debug(`Destroyed component ${this.$componentId}`)
+      delete this.$componentId
     },
     writable: false,
     enumerable: true,
@@ -186,18 +174,6 @@ export default {
     enumerable: false,
     configurable: false,
   },
-  select: {
-    /**
-     * @this {import('../../component').BlitsComponent}
-     */
-    value: function (ref) {
-      Log.warn('this.select is deprecated, use this.$select instead')
-      return this.$select(ref)
-    },
-    writable: false,
-    enumerable: true,
-    configurable: false,
-  },
   $select: {
     /**
      * @this {import('../../component').BlitsComponent}
@@ -226,18 +202,6 @@ export default {
     enumerable: true,
     configurable: false,
   },
-  trigger: {
-    /**
-     * @this {import('../../component').BlitsComponent}
-     */
-    value: function (key) {
-      Log.warn('this.trigger is deprecated, use this.$trigger instead')
-      return this.$trigger(key)
-    },
-    writable: false,
-    enumerable: true,
-    configurable: false,
-  },
   $trigger: {
     /**
      * @this {import('../../component').BlitsComponent}
@@ -259,30 +223,6 @@ export default {
     enumerable: true,
     configurable: false,
   },
-  shader: {
-    /**
-     * @this {import('../../component').BlitsComponent}
-     */
-    value: function (type, args) {
-      return {
-        type: type,
-        props: args,
-      }
-      // const shaders = renderer.driver.stage.shManager.getRegisteredEffects()
-
-      // if (target in shaders) {
-      //   return {
-      //     type: target,
-      //     props: args,
-      //   }
-      // } else {
-      //   Log.error(`Shader ${type} not found`)
-      // }
-    },
-    writable: false,
-    enumerable: true,
-    configurable: false,
-  },
 }
 
 /**

package/src/component/base/utils.js

@@ -29,6 +29,20 @@ export default {
     enumerable: true,
     configurable: false,
   },
+  $parent: {
+    get: function () {
+      return this[symbols.parent]
+    },
+    enumerable: true,
+    configurable: false,
+  },
+  $id: {
+    get: function () {
+      return this[symbols.id]
+    },
+    enumerable: true,
+    configurable: false,
+  },
   [symbols.renderer]: {
     value: () => renderer,
     writable: false,
@@ -37,7 +51,7 @@ export default {
   },
   [symbols.getChildren]: {
     value() {
-      const parent = this.rootParent || this.parent
+      const parent = this[symbols.rootParent] || this[symbols.parent]
       return (this[symbols.children] || []).concat(
         (parent &&
           parent[symbols.getChildren]()
@@ -46,7 +60,7 @@ export default {
                 return Object.values(child).map((c) => {
                   // ugly hack .. but the point is to reference the right component
                   c.forComponent =
-                    c[Symbol.for('config')] && c[Symbol.for('config')].parent.component
+                    c[Symbol.for('config')] && c[Symbol.for('config')][symbols.parent].component
                   return c
                 })
               }
@@ -57,8 +71,8 @@ export default {
               // problem is that component of a forloop in a slot has component of root component
               if (child && child.component) {
                 return (
-                  (child.component && child.component.componentId === this.componentId) ||
-                  (child.forComponent && child.forComponent.componentId === this.componentId)
+                  (child.component && child.component.$componentId === this.$componentId) ||
+                  (child.forComponent && child.forComponent.$componentId === this.$componentId)
                 )
               }
             })) ||

package/src/component/setup/props.js

@@ -16,46 +16,55 @@
  */
 
 import { Log } from '../../lib/log.js'
-
 import symbols from '../../lib/symbols.js'
 
-const baseProp = {
-  cast: (v) => v,
-  required: false,
+const normalizeProps = (props) => {
+  Log.warn(
+    'Defining props as an Array has been deprecated and will stop working in future versions. Please use the new notation instead (an object with key values pairs).',
+    props
+  )
+  const out = {}
+  const propLength = props.length
+  for (let i = 0; i < propLength; i++) {
+    const prop = props[i]
+    if (typeof prop === 'string') {
+      out[prop] = undefined
+    } else {
+      Log.error(
+        'Defining props as an array of objects is no longer supported. Please use the new format: an object with key-value pairs.'
+      )
+      break
+    }
+  }
+  return out
 }
 
-export default (component, props = []) => {
-  if (props.indexOf('ref') === -1) {
-    props.push('ref')
+export default (component, props = {}) => {
+  if (Array.isArray(props) === true) {
+    props = normalizeProps(props)
+  }
+  if (!('ref' in props)) {
+    props.ref = undefined
   }
-  component[symbols.propKeys] = []
+  const keys = Object.keys(props)
+  component[symbols.propKeys] = keys
 
-  const propsLength = props.length
+  for (let i = 0; i < keys.length; i++) {
+    const key = keys[i]
+    const defaultPropValue = props[key]
 
-  for (let i = 0; i < propsLength; i++) {
-    const prop = { ...baseProp, ...(typeof props[i] === 'object' ? props[i] : { key: props[i] }) }
-    component[symbols.propKeys].push(prop.key)
-    Object.defineProperty(component, prop.key, {
+    Object.defineProperty(component, key, {
       get() {
-        const value = prop.cast(
-          this[symbols.props] !== undefined && prop.key in this[symbols.props]
-            ? this[symbols.props][prop.key]
-            : 'default' in prop
-              ? prop.default
-              : undefined
-        )
-
-        if (prop.required === true && value === undefined) {
-          Log.warn(`${prop.key} is required`)
-        }
-
-        return value
+        if (this[symbols.props] === undefined) return undefined
+        // if the key is specified independent of the value (falsy, null, undefined) use that value
+        // otherwise return the default prop value
+        return key in this[symbols.props] ? this[symbols.props][key] : defaultPropValue
       },
       set(v) {
         Log.warn(
-          `Warning! Avoid mutating props directly (prop "${prop.key}" in component "${this.componentId}")`
+          `Warning! Avoid mutating props directly (prop "${key}" in component "${this.componentId}")`
         )
-        this[symbols.props][prop.key] = v
+        this[symbols.props][key] = v
       },
     })
   }

package/src/component/setup/state.js

@@ -28,13 +28,13 @@ export default (component, state = () => {}) => {
   })
 
   const stateKeys = Object.keys(state.apply(component) || {})
-  if (stateKeys.indexOf('hasFocus') > -1) {
+  if (stateKeys.indexOf('$hasFocus') > -1) {
     Log.warn(
-      'State `hasFocus` already exists as a built-in Component variable (to indicate whether the component currently has focus). Avoid using your own `hasFocus` key in the Component state'
+      'State `$hasFocus` already exists as a built-in Component variable (to indicate whether the component currently has focus). Avoid using your own `$hasFocus` key in the Component state'
     )
   } else {
-    // add built-in hasFocus key
-    stateKeys.push(['hasFocus'])
+    // add built-in $hasFocus key
+    stateKeys.push('$hasFocus')
   }
   const stateKeysLength = stateKeys.length