@lightningjs/blits 2.5.0 → 2.6.0

package/CHANGELOG.md

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

package/index.d.ts

@@ -1016,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
    *
@@ -1331,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.
+     *
+     * 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.6.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"
     },
+    "./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

@@ -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/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/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)
   }
 }

package/src/launch.js

@@ -19,6 +19,7 @@ import Settings from './settings.js'
 import { initLog, Log } from './lib/log.js'
 import engine from './engine.js'
 import blitsPackageInfo from '../package.json' with { type: 'json' }
+import { configurePlatform } from './platform.js'
 
 /**
  * @typedef {Object} Font
@@ -86,10 +87,12 @@ async function rendererVersion() {
  * @property {number} [holdTimeout] - Time after which a key press is considered a hold
  * @property {HTMLCanvasElement} [canvas] - Custom canvas object used to render the App
  * @property {number} [textureProcessingTimeLimit] - Max time renderer can process textures in a frame
+ * @property {import('@lightningjs/renderer').RendererMainSettings['platform']} [rendererPlatform] - Custom platform used by the renderer
  * @property {Partial<import('@lightningjs/renderer').RendererMainSettings>} [advanced] - Advanced renderer settings
  * @property {boolean} [announcer] - Whether or not the announcer should be activated on initialization
  * @property {boolean} [enableMouse] - Enable mouse support (hover and click-to-focus). Defaults to false.
  * @property {number} [maxFPS] - Maximum FPS
+ * @property {function} [platform] - Platform factory for non-browser environments
  */
 
 /**
@@ -109,10 +112,30 @@ async function rendererVersion() {
  * @returns {void}
  */
 export default (App, target, settings) => {
+  let warnLegacyRendererPlatform = false
+
+  if (settings !== undefined && 'platform' in settings) {
+    if (typeof settings.platform === 'function') {
+      settings.platform = configurePlatform(settings.platform)
+    } else {
+      if ('rendererPlatform' in settings === false) {
+        settings.rendererPlatform = settings.platform
+      }
+      delete settings.platform
+      warnLegacyRendererPlatform = true
+    }
+  }
+
   Settings.set(settings)
 
   initLog()
 
+  if (warnLegacyRendererPlatform === true) {
+    Log.warn(
+      'Passing a renderer platform via settings.platform is deprecated. Use settings.rendererPlatform instead.'
+    )
+  }
+
   rendererVersion().then((v) => {
     Log.info('Blits Version ', blitsPackageInfo.version)
     Log.info('Renderer Version ', v)

package/src/lib/reactivityguard/computedprops.js

@@ -200,8 +200,12 @@ const processComputedBlock = (configObject) => {
         currentPos = skipNonCode(computedObj, currentPos)
         if (currentPos >= computedObj.length - 1) break
 
-        // Find the next function name (computed properties are `name() { ... }`)
-        const functionNameMatch = /^(\w+)\s*\(\)\s*/.exec(computedObj.substring(currentPos))
+        // Find the next function name (computed properties are `name() { ... }`
+        // or long-form `name: function() { ... }`)
+        const functionNameMatch = /^(\w+)\s*(?:\(\)|:\s*function\s*\([^)]*\))\s*/.exec(
+          computedObj.substring(currentPos)
+        )
+
         if (!functionNameMatch) {
           const nextPos = skipComputedMember(computedObj, currentPos)
           if (nextPos === -1) break

package/src/platform.js

@@ -0,0 +1,117 @@
+/*
+ * 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 createKeyboardEventFactory = (KeyboardEventConstructor) => {
+  if (KeyboardEventConstructor === undefined) return undefined
+
+  return (type, init = {}) => {
+    const event = new KeyboardEventConstructor(type, init)
+    if ('keyCode' in init && event.keyCode !== init.keyCode) {
+      Object.defineProperty(event, 'keyCode', {
+        get: () => init.keyCode,
+      })
+    }
+    return event
+  }
+}
+
+const browserPlatform = () => {
+  const windowRef = globalScope.window
+  const documentRef = globalScope.document || (windowRef && windowRef.document)
+  const selfRef = globalScope.self || windowRef || globalScope
+  const navigatorRef =
+    globalScope.navigator || (windowRef && windowRef.navigator) || (selfRef && selfRef.navigator)
+  const KeyboardEventConstructor =
+    globalScope.KeyboardEvent || (windowRef && windowRef.KeyboardEvent)
+  let localStorage
+
+  try {
+    localStorage = (windowRef && windowRef.localStorage) || globalScope.localStorage
+  } catch {
+    localStorage = undefined
+  }
+
+  const createKeyboardEvent = createKeyboardEventFactory(KeyboardEventConstructor)
+
+  return {
+    input: documentRef,
+    viewport: windowRef,
+    dispatchEvent:
+      documentRef && documentRef.dispatchEvent
+        ? documentRef.dispatchEvent.bind(documentRef)
+        : undefined,
+    localStorage,
+    getCookie: () => (documentRef && documentRef.cookie) || '',
+    setCookie: (value) => {
+      if (documentRef !== undefined) documentRef.cookie = value
+    },
+    historyBack: () => {
+      if (windowRef && windowRef.history && windowRef.history.back) windowRef.history.back()
+    },
+    screenHeight: windowRef && windowRef.innerHeight,
+    hardwareConcurrency: navigatorRef && navigatorRef.hardwareConcurrency,
+    userAgent: navigatorRef && navigatorRef.userAgent,
+    KeyboardEvent: KeyboardEventConstructor,
+    isKeyboardEvent:
+      KeyboardEventConstructor !== undefined
+        ? (event) => event instanceof KeyboardEventConstructor
+        : undefined,
+    createKeyboardEvent,
+    SpeechSynthesisUtterance:
+      globalScope.SpeechSynthesisUtterance || (windowRef && windowRef.SpeechSynthesisUtterance),
+    speechSynthesis:
+      (selfRef && selfRef.speechSynthesis) || (windowRef && windowRef.speechSynthesis),
+    now:
+      globalScope.performance && globalScope.performance.now !== undefined
+        ? globalScope.performance.now.bind(globalScope.performance)
+        : Date.now,
+  }
+}
+
+export let platform = browserPlatform()
+
+export const configurePlatform = (customPlatform) => {
+  const basePlatform = browserPlatform()
+  const resolvedCustomPlatform = customPlatform(basePlatform) || {}
+
+  platform = {
+    ...basePlatform,
+    ...resolvedCustomPlatform,
+  }
+
+  platform.KeyboardEvent = platform.KeyboardEvent || basePlatform.KeyboardEvent
+  platform.isKeyboardEvent =
+    resolvedCustomPlatform.isKeyboardEvent ||
+    (platform.KeyboardEvent !== undefined
+      ? (event) => event instanceof platform.KeyboardEvent
+      : basePlatform.isKeyboardEvent)
+  platform.createKeyboardEvent =
+    resolvedCustomPlatform.createKeyboardEvent ||
+    createKeyboardEventFactory(platform.KeyboardEvent) ||
+    basePlatform.createKeyboardEvent
+  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.now = platform.now || basePlatform.now
+
+  return platform
+}

package/src/plugins/storage/localCookie.js

@@ -15,6 +15,8 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+import { platform } from '../../platform.js'
+
 // LocalStorage and Cookie storage library
 class localCookie {
   constructor(options) {
@@ -41,7 +43,8 @@ class localCookie {
 
   // Checks if local storage is available and works
   _checkIfLocalStorageWorks() {
-    if (typeof localStorage !== 'undefined') {
+    const localStorage = platform.localStorage
+    if (localStorage !== undefined) {
       try {
         localStorage.setItem('feature_test', 'yes')
         if (localStorage.getItem('feature_test') === 'yes') {
@@ -66,23 +69,23 @@ class localCookie {
    * Local Storage APIs
    */
   _getItemLocalStorage(key) {
-    return window.localStorage.getItem(key)
+    return platform.localStorage.getItem(key)
   }
 
   _setItemLocalStorage(key, value) {
-    return window.localStorage.setItem(key, value)
+    return platform.localStorage.setItem(key, value)
   }
 
   _removeItemLocalStorage(key) {
-    return window.localStorage.removeItem(key)
+    return platform.localStorage.removeItem(key)
   }
 
   _clearLocalStorage() {
-    return window.localStorage.clear()
+    return platform.localStorage.clear()
   }
 
   _getLocalStorageKeys() {
-    return Object.keys(window.localStorage)
+    return Object.keys(platform.localStorage)
   }
 
   /*
@@ -91,7 +94,7 @@ class localCookie {
   _getItemCookie(key) {
     /* eslint-disable */
 		function escape(s) { return s.replace(/([.*+?\^${}()|\[\]\/\\])/g, '\\$1'); };
-		var match = document.cookie.match(RegExp('(?:^|;\\s*)' + escape(key) + '=([^;]*)'));
+		var match = platform.getCookie().match(RegExp('(?:^|;\\s*)' + escape(key) + '=([^;]*)'));
 
 		//if value in key of the entire cookie is empty, its deleted
 		if (match && match[1] === '')
@@ -103,13 +106,13 @@ class localCookie {
 	_setItemCookie(key, value) {
 		var now = new Date()
 		var expires = new Date(now.getTime() +1000*60*60*24*365*5) // 5 years!
-		document.cookie = `${key}=${value}; expires=${expires.toUTCString()};`
+		platform.setCookie(`${key}=${value}; expires=${expires.toUTCString()};`)
 		return //return undefined just like localStorage
 	}
 
 	_removeItemCookie(key) {
 		// to delete an k/v set the key to empty
-		document.cookie = `${key}=;Max-Age=-99999999;`
+		platform.setCookie(`${key}=;Max-Age=-99999999;`)
 		return //return undefined just like localStorage
 	}
 
@@ -117,14 +120,14 @@ class localCookie {
 		// empty all key/values in cookies
 		// What about cookies we got from the server? ¯\_(ツ)_/¯
 		// They should have the HttpOnly flag, so we shouldn't be able to delete them
-		document.cookie.split(";").forEach( (c) => {
-			document.cookie = c.replace(/^ +/, "").replace(/=.*/, "=;expires=;Max-Age=-99999999");
+		platform.getCookie().split(";").forEach( (c) => {
+			platform.setCookie(c.replace(/^ +/, "").replace(/=.*/, "=;expires=;Max-Age=-99999999"));
 		});
 
 		return //return undefined
 	}
 	_getCookieKeys() {
-		return document.cookie.split(";").map((item)=>item.trim().split("=")[0])
+		return platform.getCookie().split(";").map((item)=>item.trim().split("=")[0])
 	}
 }
 

package/src/router/router.js

@@ -24,6 +24,7 @@ import { stage } from '../launch.js'
 import Focus from '../focus/focus.js'
 import Announcer from '../announcer/announcer.js'
 import Settings from '../settings.js'
+import { platform } from '../platform.js'
 
 /**
  * @typedef {import('../component.js').BlitsComponentFactory} BlitsComponentFactory - The component of the route
@@ -417,7 +418,8 @@ const executeBeforeHook = async function (
       this.currentRoute = previousRoute
       if (this.history.length > 0) {
         preventHashChangeNavigation = true
-        window.history.back()
+        platform.historyBack()
+
         navigatingBack = false
         state.navigating = false
       }
@@ -434,7 +436,7 @@ const executeBeforeHook = async function (
       this.currentRoute = previousRoute
       if (this.history.length > 0) {
         preventHashChangeNavigation = true
-        window.history.back()
+        platform.historyBack()
         navigatingBack = false
         state.navigating = false
       }

package/src/testing/index.d.ts

@@ -0,0 +1,58 @@
+/*
+ * 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
+ */
+
+import type { ComponentFactory, Settings } from '@lightningjs/blits'
+
+export interface SnapshotNode {
+  type: string
+  attributes: Record<string, any>
+  children: Array<SnapshotNode | ComponentSnapshotNode>
+}
+
+export interface ComponentSnapshotNode {
+  type: 'Component'
+  name: string
+  hasFocus: boolean
+  isHovered: boolean
+  attributes: Record<string, any>
+  props: Record<string, any>
+  state: Record<string, any>
+  tree: SnapshotNode | null
+}
+
+export interface RenderComponentOptions {
+  props?: Record<string, any>
+  settings?: Settings
+}
+
+export interface RenderComponentFixture {
+  component: any
+  root: any
+  snapshot(): SnapshotNode | ComponentSnapshotNode
+  setProps(props: Record<string, any>): void
+  setState(state: Record<string, any>): void
+  focus(event?: KeyboardEvent): Promise<any>
+  unfocus(): any
+  createKeyboardEvent(key: string, init?: KeyboardEventInit): KeyboardEvent
+  input(key: string, event?: KeyboardEvent): boolean
+  destroy(): void
+}
+
+export function renderComponent(
+  Component: ComponentFactory,
+  options?: RenderComponentOptions
+): RenderComponentFixture

package/src/testing/index.js

@@ -0,0 +1,20 @@
+/*
+ * 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
+ */
+
+import renderComponent from './renderComponent.js'
+
+export { renderComponent }

package/src/testing/nodePlatform.js

@@ -0,0 +1,116 @@
+/*
+ * 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
+ */
+
+class TestKeyboardEvent {
+  constructor(type, init = {}) {
+    this.type = type
+    this.key = init.key
+    this.code = init.code
+    this.keyCode = init.keyCode || 0
+    this.bubbles = init.bubbles === true
+    this.cancelable = init.cancelable === true
+    this.composed = init.composed === true
+    this.timeStamp = init.timeStamp || Date.now()
+  }
+}
+
+const createEventTarget = () => {
+  const listeners = {}
+
+  return {
+    addEventListener(type, handler) {
+      listeners[type] = listeners[type] || []
+      listeners[type].push(handler)
+    },
+    removeEventListener(type, handler) {
+      const handlers = listeners[type]
+      if (handlers === undefined) return
+      const index = handlers.indexOf(handler)
+      if (index > -1) handlers.splice(index, 1)
+    },
+    dispatchEvent(event) {
+      const handlers = listeners[event.type] || []
+      for (let i = 0; i < handlers.length; i++) {
+        handlers[i](event)
+      }
+      return true
+    },
+  }
+}
+
+const createStorage = () => {
+  const store = {}
+
+  return {
+    getItem(key) {
+      return store[key] !== undefined ? store[key] : null
+    },
+    setItem(key, value) {
+      store[key] = String(value)
+    },
+    removeItem(key) {
+      delete store[key]
+    },
+    clear() {
+      const keys = Object.keys(store)
+      for (let i = 0; i < keys.length; i++) {
+        delete store[keys[i]]
+      }
+    },
+  }
+}
+
+const nodePlatform = () => {
+  const input = createEventTarget()
+  const viewport = createEventTarget()
+  let cookie = ''
+
+  return {
+    input,
+    viewport,
+    dispatchEvent: input.dispatchEvent.bind(input),
+    localStorage: createStorage(),
+    getCookie: () => cookie,
+    setCookie: (value) => {
+      cookie = value
+    },
+    historyBack() {},
+    screenHeight: 1080,
+    hardwareConcurrency: 1,
+    userAgent: 'node',
+    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 []
+      },
+      pause() {},
+      resume() {},
+      speak() {},
+    },
+    now: Date.now,
+  }
+}
+
+export default nodePlatform

package/src/testing/renderComponent.js

@@ -0,0 +1,346 @@
+/*
+ * 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
+ */
+
+import Settings from '../settings.js'
+import { renderer, stage } from '../launch.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 nodePlatform from './nodePlatform.js'
+
+let nodeId = 0
+
+const renderComponent = (Component, options = {}) => {
+  const originalElement = stage.element
+  const originalPlatform = platform
+
+  Settings.set(options.settings || {})
+  configurePlatform(() => nodePlatform())
+  initLog()
+  initKeyMap()
+  mockRenderer()
+  // Generated template code calls stage.element through `this.element`
+  stage.element = createElement
+
+  const root = createElement()
+  const parent = {
+    $componentId: 'BlitsTestComponent::Root',
+    [symbols.lifecycle]: {
+      set state(v) {},
+    },
+    $focus() {},
+    $input() {
+      return false
+    },
+  }
+  const component = Component({ props: options.props || {} }, root, parent)
+
+  const snapshot = () => {
+    const holderMap = new WeakMap()
+    collectComponents(component, holderMap)
+    return componentSnapshot(component, holderMap)
+  }
+
+  const setProps = (props = {}) => {
+    const keys = Object.keys(props)
+    for (let i = 0; i < keys.length; i++) {
+      component[symbols.props][keys[i]] = props[keys[i]]
+    }
+  }
+
+  const setState = (state = {}) => {
+    const keys = Object.keys(state)
+    for (let i = 0; i < keys.length; i++) {
+      component[symbols.state][keys[i]] = state[keys[i]]
+    }
+  }
+
+  const focus = (event) => {
+    Focus.hold = false
+    component.$focus(event)
+    return new Promise((resolve) => {
+      setTimeout(() => {
+        setTimeout(() => resolve(component))
+      })
+    })
+  }
+
+  const unfocus = () => {
+    component.unfocus()
+    return component
+  }
+
+  const input = (key, event = createKeyboardEvent(key)) => {
+    const focused = Focus.get()
+    if (focused === null || focused.eol === true || isInComponentTree(focused, component) === false)
+      return false
+    Focus.input(key, event)
+    return true
+  }
+
+  const destroy = () => {
+    if (component.eol !== true) {
+      component.destroy()
+    }
+    stage.element = originalElement
+    configurePlatform(() => originalPlatform)
+  }
+
+  return {
+    component,
+    root,
+    snapshot,
+    setProps,
+    setState,
+    focus,
+    unfocus,
+    createKeyboardEvent,
+    input,
+    destroy,
+  }
+}
+
+const mockRenderer = () => {
+  // Lifecycle hooks register renderer events even in headless tests
+  if (renderer.on === undefined) renderer.on = () => {}
+  if (renderer.off === undefined) renderer.off = () => {}
+}
+
+const collectComponents = (component, holderMap) => {
+  if (component === undefined || component === null) return
+  // Component tags render as holder elements; keep the link for snapshots
+  if (component[symbols.holder] !== undefined) {
+    holderMap.set(component[symbols.holder], component)
+  }
+  const children = component[symbols.children] || []
+  for (let i = 0; i < children.length; i++) {
+    const child = children[i]
+    if (child && child.$componentId !== undefined) {
+      collectComponents(child, holderMap)
+    }
+  }
+}
+
+const elementSnapshot = (element, holderMap) => {
+  const component = holderMap.get(element)
+  if (component !== undefined) {
+    return componentSnapshot(component, holderMap)
+  }
+
+  const children = []
+  for (let i = 0; i < element.children.length; i++) {
+    children.push(elementSnapshot(element.children[i], holderMap))
+  }
+
+  return {
+    type: elementType(element.attributes),
+    attributes: attributesSnapshot(element.attributes),
+    children,
+  }
+}
+
+const componentSnapshot = (component, holderMap) => {
+  const holder = component[symbols.holder]
+  const wrapper = component[symbols.wrapper]
+
+  return {
+    type: 'Component',
+    name: componentName(component),
+    hasFocus: component.$hasFocus === true,
+    isHovered: component.$isHovered === true,
+    attributes: holder ? attributesSnapshot(holder.attributes) : {},
+    props: propsSnapshot(component),
+    state: stateSnapshot(component),
+    tree: wrapper ? elementSnapshot(wrapper, holderMap) : null,
+  }
+}
+
+const attributesSnapshot = (attributes) => {
+  const out = {}
+  const keys = Object.keys(attributes)
+  for (let i = 0; i < keys.length; i++) {
+    const key = keys[i]
+    if (
+      key === '___wrapper' ||
+      key === '__textnode' ||
+      key === '__layout' ||
+      key === 'holder' ||
+      key === 'parent'
+    ) {
+      continue
+    }
+    if (attributes[key] !== undefined) {
+      out[key] = clone(attributes[key])
+    }
+  }
+  return out
+}
+
+const propsSnapshot = (component) => {
+  const props = component[symbols.props] || {}
+  const propKeys = component[symbols.propKeys] || Object.keys(props)
+  const out = {}
+  for (let i = 0; i < propKeys.length; i++) {
+    const key = propKeys[i]
+    if (props[key] !== undefined) {
+      out[key] = clone(props[key])
+    }
+  }
+  return out
+}
+
+const stateSnapshot = (component) => {
+  const state = component[symbols.state] || {}
+  const originalState = component[symbols.originalState] || {}
+  const stateKeys = Object.keys(originalState)
+  const out = {}
+  for (let i = 0; i < stateKeys.length; i++) {
+    const key = stateKeys[i]
+    if (key === '$hasFocus' || key === '$isHovered') continue
+    if (state[key] !== undefined) {
+      out[key] = clone(state[key])
+    }
+  }
+  return out
+}
+
+const componentName = (component) => {
+  const match = component.$componentId && component.$componentId.match(/^BlitsComponent::(.+)_\d+$/)
+  return match ? match[1] : 'Component'
+}
+
+const elementType = (attributes) => {
+  if (attributes.__textnode === true) return 'Text'
+  if (attributes.__layout === true) return 'Layout'
+  if (attributes[symbols.isSlot] === true) return 'Slot'
+  if (attributes[symbols.isSprite] === true) return 'Sprite'
+  return 'Element'
+}
+
+const clone = (value) => {
+  value = getRaw(value)
+
+  if (Array.isArray(value) === true) {
+    return value.map((v) => clone(v))
+  }
+
+  if (
+    value !== null &&
+    typeof value === 'object' &&
+    Object.getPrototypeOf(value) === Object.prototype
+  ) {
+    return cleanObject(value)
+  }
+
+  return value
+}
+
+const cleanObject = (value) => {
+  const out = {}
+  const keys = Object.keys(value)
+  for (let i = 0; i < keys.length; i++) {
+    const key = keys[i]
+    if (value[key] !== undefined) {
+      out[key] = clone(value[key])
+    }
+  }
+  return out
+}
+
+const createElement = ({ parent } = {}) => {
+  // Minimal BlitsElement mock used by generated render/effect code
+  const element = {
+    attributes: {},
+    children: [],
+    node: {
+      children: [],
+      on() {},
+      off() {},
+    },
+    parent,
+    populate(attributes = {}) {
+      this.nodeId = ++nodeId
+      const keys = Object.keys(attributes)
+      for (let i = 0; i < keys.length; i++) {
+        this.set(keys[i], attributes[keys[i]])
+      }
+      if (attributes[symbols.isSlot] !== undefined) {
+        this.attributes[symbols.isSlot] = attributes[symbols.isSlot]
+      }
+      if (attributes[symbols.isSprite] !== undefined) {
+        this.attributes[symbols.isSprite] = attributes[symbols.isSprite]
+      }
+    },
+    set(key, value) {
+      this.attributes[key] = value
+      this.node[key] = value
+    },
+    setInspectorMetadata() {},
+    destroy() {
+      this.eol = true
+      this.children.length = 0
+      this.node.children.length = 0
+    },
+  }
+
+  appendToParent(element, parent)
+
+  return element
+}
+
+const appendToParent = (element, parent) => {
+  if (parent === undefined || parent === null || parent === 'root') return
+  if (parent.children === undefined) return
+  parent.children.push(element)
+  if (parent.node && parent.node.children) {
+    parent.node.children.push(element.node)
+  }
+}
+
+const createKeyboardEvent = (key, init = {}) => {
+  const keyCode = init.keyCode || keyCodeFromKey(key)
+  return platform.createKeyboardEvent('keydown', {
+    key,
+    ...init,
+    keyCode,
+    bubbles: true,
+    cancelable: true,
+    composed: true,
+  })
+}
+
+const keyCodeFromKey = (key) => {
+  const keys = Object.keys(keyMap)
+  for (let i = 0; i < keys.length; i++) {
+    if (keyMap[keys[i]] === key) return Number(keys[i])
+  }
+  return 0
+}
+
+const isInComponentTree = (child, parent) => {
+  let current = child
+  while (current !== undefined && current !== null) {
+    if (current === parent) return true
+    current = current[symbols.parent]
+  }
+  return false
+}
+
+export default renderComponent