@lightningjs/blits 2.0.0-beta.1 → 2.0.0-beta.11

package/src/engines/L3/index.js

@@ -1,3 +1,20 @@
+/*
+ * 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
+ */
+
 import Element from './element.js'
 import Launch from './launch.js'
 

package/src/engines/L3/launch.js

@@ -100,6 +100,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,
       },
       ...(settings.advanced || {}),
     },
@@ -118,7 +119,9 @@ export default (App, target, settings = {}) => {
 
   shaderLoader()
   fontLoader()
-  initApp()
+  // 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/engines/L3/shaderLoader.js

@@ -1,3 +1,20 @@
+/*
+ * Copyright 2024 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 } from './launch.js'
 import * as webglShaders from '@lightningjs/renderer/webgl/shaders'

package/src/engines/index.js

@@ -1 +1,18 @@
+/*
+ * 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
+ */
+
 export { default as L3 } from './L3/index.js'

package/src/{focus.js → focus/focus.js}

@@ -15,11 +15,12 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import symbols from './lib/symbols.js'
-import { state } from './router/router.js'
-import Settings from './settings.js'
-import { DEFAULT_HOLD_TIMEOUT_MS } from './constants.js'
-import { Log } from './lib/log.js'
+import symbols from '../lib/symbols.js'
+import { state } from '../router/router.js'
+import Settings from '../settings.js'
+import { DEFAULT_HOLD_TIMEOUT_MS } from '../constants.js'
+import { Log } from '../lib/log.js'
+import { getAncestors } from './helpers.js'
 
 let focusedComponent = null
 let focusChain = []
@@ -99,19 +100,6 @@ export default {
   },
 }
 
-/**
- * Recursive function that retrieves the ancestors of a component
- * @param {Array} components
- * @returns array components
- */
-const getAncestors = (components) => {
-  if (components[0][symbols.parent] !== undefined) {
-    components.unshift(components[0][symbols.parent])
-    return getAncestors(components)
-  }
-  return components
-}
-
 /**
  * Get the component in the ancestors chain that has a handler for a certain key code
  * @param {Object} component

package/src/focus/helpers.js

@@ -0,0 +1,31 @@
+/*
+ * 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 symbols from '../lib/symbols.js'
+
+/**
+ * Recursive function that retrieves the ancestors of a component
+ * @param {Array} components
+ * @returns array components
+ */
+export const getAncestors = (components) => {
+  if (components[0][symbols.parent] !== undefined) {
+    components.unshift(components[0][symbols.parent])
+    return getAncestors(components)
+  }
+  return components
+}

package/src/focus/hover.js

@@ -0,0 +1,94 @@
+/*
+ * 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 { Log } from '../lib/log.js'
+import { getAncestors } from './helpers.js'
+import symbols from '../lib/symbols.js'
+
+let hoveredComponent = null
+let hoverChain = []
+
+export default {
+  get() {
+    return hoveredComponent
+  },
+  set(component) {
+    if (component === undefined || component.eol === true) return
+
+    // early return if already hovered
+    if (component === hoveredComponent) return
+
+    if (hoveredComponent === null) {
+      hoverChain = getAncestors([component])
+    }
+
+    // unhover currently hovered components
+    if (hoveredComponent !== null) {
+      if (hoverChain[hoverChain.length - 1] === component.$parent) {
+        hoverChain.push(component)
+      } else {
+        const newhoverChain = getAncestors([component])
+        let i = hoverChain.length
+        while (i--) {
+          // don't unhover when part of the new hover chain
+          if (newhoverChain.indexOf(hoverChain[i]) > -1) break
+          // skip if component is destroyed
+          if (hoverChain[i].eol !== true) {
+            hoverChain[i][symbols.lifecycle].state = 'unhover'
+          }
+        }
+        hoverChain = newhoverChain
+      }
+    }
+
+    // ensure that all components in the hover path have hover state
+    let i = 0
+    while (i < hoverChain.length - 1) {
+      // skip if component is destroyed
+      if (hoverChain[i].eol !== true) {
+        hoverChain[i][symbols.lifecycle].state = 'hover'
+      }
+      i++
+    }
+
+    setHover(component)
+  },
+  clear() {
+    if (hoveredComponent === null) return
+    for (let i = 0; i < hoverChain.length; i++) {
+      if (hoverChain[i].eol !== true) {
+        hoverChain[i][symbols.lifecycle].state = 'unhover'
+      }
+    }
+    hoveredComponent = null
+    hoverChain = []
+  },
+}
+
+/**
+ * Set the hover to the Component
+ * @param {Object} component  - The component to hover
+ */
+const setHover = (component) => {
+  Log.info(
+    '\nHover chain:\n',
+    hoverChain.map((c, index) => '\t'.repeat(index) + '↳ ' + c.$componentId).join('\n')
+  )
+
+  hoveredComponent = component
+  component[symbols.lifecycle].state = 'hover'
+}

