@lightningjs/blits 2.14.0 → 2.16.0

package/src/engines/L3/launch.js

@@ -20,7 +20,6 @@ import { WebGlCoreRenderer, SdfTextRenderer } from '@lightningjs/renderer/webgl'
 import { CanvasCoreRenderer, CanvasTextRenderer } from '@lightningjs/renderer/canvas'
 import { Inspector } from '@lightningjs/renderer/inspector'
 
-import { Log } from '../../lib/log.js'
 import { SCREEN_RESOLUTIONS, RENDER_QUALITIES } from '../../constants.js'
 import colors from '../../lib/colors/colors.js'
 import fontLoader from './fontLoader.js'
@@ -85,7 +84,7 @@ const textureMemorySettings = (settings) => {
  * @param {Partial<import('../../launch.js').BlitsSettings>} [settings] - The settings for the renderer
  *
  */
-export default (App, target, settings = {}) => {
+export default (target, settings = {}) => {
   const screenHeight = settings.platform ? settings.platform.screenHeight : platform.screenHeight
   const hardwareConcurrency = settings.platform
     ? settings.platform.hardwareConcurrency
@@ -125,21 +124,8 @@ export default (App, target, settings = {}) => {
     target
   )
 
-  const initApp = () => {
-    let app = App()
-    app.quit = () => {
-      Log.info('Closing App')
-      app.destroy()
-      app = null
-      renderer = null
-    }
-  }
-
   shaderLoader()
   fontLoader()
-  // Defer app initialization until after the current call stack is cleared,
-  // allowing the renderer to finish setting up before the app starts creating components
-  Promise.resolve().then(initApp)
 
   return renderer
 }

package/src/focus/focus.js

@@ -68,6 +68,10 @@ export default {
         while (i--) {
           // don't unfocus when part of the new focus chain
           if (newFocusChain.indexOf(focusChain[i]) > -1) break
+          // only unfocus components that actually have focus
+          // ($hasFocus, not the lifecycle state which is shared with hover/enter/exit)
+          const componentState = focusChain[i][symbols.state]
+          if (componentState !== undefined && componentState.$hasFocus === false) continue
           focusChain[i][symbols.lifecycle].state = 'unfocus'
         }
         focusChain = newFocusChain

package/src/keymap.js

@@ -0,0 +1,27 @@
+/*
+ * Copyright 2023 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
+ */
+
+/**
+ * Merged keyMap (default + custom settings).
+ * Updated during application initialization and runtime settings changes.
+ * @type {Object<string, string>}
+ */
+export let keyMap = {}
+
+export const setKeyMap = (value) => {
+  keyMap = value
+}

package/src/launch.js

@@ -18,7 +18,6 @@
 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'
 import profiler from './lib/profiler.js'
 
@@ -52,20 +51,6 @@ const isDev = typeof __DEV__ !== 'undefined' && __DEV__
 export let renderer = {}
 export const stage = {}
 
-async function rendererVersion() {
-  let rendererPackageInfo
-  try {
-    // Dynamically import the renderer package.json
-    rendererPackageInfo = await import('../../renderer/package.json')
-    if (rendererPackageInfo !== undefined) {
-      return rendererPackageInfo.version
-    }
-  } catch (e) {
-    // Fallback to renderer version in dependencies
-    return blitsPackageInfo.dependencies['@lightningjs/renderer']
-  }
-}
-
 /**
  * @typedef {Object} BlitsSettings
  * @property {number} [w] - Width of the Application
@@ -148,15 +133,28 @@ export default (App, target, settings) => {
     )
   }
 
-  rendererVersion().then((v) => {
-    Log.info('Blits Version ', blitsPackageInfo.version)
-    Log.info('Renderer Version ', v)
-  })
+  Log.info(
+    'Blits version:',
+    typeof __BLITS_VERSION__ === 'undefined' ? 'unknown' : __BLITS_VERSION__
+  )
+  Log.info(
+    'Renderer version:',
+    typeof __RENDERER_VERSION__ === 'undefined' ? 'unknown' : __RENDERER_VERSION__
+  )
 
   stage.element = engine.Element
 
-  renderer = engine.Launch(App, target, settings)
+  renderer = engine.Launch(target, settings)
   if (isDev === true) {
     profiler.setRenderer(renderer)
   }
+
+  // Instantiate the app and wire up the quit function
+  let app = App()
+  app.quit = () => {
+    Log.info('Closing App')
+    app.destroy()
+    app = null
+    renderer = null
+  }
 }

package/src/lib/codegenerator/generator.js

@@ -87,6 +87,8 @@ export default function (templateObject = { children: [] }, devMode = false) {
     }, skips}
   `)
 
+  const renderCodeString = ctx.renderCode.join('\n')
+
   return {
     render: new Function(
       'parent',
@@ -96,7 +98,7 @@ export default function (templateObject = { children: [] }, devMode = false) {
       'effect',
       'getRaw',
       'Log',
-      ctx.renderCode.join('\n')
+      renderCodeString
     ),
     effects: ctx.effectsCode.map(
       (code) =>
@@ -112,6 +114,7 @@ export default function (templateObject = { children: [] }, devMode = false) {
         )
     ),
     context: ctx.context,
+    usesHoverState: renderCodeString.includes('.$isHovered'),
   }
 }
 
@@ -212,6 +215,7 @@ const generateElementCode = function (
 
   if (options.holder) {
     renderCode.push(`elementConfigs[${counter}]['holder'] = true`)
+    renderCode.push(`elementConfigs[${counter}]['interactive'] = cmps[${counter}].needsInteractive`)
   }
 
   Object.keys(templateObject).forEach((key) => {
@@ -342,12 +346,31 @@ const generateComponentCode = function (
 ) {
   const renderCode = options.forceEffect ? this.effectsCode : this.renderCode
 
-  renderCode.push(`
+  if ('is' in templateObject || ':is' in templateObject) {
+    const selectedComponent =
+      ':is' in templateObject
+        ? interpolate(templateObject[':is'], options.component)
+        : cast(templateObject.is, 'is', options.component)
+    // Resolve the selected factory before populating its holder and filtering props.
+    renderCode.push(`
+      componentType = ${selectedComponent} || '${templateObject[Symbol.for('componentType')]}'
+      cmps[${counter}] = typeof componentType === 'function'
+        ? componentType
+        : (context.components && context.components[componentType]) || components[componentType]
+      if (!cmps[${counter}]) {
+        throw new Error('Component "${templateObject[Symbol.for('componentType')]}" not found')
+      }
+    `)
+  } else {
+    renderCode.push(`
     cmps[${counter}] =
       (context.components && context.components['${
         templateObject[Symbol.for('componentType')]
       }']) || components['${templateObject[Symbol.for('componentType')]}']
   `)
+  }
+
+  renderCode.push(`if (cmps[${counter}].prepare !== undefined) cmps[${counter}].prepare()`)
 
   this.cleanupCode.push(`
     cmps[${counter}] = null

package/src/lib/hooks.js

@@ -57,3 +57,7 @@ export const registerHooks = (hooks = {}, identifier) => {
     if (typeof hooks[hook] === 'function') cbs[identifier][hook] = hooks[hook]
   })
 }
+
+export const hasHook = (hook, identifier) => {
+  return cbs[identifier] !== undefined && hook in cbs[identifier]
+}

package/src/lib/precompiler/precompiler.js

@@ -31,6 +31,11 @@ export default (source, filePath, mode) => {
     // Use MagicString to track changes
     const s = new MagicString(source)
 
+    // Find component definition start positions for scoping JS-layer checks
+    const componentStarts = [...source.matchAll(/Blits\.(Component|Application)\s*\(/g)]
+      .map((m) => m.index)
+      .sort((a, b) => a - b)
+
     for (const template of templates) {
       if (template[2]) {
         const templateContent = template[2]
@@ -52,10 +57,30 @@ export default (source, filePath, mode) => {
           // Generate the code
           const code = generator.call({ components: {} }, parsed, mode === 'development')
 
+          // Determine the component scope containing this template
+          let scopeStart = 0
+          let scopeEnd = source.length
+          for (let i = 0; i < componentStarts.length; i++) {
+            if (componentStarts[i] <= templateStartIndex) {
+              scopeStart = componentStarts[i]
+              scopeEnd = i + 1 < componentStarts.length ? componentStarts[i + 1] : source.length
+            }
+          }
+          const componentScope = source.slice(scopeStart, scopeEnd)
+
+          // Derive usesHoverState from both template ($$isHovered) and JS layer (this.$isHovered)
+          // Match strings first so URL/comment delimiters inside literals stay intact.
+          // Keep template literals too: their interpolations may read hover state.
+          const strippedScope = componentScope.replace(
+            /("(?:\\[\s\S]|[^"\\])*"|'(?:\\[\s\S]|[^'\\])*'|`(?:\\[\s\S]|[^`\\])*`)|\/\/[^\r\n]*|\/\*[\s\S]*?\*\//g,
+            (match, literal) => literal || ' '
+          )
+          const usesHoverState = code.usesHoverState || strippedScope.includes('this.$isHovered')
+
           // Insert the code in the component using the 'code' key, replacing the template key
           const replacement = `/* eslint-disable no-unused-vars */ \ncode: { render: ${code.render.toString()}, effects: [${code.effects.map(
             (fn) => fn.toString()
-          )}], context: {}}`
+          )}], context: {}, usesHoverState: ${usesHoverState}}`
 
           // MagicString tracks all changes automatically, no offset needed
           s.overwrite(templateStartIndex, templateEndIndex, replacement)

package/src/lib/reactivity/effect.js

@@ -15,8 +15,12 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+import symbols from '../symbols.js'
+
 let currentEffect = null
 let currentKey = null
+// Write position for dependency-array reuse, restored after nested computed getters.
+let computedDependencyIndex = 0
 
 // counter that tracks all pauseTracking invocations
 // to ensure nested array operations don't prematurely
@@ -33,20 +37,98 @@ export const resumeTracking = () => {
 
 const objectMap = new WeakMap()
 const effectDependenciesMap = new WeakMap()
+const computedEffects = new WeakMap()
+const effectQueue = new Set()
+let pendingEffects = null
+
+const computedRunner = (effectFn, key) => {
+  if (effectFn.computed === true) return effectFn
+  let runner = computedEffects.get(effectFn)
+  if (runner === undefined) {
+    runner = (force) => effect(effectFn, key, force)
+    computedEffects.set(effectFn, runner)
+  }
+  return runner
+}
+
+export const createComputed = (getter, component, key) => {
+  let value
+  let status = 'dirty'
+
+  const invalidate = (force) => {
+    if (status === 'dirty' || status === 'disposed') return
+    status = 'dirty'
+    trigger(component, key, force)
+  }
+  invalidate.computed = true
+  invalidate.dispose = () => {
+    value = undefined
+    status = 'disposed'
+  }
+  if (component[symbols.effects] !== undefined) component[symbols.effects].push(invalidate)
+
+  return () => {
+    if (status === 'disposed') return undefined
+
+    if (currentEffect !== null) track(component, key, true)
+    if (status === 'clean') return value
+
+    const previousEffect = currentEffect
+    const previousKey = currentKey
+    const previousPauseCounter = pauseCounter
+    const previousDependencyIndex = computedDependencyIndex
+    computedDependencyIndex = 0
+    try {
+      // Refresh dependencies in isolation, including reads made outside effects.
+      clearDependencies(invalidate)
+      currentEffect = invalidate
+      currentKey = null
+      pauseCounter = 0
+      value = getter.call(component)
+      status = 'clean'
+      return value
+    } catch (error) {
+      status = 'failed'
+      throw error
+    } finally {
+      const dependencies = effectDependenciesMap.get(invalidate)
+      if (dependencies !== undefined) dependencies.length = computedDependencyIndex
+      computedDependencyIndex = previousDependencyIndex
+      currentEffect = previousEffect
+      currentKey = previousKey
+      pauseCounter = previousPauseCounter
+    }
+  }
+}
+
+const clearDependencies = (effect, releaseStorage) => {
+  const dependencies = effectDependenciesMap.get(effect)
+  if (dependencies === undefined) return
+  for (let i = 0; i < dependencies.length; i++) {
+    const effects = dependencies[i]
+    effects.delete(effect)
+    if (effect.computed === true) effects.computedCount--
+  }
+  if (releaseStorage === true) dependencies.length = 0
+}
 
 export const removeEffects = (effectsToRemove) => {
   for (let i = 0; i < effectsToRemove.length; i++) {
     const effect = effectsToRemove[i]
-    const dependencies = effectDependenciesMap.get(effect)
-    if (dependencies === undefined) continue
-    for (let j = 0; j < dependencies.length; j++) {
-      dependencies[j].delete(effect)
+    const computedEffect = computedEffects.get(effect)
+    if (computedEffect !== undefined) {
+      // Computed dependencies subscribe the runner itself, so unsubscribe it separately.
+      clearDependencies(computedEffect, true)
+      effectDependenciesMap.delete(computedEffect)
+      computedEffects.delete(effect)
     }
+    clearDependencies(effect, true)
     effectDependenciesMap.delete(effect)
+    if (effect.computed === true) effect.dispose()
   }
 }
 
-export const track = (target, key) => {
+export const track = (target, key, computed) => {
   if (currentEffect !== null) {
     if (pauseCounter > 0) {
       return
@@ -56,6 +138,7 @@ export const track = (target, key) => {
       if (currentKey.includes(key) === false) return
     } else if (currentKey !== null && key !== currentKey) return
 
+    const subscriber = computed === true ? computedRunner(currentEffect, currentKey) : currentEffect
     let effectsMap = objectMap.get(target)
     if (effectsMap === undefined) {
       effectsMap = new Map()
@@ -66,14 +149,19 @@ export const track = (target, key) => {
       effects = new Set()
       effectsMap.set(key, effects)
     }
-    if (effects.has(currentEffect) === false) {
-      let dependencies = effectDependenciesMap.get(currentEffect)
+    if (effects.has(subscriber) === false) {
+      let dependencies = effectDependenciesMap.get(subscriber)
       if (dependencies === undefined) {
         dependencies = []
-        effectDependenciesMap.set(currentEffect, dependencies)
+        effectDependenciesMap.set(subscriber, dependencies)
+      }
+      effects.add(subscriber)
+      if (subscriber.computed === true) {
+        dependencies[computedDependencyIndex++] = effects
+        effects.computedCount = effects.computedCount === undefined ? 1 : effects.computedCount + 1
+      } else {
+        dependencies.push(effects)
       }
-      dependencies.push(effects)
-      effects.add(currentEffect)
     }
   }
 }
@@ -85,14 +173,52 @@ export const trigger = (target, key, force = false) => {
     return
   }
   const effects = effectsMap.get(key)
+  // Ordinary state updates keep their direct path.
+  if (
+    effects !== undefined &&
+    pendingEffects === null &&
+    (effects.computedCount === undefined || effects.computedCount === 0)
+  ) {
+    for (const effect of effects) {
+      if (effect.computed !== true) effect(force)
+    }
+    return
+  }
   if (effects !== undefined) {
-    for (let effect of effects) {
-      effect(force)
+    const parentQueue = pendingEffects
+    // Reuse the root queue; only nested updates with pending consumers need another set.
+    let queue = parentQueue
+    if (queue === null) {
+      queue = effectQueue.size === 0 ? effectQueue : new Set()
+      // All consumers share the source mutation's force flag.
+      queue.force = force
+    }
+    pendingEffects = queue
+    try {
+      for (const effect of effects) {
+        if (effect.computed === true) {
+          effect(force)
+        } else {
+          const runner = computedEffects.get(effect)
+          queue.add(runner === undefined ? effect : runner)
+        }
+      }
+      // Invalidate the whole computed chain before any consumer can read its cache.
+      if (parentQueue === null) {
+        pendingEffects = null
+        for (const effect of queue) {
+          queue.delete(effect)
+          if (effectDependenciesMap.has(effect) === true) effect(queue.force)
+        }
+      }
+    } finally {
+      pendingEffects = parentQueue
+      if (parentQueue === null) queue.clear()
     }
   }
 }
 
-export const effect = (effectFn, key = null) => {
+export const effect = (effectFn, key = null, force) => {
   const previousEffect = currentEffect
   const previousKey = currentKey
 
@@ -100,7 +226,7 @@ export const effect = (effectFn, key = null) => {
   currentKey = key
 
   try {
-    effectFn()
+    effectFn(force)
   } finally {
     currentEffect = previousEffect
     currentKey = previousKey

package/src/lib/reactivity/reactive.js

@@ -100,9 +100,7 @@ const reactiveProxy = (original, _parent = null, _key) => {
 
       // handling objects (but not null values, which have object type in JS)
       if (typeof target[key] === 'object' && target[key] !== null) {
-        if (Array.isArray(target[key]) === true) {
-          track(target, key)
-        }
+        track(target, key)
         // create a new reactive proxy
         return reactiveProxy(getRaw(target[key]), target, key)
       }
@@ -140,6 +138,8 @@ const reactiveProxy = (original, _parent = null, _key) => {
             Object.getPrototypeOf(value) === Object.prototype
           ) {
             value = Object.assign(receiver[key], value)
+            // The object keeps its identity; its nested setters already notified consumers.
+            isEqual = true
           }
         }
         result = Reflect.set(target, key, value, receiver)
@@ -167,7 +167,7 @@ const reactiveDefineProperty = (target) => {
 
     if (target[key] !== null && typeof target[key] === 'object') {
       if (Object.getPrototypeOf(target[key]) === Object.prototype) {
-        return reactiveDefineProperty(target[key])
+        reactiveDefineProperty(target[key])
       } else if (Array.isArray(target[key]) === true) {
         for (let i = 0; i < arrayPatchMethods.length; i++) {
           target[key][arrayPatchMethods[i]] = function (v) {
@@ -189,6 +189,13 @@ const reactiveDefineProperty = (target) => {
         // todo: support assigning array (as we do with proxies)
         let oldValue = internalValue
         if (oldValue !== newValue) {
+          if (
+            newValue !== null &&
+            typeof newValue === 'object' &&
+            Object.getPrototypeOf(newValue) === Object.prototype
+          ) {
+            reactiveDefineProperty(newValue)
+          }
           internalValue = newValue
           trigger(target, key)
         }

package/src/router/router.js

@@ -44,7 +44,7 @@ import { platform } from '../platform.js'
  * @property {Object} hooks - The hooks of the route
  * @property {Object} transition - The transition of the route
  * @property {Object} announce - The announce of the route
- * @property {(options: Object, parentEl: BlitsElement, parentComponent: BlitsComponent, rootComponent?: BlitsComponent) => BlitsComponent} component - The component factory of the route
+ * @property {BlitsComponentFactory} component - The component factory of the route (or a lazy import function)
  *
  * @typedef {Object} Hash
  * @property {string} path - The path of the hash
@@ -288,9 +288,13 @@ const performNavigation = async function (viewState) {
 
   // routing to a new page (instead of routing back to a keepAlive page)
   if (view === undefined) {
+    // Prepare eager runtime factories before creating their holder. Lazy loaders
+    // retain the conservative interactive fallback until their factory is known.
+    if (route.component.prepare !== undefined) route.component.prepare()
+    const needsInteractive = route.component.needsInteractive ?? true
     // create a holder element for the new view
     holder = stage.element({ parent: this[symbols.children][0] })
-    holder.populate({})
+    holder.populate({ holder: true, interactive: needsInteractive })
     holder.set('w', '100%')
     holder.set('h', '100%')
 
@@ -590,9 +594,22 @@ export const getSingleRegisteredRouterView = () => {
   return singleRouterView
 }
 
-export const back = function () {
+export const back = function (steps = 1) {
   if (this.history === undefined) return
+  if (steps < 1) steps = 1
+  if (steps > this.history.length) steps = this.history.length
   const viewState = getViewState(this.name)
+
+  // discard the intermediate history entries when navigating back more than 1 step
+  for (let i = 1; i < steps; i++) {
+    const poppedRoute = this.history.pop()
+    // if skipped history item is configured as keepAlive true then invoke destroy on view
+    if (poppedRoute.view !== undefined && poppedRoute.view !== null) {
+      poppedRoute.view.destroy()
+      poppedRoute.focus = null
+    }
+  }
+
   const route = this.history.pop()
   if (route && this.currentRoute !== route) {
     // set indicator that we are navigating back (to prevent adding page to history stack)

package/src/settings.js

@@ -19,6 +19,8 @@ import symbols from './lib/symbols.js'
 
 const settings = {
   [symbols.settings]: {},
+  // Reacts to Blits-only settings changed at runtime via `this.$settings.set()`.
+  onRuntimeSettingChange: null,
   get(key, defaultValue = null) {
     if (key in this[symbols.settings]) {
       return this[symbols.settings][key]
@@ -33,6 +35,9 @@ const settings = {
       })
     } else {
       this[symbols.settings][key] = value
+      if (typeof this.onRuntimeSettingChange === 'function') {
+        this.onRuntimeSettingChange(key, value)
+      }
     }
   },
 }

package/vite/index.js

@@ -20,15 +20,18 @@ import msdfGenerator from './msdfGenerator.js'
 import blitsFileConverter from './blitsFileConverter.js'
 import reactivityGuard from './reactivityGuard.js'
 import injectDevConfig from './inject-dev-config.js'
+import injectVersions from './injectVersions.js'
 
 export { default as preCompiler } from './preCompiler.js'
 export { default as msdfGenerator } from './msdfGenerator.js'
 export { default as blitsFileConverter } from './blitsFileConverter.js'
 export { default as reactivityGuard } from './reactivityGuard.js'
 export { default as injectDevConfig } from './inject-dev-config.js'
+export { default as injectVersions } from './injectVersions.js'
 
 export default [
   injectDevConfig(),
+  injectVersions(),
   blitsFileConverter(),
   reactivityGuard(),
   preCompiler(),

package/vite/injectVersions.js

@@ -0,0 +1,58 @@
+/*
+ * Copyright 2025 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 { readFileSync, existsSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { dirname, join } from 'node:path'
+
+const require = createRequire(import.meta.url)
+
+function getVersions() {
+  const blits = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'))
+  // Resolve the public entry: the renderer does not export its package.json.
+  // Walk upwards to support hoisted, nested, and symlinked installations.
+  let directory = dirname(require.resolve('@lightningjs/renderer'))
+  while (true) {
+    const filename = join(directory, 'package.json')
+    if (existsSync(filename)) {
+      const pkg = JSON.parse(readFileSync(filename, 'utf8'))
+      if (pkg.name === '@lightningjs/renderer') {
+        return { blits: blits.version, renderer: pkg.version }
+      }
+    }
+    const parent = dirname(directory)
+    if (parent === directory) throw new Error('Unable to locate @lightningjs/renderer/package.json')
+    directory = parent
+  }
+}
+
+export default function injectVersions() {
+  return {
+    name: 'inject-versions',
+    config(config) {
+      const versions = getVersions()
+      return {
+        define: {
+          __BLITS_VERSION__: JSON.stringify(versions.blits || 'unknown'),
+          __RENDERER_VERSION__: JSON.stringify(versions.renderer || 'unknown'),
+          // merge any existing define block
+          ...config.define,
+        },
+      }
+    },
+  }
+}