@lightningjs/blits 1.29.1 → 1.29.3

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+_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
+
+- Added end of life flag to prevent timers, intervals and listeners to be registered after component destroy
+
 _22 may 2025_
 
 ## v1.29.1

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.1",
+  "version": "1.29.3",
   "description": "Blits: The Lightning 3 App Development Framework",
   "bin": "bin/index.js",
   "exports": {

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,14 +34,30 @@ 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
+      if (this.eol === true) return
       eventListeners.registerListener(this, event, callback, priority)
     },
     writable: false,
     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,7 +60,11 @@ export default {
     configurable: false,
   },
   destroy: {
+    /**
+     * @this {import('../../component').BlitsComponent}
+     */
     value: function () {
+      this.eol = true
       this.lifecycle.state = 'destroy'
       this.$clearTimeouts()
       this.$clearIntervals()
@@ -93,6 +106,9 @@ export default {
     configurable: false,
   },
   [symbols.removeGlobalEffects]: {
+    /**
+     * @this {import('../../component').BlitsComponent}
+     */
     value: function (effects = []) {
       removeGlobalEffects(effects)
     },
@@ -101,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)
@@ -110,6 +129,9 @@ export default {
     configurable: false,
   },
   $select: {
+    /**
+     * @this {import('../../component').BlitsComponent}
+     */
     value: function (ref) {
       let selected = null
       this[symbols.children].forEach((child) => {
@@ -132,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)
@@ -141,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
@@ -159,6 +187,9 @@ export default {
     configurable: false,
   },
   shader: {
+    /**
+     * @this {import('../../component').BlitsComponent}
+     */
     value: function (type, args) {
       return {
         type: type,
@@ -181,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/base/timeouts_intervals.js

@@ -20,6 +20,8 @@ import symbols from '../../lib/symbols.js'
 export default {
   $setTimeout: {
     value: function (fn, ms, ...params) {
+      // early exit when component is marked as end of life
+      if (this.eol === true) return
       const timeoutId = setTimeout(
         () => {
           this[symbols.timeouts] = this[symbols.timeouts].filter((id) => id !== timeoutId)
@@ -59,6 +61,8 @@ export default {
   },
   $setInterval: {
     value: function (fn, ms, ...params) {
+      // early exit when component is marked as end of life
+      if (this.eol === true) return
       const intervalId = setInterval(() => fn.apply(null, params), ms, params)
       this[symbols.intervals].push(intervalId)
       return intervalId

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
@@ -167,6 +305,7 @@ const Component = (name = required('name'), config = required('config')) => {
     // setup (and execute) all the generated side effects based on the
     // reactive bindings define in the template
     const effects = config.code.effects
+    this[symbols.effects] = []
     for (let i = 0; i < effects.length; i++) {
       const eff = () => {
         effects[i](this, this[symbols.children], config, globalComponents, rootComponent, effect)
@@ -216,11 +355,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]

package/src/engines/L3/element.js

@@ -25,6 +25,12 @@ import Settings from '../../settings.js'
 // temporary counter to work around shader caching issues
 let counter = 0
 
+/**
+ * Creates a padding object from a value and direction.
+ * @param {number|object|string|undefined} padding - The padding value.
+ * @param {string} direction - The layout direction ('vertical' or 'horizontal').
+ * @returns {{start: number, end: number, oppositeStart: number, oppositeEnd: number}} The padding object.
+ */
 const createPaddingObject = (padding, direction) => {
   if (padding === undefined) {
     return { start: 0, end: 0, oppositeStart: 0, oppositeEnd: 0 }
@@ -67,6 +73,11 @@ const createPaddingObject = (padding, direction) => {
   return { start: 0, end: 0, oppositeStart: 0, oppositeEnd: 0 }
 }
 
+/**
+ * Layout function for arranging children in a layout container.
+ * @param {object} config - The layout configuration object.
+ * @this {import('../../component.js').BlitsElement}
+ */
 const layoutFn = function (config) {
   const position = config.direction === 'vertical' ? 'y' : 'x'
   const oppositePosition = config.direction === 'vertical' ? 'x' : 'y'
@@ -135,18 +146,40 @@ const layoutFn = function (config) {
   }
 }
 
+/**
+ * Checks if a value is a transition object.
+ * @param {any} value - The value to check.
+ * @returns {boolean} True if the value is a transition object, false otherwise.
+ */
 const isTransition = (value) => {
   return value !== null && typeof value === 'object' && 'transition' in value === true
 }
 
+/**
+ * Checks if a string is an object string (starts and ends with curly braces).
+ * @param {string} str - The string to check.
+ * @returns {boolean} True if the string is an object string, false otherwise.
+ */
 const isObjectString = (str) => {
   return typeof str === 'string' && str.startsWith('{') && str.endsWith('}')
 }
 
+/**
+ * Parses a string into an object, converting single quotes to double and adding quotes to keys.
+ * @param {string} str - The string to parse.
+ * @returns {object} The parsed object.
+ */
 const parseToObject = (str) => {
   return JSON.parse(str.replace(/'/g, '"').replace(/([\w-_]+)\s*:/g, '"$1":'))
 }
 
+/**
+ * Parses a percentage string or returns the value as-is.
+ * @param {string|number} v - The value to parse (may be a percentage string).
+ * @param {string} base - The base property name ('width' or 'height').
+ * @returns {number|string} The parsed value as a number or the original value.
+ * @this {{ element: { config: { parent?: { node?: Record<string, number> } } } }}
+ */
 const parsePercentage = function (v, base) {
   if (typeof v !== 'string') {
     return v
@@ -160,6 +193,11 @@ const parsePercentage = function (v, base) {
   return v
 }
 
+/**
+ * Unpacks a transition value from an object or returns the value as-is.
+ * @param {any} v - The value to unpack.
+ * @returns {any} The unpacked value.
+ */
 const unpackTransition = (v) => {
   if (typeof v !== 'object' || v === null) return v
   if (v.constructor === Object) {
@@ -180,8 +218,18 @@ const colorMap = {
   right: 'colorRight',
 }
 
+/**
+ * Default text settings for text nodes (initialized on first use).
+ * @type {object|null}
+ */
 let textDefaults = null
 
+/**
+ * @typedef {import('../../component.js').BlitsElement} BlitsElement
+ *
+ * This is always a BlitsElement
+ * @this {BlitsElement} this
+ */
 const propsTransformer = {
   set parent(v) {
     this.props['parent'] = v === 'root' ? renderer.root : v.node
@@ -448,6 +496,10 @@ const propsTransformer = {
 }
 
 const Element = {
+  /**
+   * Populates the element with data
+   * @param {import('../../component.js').BlitsElementProps} data
+   */
   populate(data) {
     const props = data
     props['node'] = this.config.node
@@ -459,6 +511,7 @@ const Element = {
     this.props.element = this
 
     this.props['parent'] = props['parent'] || this.config.parent
+    //@ts-ignore This might be a left over from the old code?
     delete props.parent
 
     this.props.raw = data
@@ -506,12 +559,24 @@ const Element = {
       })
     }
   },
+  /**
+   * Set an individual property on the node
+   *
+   * @this {import('../../component').BlitsElement} this
+   *
+   * @param {import('../..//component.js').BlitsElementProps} prop
+   * @param {any} value
+   * @returns {void}
+   */
   set(prop, value) {
     if (value === undefined) return
+    // @ts-ignore
     if (this.props.raw[prop] === value) return
+    // @ts-ignore
     this.props.raw[prop] = value
 
     this.props.props = {}
+    // @ts-ignore
     this.props[prop] = unpackTransition(value)
 
     const propsKeys = Object.keys(this.props.props)
@@ -654,6 +719,13 @@ const Element = {
   },
 }
 
+/**
+ * Returns a new Blits Element
+ *
+ * @param {Object} config - The configuration object for the element
+ * @param {import('../../component.js').BlitsComponent} component - The component to which the element belongs
+ * @returns {import('../../component.js').BlitsElement} - The new Blits Element
+ */
 export default (config, component) => {
   if (textDefaults === null) {
     textDefaults = {

package/src/engines/L3/launch.js

@@ -26,7 +26,8 @@ import colors from '../../lib/colors/colors.js'
 import fontLoader from './fontLoader.js'
 import shaderLoader from './shaderLoader.js'
 
-export let renderer = {}
+/** @type {RendererMain|null} */
+export let renderer = null
 
 const renderEngine = (settings) => {
   const renderMode = 'renderMode' in settings ? settings.renderMode : 'webgl'
@@ -63,6 +64,14 @@ const textureMemorySettings = (settings) => {
   }
 }
 
+/**
+ * Launch the render engine and application
+ *
+ * @param {import('../../launch.js').BlitsAppFactory} App - Factory function that returns the application instance (extends BlitsComponent with .quit())
+ * @param {HTMLElement} target - The target element to render the application into
+ * @param {Partial<import('../../launch.js').BlitsSettings>} [settings] - The settings for the renderer
+ *
+ */
 export default (App, target, settings = {}) => {
   renderer = new RendererMain(
     {

package/src/launch.js

@@ -20,6 +20,30 @@ import { initLog, Log } from './lib/log.js'
 import engine from './engine.js'
 import blitsPackageInfo from '../package.json' assert { type: 'json' }
 
+/**
+ * @typedef {Object} Font
+ * @property {string} family - Name of the font family
+ * @property {string} type - Type of font (web, msdf, sdf)
+ * @property {string} [file] - Location to the font file
+ * @property {string} [json] - Location of the font map (for msdf/sdf)
+ * @property {string} [png] - Location of the font png (for msdf/sdf)
+ */
+/**
+ * @typedef {Object} ShaderEffect
+ * @property {string} name
+ * @property {any} type
+ */
+/**
+ * @typedef {Object} Shader
+ * @property {string} name
+ * @property {any} type
+ */
+
+/**
+ * @typedef {import('@lightningjs/renderer').RendererMain} RendererMain
+ * @type {RendererMain}
+ */
+// @ts-ignore - We ignore this because it will be replaced by the renderer once the app is launched
 export let renderer = {}
 export const stage = {}
 
@@ -37,6 +61,52 @@ async function rendererVersion() {
   }
 }
 
+/**
+ * @typedef {Object} BlitsSettings
+ * @property {number} [w] - Width of the Application
+ * @property {number} [h] - Height of the Application
+ * @property {boolean} [multithreaded] - Whether to enable multithreaded
+ * @property {0|1|2|"info"|"warn"|"error"|"debug"[]} [debugLevel] - Debug level for console log messages
+ * @property {Font[]} [fonts] - Fonts to be used in the Application
+ * @property {ShaderEffect[]} [effects] - Effects to be used by DynamicShader
+ * @property {Shader[]} [shaders] - Shaders to be used in the application
+ * @property {string} [defaultFont] - Default font family to use in the Application
+ * @property {object} [keymap] - Custom keymapping
+ * @property {"Proxy"|"defineProperty"} [reactivityMode] - Mode of reactivity
+ * @property {"hd"|"720p"|720|"fhd"|"fullhd"|"1080p"|1080|"4k"|"2160p"|2160} [screenResolution] - Screen resolution of the device
+ * @property {"low"|"medium"|"high"|"retina"|number} [renderQuality] - Quality of the rendered App
+ * @property {number} [pixelRatio] - Custom pixel ratio of the device
+ * @property {number} [fpsInterval] - Interval in ms to receive FPS updates
+ * @property {number} [webWorkersLimit] - Maximum number of web workers
+ * @property {string} [canvasColor] - Background color of the canvas
+ * @property {boolean} [inspector] - Enable inspector
+ * @property {number|[number,number,number,number]} [viewportMargin] - Extra margin to the viewport
+ * @property {number} [gpuMemoryLimit] - Threshold after which textures are freed (deprecated)
+ * @property {object} [gpuMemory] - Configures the gpu memory settings
+ * @property {"webgl"|"canvas"} [renderMode] - Defines which mode the renderer should operate in
+ * @property {number} [holdTimeout] - Time after which a key press is considered a hold
+ * @property {HTMLCanvasElement} [canvas] - Custom canvas object used to render the App
+ * @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
+ */
+
+/**
+ * Blits App defines the structure of the Blits application.
+ * @typedef {import('./component').BlitsComponent} BlitsComponent
+ * @typedef {BlitsComponent & { quit: () => void }} BlitsAppComponent
+ * @typedef {() => BlitsAppComponent} BlitsAppFactory
+ */
+
+/**
+ * Launches the Blits application with the given App, target, and settings.
+ * Sets up logging, version info, and initializes the renderer and stage singletons.
+ *
+ * @param {BlitsAppFactory} App - The root BlitsComponent to launch.
+ * @param {HTMLElement} target - The DOM element or rendering target.
+ * @param {BlitsSettings} settings - Configuration settings for the application.
+ * @returns {void}
+ */
 export default (App, target, settings) => {
   Settings.set(settings)
 

package/src/lib/componentId.js

@@ -18,18 +18,31 @@
 const counters = {}
 let counter = 0
 
+/**
+ * Creates a human-readable component ID string for a given component name.
+ *
+ * @param {string} name - The name of the component.
+ * @returns {string} The generated human-readable component ID.
+ */
 export const createHumanReadableId = (name) => {
   return `BlitsComponent::${name}_${(counters[name] = (counters[name] || 0) + 1)}`
 }
 
+/**
+ * Generates a new unique internal numeric ID.
+ *
+ * @returns {number} The next unique internal ID.
+ */
 export const createInternalId = () => {
   return ++counter
 }
 
 /**
- * Resets the counter value back to 0.
+ * Resets the internal counter value back to 0.
  * Used in automated tests to ensure consistent results, not intended
  * to be used in the actual framework code!
+ *
+ * @returns {void}
  */
 export const resetCounter = () => {
   counter = 0

package/src/lib/eventListeners.js

@@ -19,6 +19,15 @@ const eventsMap = new Map()
 const callbackCache = new Map()
 
 export default {
+  /**
+   * Registers a listener callback for a specific event on a component.
+   *
+   * @param {object} component - The component instance to register the listener for.
+   * @param {string} event - The name of the event to listen for.
+   * @param {Function} cb - The callback function to execute when the event is emitted.
+   * @param {number} [priority=0] - The priority of the listener (higher runs first).
+   * @returns {void}
+   */
   registerListener(component, event, cb, priority = 0) {
     let componentsMap = eventsMap.get(event)
     if (componentsMap === undefined) {
@@ -36,6 +45,13 @@ export default {
     callbackCache.delete(event) // Invalidate the callbackCache when a new callback is added
   },
 
+  /**
+   * Deregisters a listener for a specific event on a component.
+   *
+   * @param {object} component - The component instance to deregister the listener for.
+   * @param {string} event - The name of the event to stop listening for.
+   * @returns {void}
+   */
   deregisterListener(component, event) {
     let componentsMap = eventsMap.get(event)
     if (componentsMap === undefined) {
@@ -49,6 +65,13 @@ export default {
     }
   },
 
+  /**
+   * Executes all registered listeners for a given event, in priority order.
+   *
+   * @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 without stopping propagation, false if any listener returned false.
+   */
   executeListeners(event, params) {
     const componentsMap = eventsMap.get(event)
     if (componentsMap === undefined || componentsMap.size === 0) {
@@ -78,6 +101,12 @@ export default {
     return true // All listeners executed without stopping propagation
   },
 
+  /**
+   * Removes all listeners for a given component from all events.
+   *
+   * @param {object} component - The component instance to remove listeners for.
+   * @returns {void}
+   */
   removeListeners(component) {
     for (const [event, componentsMap] of eventsMap) {
       if (componentsMap.has(component)) {

package/src/lib/hooks.js

@@ -19,15 +19,36 @@ import symbols from './symbols.js'
 
 const cbs = {}
 
+/**
+ * Emits a registered hook for a given identifier, calling the hook with the provided scope and data.
+ *
+ * @param {string|symbol} hook - The name or symbol of the hook to emit.
+ * @param {string} identifier - The unique identifier for the hook set.
+ * @param {object} scope - The value of `this` inside the hook function.
+ * @param {Array} [data=[]] - Arguments to pass to the hook function.
+ */
 export const emit = (hook, identifier, scope, data = []) => {
   cbs[identifier] && cbs[identifier][hook] && cbs[identifier][hook].apply(scope, data)
 }
 
+/**
+ * Emits a registered symbol-based hook for a given identifier, calling the hook with the provided scope.
+ *
+ * @param {string|symbol} hook - The name or symbol of the hook to emit (will be mapped to a symbol).
+ * @param {string} identifier - The unique identifier for the hook set.
+ * @param {object} scope - The value of `this` inside the hook function.
+ */
 export const privateEmit = (hook, identifier, scope) => {
   const symHook = symbols[hook]
   cbs[identifier] && cbs[identifier][symHook] && cbs[identifier][symHook].apply(scope)
 }
 
+/**
+ * Registers a set of hooks (functions) for a given identifier.
+ *
+ * @param {Object<string,Function>|Object<symbol,Function>} hooks - An object whose keys are hook names or symbols and values are functions.
+ * @param {string} identifier - The unique identifier for the hook set.
+ */
 export const registerHooks = (hooks = {}, identifier) => {
   cbs[identifier] = {}
   // Combines enumerable keys and symbol properties of the 'hooks' object

package/src/lib/lifecycle.js

@@ -19,6 +19,10 @@ import { Log } from './log.js'
 import { emit, privateEmit } from './hooks.js'
 import symbols from './symbols.js'
 
+/**
+ * List of valid lifecycle states for a component.
+ * @type {Array<string>}
+ */
 const states = [
   'init', // fired upon component instantiation
   'ready', // fired when component instantiated, reactivity setup done and template spawned
@@ -31,12 +35,40 @@ const states = [
   'exit', // fired when leaving the visible viewport
 ]
 
+/**
+ * Lifecycle state manager for components.
+ *
+ * @typedef {Object} Lifecycle
+ * @property {string|null} previous - The previous lifecycle state.
+ * @property {string|null} current - The current lifecycle state.
+ * @property {Object} [component] - The component instance this lifecycle belongs to.
+ * @property {string|null} state - The current lifecycle state (getter/setter).
+ */
+
+/**
+ * Lifecycle state management object for components.
+ * Handles state transitions and emits corresponding hooks.
+ *
+ * @type {Lifecycle}
+ * @this {Lifecycle & {component: Object}}
+ * The 'component' property is expected to be set by the component instance at runtime.
+ */
 export default {
   previous: null,
   current: null,
+  /**
+   * Gets the current lifecycle state.
+   * @this {Lifecycle & {component: Object}}
+   * @returns {string|null}
+   */
   get state() {
     return this.current
   },
+  /**
+   * Sets the lifecycle state and emits hooks if the state is valid and changed.
+   * @this {Lifecycle & {component: Object}}
+   * @param {string} v - The new lifecycle state.
+   */
   set state(v) {
     if (states.indexOf(v) > -1 && (v !== this.current || v === 'focus')) {
       Log.debug(

package/src/lib/log.js

@@ -19,6 +19,10 @@ import Settings from '../settings.js'
 
 const n = () => {}
 
+/**
+ * Returns the current time as a locale time string (hh:mm:ss).
+ * @returns {string} The current time string.
+ */
 const time = () =>
   new Date().toLocaleTimeString([], {
     hour: '2-digit',
@@ -26,6 +30,13 @@ const time = () =>
     second: '2-digit',
   })
 
+/**
+ * Returns a logger object for the given context, with info, warn, debug, and error methods.
+ * Logging methods are no-ops if the debug level does not match.
+ *
+ * @param {string} context - The context label for log messages.
+ * @returns {Object} Logger object with info, warn, debug, and error methods.
+ */
 const logger = (context) => {
   const level = Settings.get('debugLevel')
   const log = {}

package/src/lib/symbols.js

@@ -1,3 +1,55 @@
+/**
+ * Symbol registry for internal framework properties and generated code.
+ *
+ * @typedef {Object} BlitsSymbols
+ * @property {symbol} currentView
+ * @property {symbol} cursorTagStart
+ * @property {symbol} computedKeys
+ * @property {symbol} destroy
+ * @property {symbol} getChildren
+ * @property {symbol} holder
+ * @property {symbol} id
+ * @property {symbol} identifier
+ * @property {symbol} index
+ * @property {symbol} init
+ * @property {symbol} inputEvents
+ * @property {symbol} intervals
+ * @property {symbol} launched
+ * @property {symbol} level
+ * @property {symbol} methodKeys
+ * @property {symbol} originalState
+ * @property {symbol} propKeys
+ * @property {symbol} raw
+ * @property {symbol} ready
+ * @property {symbol} renderer
+ * @property {symbol} routes
+ * @property {symbol} routerHooks
+ * @property {symbol} settings
+ * @property {symbol} state
+ * @property {symbol} stateKeys
+ * @property {symbol} textnode
+ * @property {symbol} timeouts
+ * @property {symbol} type
+ * @property {symbol} watchers
+ * @property {symbol} watchKeys
+ * @property {symbol} wrapper
+ * @property {symbol} children
+ * @property {symbol} components
+ * @property {symbol} config
+ * @property {symbol} isSlot
+ * @property {symbol} props
+ * @property {symbol} slots
+ * @property {symbol} componentType
+ * @property {symbol} isComponent
+ * @property {symbol} effects
+ * @property {symbol} removeGlobalEffects
+ */
+
+/**
+ * Internal symbol registry for Blits framework and generated code.
+ *
+ * @type {BlitsSymbols}
+ */
 export default {
   currentView: Symbol('currentView'),
   cursorTagStart: Symbol('cursorTagStart'),

package/src/lib/utils.js

@@ -1,3 +1,18 @@
+/**
+ * A mapping of common screen resolution names to their scale factors relative to 1080p (Full HD).
+ *
+ * @type {Object<string|number, number>}
+ * @property {number} hd - 0.666... (720p)
+ * @property {number} '720p' - 0.666... (720p)
+ * @property {number} 720 - 0.666... (720p)
+ * @property {number} fhd - 1 (Full HD)
+ * @property {number} fullhd - 1 (Full HD)
+ * @property {number} '1080p' - 1 (Full HD)
+ * @property {number} 1080 - 1 (Full HD)
+ * @property {number} '4k' - 2 (2160p)
+ * @property {number} '2160p' - 2 (2160p)
+ * @property {number} 2160 - 2 (2160p)
+ */
 export const screenResolutions = {
   hd: 0.66666667,
   '720p': 0.66666667,

package/src/router/router.js

@@ -25,6 +25,30 @@ import Focus from '../focus.js'
 import Announcer from '../announcer/announcer.js'
 import Settings from '../settings.js'
 
+/**
+ * @typedef {import('../component.js').BlitsComponentFactory} BlitsComponentFactory - The component of the route
+ * @typedef {import('../component.js').BlitsComponent} BlitsComponent - The element of the route
+ * @typedef {import('../engines/L3/element.js').BlitsElement} BlitsElement - The element of the route
+ *
+ * @typedef {Object} Route
+ * @property {string} path - The path of the route
+ * @property {string} hash - The hash of the route
+ * @property {Object} params - The params of the route
+ * @property {Object} data - The data of the route
+ * @property {Object} options - The options of the route
+ * @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
+ *
+ * @typedef {Object} Hash
+ * @property {string} path - The path of the hash
+ * @property {URLSearchParams} queryParams - The query params of the hash
+ * @property {string} hash - The hash
+ *
+ */
+
+/** @type {Route} */
 export let currentRoute
 export const state = reactive(
   {
@@ -40,6 +64,14 @@ export const state = reactive(
 
 // Changed from WeakMap to Map to allow for caching of views by the url hash.
 // We are manually doing the cleanup of the cache when the route is not marked as keepAlive.
+
+/**
+ * @typedef {Object} CacheMapEntry
+ * @property {BlitsComponent|BlitsComponentFactory} view - The view of the route
+ * @property {BlitsComponent} focus - The focus of the route
+ */
+
+/** @type {Map<String, CacheMapEntry>} */
 const cacheMap = new Map()
 const history = []
 
@@ -48,6 +80,10 @@ let navigationData = {}
 let navigatingBack = false
 let previousFocus
 
+/**
+ * Get the current hash
+ * @returns {Hash}
+ */
 export const getHash = () => {
   const hashParts = (document.location.hash || '/').replace(/^#/, '').split('?')
   return {
@@ -65,14 +101,34 @@ const normalizePath = (path) => {
       .toLowerCase()
   )
 }
+
+/**
+ * Check if a value is an object
+ * @param {any} v
+ * @returns {boolean} True if v is an object
+ */
 const isObject = (v) => typeof v === 'object' && v !== null
 
+/**
+ * Check if a value is a function
+ * @param {any} v
+ * @returns {boolean} True if v is a string
+ */
 const isString = (v) => typeof v === 'string'
 
+/**
+ * Match a path to a route
+ *
+ * @param {string} path
+ * @param {Route[]} routes
+ * @returns {Route}
+ */
 export const matchHash = (path, routes = []) => {
   // remove trailing slashes
   const originalPath = path.replace(/^\/+|\/+$/g, '')
   path = normalizePath(path)
+
+  /** @type {boolean|Route} */
   let matchingRoute = false
   let i = 0
   while (!matchingRoute && i < routes.length) {
@@ -126,9 +182,22 @@ export const matchHash = (path, routes = []) => {
     }
   }
 
+  // @ts-ignore - Remove me when we have a better way to handle this
   return matchingRoute
 }
 
+/**
+ * Navigate to a route
+ *
+ * This isn't the prettiest way to do this, but it works. The reason is that extends
+ * only works for Classes or Factory functions. As such we need to use this
+ * @typedef {BlitsComponent & {
+ *   activeView: BlitsComponent
+ * }} RouterViewComponent
+ *
+ * @this {RouterViewComponent} this
+ * @returns {Promise<void>}
+ */
 export const navigate = async function () {
   Announcer.stop()
   Announcer.clear()
@@ -178,6 +247,7 @@ export const navigate = async function () {
       }
       // apply default transition if none specified
       if (!('transition' in route)) {
+        /** @ts-ignore */
         route.transition = fadeInFadeOutTransition
       }
       // a transition can be a function returning a dynamic transition object
@@ -186,8 +256,10 @@ export const navigate = async function () {
         route.transition = route.transition(previousRoute, route)
       }
 
+      /** @type {import('../engines/L3/element.js').BlitsElement} */
       let holder
       let routeData
+
       let { view, focus } = cacheMap.get(route.hash) || {}
 
       // Announce route change if a message has been specified for this route
@@ -236,7 +308,9 @@ export const navigate = async function () {
           }
         }
         if (typeof view === 'function') {
-          view = view({ props }, holder, this)
+          // had to inline this because the tscompiler does not like LHS reassignments
+          // that also change the type of the variable in a variable union
+          view = /** @type {BlitsComponentFactory} */ (view)({ props }, holder, this)
         }
       } else {
         holder = view[symbols.holder]
@@ -267,7 +341,7 @@ export const navigate = async function () {
       previousFocus = Focus.get()
 
       // set focus to the view that we're routing to
-      focus ? focus.$focus() : view.$focus()
+      focus ? focus.$focus() : /** @type {BlitsComponent} */ (view).$focus()
 
       // apply before settings to holder element
       if (route.transition.before) {
@@ -321,6 +395,13 @@ export const navigate = async function () {
   state.navigating = false
 }
 
+/**
+ * Remove the currently active view
+ *
+ * @param {Route} route
+ * @param {BlitsComponent} view
+ * @param {Object} transition
+ */
 const removeView = async (route, view, transition) => {
   // apply out transition
   if (transition) {