@lightningjs/blits 2.4.1 → 2.6.0

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## 2.6.0
+
+_25 jun 2026_
+
+- Added platform layer for browser API abstraction (passed as a launch option)
+- Improved reactivity guard vite plugin
+- Added testing harness to support Blits component testing
+
+## 2.5.0
+
+_11 jun 2026_
+
+- Improved performance of Sprites
+- Fixed correct typing of computed props
+- Bumped renderer to 3.0.6
+- Added re-export of platforms from renderer
+
 ## v2.4.1
 
 _02 jun 2026_

package/index.d.ts

@@ -623,24 +623,36 @@ declare module '@lightningjs/blits' {
     [K in keyof T]: InferProp<T[K]>
   }
 
+  type Computed<T extends Record<string, () => any>> = {
+    [K in keyof T]: Readonly<ReturnType<T[K]>>
+  }
+
   export type ComponentContext<
     P extends Record<string, any>,
     S,
     M,
-    C
-  > = ThisType<Readonly<InferProps<P>> & S & M & Readonly<C> & ChildComponentBase>
+    C extends Record<string, () => any>,
+  > = ThisType<
+    Readonly<InferProps<P>> & S & M & Computed<C> & ChildComponentBase
+  >
 
   export type ApplicationContext<
     P extends Record<string, any>,
     S,
     M,
-    C
-  > = ThisType<Readonly<InferProps<P>> & S & M & Readonly<C> & ApplicationBase>
+    C,
+  > = ThisType<Readonly<InferProps<P>> & S & M & Computed<C> & ApplicationBase>
 
-  export interface ComponentConfig<P extends Props = {}, S, M, C, W> {
+  export interface ComponentConfig<
+    P extends Props = {},
+    S,
+    M,
+    C extends Record<string, () => any>,
+    W,
+  > {
     components?: {
-        [key: string]: ComponentFactory,
-    },
+      [key: string]: ComponentFactory
+    }
     /**
      * XML-based template string of the Component
      *
@@ -1004,6 +1016,74 @@ declare module '@lightningjs/blits' {
   type ReactivityModes = 'Proxy' | 'defineProperty'
   type RenderModes = 'webgl' | 'canvas'
 
+  interface Platform {
+    /**
+     * Target used for keyboard and pointer input listeners.
+     */
+    input?: EventTarget | any,
+    /**
+     * Target used for viewport-level listeners such as resize, scroll, and hashchange.
+     */
+    viewport?: EventTarget | any,
+    /**
+     * Dispatch an event through the platform's event system.
+     */
+    dispatchEvent?: (event: any) => boolean | void,
+    /**
+     * Persistent key/value storage API.
+     */
+    localStorage?: Storage | any,
+    /**
+     * Read the platform cookie string.
+     */
+    getCookie?: () => string,
+    /**
+     * Write a cookie string.
+     */
+    setCookie?: (value: string) => void,
+    /**
+     * Navigate back in the platform history, when available.
+     */
+    historyBack?: () => void,
+    /**
+     * Current viewport/screen height.
+     */
+    screenHeight?: number,
+    /**
+     * Available hardware concurrency.
+     */
+    hardwareConcurrency?: number,
+    /**
+     * User agent string for platform-specific defaults.
+     */
+    userAgent?: string,
+    /**
+     * KeyboardEvent constructor used for event creation and type checks.
+     */
+    KeyboardEvent?: typeof KeyboardEvent | any,
+    /**
+     * Check whether an object should be treated as a keyboard event.
+     */
+    isKeyboardEvent?: (event: any) => boolean,
+    /**
+     * Create a keyboard event for the current platform.
+     */
+    createKeyboardEvent?: (type: string, init?: KeyboardEventInit | any) => any,
+    /**
+     * SpeechSynthesisUtterance constructor used by the announcer.
+     */
+    SpeechSynthesisUtterance?: typeof SpeechSynthesisUtterance | any,
+    /**
+     * Speech synthesis API implementation used by the announcer.
+     */
+    speechSynthesis?: SpeechSynthesis | any,
+    /**
+     * Monotonic timestamp provider used for input throttling.
+     */
+    now?: () => number,
+    [key: string]: any,
+  }
+
     /**
    * Settings
    *
@@ -1319,11 +1399,20 @@ declare module '@lightningjs/blits' {
      */
     maxFPS?: number,
     /**
-     * Custom platform layer to be used by the App (experimental)
+     * Custom platform layer to be used by the App.
      *
-     * Defaults to `null` which will be resolved internally to WebPlatform
+     * Allows replacing platform capabilities such as input targets, storage,
+     * keyboard event constructors, and speech APIs.
+     * A callback receives Blits' browser defaults and should return the platform overrides.
      */
