@lightningjs/blits 2.5.0 → 2.7.0

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## 2.7.0
+
+_2 jul 2026_
+
+- Added `keepAlive` option to `src`-object to prevent a texture from being cleaned up by the renderer
+- Abstracted announcer (and speechSynthesis) to be platform provided (with speechSynthesis as the built-in default)
+- Added dedicated findByData methods to testing harness to select specific nodes in the tree
+- Improved test cases around frameTick cleanup
+
+## 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_

package/index.d.ts

@@ -66,6 +66,28 @@ declare module '@lightningjs/blits' {
     enableUtteranceKeepAlive?: boolean
   }
 
+  export interface AnnouncerDriverOptions extends AnnouncerUtteranceOptions {
+    /**
+     * Message to be spoken by the platform announcer driver.
+     */
+    message: string | number,
+    /**
+     * Internal announcement id used by the Blits announcer queue.
+     */
+    id: number,
+  }
+
+  export interface AnnouncerDriver {
+    /**
+     * Speak one queued announcement.
+     */
+    speak(options: AnnouncerDriverOptions): Promise<any>,
+    /**
+     * Stop the active platform announcement, when supported.
+     */
+    cancel(): void,
+  }
+
   export interface AnnouncerUtterance<T = any> extends Promise<T> {
     /**
      * Removes a specific message from the announcement queue,
@@ -1016,6 +1038,70 @@ 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,
+    /**
+     * Platform-specific announcer driver used instead of the default Web Speech driver.
+     */
+    announcer?: AnnouncerDriver,
+    /**
+     * Monotonic timestamp provider used for input throttling.
+     */
+    now?: () => number,
+    [key: string]: any,
+  }
+
     /**
    * Settings
    *
@@ -1331,11 +1417,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.
+     *
+     * 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?: (defaults: Platform) => Partial<Platform>,
+    /**
+     * Custom platform layer to be used by the renderer.
      *
-     * Defaults to `null` which will be resolved internally to WebPlatform
+     * For renderer-specific platform implementations. Passing a renderer platform
+     * through `platform` is deprecated.
      */
-    platform?: any
+    rendererPlatform?: RendererMainSettings['platform']
 
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lightningjs/blits",
-  "version": "2.5.0",
+  "version": "2.7.0",
   "description": "Blits: The Lightning 3 App Development Framework",
   "bin": "bin/index.js",
   "exports": {
@@ -32,6 +32,14 @@
       "types": "./src/plugins/storage/storage.d.ts",
       "default": "./src/plugins/storage/storage.js"
     },
