@lightningjs/blits 2.6.0 → 2.7.0

package/CHANGELOG.md

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

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,
@@ -1070,13 +1092,9 @@ declare module '@lightningjs/blits' {
      */
     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.
+     * Platform-specific announcer driver used instead of the default Web Speech driver.
      */
-    speechSynthesis?: SpeechSynthesis | any,
+    announcer?: AnnouncerDriver,
     /**
      * Monotonic timestamp provider used for input throttling.
      */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lightningjs/blits",
-  "version": "2.6.0",
+  "version": "2.7.0",
   "description": "Blits: The Lightning 3 App Development Framework",
   "bin": "bin/index.js",
   "exports": {
@@ -32,6 +32,10 @@
       "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"

package/src/announcer/announcer.js

@@ -16,7 +16,6 @@
  */
 
 import { Log } from '../lib/log.js'
-import speechSynthesis from './speechSynthesis.js'
 import { platform } from '../platform.js'
 
 let active = false
@@ -31,6 +30,20 @@ let globalDefaultOptions = {
   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 = {
   then() {},
   done() {},
@@ -84,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')
     }
   }
 
@@ -133,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,
@@ -180,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

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

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/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/platform.js

@@ -15,6 +15,8 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+import speechSynthesis from './announcer/speechSynthesis.js'
+
 const globalScope = globalThis
 
 const createKeyboardEventFactory = (KeyboardEventConstructor) => {
@@ -73,10 +75,7 @@ const browserPlatform = () => {
         ? (event) => event instanceof KeyboardEventConstructor
         : undefined,
     createKeyboardEvent,
-    SpeechSynthesisUtterance:
-      globalScope.SpeechSynthesisUtterance || (windowRef && windowRef.SpeechSynthesisUtterance),
-    speechSynthesis:
-      (selfRef && selfRef.speechSynthesis) || (windowRef && windowRef.speechSynthesis),
+    announcer: speechSynthesis,
     now:
       globalScope.performance && globalScope.performance.now !== undefined
         ? globalScope.performance.now.bind(globalScope.performance)
@@ -108,9 +107,7 @@ export const configurePlatform = (customPlatform) => {
   platform.getCookie = platform.getCookie || basePlatform.getCookie
   platform.setCookie = platform.setCookie || basePlatform.setCookie
   platform.historyBack = platform.historyBack || basePlatform.historyBack
-  platform.SpeechSynthesisUtterance =
-    platform.SpeechSynthesisUtterance || basePlatform.SpeechSynthesisUtterance
-  platform.speechSynthesis = platform.speechSynthesis || basePlatform.speechSynthesis
+  platform.announcer = platform.announcer || basePlatform.announcer
   platform.now = platform.now || basePlatform.now
 
   return platform

package/src/platforms/webOS/announcer.d.ts

@@ -0,0 +1,39 @@
+import type { AnnouncerDriver } from '@lightningjs/blits'
+
+export interface WebOSRequestOptions {
+  method: 'speak'
+  parameters: {
+    text: string
+    clear: boolean
+  }
+  onFailure(error: any): void
+}
+
+export type WebOSRequest = (uri: string, options: WebOSRequestOptions) => any
+
+export interface WebOSAnnouncerOptions {
+  /**
+   * webOS service request function. Defaults to `webOS.service.request` when available.
+   */
+  request?: WebOSRequest
+  /**
+   * webOS TTS service URI.
+   *
+   * @default 'luna://com.webos.service.tts'
+   */
+  uri?: string
+  /**
+   * Whether the platform TTS queue should be cleared before speaking.
+   *
+   * @default true
+   */
+  clear?: boolean
+  /**
+   * Optional failure callback for the webOS TTS request.
+   */
+  onFailure?: (error: any) => void
+}
+
+declare function createAnnouncer(options?: WebOSAnnouncerOptions): AnnouncerDriver
+
+export default createAnnouncer

package/src/platforms/webOS/announcer.js

@@ -0,0 +1,77 @@
+/*
+ * Copyright 2026 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
+ */
+
+const globalScope = globalThis
+const defaultUri = 'luna://com.webos.service.tts'
+
+const getDefaultRequest = () => {
+  const windowRef = globalScope.window
+  const webOS = globalScope.webOS || (windowRef && windowRef.webOS)
+
+  if (webOS && webOS.service && typeof webOS.service.request === 'function') {
+    return webOS.service.request.bind(webOS.service)
+  }
+}
+
+const createAnnouncer = (options = {}) => {
+  const request = options.request || getDefaultRequest()
+  const uri = options.uri || defaultUri
+  const clear = options.clear !== false
+
+  let currentRequest
+
+  return {
+    speak(announcement) {
+      if (request === undefined) {
+        return Promise.reject({ error: 'unavailable' })
+      }
+
+      if (!announcement || announcement.message === undefined || announcement.message === null) {
+        return Promise.reject({ error: 'Missing message' })
+      }
+
+      try {
+        currentRequest = request(uri, {
+          method: 'speak',
+          parameters: {
+            text: String(announcement.message),
+            clear,
+          },
+          onFailure(error) {
+            currentRequest = undefined
+            if (options.onFailure) {
+              options.onFailure(error)
+            }
+          },
+        })
+      } catch (error) {
+        currentRequest = undefined
+        return Promise.reject(error)
+      }
+
+      return Promise.resolve()
+    },
+    cancel() {
+      if (currentRequest && typeof currentRequest.cancel === 'function') {
+        currentRequest.cancel()
+      }
+      currentRequest = undefined
+    },
+  }
+}
+
+export default createAnnouncer

package/src/testing/index.d.ts

@@ -43,6 +43,8 @@ export interface RenderComponentFixture {
   component: any
   root: any
   snapshot(): SnapshotNode | ComponentSnapshotNode
+  findByData(key: string, value: any): SnapshotNode | ComponentSnapshotNode | null
+  findAllByData(key: string, value: any): Array<SnapshotNode | ComponentSnapshotNode>
   setProps(props: Record<string, any>): void
   setState(state: Record<string, any>): void
   focus(event?: KeyboardEvent): Promise<any>

package/src/testing/nodePlatform.js

@@ -95,19 +95,11 @@ const nodePlatform = () => {
     KeyboardEvent: TestKeyboardEvent,
     isKeyboardEvent: (event) => event instanceof TestKeyboardEvent,
     createKeyboardEvent: (type, init = {}) => new TestKeyboardEvent(type, init),
-    SpeechSynthesisUtterance: class TestSpeechSynthesisUtterance {
-      constructor(text = '') {
-        this.text = text
-      }
-    },
-    speechSynthesis: {
-      cancel() {},
-      getVoices() {
-        return []
+    announcer: {
+      speak() {
+        return Promise.resolve()
       },
-      pause() {},
-      resume() {},
-      speak() {},
+      cancel() {},
     },
     now: Date.now,
   }

package/src/testing/renderComponent.js

@@ -17,12 +17,14 @@
 
 import Settings from '../settings.js'
 import { renderer, stage } from '../launch.js'
+import { setDevMode } from '../component.js'
 import symbols from '../lib/symbols.js'
 import { initLog } from '../lib/log.js'
 import { getRaw } from '../lib/reactivity/reactive.js'
 import Focus from '../focus/focus.js'
 import { initKeyMap, keyMap } from '../application.js'
 import { configurePlatform, platform } from '../platform.js'
+import { isObjectString, parseToObject } from '../lib/utils.js'
 import nodePlatform from './nodePlatform.js'
 
 let nodeId = 0
@@ -32,6 +34,7 @@ const renderComponent = (Component, options = {}) => {
   const originalPlatform = platform
 
   Settings.set(options.settings || {})
+  setDevMode(true)
   configurePlatform(() => nodePlatform())
   initLog()
   initKeyMap()
@@ -58,6 +61,27 @@ const renderComponent = (Component, options = {}) => {
     return componentSnapshot(component, holderMap)
   }
 
+  const findAllByData = (key, value) => {
+    const matches = []
+    visitSnapshot(snapshot(), (node) => {
+      if (node.attributes && node.attributes.data && node.attributes.data[key] === value) {
+        matches.push(node)
+      }
+    })
+    return matches
+  }
+
+  const findByData = (key, value) => {
+    let match = null
+    visitSnapshot(snapshot(), (node) => {
+      if (node.attributes && node.attributes.data && node.attributes.data[key] === value) {
+        match = node
+        return true
+      }
+    })
+    return match
+  }
+
   const setProps = (props = {}) => {
     const keys = Object.keys(props)
     for (let i = 0; i < keys.length; i++) {
@@ -107,6 +131,8 @@ const renderComponent = (Component, options = {}) => {
     component,
     root,
     snapshot,
+    findByData,
+    findAllByData,
     setProps,
     setState,
     focus,
@@ -289,10 +315,21 @@ const createElement = ({ parent } = {}) => {
       }
     },
     set(key, value) {
+      if (key === 'inspector-data') {
+        this.setInspectorMetadata(value)
+        return
+      }
       this.attributes[key] = value
       this.node[key] = value
     },
-    setInspectorMetadata() {},
+    setInspectorMetadata(data) {
+      if (isObjectString(data) === true) {
+        data = parseToObject(data)
+      }
+      if (data === null || typeof data !== 'object') return
+      this.attributes.data = { ...(this.attributes.data || {}), ...data }
+      this.node.data = { ...(this.node.data || {}), ...data }
+    },
     destroy() {
       this.eol = true
       this.children.length = 0
@@ -314,6 +351,19 @@ const appendToParent = (element, parent) => {
   }
 }
 
+const visitSnapshot = (node, visit) => {
+  if (node === undefined || node === null) return false
+  if (visit(node) === true) return true
+  if (node.type === 'Component') {
+    return visitSnapshot(node.tree, visit)
+  }
+  const children = node.children || []
+  for (let i = 0; i < children.length; i++) {
+    if (visitSnapshot(children[i], visit) === true) return true
+  }
+  return false
+}
+
 const createKeyboardEvent = (key, init = {}) => {
   const keyCode = init.keyCode || keyCodeFromKey(key)
   return platform.createKeyboardEvent('keydown', {