@lightningjs/blits 1.29.2 → 1.29.4

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+_03 jun 2025_
+
+## v1.29.4
+
+- Removed excessive shader creation for effects
+- Added explicit cleanup of effects in for loop
+- Improved element destruction
+
+_03 jun 2025_
+
+## v1.29.3
+
+- Added first batch internal JS doc types
+- Added documentation on Launch settings
+- Fixed issue with reactivity effects being shared (and retained) on the prototype
+
 _28 may 2025_
 
 ## v1.29.2

package/docs/essentials/settings.md

@@ -0,0 +1,117 @@
+# Application Settings
+
+Blits provides a flexible and performant way to configure your application at launch using the settings object passed to `Blits.Launch`. These settings allow you to fine-tune rendering, performance, input, fonts, and more.
+
+Below is a comprehensive overview of the available settings you can provide to a Blits Application:
+
+## Basic Settings
+
+| Setting         | Type                | Description |
+|----------------|---------------------|-------------|
+| `w`            | `number`            | Width of the application (canvas) |
+| `h`            | `number`            | Height of the application (canvas) |
+| `debugLevel`   | `number \| string[]`| Debug level for console log messages |
+| `multithreaded`| `boolean`           | Enable multithreaded rendering |
+
+## Fonts & Text
+
+| Setting         | Type      | Description |
+|----------------|-----------|-------------|
+| `fonts`        | `Font[]`  | Array of font objects to register |
+| `defaultFont`  | `string`  | Default font family to use |
+
+Example font object:
+```js
+{
+  family: 'lato',
+  type: 'msdf', // or 'web'
+  file: 'fonts/Lato-Regular.ttf',
+}
+```
+
+## Rendering & Performance
+
+| Setting         | Type      | Description |
+|----------------|-----------|-------------|
+| `renderQuality` | `'low' \| 'medium' \| 'high' \| 'retina' \| number` | Controls render quality (1 = 100%) |
+| `screenResolution` | `'hd' \| 'fhd' \| '4k' \| number` | Sets device screen resolution |
+| `pixelRatio`    | `number`  | Custom pixel ratio (overrides screenResolution) |
+| `canvasColor`   | `string`  | Background color of the canvas |
+| `fpsInterval`   | `number`  | Interval (ms) for FPS updates (0 disables) |
+| `webWorkersLimit` | `number`| Max number of web workers for image handling |
+| `gpuMemory`     | `object`  | GPU memory management (see below) |
+| `gpuMemoryLimit`| `number`  | (Deprecated) Use `gpuMemory` instead |
+| `textureProcessingTimeLimit` | `number` | Max ms per frame for texture processing |
+| `viewportMargin`| `number \| [number,number,number,number]` | Extra margin for preloading elements |
+| `advanced`      | `object`  | Advanced renderer settings (use with care) |
+
+### GPU Memory Example
+```js
+{
+  max: 200, // MB
+  target: 0.8, // 80% of max
+  cleanupInterval: 5000, // ms
+  baseline: 25, // MB
+  strict: false
+}
+```
+
+## Input & Focus
+
+| Setting         | Type      | Description |
+|----------------|-----------|-------------|
+| `keymap`       | `object`  | Custom key mapping for input events |
+| `holdTimeout`  | `number`  | Time (ms) to consider a key press as hold |
+
+## Renderer
+
+| Setting         | Type      | Description |
+|----------------|-----------|-------------|
+| `renderMode`   | `'webgl' \| 'canvas'` | Renderer mode (default: 'webgl') |
+| `canvas`       | `HTMLCanvasElement` | Custom canvas to render to |
+
+## Effects & Shaders
+
+| Setting         | Type      | Description |
+|----------------|-----------|-------------|
+| `effects`      | `ShaderEffect[]` | Effects for DynamicShader |
+| `shaders`      | `Shader[]` | Custom shaders |
+
+## Inspector & Debugging
+
+| Setting         | Type      | Description |
+|----------------|-----------|-------------|
+| `inspector`    | `boolean` | Enable the inspector tool |
+
+## Accessibility
+
+| Setting         | Type      | Description |
+|----------------|-----------|-------------|
+| `announcer`    | `boolean` | Enable/disable text-to-speech announcer |
+
+## Example Usage
+
+```js
+Blits.Launch(App, 'app', {
+  w: 1920,
+  h: 1080,
+  debugLevel: 1,
+  renderQuality: 'high',
+  fonts: [
+    { family: 'lato', type: 'msdf', file: 'fonts/Lato-Regular.ttf' },
+  ],
+  keymap: {
+    ArrowLeft: 'left',
+    ArrowRight: 'right',
+  },
+  gpuMemory: {
+    max: 200,
+    target: 0.8,
+    cleanupInterval: 5000,
+    baseline: 25,
+    strict: false,
+  },
+  inspector: false,
+  announcer: true,
+})
+```