+    "./platforms/webOS/announcer": {
+      "types": "./src/platforms/webOS/announcer.d.ts",
+      "default": "./src/platforms/webOS/announcer.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"

package/src/announcer/announcer.js

@@ -16,7 +16,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 +27,21 @@ let debounce = null
 
 // Global default utterance options
 let globalDefaultOptions = {
-  enableUtteranceKeepAlive: !/android/i.test((self.navigator || {}).userAgent || ''),
+  enableUtteranceKeepAlive: !/android/i.test(platform.userAgent || ''),
+}
+
+const getDriver = () => {
+  const driver = platform.announcer
+  if (driver && typeof driver.speak === 'function') {
+    return driver
+  }
+}
+
+const cancelDriver = () => {
+  const driver = getDriver()
+  if (driver && typeof driver.cancel === 'function') {
+    driver.cancel()
+  }
 }
 
 const noopAnnouncement = {
@@ -83,9 +97,9 @@ const addToQueue = (message, politeness, delay = false, options = {}) => {
   // augment the promise with a stop function
   done.stop = () => {
     if (id === currentId) {
-      speechSynthesis.cancel()
+      cancelDriver()
       isProcessing = false
-      resolveFn('interupted')
+      resolveFn('interrupted')
     }
   }
 
@@ -132,7 +146,17 @@ const processQueue = async () => {
     debounce = setTimeout(() => {
       Log.debug(`Announcer - speaking: "${message}" (id: ${id})`)
 
-      speechSynthesis
+      const driver = getDriver()
+      if (driver === undefined) {
+        currentId = null
+        currentResolveFn = null
+        isProcessing = false
+        resolveFn('unavailable')
+        processQueue()
+        return
+      }
+
+      driver
         .speak({
           message,
           id,
@@ -179,8 +203,8 @@ const stop = () => {
   // Clear debounce timer if speech hasn't started yet
   clearDebounceTimer()
 
-  // Always cancel speech synthesis to ensure clean state
-  speechSynthesis.cancel()
+  // Always cancel the platform announcer to ensure clean state
+  cancelDriver()
 
   // Store resolve function before resetting state
   const resolveFn = currentResolveFn

package/src/announcer/speechSynthesis.js

@@ -17,11 +17,27 @@
 
 import { Log } from '../lib/log.js'
 
-const syn = self.speechSynthesis
-
 const utterances = new Map() // id -> { utterance, timer, ignoreResume }
 
 let initialized = false
+const globalScope = globalThis
+
+const getSpeechSynthesis = () => {
+  const windowRef = globalScope.window
+  const selfRef = globalScope.self || windowRef || globalScope
+
+  return (
+    globalScope.speechSynthesis ||
+    (selfRef && selfRef.speechSynthesis) ||
+    (windowRef && windowRef.speechSynthesis)
+  )
+}
+
+const getSpeechSynthesisUtterance = () => {
+  const windowRef = globalScope.window
+
+  return globalScope.SpeechSynthesisUtterance || (windowRef && windowRef.SpeechSynthesisUtterance)
+}
 
 const clear = (id) => {
   const state = utterances.get(id)
@@ -36,6 +52,7 @@ const clear = (id) => {
 }
 
 const startKeepAlive = (id) => {
+  const syn = getSpeechSynthesis()
   const state = utterances.get(id)
 
   // utterance status: utterance was removed (cancelled or finished)
@@ -85,6 +102,7 @@ const defaultUtteranceProps = {
 }
 
 const initialize = () => {
+  const syn = getSpeechSynthesis()
   // syn api check: syn might not have getVoices method
   if (!syn || typeof syn.getVoices !== 'function') {
     initialized = false
@@ -98,6 +116,7 @@ const initialize = () => {
 
 const waitForSynthReady = (timeoutMs = 2000, checkIntervalMs = 100) => {
   return new Promise((resolve) => {
+    const syn = getSpeechSynthesis()
     if (!syn) {
       Log.debug('SpeechSynthesis - syn unavailable')
       resolve()
@@ -135,6 +154,7 @@ const waitForSynthReady = (timeoutMs = 2000, checkIntervalMs = 100) => {
 }
 
 const speak = async (options) => {
+  const syn = getSpeechSynthesis()
   // options check: missing required options
   if (!options || !options.message) {
     return Promise.reject({ error: 'Missing message' })
@@ -154,6 +174,11 @@ const speak = async (options) => {
   // Wait for engine to be ready
   await waitForSynthReady()
 
+  const SpeechSynthesisUtterance = getSpeechSynthesisUtterance()
+  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 +233,7 @@ const speak = async (options) => {
 
 export default {
   speak(options) {
+    const syn = getSpeechSynthesis()
     if (syn !== undefined) {
       if (initialized === false) {
         initialize()
@@ -219,6 +245,7 @@ export default {
     }
   },
   cancel() {
+    const syn = getSpeechSynthesis()
     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

@@ -38,6 +38,11 @@ import { plugins } from './plugin.js'
 
 // object to store global components
 let globalComponents
+let devMode = false
+
+export const setDevMode = (enabled) => {
+  devMode = enabled === true
+}
 
 const required = (name) => {
   throw new Error(`Parameter ${name} is required`)
@@ -493,7 +498,7 @@ const Component = (name = required('name'), config = required('config')) => {
     // one time code generation (only if precompilation is turned off)
     if (config.code === undefined) {
       Log.debug(`Generating code for ${name} component`)
-      config.code = codegenerator.call(config, parser(config.template, name))
+      config.code = codegenerator.call(config, parser(config.template, name), devMode)
     }
 
     // create an instance of the component, using base as the prototype (which contains Base)

package/src/components/RouterView.js

@@ -23,6 +23,7 @@ import Router, {
 } from '../router/router.js'
 import symbols from '../lib/symbols.js'
 import Focus from '../focus/focus.js'
+import { platform } from '../platform.js'
 
 /** @typedef {{ $input?: (event: any) => boolean, $focus?: (event: any) => void }} RouterViewParent */
 
@@ -159,11 +160,18 @@ export default () =>
             Router.navigate.apply(this)
           }
 
-          window.addEventListener('hashchange', this.hashchangeHandler)
+          const viewport = platform.viewport
+          if (viewport !== undefined) {
+            this.hashchangeViewport = viewport
+            viewport.addEventListener('hashchange', this.hashchangeHandler)
+          }
         },
         destroy() {
           unregisterRouterView(this)
-          window.removeEventListener('hashchange', this.hashchangeHandler, false)
+          if (this.hashchangeViewport !== undefined) {
+            this.hashchangeViewport.removeEventListener('hashchange', this.hashchangeHandler, false)
+            this.hashchangeViewport = undefined
+          }
         },
         focus() {
           if (this.activeView && Focus.get() === this) {

package/src/engines/L3/element.js

@@ -202,6 +202,15 @@ const colorMap = {
   right: 'colorRight',
 }
 
+const setTextureOption = (target, key, value) => {
+  const opts =
+    target.props['textureOptions'] ||
+    (target.element.node && target.element.node.textureOptions) ||
+    {}
+  opts[key] = value
+  target.props['textureOptions'] = opts
+}
+
 /**
  * Default text settings for text nodes (initialized on first use).
  * @type {object|null}
@@ -275,6 +284,9 @@ const propsTransformer = {
     if (typeof v === 'object' || (isObjectString(v) === true && (v = parseToObject(v)))) {
       this.props['src'] = v.src
       this.props['imageType'] = v.type
+      if ('keepAlive' in v) {
+        setTextureOption(this, 'preventCleanup', v.keepAlive === true)
+      }
     } else {
       this.props['src'] = v
     }
@@ -318,7 +330,7 @@ const propsTransformer = {
     const resizeMode = {}
 
     if (v === 'cover' || v === 'contain') {
-      this.props['textureOptions'] = { resizeMode: { type: v } }
+      setTextureOption(this, 'resizeMode', { type: v })
       return
     }
 
@@ -333,7 +345,7 @@ const propsTransformer = {
         resizeMode['clipX'] = 'x' in v.position === true ? v.position.x : null
         resizeMode['clipY'] = 'y' in v.position === true ? v.position.y : null
       }
-      this.props['textureOptions'] = { resizeMode }
+      setTextureOption(this, 'resizeMode', resizeMode)
     }
   },
   set rtt(v) {

package/src/engines/L3/launch.js

@@ -25,6 +25,7 @@ import { SCREEN_RESOLUTIONS, RENDER_QUALITIES } from '../../constants.js'
 import colors from '../../lib/colors/colors.js'
 import fontLoader from './fontLoader.js'
 import shaderLoader from './shaderLoader.js'
+import { platform } from '../../platform.js'
 
 /** @type {RendererMain|{}} */
 export let renderer = {}
@@ -73,6 +74,11 @@ const textureMemorySettings = (settings) => {
  *
  */
 export default (App, target, settings = {}) => {
+  const screenHeight = settings.platform ? settings.platform.screenHeight : platform.screenHeight
+  const hardwareConcurrency = settings.platform
+    ? settings.platform.hardwareConcurrency
+    : platform.hardwareConcurrency
+
   renderer = new RendererMain(
     {
       ...{
@@ -84,12 +90,10 @@ export default (App, target, settings = {}) => {
         deviceLogicalPixelRatio:
           settings.pixelRatio ||
           SCREEN_RESOLUTIONS[settings.screenResolution] ||
-          SCREEN_RESOLUTIONS[window.innerHeight] ||
+          SCREEN_RESOLUTIONS[screenHeight] ||
           1,
         numImageWorkers:
-          'webWorkersLimit' in settings
-            ? settings.webWorkersLimit
-            : window.navigator.hardwareConcurrency || 2,
+          'webWorkersLimit' in settings ? settings.webWorkersLimit : hardwareConcurrency || 2,
         clearColor: (settings.canvasColor && colors.normalize(settings.canvasColor)) || 0x00000000,
         inspector: settings.inspector === true ? Inspector : undefined,
         boundsMargin: settings.viewportMargin || 0,
@@ -100,7 +104,7 @@ export default (App, target, settings = {}) => {
         textureMemory: textureMemorySettings(settings),
         createImageBitmapSupport: 'auto',
         targetFPS: 'maxFPS' in settings ? settings.maxFPS : 0,
-        platform: 'platform' in settings ? settings.platform : null,
+        platform: settings.rendererPlatform || null,
       },
       ...(settings.advanced || {}),
     },

package/src/focus/focus.js

@@ -21,7 +21,7 @@ import Settings from '../settings.js'
 import { DEFAULT_HOLD_TIMEOUT_MS } from '../constants.js'
 import { Log } from '../lib/log.js'
 import { getAncestors } from './helpers.js'
-import InternalKeyboardEvent from '../lib/events/internalkeyboardevent.js'
+import { platform } from '../platform.js'
 
 let focusedComponent = null
 let focusChain = []
@@ -136,8 +136,11 @@ const setFocus = (component, event) => {
   focusedComponent = component
   component[symbols.lifecycle].state = 'focus'
 
-  if (event instanceof KeyboardEvent) {
-    const internalEvent = new InternalKeyboardEvent('keydown', event)
-    document.dispatchEvent(internalEvent)
+  if (platform.isKeyboardEvent && platform.isKeyboardEvent(event) && platform.dispatchEvent) {
+    const internalEvent = platform.createKeyboardEvent
+      ? platform.createKeyboardEvent('keydown', event)
+      : event
+    internalEvent[symbols.internalEvent] = true
+    platform.dispatchEvent(internalEvent)
   }
 }