@lightningjs/blits 2.13.0 → 2.14.0

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+# 2.14.0
+
+_19 oct 2026_
+
+- Added built-in profiler support to for both internal and app dev use
+- Added benchmark for performance comparison (and GitHub workflow to run on PRs)
+
 ## 2.13.0
 
 _13 oct 2026_

package/eslint.config.cjs

@@ -37,6 +37,7 @@ module.exports = defineConfig([
         ...globals.browser,
         ...globals.node,
         globalThis: false,
+        __DEV__: false,
       },
 
       parser: babelParser,

package/index.d.ts

@@ -1111,6 +1111,15 @@ declare module '@lightningjs/blits' {
    * the Blits App
    */
   export interface Settings {
+    /**
+     * Start the performance profiler when the App launches
+     *
+     * The profiler is also available on `globalThis.__BLITS_PROFILER__`, so it
+     * can be started and stopped from the devtools console
+     *
+     * @default false
+     */
+    profiler?: boolean,
     /**
      * Width of the Application
      */
@@ -1477,6 +1486,98 @@ declare module '@lightningjs/blits' {
   }
 
 
+  export interface ProfilerEntry {
+    /**
+     * Number of times the measurement was recorded
+     */
+    calls: number,
+    /**
+     * Total time spent, in milliseconds
+     */
+    totalMs: number,
+    /**
+     * Slowest single measurement, in milliseconds
+     */
+    maxMs: number,
+    /**
+     * Average time per call, in milliseconds
+     */
+    averageMs: number
+  }
+
+  export interface ProfilerFrameSummary {
+    medianMs: number,
+    p95Ms: number,
+    p99Ms: number,
+    maxMs: number
+  }
+
+  export interface ProfilerFrameLabel {
+    calls: number,
+    totalMs: number
+  }
+
+  export interface ProfilerFrameSnapshot {
+    frameCount: number,
+    retainedFrameLimit: number,
+    frameInterval: ProfilerFrameSummary,
+    instrumentedTime: ProfilerFrameSummary,
+    slowFramePercent: number,
+    slowestFrames: Array<{
+      intervalMs: number,
+      instrumentedMs: number,
+      labels: Record<string, ProfilerFrameLabel>
+    }>,
+    labels: Record<string, ProfilerFrameLabel & {
+      callsPerFrame: number,
+      averageMsPerFrame: number
+    }>
+  }
+
+  export interface ProfilerSnapshot {
+    measurements: Record<string, ProfilerEntry>,
+    frames: ProfilerFrameSnapshot
+  }
+
+  export interface Profiler {
+    /**
+     * Marks the start of a measurement
+     */
+    mark(name: string): void,
+    /**
+     * Ends the most recent measurement started with the same name
+     */
+    markEnd(name: string): void,
+    /**
+     * Clears previously collected measurements and starts recording
+     */
+    start(options?: { frames?: boolean, maxFrames?: number, targetFps?: number }): void,
+    /**
+     * Stops recording and returns the collected measurements
+     */
+    stop(): ProfilerSnapshot,
+    /**
+     * Clears all collected measurements, without changing the enabled state
+     */
+    reset(): void,
+    /**
+     * Returns the measurements collected so far
+     */
+    snapshot(): ProfilerSnapshot,
+    /**
+     * Returns frame-oriented results collected by default or with start({ frames: true })
+     */
+    frameSnapshot(): ProfilerFrameSnapshot,
+    /**
+     * Logs marker and frame results as console tables and returns the combined snapshot
+     */
+    report(): ProfilerSnapshot,
+    /**
+     * Whether the profiler is currently recording
+     */
+    readonly enabled: boolean
+  }
+
   /**
    * Blits App Framework
    */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lightningjs/blits",
-  "version": "2.13.0",
+  "version": "2.14.0",
   "description": "Blits: The Lightning 3 App Development Framework",
   "bin": "bin/index.js",
   "exports": {
@@ -49,6 +49,10 @@
       "default": "./src/testing/index.js"
     },
     "./symbols": "./src/lib/symbols.js",
+    "./profiler": {
+      "types": "./src/lib/profiler.d.ts",
+      "default": "./src/lib/profiler.js"
+    },
     "./blitsFileConverter": "./src/lib/blitsfileconverter/blitsfileconverter.js",
     "./components": "./src/components/FPScounter.js"
   },
@@ -62,6 +66,10 @@
     "postpublish": "node scripts/postpublish.js",
     "prepare": "husky",
     "pack-preview": "npm pack --dry-run",
+    "bench": "npm --prefix benchmarks run bench --",
+    "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"
   },
   "types": "./index.d.ts",

package/src/launch.js

@@ -20,6 +20,11 @@ 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'
+
+// Vite replaces __DEV__ with a boolean at build time. The typeof check keeps
+// the source usable outside Vite (for example in the test runner).
+const isDev = typeof __DEV__ !== 'undefined' && __DEV__
 
 /**
  * @typedef {Object} Font
@@ -93,6 +98,7 @@ async function rendererVersion() {
  * @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
+ * @property {boolean} [profiler] - Start the performance profiler on launch
  */
 
 /**
@@ -130,6 +136,12 @@ export default (App, target, settings) => {
 
   initLog()
 
+  if (isDev === true) {
+    // expose the profiler, so it can be controlled from the devtools console
+    globalThis.__BLITS_PROFILER__ = profiler
+    if (Settings.get('profiler', false) === true) profiler.start()
+  }
+
   if (warnLegacyRendererPlatform === true) {
     Log.warn(
       'Passing a renderer platform via settings.platform is deprecated. Use settings.rendererPlatform instead.'
@@ -144,4 +156,7 @@ export default (App, target, settings) => {
   stage.element = engine.Element
 
   renderer = engine.Launch(App, target, settings)
+  if (isDev === true) {
+    profiler.setRenderer(renderer)
+  }
 }

package/src/lib/profiler.d.ts

@@ -0,0 +1,62 @@
+/*
+ * 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 { Profiler } from '@lightningjs/blits'
+
+export type {
+  Profiler,
+  ProfilerEntry,
+  ProfilerFrameLabel,
+  ProfilerFrameSummary,
+  ProfilerFrameSnapshot,
+  ProfilerSnapshot,
+} from '@lightningjs/blits'
+
+/** Session-bound measurement token. Pass unchanged to profileEnd. */
+export interface ProfileToken {
+  readonly sessionId: number
+  readonly startTime: number
+}
+
+export interface ProfilerFrameOptions {
+  frames?: boolean
+  maxFrames?: number
+  targetFps?: number
+}
+
+/**
+ * Marks the start of a measurement.
+ *
+ * Returns `0` when the profiler is disabled.
+ */
+export function profileBegin(): ProfileToken | 0
+
+/**
+ * Records a measurement started with `profileBegin`
+ */
+export function profileEnd(name: string, start: ProfileToken | 0): void
+
+/**
+ * Measures the execution time of a (synchronous) function
+ */
+export function profile<T>(name: string, fn: () => T): T
+
+/** Attaches the profiler to a renderer that emits frameTick events. */
+export function setProfilerRenderer(renderer: unknown): void
+
+declare const profiler: Profiler
+export default profiler

package/src/lib/profiler.js

@@ -0,0 +1,386 @@
+/*
+ * 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 { Log } from './log.js'
+
+/**
+ * @typedef {Object} ProfilerEntry
+ * @property {number} calls - Number of times the measurement was recorded
+ * @property {number} totalMs - Total time spent, in milliseconds
+ * @property {number} maxMs - Slowest single measurement, in milliseconds
+ * @property {number} averageMs - Average time per call, in milliseconds
+ */
+
+const stats = new Map()
+const activeMarks = new Map()
+let enabled = false
+let sessionId = 0
+let activeSpan
+let renderer
+let frameTickHandler
+let frameConfig
+let activeFrame
+let frameHistory = []
+
+const hasPerformance = typeof globalThis.performance === 'object'
+
+const now = () => (hasPerformance === true ? globalThis.performance.now() : Date.now())
+
+const percentile = (values, percent) => {
+  if (values.length === 0) return 0
+  const index = Math.min(values.length - 1, Math.floor(values.length * percent))
+  return values.slice().sort((a, b) => a - b)[index]
+}
+
+const frameSummary = (values) => ({
+  medianMs: percentile(values, 0.5),
+  p95Ms: percentile(values, 0.95),
+  p99Ms: percentile(values, 0.99),
+  maxMs: values.length === 0 ? 0 : Math.max(...values),
+})
+
+const clearFrames = () => {
+  activeFrame = undefined
+  frameHistory = []
+}
+
+const finishFrame = (data) => {
+  if (activeFrame === undefined || activeFrame.sessionId !== sessionId) return
+  activeFrame.intervalMs = typeof data.delta === 'number' ? data.delta : 0
+  frameHistory.push(activeFrame)
+  if (frameHistory.length > frameConfig.maxFrames) frameHistory.shift()
+}
+
+const beginFrame = (data) => {
+  finishFrame(data)
+  activeFrame = {
+    sessionId,
+    intervalMs: 0,
+    totalMs: 0,
+    labels: new Map(),
+  }
+}
+
+const onFrameTick = (...args) => {
+  if (enabled !== true || frameConfig === undefined) return
+  const data = args[args.length - 1]
+  if (!data || typeof data.time !== 'number') return
+  beginFrame(data)
+}
+
+/**
+ * Attaches optional frame collection to a renderer that emits `frameTick`.
+ * @param {{on?: Function, off?: Function}} nextRenderer RendererMain instance
+ * @returns {void}
+ */
+export const setProfilerRenderer = (nextRenderer) => {
+  if (renderer === nextRenderer) return
+  if (renderer && frameTickHandler && typeof renderer.off === 'function') {
+    renderer.off('frameTick', frameTickHandler)
+  }
+  renderer = nextRenderer
+  frameTickHandler = undefined
+  if (renderer && typeof renderer.on === 'function') {
+    frameTickHandler = onFrameTick
+    renderer.on('frameTick', frameTickHandler)
+  }
+}
+
+/**
+ * Marks the start of a measurement.
+ *
+ * Returns `0` when the profiler is disabled, which keeps the overhead
+ * down to a single boolean check.
+ *
+ * @returns {{sessionId: number, startTime: number} | 0} Token to pass into {@link profileEnd}
+ */
+export const profileBegin = () => {
+  if (enabled !== true) return 0
+  const token = {
+    sessionId,
+    startTime: now(),
+    parent: activeSpan,
+    frame: activeFrame,
+  }
+  activeSpan = token
+  return token
+}
+
+/**
+ * Records a measurement started with {@link profileBegin}.
+ *
+ * @param {string} name - Label the measurement is aggregated under
+ * @param {{sessionId: number, startTime: number} | 0} start - Token returned by {@link profileBegin}
+ * @returns {void}
+ */
+export const profileEnd = (name, start) => {
+  if (enabled !== true || !start || start.sessionId !== sessionId) return
+
+  let entry = stats.get(name)
+  if (entry === undefined) {
+    entry = { calls: 0, totalMs: 0, maxMs: 0 }
+    stats.set(name, entry)
+  }
+
+  const elapsed = now() - start.startTime
+  start.closed = true
+  entry.calls++
+  entry.totalMs += elapsed
+  if (elapsed > entry.maxMs) entry.maxMs = elapsed
+
+  if (start.frame && start.frame.sessionId === sessionId) {
+    let frameEntry = start.frame.labels.get(name)
+    if (frameEntry === undefined) {
+      frameEntry = { calls: 0, totalMs: 0 }
+      start.frame.labels.set(name, frameEntry)
+    }
+    frameEntry.calls++
+    frameEntry.totalMs += elapsed
+    if (start.parent === undefined || start.parent.frame !== start.frame)
+      start.frame.totalMs += elapsed
+  }
+
+  if (activeSpan === start) {
+    activeSpan = start.parent
+    while (activeSpan !== undefined && activeSpan.closed === true) activeSpan = activeSpan.parent
+  }
+}
+
+const mark = (name) => {
+  if (enabled !== true) return
+
+  let marks = activeMarks.get(name)
+  if (marks === undefined) {
+    marks = []
+    activeMarks.set(name, marks)
+  }
+  marks.push(profileBegin())
+}
+
+const markEnd = (name) => {
+  if (enabled !== true) return
+
+  const marks = activeMarks.get(name)
+  if (marks === undefined) return
+
+  const start = marks.pop()
+  if (marks.length === 0) activeMarks.delete(name)
+  profileEnd(name, start)
+}
+
+/**
+ * Measures the execution time of a (synchronous) function.
+ *
+ * @template T
+ * @param {string} name - Label the measurement is aggregated under
+ * @param {() => T} fn - Function to measure
+ * @returns {T} The return value of `fn`
+ */
+export const profile = (name, fn) => {
+  if (enabled !== true) return fn()
+  const start = profileBegin()
+  try {
+    return fn()
+  } finally {
+    profileEnd(name, start)
+  }
+}
+
+const measurementsSnapshot = () =>
+  Object.fromEntries(
+    [...stats].map(([name, entry]) => [name, { ...entry, averageMs: entry.totalMs / entry.calls }])
+  )
+
+const frameSnapshot = () => {
+  const config = frameConfig || { maxFrames: 0, targetFrameMs: 1000 / 60 }
+  const intervals = frameHistory.map((frame) => frame.intervalMs)
+  const instrumented = frameHistory.map((frame) => frame.totalMs)
+  const labels = new Map()
+  for (const frame of frameHistory) {
+    for (const [name, entry] of frame.labels) {
+      let total = labels.get(name)
+      if (total === undefined) {
+        total = { calls: 0, totalMs: 0 }
+        labels.set(name, total)
+      }
+      total.calls += entry.calls
+      total.totalMs += entry.totalMs
+    }
+  }
+  const frameCount = frameHistory.length
+  const slowFrames = intervals.filter((value) => value > config.targetFrameMs * 1.5).length
+  const slowestFrames = frameHistory
+    .slice()
+    .sort((a, b) => b.totalMs - a.totalMs)
+    .slice(0, 10)
+    .map((frame) => ({
+      intervalMs: frame.intervalMs,
+      instrumentedMs: frame.totalMs,
+      labels: Object.fromEntries(frame.labels),
+    }))
+  return {
+    frameCount,
+    retainedFrameLimit: config.maxFrames,
+    frameInterval: frameSummary(intervals),
+    instrumentedTime: frameSummary(instrumented),
+    slowFramePercent: frameCount === 0 ? 0 : (slowFrames / frameCount) * 100,
+    slowestFrames,
+    labels: Object.fromEntries(
+      [...labels].map(([name, entry]) => [
+        name,
+        {
+          ...entry,
+          callsPerFrame: frameCount === 0 ? 0 : entry.calls / frameCount,
+          averageMsPerFrame: frameCount === 0 ? 0 : entry.totalMs / frameCount,
+        },
+      ])
+    ),
+  }
+}
+
+const snapshot = () => ({
+  measurements: measurementsSnapshot(),
+  frames: frameSnapshot(),
+})
+
+const report = () => {
+  const result = snapshot()
+  const measurements = result.measurements
+  const frameLabels = result.frames.labels
+  const slowFrames = Object.fromEntries(
+    result.frames.slowestFrames.map((frame, index) => [
+      `#${index + 1}`,
+      {
+        intervalMs: frame.intervalMs,
+        instrumentedMs: frame.instrumentedMs,
+        labels: Object.entries(frame.labels)
+          .sort(([, a], [, b]) => b.totalMs - a.totalMs)
+          .map(
+            ([name, entry]) =>
+              `${name}: ${entry.totalMs.toFixed(2)} ms (${entry.calls} ${
+                entry.calls === 1 ? 'call' : 'calls'
+              })`
+          )
+          .join(' | '),
+      },
+    ])
+  )
+
+  Log.info('Profiler summary')
+  console.table({
+    'Measurements tracked': Object.keys(measurements).length,
+    'Frames analyzed': result.frames.frameCount,
+    'Median frame interval (ms)': result.frames.frameInterval.medianMs,
+    'p95 frame interval (ms)': result.frames.frameInterval.p95Ms,
+    'Median instrumented time (ms)': result.frames.instrumentedTime.medianMs,
+    'p95 instrumented time (ms)': result.frames.instrumentedTime.p95Ms,
+    'Slow frames (%)': result.frames.slowFramePercent,
+  })
+  if (Object.keys(measurements).length) {
+    Log.info('Profiler: all marker timings')
+    console.table(measurements)
+  }
+  if (Object.keys(frameLabels).length) {
+    Log.info('Profiler: marker timings within retained frames')
+    console.table(frameLabels)
+  }
+  if (Object.keys(slowFrames).length) {
+    Log.info('Profiler: most expensive retained frames')
+    console.table(slowFrames)
+  }
+  return result
+}
+
+/**
+ * Lightweight, opt-in profiler used to measure performance bottlenecks
+ * in Blits internals and in App code.
+ */
+const profiler = {
+  /**
+   * Clears previously collected measurements and starts recording
+   * @returns {void}
+   */
+  start(options = {}) {
+    sessionId++
+    stats.clear()
+    activeMarks.clear()
+    activeSpan = undefined
+    frameConfig =
+      options.frames !== false
+        ? {
+            maxFrames: options.maxFrames || 300,
+            targetFrameMs: 1000 / (options.targetFps || 60),
+          }
+        : undefined
+    clearFrames()
+    enabled = true
+  },
+  /**
+   * Marks the start of a measurement
+   * @param {string} name - Label the measurement is aggregated under
+   * @returns {void}
+   */
+  mark,
+  /**
+   * Ends the most recent measurement started with the same name
+   * @param {string} name - Label passed to {@link mark}
+   * @returns {void}
+   */
+  markEnd,
+  /**
+   * Stops recording and returns the collected measurements
+   * @returns {Object.<string, ProfilerEntry>}
+   */
+  stop() {
+    enabled = false
+    activeMarks.clear()
+    activeSpan = undefined
+    return snapshot()
+  },
+  /**
+   * Clears collected measurements and pending spans, without changing the enabled state
+   * @returns {void}
+   */
+  reset() {
+    sessionId++
+    stats.clear()
+    activeMarks.clear()
+    activeSpan = undefined
+    clearFrames()
+  },
+  /**
+   * Returns the measurements collected so far
+   * @returns {Object.<string, ProfilerEntry>}
+   */
+  snapshot,
+  report,
+  setRenderer: setProfilerRenderer,
+  /**
+   * Returns frame-oriented measurements collected by default or with start({ frames: true }).
+   * @returns {object}
+   */
+  frameSnapshot,
+  /**
+   * Whether the profiler is currently recording
+   * @returns {boolean}
+   */
+  get enabled() {
+    return enabled
+  },
+}
+
+export default profiler