package/src/helpers/fetchJson.js

@@ -1,10 +1,6 @@
 /*
- * If not stated otherwise in this file or this component's LICENSE file the
- * following copyright and licenses apply:
- *
- * Copyright 2020 Metrological
- *
- * Licensed under the Apache License, Version 2.0 (the License);
+ * Copyright 2024 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
  *
@@ -15,6 +11,8 @@
  * 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
  */
 
 export default (file) => {

package/src/launch.js

@@ -88,6 +88,7 @@ async function rendererVersion() {
  * @property {number} [textureProcessingTimeLimit] - Max time renderer can process textures in a frame
  * @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
  */
 

package/src/lib/codegenerator/generator.js

@@ -163,6 +163,10 @@ const generateElementCode = function (
 
   renderCode.push(`elementConfigs[${counter}] = {}`)
 
+  if (counter === 0) {
+    renderCode.push(`elementConfigs[${counter}]['___wrapper'] = true `)
+  }
+
   if (options.forloop) {
     renderCode.push(`if(${elm} === undefined) {`)
   }
@@ -182,6 +186,10 @@ const generateElementCode = function (
     renderCode.push(`elementConfigs[${counter}][Symbol.for('isSlot')] = true`)
   }
 
+  if (options.holder) {
+    renderCode.push(`elementConfigs[${counter}]['holder'] = true`)
+  }
+
   Object.keys(templateObject).forEach((key) => {
     if (key === 'slot') {
       renderCode.push(`
@@ -325,9 +333,11 @@ const generateComponentCode = function (
 
   const children = templateObject.children
   delete templateObject.children
+  // Capture holder counter before generating element code (which may process children and increment counter)
+  const holderCounter = counter
   generateElementCode.call(this, templateObject, parent, { ...options, ...{ holder: true } })
 
-  parent = options.key ? `elms[${counter}][${options.key}]` : `elms[${counter}]`
+  parent = options.key ? `elms[${holderCounter}][${options.key}]` : `elms[${holderCounter}]`
 
   counter++
 
@@ -396,6 +406,21 @@ const generateComponentCode = function (
     }
   `)
 
+  if (isDev === true) {
+    const templateTagName = templateObject[Symbol.for('componentType')]
+    const holderElm = options.key
+      ? `elms[${holderCounter}][${options.key}]`
+      : `elms[${holderCounter}]`
+    const componentDisplayName = `typeof componentType === 'string'
+      ? componentType
+      : (componentType?.[Symbol.for('componentType')] || '${templateTagName}')`
+    renderCode.push(`
+      if (${holderElm} !== undefined && typeof ${holderElm}.setInspectorMetadata === 'function') {
+        ${holderElm}.setInspectorMetadata({ 'blits-componentType': ${componentDisplayName} })
+      }
+    `)
+  }
+
   this.cleanupCode.push(`components[${counter}] = null`)
 
   if (options.forloop) {
@@ -451,7 +476,7 @@ const generateForLoopCode = function (templateObject, parent) {
     .replace(')', '')
     .split(/\s*,\s*/)
 
-  const scopeRegex = new RegExp(`(scope\\.(?!${item}\\.|${index}|key)(\\$?\\w+))`, 'gi')
+  const scopeRegex = new RegExp(`(scope\\.(?!${item}\\.|${index}|key)([\\w$]+))`, 'gi')
 
   // local context
   const ctx = {
@@ -524,10 +549,16 @@ const generateForLoopCode = function (templateObject, parent) {
 
       component !== null && component[Symbol.for('removeGlobalEffects')](effects[${forStartCounter}])
 
-      for(let i = 0; i < effects[${forStartCounter}].length; i++) {
-        const value = effects[${forStartCounter}][i]
-        const index = component[Symbol.for('effects')].indexOf(value)
-        if (index > -1) component[Symbol.for('effects')].splice(index, 1)
+     const effectsToRemove = new Set(effects[${forStartCounter}].slice(0))
+      if (effectsToRemove.size > 0) {
+        const componentEffects = component?.[Symbol.for('effects')] || []
+        let writeIndex = 0
+        for (let readIndex = 0; readIndex < componentEffects.length; readIndex++) {
+          if (!effectsToRemove.has(componentEffects[readIndex])) {
+            componentEffects[writeIndex++] = componentEffects[readIndex]
+          }
+        }
+        componentEffects.length = writeIndex
       }
 
       effects[${forStartCounter}].length = 0
@@ -633,11 +664,21 @@ const generateForLoopCode = function (templateObject, parent) {
   const forEndCounter = counter
 
   for (let i = forStartCounter; i <= forEndCounter; i++) {
-    destroyCode.push(`
+    if (i == forStartCounter) {
+      destroyCode.push(`
         elms[${i}][key] && elms[${i}][key].destroy()
         elms[${i}][key] = null
         delete elms[${i}][key]
     `)
+    } else {
+      destroyCode.push(`
+        if (elms[${i}][key] && elms[${i}][key].$componentId !== undefined) {
+          elms[${i}][key] && elms[${i}][key].destroy()
+        }
+        elms[${i}][key] = null
+        delete elms[${i}][key]
+      `)
+    }
   }
   destroyCode.push(`
       }
@@ -825,8 +866,13 @@ const cast = (val = '', key = false, component = 'component.') => {
   }
   // @-listener
   else if (key.startsWith('@') && val) {
-    const c = component.slice(0, -1)
-    castedValue = `${c}['${val.replace('$', '')}'] && ${c}['${val.replace('$', '')}'].bind(${c})`
+    const trimmed = val.trim()
+    if (/^\$?\w+$/.test(trimmed)) {
+      const c = component.slice(0, -1)
+      castedValue = `${c}['${trimmed.replace('$', '')}'] && ${c}['${trimmed.replace('$', '')}'].bind(${c})`
+    } else {
+      castedValue = interpolate(trimmed, component)
+    }
   }
   // dynamic value
   else if (val.startsWith('$')) {

package/src/lib/lifecycle.js

@@ -18,6 +18,9 @@
 import { Log } from './log.js'
 import { emit, privateEmit } from './hooks.js'
 import symbols from './symbols.js'
+import Settings from '../settings.js'
+
+let inspectorEnabled = null
 
 /**
  * List of valid lifecycle states for a component.
@@ -28,6 +31,8 @@ const states = [
   'ready', // fired when component instantiated, reactivity setup done and template spawned
   'focus', // fired when receiving focus (can occur multiple times)
   'unfocus', // fired when losing focus (can occur multiple times)
+  'hover', // fired when pointer enters the component (mouse support only; can occur multiple times)
+  'unhover', // fired when pointer leaves the component (mouse support only; can occur multiple times)
   'destroy', // fired when component is destroyed and removed
   'attach', // fired when entering the viewport margin and attached to the render tree
   'detach', // fired when leaving the viewport margin and detached from the render tree
@@ -81,9 +86,35 @@ export default {
       privateEmit(v, this.component[symbols.identifier], this.component)
       // emit 'public' hook
       emit(v, this.component[symbols.identifier], this.component)
-      // update the built-in hasFocus state variable
-      if (v === 'focus') this.component[symbols.state].$hasFocus = true
-      if (v === 'unfocus') this.component[symbols.state].$hasFocus = false
+      // update the built-in $hasFocus state variable
+      if (v === 'focus' || v === 'unfocus') {
+        if (inspectorEnabled === null) {
+          inspectorEnabled = Settings.get('inspector', false)
+        }
+      }
+      // update the built-in isHovered state variable
+      if (v === 'hover') this.component[symbols.state].$isHovered = true
+      if (v === 'unhover') this.component[symbols.state].$isHovered = false
+      if (v === 'focus') {
+        this.component[symbols.state].$hasFocus = true
+        if (
+          inspectorEnabled === true &&
+          this.component[symbols.holder] &&
+          typeof this.component[symbols.holder].setInspectorMetadata === 'function'
+        ) {
+          this.component[symbols.holder].setInspectorMetadata({ 'blits-hasFocus': true })
+        }
+      }
+      if (v === 'unfocus') {
+        this.component[symbols.state].$hasFocus = false
+        if (
+          inspectorEnabled === true &&
+          this.component[symbols.holder] &&
+          typeof this.component[symbols.holder].setInspectorMetadata === 'function'
+        ) {
+          this.component[symbols.holder].setInspectorMetadata({ 'blits-hasFocus': false })
+        }
+      }
     }
   },
 }

package/src/lib/log.js

@@ -46,7 +46,7 @@ const logger = (context) => {
       return (
         ((level >= 1 || (Array.isArray(level) && level.indexOf('info') > -1)) &&
           console.info.bind(
-            window.console,
+            console,
             `%c ⚡️ ${context} %c ${time()}`,
             'background-color: #0284c7; color: white; padding: 3px 6px 3px 1px; border-radius: 3px',
             'color: ##94a3b8;'
@@ -61,7 +61,7 @@ const logger = (context) => {
       return (
         ((level >= 1 || (Array.isArray(level) && level.indexOf('warn') > -1)) &&
           console.warn.bind(
-            window.console,
+            console,
             `%c ⚡️ ${context} %c ${time()}`,
             'background-color: #fbbf24; color: white; padding: 3px 6px 3px 1px; border-radius: 3px',
             'color: ##94a3b8;'
@@ -76,7 +76,7 @@ const logger = (context) => {
       return (
         ((level >= 1 || (Array.isArray(level) && level.indexOf('error') > -1)) &&
           console.error.bind(
-            window.console,
+            console,
             `%c ⚡️ ${context} %c ${time()}`,
             'background-color: #dc2626; color: white; padding: 3px 6px 3px 1px; border-radius: 3px',
             'color: ##94a3b8;'
@@ -91,7 +91,7 @@ const logger = (context) => {
       return (
         ((level >= 2 || (Array.isArray(level) && level.indexOf('debug') > -1)) &&
           console.debug.bind(
-            window.console,
+            console,
             `%c ⚡️ ${context} %c (${new Date().toLocaleTimeString([], {
               hour: '2-digit',
               minute: '2-digit',

package/src/lib/precompiler/precompiler.js

@@ -17,6 +17,7 @@
 
 import parser from '../templateparser/parser.js'
 import generator from '../codegenerator/generator.js'
+import MagicString from 'magic-string'
 
 export default (source, filePath, mode) => {
   if (
@@ -26,12 +27,9 @@ export default (source, filePath, mode) => {
     /\{.*?template\s*:\s*(['"`])((?:\\?.)*?)\1.*?\}/s.test(source) // object with template key
   ) {
     const templates = source.matchAll(/(?<!\/\/\s*)template\s*:\s*(['"`])((?:\\?.)*?)\1/gs)
-    let newSource = source
-    /*
-      if there are multiple templates in the file, we need to keep
-      track of the offset caused by the previous replacements
-    */
-    let offset = 0
+
+    // Use MagicString to track changes
+    const s = new MagicString(source)
 
     for (const template of templates) {
       if (template[2]) {
@@ -39,7 +37,8 @@ export default (source, filePath, mode) => {
 
         // Only process if it looks like a Blits template
         if (templateContent.match(/^\s*(<!--[\s\S]*?-->|<[A-Za-z][^>]*>)/s)) {
-          const templateStartIndex = template.index + offset
+          // Use original indices - MagicString handles position tracking automatically
+          const templateStartIndex = template.index
           const templateEndIndex = templateStartIndex + template[0].length
 
           // Parse the template
@@ -58,16 +57,26 @@ export default (source, filePath, mode) => {
             (fn) => fn.toString()
           )}], context: {}}`
 
-          offset += replacement.length - template[0].length
-
-          newSource =
-            newSource.substring(0, templateStartIndex) +
-            replacement +
-            newSource.substring(templateEndIndex)
+          // MagicString tracks all changes automatically, no offset needed
+          s.overwrite(templateStartIndex, templateEndIndex, replacement)
         }
       }
     }
-    return newSource
+
+    const newSource = s.toString()
+
+    if (newSource !== source) {
+      const fileName = filePath.split(/[\\/]/).pop()
+      return {
+        code: newSource,
+        map: s.generateMap({
+          hires: true,
+          source: fileName,
+          includeContent: true,
+          file: fileName,
+        }),
+      }
+    }
   }
   return source
 }

package/src/lib/reactivity/effect.js

@@ -32,9 +32,10 @@ const objectMap = new WeakMap()
 const globalEffectsMap = new Map()
 
 export const removeGlobalEffects = (effectsToRemove) => {
-  if (globalEffectsMap.size === 0) return
+  if (globalEffectsMap.size === 0 || effectsToRemove.length === 0) return
+  const effectsToRemoveSet = new Set(effectsToRemove)
   for (const [effect, target] of globalEffectsMap) {
-    if (effectsToRemove.indexOf(effect) === -1) continue
+    if (!effectsToRemoveSet.has(effect)) continue
     const effectsSet = objectMap.get(target)
     if (effectsSet === undefined) continue
     for (const set of effectsSet.values()) {