@lightningjs/blits 2.14.0 → 2.15.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lightningjs/blits",
-  "version": "2.14.0",
+  "version": "2.15.0",
   "description": "Blits: The Lightning 3 App Development Framework",
   "bin": "bin/index.js",
   "exports": {
@@ -70,7 +70,7 @@
     "bench:compare": "npm --prefix benchmarks run bench:compare --",
     "bench:profile": "npm --prefix benchmarks run bench:profile --",
     "bench:serve": "npm --prefix benchmarks run serve",
-    "release": "npm publish --access public"
+    "release": "node scripts/release.js"
   },
   "types": "./index.d.ts",
   "lint-staged": {
@@ -95,7 +95,7 @@
     "globals": "^17.12.0",
     "husky": "^9.1.7",
     "jsdom": "^30.1.0",
-    "lint-staged": "^15.5.2",
+    "lint-staged": "^17.6.0",
     "prettier": "^3.6.2",
     "sinon": "^22.1.0",
     "tap-diff": "^0.1.1",

package/src/application.js

@@ -25,6 +25,55 @@ import { DEFAULT_HOLD_TIMEOUT_MS, DEFAULT_KEYMAP } from './constants.js'
 import { renderer } from './launch.js'
 import { platform } from './platform.js'
 
+// Reacts to Blits-only settings changed at runtime via `this.$settings.set()`.
+Settings.onRuntimeSettingChange = (key, value) => {
+  if (key === 'keymap') {
+    initKeyMap()
+    return
+  }
+
+  if (key === 'inputThrottle') {
+    inputThrottleMs = value
+    return
+  }
+
+  if (key === 'mouseMoveThrottle') {
+    mouseMoveThrottleMs = value
+    return
+  }
+
+  if (
+    key === 'announcerOptions' &&
+    liveAppInstance &&
+    liveAppInstance.$announcer &&
+    value &&
+    typeof value === 'object'
+  ) {
+    liveAppInstance.$announcer.configure(value)
+    return
+  }
+
+  if (key === 'enableMouse') {
+    enableMouseFlag = value
+    if (liveInput !== null && liveViewport !== null) {
+      if (value === true && mouseListenersAttached === false) {
+        liveInput.addEventListener('mousemove', mouseMoveHandlerRef)
+        liveInput.addEventListener('click', mouseClickHandlerRef)
+        liveViewport.addEventListener('resize', updateCanvasRectRef)
+        liveViewport.addEventListener('scroll', updateCanvasRectRef)
+        mouseListenersAttached = true
+      } else if (value === false && mouseListenersAttached === true) {
+        liveInput.removeEventListener('mousemove', mouseMoveHandlerRef)
+        liveInput.removeEventListener('click', mouseClickHandlerRef)
+        liveViewport.removeEventListener('resize', updateCanvasRectRef)
+        liveViewport.removeEventListener('scroll', updateCanvasRectRef)
+        mouseListenersAttached = false
+        Hover.clear()
+      }
+    }
+  }
+}
+
 /**
  * Merged keyMap (default + custom settings).
  * Initialized once during application init.
@@ -32,6 +81,24 @@ import { platform } from './platform.js'
  */
 export let keyMap = {}
 
+/** @type {any} Active App component instance, set during App init */
+let liveAppInstance = null
+/** @type {any} Platform input target, set during App init */
+let liveInput = null
+/** @type {any} Platform viewport target, set during App init */
+let liveViewport = null
+let mouseListenersAttached = false
+/** @type {((e: any) => void)|null} */
+let mouseMoveHandlerRef = null
+/** @type {(() => void)|null} */
+let mouseClickHandlerRef = null
+/** @type {(() => void)|null} */
+let updateCanvasRectRef = null
+
+let inputThrottleMs = 0
+let mouseMoveThrottleMs = 100
+let enableMouseFlag = false
+
 export const initKeyMap = () => {
   keyMap = { ...DEFAULT_KEYMAP, ...Settings.get('keymap', {}) }
 }
@@ -66,6 +133,7 @@ const Application = (config) => {
   }
 
   config.hooks[symbols.init] = function () {
+    liveAppInstance = this
     // set the initial activation state of the announcer based on launch setting
     this.$announcer.toggle(Settings.get('announcer', false))
     // configure global default utterance options if provided in settings
@@ -75,15 +143,15 @@ const Application = (config) => {
     }
     // Initialize merged keyMap once during application init
     initKeyMap()
-
-    /** @type {number} Input throttle time in milliseconds (0 = disabled) */
-    const throttleMs = Settings.get('inputThrottle', 0)
-
-    const mouseEnabled = Settings.get('enableMouse', false)
-    const mouseMoveThrottle = Settings.get('mouseMoveThrottle', 100)
+    // Initialize fast-path cached settings once during application init
+    inputThrottleMs = Settings.get('inputThrottle', 0)
+    mouseMoveThrottleMs = Settings.get('mouseMoveThrottle', 100)
+    enableMouseFlag = Settings.get('enableMouse', false)
     const { createKeyboardEvent, input, isKeyboardEvent, now = Date.now, viewport } = platform
+    liveInput = input
+    liveViewport = viewport
 
-    keyDownHandler = async (e) => {
+    keyDownHandler = async (/** @type {any} */ e) => {
       const currentTime = now()
 
       const key = keyMap[e.keyCode] || e.keyCode
@@ -91,11 +159,11 @@ const Application = (config) => {
       lastInputKey = key
       // execute immediately when no throttle is specified or event is internal (bubbled up by focus manager)
       // or key is different from the last used key
-      if (throttleMs === 0 || e[symbols.internalEvent] === true || sameKey === false) {
+      if (inputThrottleMs === 0 || e[symbols.internalEvent] === true || sameKey === false) {
         return await processInput.call(this, e, key)
       }
 
-      if (currentTime - lastInputTime < throttleMs) {
+      if (currentTime - lastInputTime < inputThrottleMs) {
         return
       }
 
@@ -115,7 +183,7 @@ const Application = (config) => {
       }
 
       Focus.input(key, e)
-      if (mouseEnabled === true) {
+      if (enableMouseFlag === true) {
         Hover.clear()
         // forget the node under the pointer too, so moving on it hovers it again
         currentNode = undefined
@@ -130,6 +198,9 @@ const Application = (config) => {
     }
 
     keyUpHandler = (e) => {
+      clearTimeout(holdTimeout)
+      Focus.hold = false
+
       const entry = keyUpCallbacks.get(e.keyCode)
       if (entry !== undefined) {
         keyUpCallbacks.delete(e.keyCode)
@@ -137,8 +208,6 @@ const Application = (config) => {
           entry.callback()
         }
       }
-      clearTimeout(holdTimeout)
-      Focus.hold = false
     }
 
     let lastMoved = 0
@@ -154,7 +223,7 @@ const Application = (config) => {
 
     // limit the amount of move events per time frame
     mouseMoveHandler = (e) => {
-      if (e.timeStamp - lastMoved < mouseMoveThrottle) return
+      if (e.timeStamp - lastMoved < mouseMoveThrottleMs) return
       lastMoved = e.timeStamp
 
       this.$emit('mouse::move', e)
@@ -166,7 +235,7 @@ const Application = (config) => {
         return
       }
 
-      const stage = renderer.stage
+      const stage = /** @type {any} */ (renderer).stage
       if (stage == null) {
         return
       }
@@ -215,16 +284,21 @@ const Application = (config) => {
       input.addEventListener('keydown', keyDownHandler)
       input.addEventListener('keyup', keyUpHandler)
       inputCleanup = () => {
-        input.removeEventListener('keydown', keyDownHandler)
-        input.removeEventListener('keyup', keyUpHandler)
+        input.removeEventListener('keydown', /** @type {any} */ (keyDownHandler))
+        input.removeEventListener('keyup', /** @type {any} */ (keyUpHandler))
       }
     }
-    if (mouseEnabled === true && input !== undefined && viewport !== undefined) {
+    mouseMoveHandlerRef = mouseMoveHandler
+    mouseClickHandlerRef = mouseClickHandler
+    updateCanvasRectRef = updateCanvasRect
+
+    if (enableMouseFlag === true && input !== undefined && viewport !== undefined) {
       updateCanvasRect()
       input.addEventListener('mousemove', mouseMoveHandler)
       input.addEventListener('click', mouseClickHandler)
       viewport.addEventListener('resize', updateCanvasRect)
       viewport.addEventListener('scroll', updateCanvasRect)
+      mouseListenersAttached = true
       mouseCleanup = () => {
         input.removeEventListener('mousemove', mouseMoveHandler)
         input.removeEventListener('click', mouseClickHandler)
@@ -233,8 +307,9 @@ const Application = (config) => {
       }
     }
 
-    // next tick
-    setTimeout(() => Focus.set(this))
+    // focus once the component tree is built (microtask: runs right after the
+    // current instantiation finishes, without yielding to render-loop frames)
+    Promise.resolve().then(() => Focus.set(this))
   }
 
   return Component('App', config)

package/src/component/base/index.js

@@ -21,6 +21,7 @@ import events from './events.js'
 import router from './router.js'
 import announcer from './announcer.js'
 import utils from './utils.js'
+import settings from './settings.js'
 import symbols from '../../lib/symbols.js'
 import { reactive } from '../../lib/reactivity/reactive.js'
 import Settings from '../../settings.js'
@@ -29,6 +30,7 @@ export const shared = {
   ...events,
   ...router,
   ...announcer,
+  ...settings,
   $reactive: {
     value: function (target) {
       return reactive(target, Settings.get('reactivityMode'), true)

package/src/component/base/router.js

@@ -149,9 +149,9 @@ const createRouter = (component, routerViewName) => {
       toRouterView(routerView, path, data, options)
       return true
     },
-    back() {
+    back(steps = 1) {
       const routerView = resolveRouterView(component, routerViewName)
-      return routerView === null ? false : back.call(routerView)
+      return routerView === null ? false : back.call(routerView, steps)
     },
     get(name) {
       return getRouterFromCache(component, name)
@@ -172,6 +172,10 @@ const createRouter = (component, routerViewName) => {
     get navigating() {
       return state.navigating
     },
+    get history() {
+      const routerView = resolveRouterView(component, routerViewName)
+      return routerView === null ? [] : routerView.history.slice()
+    },
     state,
   }
 }

package/src/component/base/settings.js

@@ -0,0 +1,68 @@
+/*
+ * 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 Settings from '../../settings.js'
+import engine from '../../engine.js'
+import { Log } from '../../lib/log.js'
+
+// Settings that can be changed at runtime via `this.$settings.set()`.
+const blitsKeys = [
+  'keymap',
+  'debugLevel',
+  'inputThrottle',
+  'announcerOptions',
+  'enableMouse',
+  'mouseMoveThrottle',
+]
+
+const rendererKeys = [
+  'w',
+  'h',
+  'screenResolution',
+  'renderQuality',
+  'pixelRatio',
+  'canvasColor',
+  'viewportMargin',
+  'maxFPS',
+  'fpsInterval',
+]
+
+const changeableKeys = [...blitsKeys, ...rendererKeys]
+
+export default {
+  $settings: {
+    value: {
+      get(key, defaultValue) {
+        return Settings.get(key, defaultValue)
+      },
+      set(key, value) {
+        if (changeableKeys.indexOf(key) === -1) {
+          Log.warn(`Setting "${key}" can not be changed at runtime`)
+          return
+        }
+        Settings.set(key, value)
+
+        if (rendererKeys.indexOf(key) !== -1) {
+          engine.updateSetting(key, value)
+        }
+      },
+    },
+    writable: false,
+    enumerable: true,
+    configurable: false,
+  },
+}

package/src/component.js

@@ -426,8 +426,9 @@ const Component = (name = required('name'), config = required('config')) => {
       }
     }
 
-    // finaly set the lifecycle state to ready (in the next tick)
-    setTimeout(() => (this[symbols.lifecycle].state = 'ready'))
+    // finally set the lifecycle state to ready (synchronously: instantiation,
+    // reactivity setup and template spawn are all complete at this point)
+    this[symbols.lifecycle].state = 'ready'
 
     // and return this
     return this

package/src/components/FPScounter.js

@@ -16,11 +16,15 @@
  */
 
 import Blits from '../../index.js'
-import { renderer } from '../launch.js'
 import fps_sprite from '../../public/assets/fps_sprite.base64.js'
 
 // exporting as named export to allow selective importing
 export const FPScounter = Blits.Component('FPScounter', {
+  props: {
+    active: true,
+    show: true,
+    alpha: 1,
+  },
   /* eslint-disable no-unused-vars */
   code: {
     render: function anonymous(parent, component, context, components, effect, getRaw, Log) {
@@ -662,28 +666,34 @@ export const FPScounter = Blits.Component('FPScounter', {
       avgFps: '---',
       minFps: '---',
       maxFps: '---',
+
+      data: {
+        minFps: 10000,
+        maxFps: 0,
+        totalFps: 0,
+        fpsUpdateCounter: 0,
+        avgFps: 0,
+      },
     }
   },
   hooks: {
-    ready() {
-      let minFps = 10000
-      let maxFps = 0
-      let avgFps = 0
-      let totalFps = 0
-      let fpsUpdateCounter = 0
-
-      renderer.on('fpsUpdate', (rM, { fps }) => {
-        minFps = Math.min(fps, minFps)
-        maxFps = Math.max(fps, maxFps)
-        totalFps += fps
-        fpsUpdateCounter++
-        avgFps = Math.round(totalFps / fpsUpdateCounter)
-
-        this.fps = fps.toString().padStart(3, '0')
-        this.avgFps = avgFps.toString().padStart(3, '0')
-        this.minFps = minFps.toString().padStart(3, '0')
-        this.maxFps = maxFps.toString().padStart(3, '0')
-      })
+    /**
+     * @param {number} fps
+     */
+    fpsUpdate(fps) {
+      // early return when not active or hidden
+      if (!this.active || !this.show || this.alpha === 0) return
+
+      this.data.minFps = Math.min(fps, this.data.minFps)
+      this.data.maxFps = Math.max(fps, this.data.maxFps)
+      this.data.totalFps += fps
+      this.data.fpsUpdateCounter++
+      this.data.avgFps = Math.round(this.data.totalFps / this.data.fpsUpdateCounter)
+
+      this.fps = fps.toString().padStart(3, '0')
+      this.avgFps = this.data.avgFps.toString().padStart(3, '0')
+      this.minFps = this.data.minFps.toString().padStart(3, '0')
+      this.maxFps = this.data.maxFps.toString().padStart(3, '0')
     },
   },
 })

package/src/engines/L3/index.js

@@ -16,9 +16,47 @@
  */
 
 import Element from './element.js'
-import Launch from './launch.js'
+import Launch, { renderer } from './launch.js'
+import colors from '../../lib/colors/colors.js'
+import { SCREEN_RESOLUTIONS, RENDER_QUALITIES } from '../../constants.js'
+
+/**
+ * Maps Blits setting keys to renderer runtime options
+ *
+ * @type {Record<string, (value: any) => Partial<import('@lightningjs/renderer').RendererRuntimeSettings>>}
+ */
+const rendererOptions = {
+  // defaults to transparent (same as on launch) for empty or invalid colors
+  w: (v) => ({ appWidth: v }),
+  h: (v) => ({ appHeight: v }),
+  screenResolution: (v) => ({
+    deviceLogicalPixelRatio: typeof v === 'string' ? (SCREEN_RESOLUTIONS[v] ?? 1) : v,
+  }),
+  renderQuality: (v) => ({
+    devicePhysicalPixelRatio: RENDER_QUALITIES[v] ?? v ?? 1,
+  }),
+  canvasColor: (v) => ({ clearColor: Number(colors.normalize(v ?? '', '0x00000000')) }),
+  fpsInterval: (v) => ({ fpsUpdateInterval: v }),
+  pixelRatio: (v) => ({ deviceLogicalPixelRatio: v }),
+  viewportMargin: (v) => ({ boundsMargin: v }),
+  maxFPS: (v) => ({ targetFPS: v }),
+}
+
+/**
+ * Applies a runtime setting to the renderer via RendererMain.setOptions()
+ *
+ * @param {string} key - Blits setting key (validated by $settings)
+ * @param {any} value - New value
+ */
+const updateSetting = (key, value) => {
+  const rendererInstance = renderer
+  if (rendererInstance && typeof rendererInstance.setOptions === 'function') {
+    rendererInstance.setOptions(rendererOptions[key](value))
+  }
+}
 
 export default {
   Element,
   Launch,
+  updateSetting,
 }

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

@@ -155,8 +155,17 @@ export default (App, target, settings) => {
 
   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/router/router.js

@@ -590,9 +590,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)
+      }
     }
   },
 }