-    platform?: any
+    platform?: (defaults: Platform) => Partial<Platform>,
+    /**
+     * Custom platform layer to be used by the renderer.
+     *
+     * For renderer-specific platform implementations. Passing a renderer platform
+     * through `platform` is deprecated.
+     */
+    rendererPlatform?: RendererMainSettings['platform']
 
   }
 
@@ -1340,7 +1429,7 @@ declare module '@lightningjs/blits' {
   }
 
   interface Computed {
-    [key: string]: any
+    [key: string]: () => any
   }
 
 

package/package.json

@@ -1,10 +1,14 @@
 {
   "name": "@lightningjs/blits",
-  "version": "2.4.1",
+  "version": "2.6.0",
   "description": "Blits: The Lightning 3 App Development Framework",
   "bin": "bin/index.js",
   "exports": {
     ".": "./index.js",
+    "./platforms": {
+      "types": "./src/platforms.d.ts",
+      "default": "./src/platforms.js"
+    },
     "./vite": "./vite/index.js",
     "./transitions": "./src/router/transitions/index.js",
     "./precompiler": "./src/lib/precompiler/precompiler.js",
@@ -28,6 +32,10 @@
       "types": "./src/plugins/storage/storage.d.ts",
       "default": "./src/plugins/storage/storage.js"
     },
+    "./testing": {
+      "types": "./src/testing/index.d.ts",
+      "default": "./src/testing/index.js"
+    },
     "./symbols": "./src/lib/symbols.js",
     "./blitsFileConverter": "./src/lib/blitsfileconverter/blitsfileconverter.js",
     "./components": "./src/components/FPScounter.js"
@@ -75,7 +83,7 @@
     "tape": "^5.5.0"
   },
   "dependencies": {
-    "@lightningjs/renderer": "^3.0.3",
+    "@lightningjs/renderer": "^3.0.6",
     "magic-string": "^0.30.21"
   },
   "repository": {

package/src/announcer/announcer.js

@@ -17,6 +17,7 @@
 
 import { Log } from '../lib/log.js'
 import speechSynthesis from './speechSynthesis.js'
+import { platform } from '../platform.js'
 
 let active = false
 let count = 0
@@ -27,7 +28,7 @@ let debounce = null
 
 // Global default utterance options
 let globalDefaultOptions = {
-  enableUtteranceKeepAlive: !/android/i.test((self.navigator || {}).userAgent || ''),
+  enableUtteranceKeepAlive: !/android/i.test(platform.userAgent || ''),
 }
 
 const noopAnnouncement = {

package/src/announcer/speechSynthesis.js

@@ -16,8 +16,7 @@
  */
 
 import { Log } from '../lib/log.js'
-
-const syn = self.speechSynthesis
+import { platform } from '../platform.js'
 
 const utterances = new Map() // id -> { utterance, timer, ignoreResume }
 
@@ -36,6 +35,7 @@ const clear = (id) => {
 }
 
 const startKeepAlive = (id) => {
+  const syn = platform.speechSynthesis
   const state = utterances.get(id)
 
   // utterance status: utterance was removed (cancelled or finished)
@@ -85,6 +85,7 @@ const defaultUtteranceProps = {
 }
 
 const initialize = () => {
+  const syn = platform.speechSynthesis
   // syn api check: syn might not have getVoices method
   if (!syn || typeof syn.getVoices !== 'function') {
     initialized = false
@@ -98,6 +99,7 @@ const initialize = () => {
 
 const waitForSynthReady = (timeoutMs = 2000, checkIntervalMs = 100) => {
   return new Promise((resolve) => {
+    const syn = platform.speechSynthesis
     if (!syn) {
       Log.debug('SpeechSynthesis - syn unavailable')
       resolve()
@@ -135,6 +137,7 @@ const waitForSynthReady = (timeoutMs = 2000, checkIntervalMs = 100) => {
 }
 
 const speak = async (options) => {
+  const syn = platform.speechSynthesis
   // options check: missing required options
   if (!options || !options.message) {
     return Promise.reject({ error: 'Missing message' })
@@ -154,6 +157,11 @@ const speak = async (options) => {
   // Wait for engine to be ready
   await waitForSynthReady()
 
+  const SpeechSynthesisUtterance = platform.SpeechSynthesisUtterance
+  if (SpeechSynthesisUtterance === undefined) {
+    return Promise.reject({ error: 'unavailable' })
+  }
+
   const utterance = new SpeechSynthesisUtterance(options.message)
   utterance.lang = options.lang || defaultUtteranceProps.lang
   utterance.pitch = options.pitch || defaultUtteranceProps.pitch
@@ -208,6 +216,7 @@ const speak = async (options) => {
 
 export default {
   speak(options) {
+    const syn = platform.speechSynthesis
     if (syn !== undefined) {
       if (initialized === false) {
         initialize()
@@ -219,6 +228,7 @@ export default {
     }
   },
   cancel() {
+    const syn = platform.speechSynthesis
     if (syn !== undefined) {
       // timers: clear all timers before cancelling
       for (const id of utterances.keys()) {

package/src/application.js

@@ -23,6 +23,7 @@ import Settings from './settings.js'
 import symbols from './lib/symbols.js'
 import { DEFAULT_HOLD_TIMEOUT_MS, DEFAULT_KEYMAP } from './constants.js'
 import { renderer } from './launch.js'
+import { platform } from './platform.js'
 
 /**
  * Merged keyMap (default + custom settings).
@@ -31,6 +32,10 @@ import { renderer } from './launch.js'
  */
 export let keyMap = {}
 
+export const initKeyMap = () => {
+  keyMap = { ...DEFAULT_KEYMAP, ...Settings.get('keymap', {}) }
+}
+
 const Application = (config) => {
   config.hooks = config.hooks || {}
 
@@ -39,22 +44,23 @@ const Application = (config) => {
   let mouseMoveHandler
   let mouseClickHandler
   let updateCanvasRect
+  let inputCleanup
+  let mouseCleanup
   let holdTimeout
   let lastInputTime = 0
   let lastInputKey = null
-  let mouseListenersAdded = false
 
   config.hooks[symbols.destroy] = function () {
     // Cancel pending key-hold timeout and reset hold state so focus is not left in hold mode after teardown
     clearTimeout(holdTimeout)
     Focus.hold = false
-    document.removeEventListener('keydown', keyDownHandler)
-    document.removeEventListener('keyup', keyUpHandler)
-    if (mouseListenersAdded) {
-      document.removeEventListener('mousemove', mouseMoveHandler)
-      document.removeEventListener('click', mouseClickHandler)
-      window.removeEventListener('resize', updateCanvasRect)
-      window.removeEventListener('scroll', updateCanvasRect)
+    if (typeof inputCleanup === 'function') {
+      inputCleanup()
+      inputCleanup = undefined
+    }
+    if (typeof mouseCleanup === 'function') {
+      mouseCleanup()
+      mouseCleanup = undefined
       Hover.clear()
     }
   }
@@ -68,15 +74,16 @@ const Application = (config) => {
       this.$announcer.configure(announcerOptions)
     }
     // Initialize merged keyMap once during application init
-    keyMap = { ...DEFAULT_KEYMAP, ...Settings.get('keymap', {}) }
+    initKeyMap()
 
     /** @type {number} Input throttle time in milliseconds (0 = disabled) */
     const throttleMs = Settings.get('inputThrottle', 0)
 
     const mouseEnabled = Settings.get('enableMouse', false)
+    const { createKeyboardEvent, input, isKeyboardEvent, now = Date.now, viewport } = platform
 
     keyDownHandler = async (e) => {
-      const currentTime = performance.now()
+      const currentTime = now()
 
       const key = keyMap[e.keyCode] || e.keyCode
       const sameKey = lastInputKey === key
@@ -103,7 +110,7 @@ const Application = (config) => {
       ) {
         e = await this[symbols.inputEvents].intercept.call(this, e)
         // only pass on the key press to focused component when keyboard event is returned
-        if (e instanceof KeyboardEvent === false) return
+        if (isKeyboardEvent && isKeyboardEvent(e) === false) return
       }
 
       Focus.input(key, e)
@@ -183,7 +190,9 @@ const Application = (config) => {
     mouseClickHandler = () => {
       if (currentComponent === undefined || currentComponent.eol === true) return
 
-      const e = new KeyboardEvent('keydown', {
+      if (createKeyboardEvent === undefined) return
+
+      const e = createKeyboardEvent('keydown', {
         key: 'Enter',
         code: 'Enter',
         keyCode: 13,
@@ -195,15 +204,26 @@ const Application = (config) => {
       currentComponent.$input(e)
     }
 
-    document.addEventListener('keydown', keyDownHandler)
-    document.addEventListener('keyup', keyUpHandler)
-    if (mouseEnabled === true) {
+    if (input !== undefined) {
+      input.addEventListener('keydown', keyDownHandler)
+      input.addEventListener('keyup', keyUpHandler)
+      inputCleanup = () => {
+        input.removeEventListener('keydown', keyDownHandler)
+        input.removeEventListener('keyup', keyUpHandler)
+      }
+    }
+    if (mouseEnabled === true && input !== undefined && viewport !== undefined) {
       updateCanvasRect()
-      document.addEventListener('mousemove', mouseMoveHandler)
-      document.addEventListener('click', mouseClickHandler)
-      window.addEventListener('resize', updateCanvasRect)
-      window.addEventListener('scroll', updateCanvasRect)
-      mouseListenersAdded = true
+      input.addEventListener('mousemove', mouseMoveHandler)
+      input.addEventListener('click', mouseClickHandler)
+      viewport.addEventListener('resize', updateCanvasRect)
+      viewport.addEventListener('scroll', updateCanvasRect)
+      mouseCleanup = () => {
+        input.removeEventListener('mousemove', mouseMoveHandler)
+        input.removeEventListener('click', mouseClickHandler)
+        viewport.removeEventListener('resize', updateCanvasRect)
+        viewport.removeEventListener('scroll', updateCanvasRect)
+      }
     }
 
     // next tick

package/src/component/base/methods.js

@@ -23,6 +23,7 @@ import { Log } from '../../lib/log.js'
 import { removeGlobalEffects } from '../../lib/reactivity/effect.js'
 import { renderer } from '../../launch.js'
 import { keyMap } from '../../application.js'
+import { platform } from '../../platform.js'
 
 export default {
   $focus: {
@@ -48,7 +49,11 @@ export default {
      * @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)
+      if (
+        event === null ||
+        event === undefined ||
+        (platform.isKeyboardEvent && platform.isKeyboardEvent(event) === false)
+      )
         return false
 
       const key = keyMap[event.keyCode] || event.keyCode

package/src/component.js

@@ -92,10 +92,14 @@ export const componentMap = new WeakMap()
  * @typedef {Object} BlitsElement
  * @property {BlitsComponent} component - Reference to the owning Blits component.
  * @property {BlitsElementConfig} config - Configuration object for the element.
+ * @property {boolean} eol - Indicates when the element is end-of-life (destroyed).
  * @property {number} counter - Unique counter used for shader workarounds. FIXME?
  * @property {string[]} effectNames - Names of active shader effects.
  * @property {any} node - The underlying renderer node (e.g., WebGL node or text node).
  * @property {BlitsElementProps} props - Proxy-like object containing transformed props.
+ * @property {Object<string, any>} scheduledTransitions - Tracks transitions by property name.
+ * @property {Object<string, ReturnType<typeof setTimeout>>} debounceTimeouts - Pending animation debounce timers.
+ * @property {any} [_spriteState] - Native Sprite texture cache (L3 only).
  * @property {any[]} children - WVB I cant see this populated? Filtered list of children owned by this element. FIXME?
  * @property {any} parent - WVB Shortcut to the parent CoreNode?
  * @property {number} nodeId - ID of the CoreNode, if available.
@@ -105,6 +109,9 @@ export const componentMap = new WeakMap()
  * @property {function(string, any, Object):void} animate - Animates a property with transition options.
  * @property {function():void} destroy - Destroys the underlying node and cancels transitions.
  * @property {function(any): any} triggerLayout - Triggers a layout update for the element.
+ * @property {function(Object):void} setInspectorMetadata - Merges inspector metadata onto the node.
+ * @property {function():void} _scheduleNativeSpriteSync - Queues a coalesced native Sprite texture sync.
+ * @property {function():void} _syncNativeSprite - Resolves and applies the native Sprite texture.
  *
  * @typedef {Object} BlitsLifecycle
  * @property {BlitsComponent} component - The Blits comonent instance this lifecycle belongs to.

package/src/components/Circle.js

@@ -35,6 +35,9 @@ export default () =>
           'color',
           'src',
           'texture',
+          'image',
+          'map',
+          'frame',
           'fit',
           'rtt',
           'mount',