package/docs/sidebar.json

@@ -42,6 +42,10 @@
       {
         "text": "Displaying text",
         "link": "/essentials/displaying_text"
+      },
+      {
+        "text": "Application settings",
+        "link": "/essentials/settings"
       }
     ]
   },

package/jsconfig.json

@@ -0,0 +1,12 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ESNext",
+    "allowJs": true,
+    "checkJs": true,
+    "moduleResolution": "node",
+    "baseUrl": "./"
+  },
+  "include": ["src"],
+  "exclude": ["node_modules"]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lightningjs/blits",
-  "version": "1.29.2",
+  "version": "1.29.4",
   "description": "Blits: The Lightning 3 App Development Framework",
   "bin": "bin/index.js",
   "exports": {
@@ -47,7 +47,7 @@
   },
   "dependencies": {
     "@lightningjs/msdf-generator": "^1.1.1",
-    "@lightningjs/renderer": "^2.13.2"
+    "@lightningjs/renderer": "^2.13.4"
   },
   "repository": {
     "type": "git",

package/src/component/base/events.js

@@ -18,6 +18,13 @@
 import eventListeners from '../../lib/eventListeners.js'
 
 export default {
+  /**
+   * Emits an event to all registered listeners for the given event name.
+   *
+   * @param {string} event - The name of the event to emit.
+   * @param {any} params - The parameters to pass to the event listeners.
+   * @returns {boolean} True if all listeners executed, false otherwise.
+   */
   $emit: {
     value: function (event, params) {
       // returning if all listeners executed
@@ -27,6 +34,14 @@ export default {
     enumerable: true,
     configurable: false,
   },
+  /**
+   * Registers a listener callback for a specific event.
+   *
+   * @param {string} event - The name of the event to listen for.
+   * @param {Function} callback - The callback function to execute when the event is emitted.
+   * @param {number} [priority=0] - The priority of the listener (higher runs first).
+   * @returns {void}
+   */
   $listen: {
     value: function (event, callback, priority = 0) {
       // early exit when component is marked as end of life
@@ -37,6 +52,12 @@ export default {
     enumerable: true,
     configurable: false,
   },
+  /**
+   * Deregisters a listener for a specific event.
+   *
+   * @param {string} event - The name of the event to stop listening for.
+   * @returns {void}
+   */
   $unlisten: {
     value: function (event) {
       eventListeners.deregisterListener(this, event)

package/src/component/base/methods.js

@@ -24,6 +24,9 @@ import { removeGlobalEffects } from '../../lib/reactivity/effect.js'
 
 export default {
   focus: {
+    /**
+     * @this {import('../../component').BlitsComponent}
+     */
     value: function (e) {
       Log.warn('this.focus is deprecated, use this.$focus instead')
       return this.$focus(e)
@@ -33,6 +36,9 @@ export default {
     configurable: false,
   },
   $focus: {
+    /**
+     * @this {import('../../component').BlitsComponent}
+     */
     value: function (e) {
       this[symbols.state].hasFocus = true
       Focus.set(this, e)
@@ -42,6 +48,9 @@ export default {
     configurable: false,
   },
   unfocus: {
+    /**
+     * @this {import('../../component').BlitsComponent}
+     */
     value: function () {
       this[symbols.state].hasFocus = false
       this.lifecycle.state = 'unfocus'
@@ -51,6 +60,9 @@ export default {
     configurable: false,
   },
   destroy: {
+    /**
+     * @this {import('../../component').BlitsComponent}
+     */
     value: function () {
       this.eol = true
       this.lifecycle.state = 'destroy'
@@ -94,6 +106,9 @@ export default {
     configurable: false,
   },
   [symbols.removeGlobalEffects]: {
+    /**
+     * @this {import('../../component').BlitsComponent}
+     */
     value: function (effects = []) {
       removeGlobalEffects(effects)
     },
@@ -102,6 +117,9 @@ export default {
     configurable: false,
   },
   select: {
+    /**
+     * @this {import('../../component').BlitsComponent}
+     */
     value: function (ref) {
       Log.warn('this.select is deprecated, use this.$select instead')
       return this.$select(ref)
@@ -111,6 +129,9 @@ export default {
     configurable: false,
   },
   $select: {
+    /**
+     * @this {import('../../component').BlitsComponent}
+     */
     value: function (ref) {
       let selected = null
       this[symbols.children].forEach((child) => {
@@ -133,6 +154,9 @@ export default {
     configurable: false,
   },
   trigger: {
+    /**
+     * @this {import('../../component').BlitsComponent}
+     */
     value: function (key) {
       Log.warn('this.trigger is deprecated, use this.$trigger instead')
       return this.$trigger(key)
@@ -142,6 +166,9 @@ export default {
     configurable: false,
   },
   $trigger: {
+    /**
+     * @this {import('../../component').BlitsComponent}
+     */
     value: function (key) {
       let target = this[symbols.originalState]
       // when dot notation used, find the nested target
@@ -160,6 +187,9 @@ export default {
     configurable: false,
   },
   shader: {
+    /**
+     * @this {import('../../component').BlitsComponent}
+     */
     value: function (type, args) {
       return {
         type: type,
@@ -182,6 +212,10 @@ export default {
   },
 }
 
+/**
+ * Recursively destroys all BlitsComponent children.
+ * @param {import('../../component').BlitsComponent[]} children
+ */
 const deleteChildren = function (children) {
   for (let i = 0; i < children.length; i++) {
     if (!children[i]) return

package/src/component/setup/index.js

@@ -32,8 +32,6 @@ let counter = 0
 export default function (component, config) {
   component[symbols.identifier] = ++counter
 
-  component[symbols.effects] = []
-
   // setup hooks
   registerHooks(config.hooks, component[symbols.identifier])
 

package/src/component.js

@@ -43,12 +43,150 @@ const required = (name) => {
   throw new Error(`Parameter ${name} is required`)
 }
 
+/**
+ * @typedef {function} BlitsComponentFactory
+ * @param {object} opts - The options for the component instance
+ * @param {BlitsComponent} parentEl - The parent element for the component instance
+ * @param {BlitsComponent} parentComponent - The parent component for the component instance
+ * @param {BlitsComponent} rootComponent - The root component for the component instance
+ * @returns {BlitsComponent} - The component instance
+ */
+
+/**
+ *  Structure of a Blits component:
+ *  Component:
+ *   <Holder>
+ *      <Wrapper>
+ *           []<Elements>
+ *      </Wrapper>
+ *   </Holder>
+ *
+ * A Blits Element
+ * @typedef {Object} BlitsAnnouncer
+ * @property {(message: string) => void} assertive - Function to assertively announce a message.
+ * @property {() => void} clear - Function to clear the announcer.
+ * @property {() => void} disable - Function to disable the announcer.
+ * @property {() => void} enable - Function to enable the announcer.
+ * @property {(delay: number) => void} pause - Function to pause the announcer.
+ * @property {(message: string) => void} polite - Function to politely announce a message.
+ * @property {(message: string, politeness: 'off'|'polite'|'assertive') => void} announce - Function to announce a message with specified politeness.
+ * @property {() => void} stop - Function to stop the announcer.
+ * @property {(v: boolean) => void} toggle - Function to toggle the announcer.
+ *
+ * @typedef {Object} BlitsElementConfig
+ * @property {BlitsElement} parent - The parent element of this element.
+ * @property {any} node - The node object for the element.
+ *
+ * @typedef {Object} BlitsElementProps
+ * @property {boolean} __textnode - Indicates if the element is a text node.
+ * @property {boolean} __layout - Indicates if the element is a layout node.
+ * @property {BlitsElement} element - The element to which the props belong?? Do we need this?
+ * @property {BlitsElementConfig} config - Configuration object for the element.
+ * @property {Object<string, any>} props - The props object containing the properties of the element.
+ * @property {Object<string, any>} raw - The raw input props.
+ * @property {Object<string, any>} scheduledTransitions - Tracks transitions by property name.
+ *
+ * @typedef {Object} BlitsElement
+ * @property {BlitsComponent} component - Reference to the owning Blits component.
+ * @property {BlitsElementConfig} config - Configuration object for the element.
+ * @property {number} counter - Unique counter used for shader workarounds. FIXME?
+ * @property {string[]} effectNames - Names of active shader effects.
+ * @property {any} node - The underlying renderer node (e.g., WebGL node or text node).
+ * @property {BlitsElementProps} props - Proxy-like object containing transformed props.
+ * @property {any[]} children - WVB I cant see this populated? Filtered list of children owned by this element. FIXME?
+ * @property {any} parent - WVB Shortcut to the parent CoreNode?
+ * @property {number} nodeId - ID of the CoreNode, if available.
+ * @property {string|null} ref - Ref name (if defined).
+ * @property {function(Object):void} populate - Initializes the element with props and hooks.
+ * @property {function(string, any):void} set - Updates a single property.
+ * @property {function(string, any, Object):void} animate - Animates a property with transition options.
+ * @property {function():void} destroy - Destroys the underlying node and cancels transitions.
+ * @property {function(any): any} triggerLayout - Triggers a layout update for the element.
+ *
+ * @typedef {Object} BlitsLifecycle
+ * @property {BlitsComponent} component - The Blits comonent instance this lifecycle belongs to.
+ * @property {'init'|'ready'|'destroyed'} current - The current lifecycle state of the component.
+ * @property {'init'|'ready'|'destroyed'|null} previous - The previous lifecycle state of the component.
+ * @property {string} state - The current lifecycle state of the component.
+ *
+ * @typedef {object} BlitsComponent
+ * Main properties of the Blits component:
+ * @property {string} componentId - The unique identifier for the component instance
+ * @property {BlitsLifecycle} lifecycle - The lifecycle object for the component instance
+ * @property {BlitsComponent} parent - The parent component of the current component instance
+ * @property {BlitsComponent} rootParent - Reference to the root component in case of slots, otherwise this is the same as parent
+ * @property {BlitsComponent|BlitsElement[]} [children] - The children of the component instance
+ * @property {BlitsElement} [holder] - The wrapper of the entire component instance
+ * @property {number} [id] - The internal ID for the component instance
+ * @property {number} [identifier] - The identifier for the component instance WVB Whats the difference with id?
+ * @property {any[]} [intervals] - The intervals created by the component instance WVB Fixme
+ * @property {Object<string, any>} [originalState] - The original state of the component instance
+ * @property {Object<string, any>} [props] - The reactive properties of the component instance
+ * @property {any[]} [slots] - The slots of the component instance WVB Fixme
+ * @property {Object<string, any>} [state] - The reactive state of the component instance
+ * @property {any[]} [timeouts] - The timeouts created by the component instance
+ * @property {BlitsElement} [wrapper] - The reference to the outer element of the component instance
+ * @property {object} [effects] - The effects of the component instance
+ * @property {object} [watchers] - The watchers of the component instance
+ * @property {Object<string, any>} computedKeys - The computed keys of the component instance
+ * @property {any[]} [effects] - The effects of the component instance
+ * @property {string[]} [propKeys] - The keys of the props of the component instance
+ * @property {any[]} [stateKeys] - The keys of the state of the component instance
+ * Single props:
+ * @property {object} activeView - The active view of the component instance
+ * @property {boolean} hasFocus - Indicates if the component has focus
+ * @property {string} ref - The reference name of the component instance
+ * @property {number|undefined} index - The index in a for loop
+ * @property {number|undefined} activeRow - The active row in a for loop
+ * @property {string} color - The color of the component instance
+ * @property {number} radius - The radius of the component instance
+ * @property {number} size - The size of the component instance
+ * Methods:
+ * @property {function(): void} destroy - Destroys the component and its children, clearing listeners and effects.
+ * @property {function(any): any} focus - ⚠️ Deprecated. Use `$focus()` instead.
+ * @property {function(string): any} select - ⚠️ Deprecated. Use `$select(ref)` instead.
+ * @property {function(string, object): {type: string, props: object}} shader - Creates a shader definition object.
+ * @property {function(string): void} trigger - ⚠️ Deprecated. Use `$trigger(key)` instead.
+ * @property {function(): void} unfocus - Clears the focus state and sets lifecycle to 'unfocus'.
+ * Builtins:
+ * @property {BlitsAnnouncer} $announcer - The announcer object for the component instance
+ * @property {() => void} $clearTimeouts - Clears all timeouts created by the component instance
+ * @property {(timeoutId: number) => void} $clearTimeout - Clears all timeouts created by the component instance
+ * @property {() => void} $clearIntervals - Clears all intervals created by the component instance
+ * @property {(intervalId: number) => void} $clearInterval - Clears all intervals created by the component instance
+ * @property {Object} $colors - The colors object for the component instance
+ * @property {(event: string, params: object) => void} $emit - Emits an event with the specified parameters
+ * @property {function(any): void} $focus - Sets the component focus state and delegates to the Focus manager.
+ * @property {Object} $language - The language object for the component instance
+ * @property {function(any): any} $listen - The listen object for the component instance
+ * @property {Object} $log - The log object for the component instance
+ * @property {Object} $router - The router object for the component instance
+ * @property {function(string): any} $select - Selects a child component by `ref`.
+ * @property {function(any): any} $setInterval - Sets an interval for the component instance
+ * @property {function(any): any} $setTimeout - Sets a timeout for the component instance
+ * @property {function(any): any} $size - The size object for the component instance
+ * @property {function(any): any} $sizes - The sizes object for the component instance
+ * @property {function(string): void} $trigger - Forces a reactivity trigger on a property in `originalState`.
+ * @property {function(any): any} $unlisten - The unlisten object for the component instance
+ *
+ */
+
+/**
+ * @typedef {Object} BlitsComponentConfig
+ * @property {string} template - The template string for the component.
+ * @property {function(this: BlitsComponent): Object} [state] - State factory function.
+ * @property {Object} [hooks] - Lifecycle hooks (frameTick, idle, attach, detach, enter, exit, etc).
+ * @property {Object} [code] - Compiled render/effects code (render: Function, effects: Function[]).
+ * @property {string} [name] - Optional name for the component.
+ * @property {any} [data] - Optional static data for the component.
+ * @property {Object} [options] - Optional options for the component.
+ */
+
 /**
  * Component factory function
  * @param {string} name - The name of the component
- * @param {object} config - The configuration object for the component
- * @returns {function} - A factory function that creates a new component instance
- *
+ * @param {BlitsComponentConfig} config - The configuration object for the component
+ * @returns {BlitsComponentFactory} - The component factory function
  */
 const Component = (name = required('name'), config = required('config')) => {
   let base = undefined
@@ -57,6 +195,8 @@ const Component = (name = required('name'), config = required('config')) => {
     // generate a human readable ID for the component instance (i.e. Blits::ComponentName1)
     this.componentId = createHumanReadableId(name)
 
+    this[symbols.effects] = []
+
     // instantiate a lifecycle object for this instance
     this.lifecycle = Object.assign(Object.create(Lifecycle), {
       component: this,
@@ -216,11 +356,21 @@ const Component = (name = required('name'), config = required('config')) => {
     return this
   }
 
+  /**
+   * Component factory function
+   * @typedef {BlitsComponentFactory}
+   * @param {Object} options
+   * @param {BlitsComponent} parentEl
+   * @param {BlitsComponent} parentComponent
+   * @param {BlitsComponent} rootComponent
+   * @returns {BlitsComponent}
+   */
   const factory = (options = {}, parentEl, parentComponent, rootComponent) => {
     if (Base[symbols['launched']] === false) {
       // Register user defined plugins once on the Base object (after launch)
       const pluginKeys = Object.keys(plugins)
       const pluginKeysLength = pluginKeys.length
+      /** @type {Object} */
       const pluginInstances = {}
       for (let i = 0; i < pluginKeysLength; i++) {
         const pluginName = pluginKeys[i]