From f468eac2e58112ca95e4c0fb048421deb674898d Mon Sep 17 00:00:00 2001 From: tuncayuk Date: Tue, 9 Jun 2026 11:22:20 +0100 Subject: [PATCH 1/5] feat: add platform property to renderer settings for platform abstraction --- src/engines/L3/launch.js | 15 ++++++++++++++- src/launch.js | 1 + 2 files changed, 15 insertions(+), 1 deletion(-) diff --git a/src/engines/L3/launch.js b/src/engines/L3/launch.js index 5ee5ed2f..18779dfb 100644 --- a/src/engines/L3/launch.js +++ b/src/engines/L3/launch.js @@ -19,6 +19,12 @@ import { RendererMain } from '@lightningjs/renderer' import { WebGlCoreRenderer, SdfTextRenderer } from '@lightningjs/renderer/webgl' import { CanvasCoreRenderer, CanvasTextRenderer } from '@lightningjs/renderer/canvas' import { Inspector } from '@lightningjs/renderer/inspector' +import { + WebPlatform, + WebPlatformNext, + WebPlatformChrome50, + WebPlatformLegacy, +} from '@lightningjs/renderer/platforms' import { Log } from '../../lib/log.js' import { SCREEN_RESOLUTIONS, RENDER_QUALITIES } from '../../constants.js' @@ -43,6 +49,13 @@ const textRenderEngines = (settings) => { if (renderMode === 'canvas') return [CanvasTextRenderer] } +const PLATFORMS = { + web: WebPlatform, + next: WebPlatformNext, + chrome50: WebPlatformChrome50, + legacy: WebPlatformLegacy, +} + const textureMemorySettings = (settings) => { const gpuMemory = { ...{ @@ -100,7 +113,7 @@ export default (App, target, settings = {}) => { textureMemory: textureMemorySettings(settings), createImageBitmapSupport: 'auto', targetFPS: 'maxFPS' in settings ? settings.maxFPS : 0, - platform: 'platform' in settings ? settings.platform : null, + platform: PLATFORMS[settings.platform] || WebPlatform, }, ...(settings.advanced || {}), }, diff --git a/src/launch.js b/src/launch.js index 0449c977..f91788d5 100644 --- a/src/launch.js +++ b/src/launch.js @@ -83,6 +83,7 @@ async function rendererVersion() { * @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 {"web"|"next"|"chrome50"|"legacy"} [platform] - Platform abstraction layer used by the renderer * @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 From cb18bbf531dec1fbdd7155d386e784d7fc83890c Mon Sep 17 00:00:00 2001 From: tuncayuk Date: Tue, 9 Jun 2026 11:22:44 +0100 Subject: [PATCH 2/5] feat: update @lightningjs/renderer to version 3.0.5 --- package-lock.json | 8 ++++---- package.json | 2 +- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/package-lock.json b/package-lock.json index 1b45ee93..7798b625 100644 --- a/package-lock.json +++ b/package-lock.json @@ -9,7 +9,7 @@ "version": "2.4.1", "license": "Apache-2.0", "dependencies": { - "@lightningjs/renderer": "^3.0.3", + "@lightningjs/renderer": "^3.0.5", "magic-string": "^0.30.21" }, "bin": { @@ -752,9 +752,9 @@ } }, "node_modules/@lightningjs/renderer": { - "version": "3.0.3", - "resolved": "https://registry.npmjs.org/@lightningjs/renderer/-/renderer-3.0.3.tgz", - "integrity": "sha512-DKvQsesjjGZCDAyG/mK40V9sm+L8KYassB9HJGOvBcA/EOdNwYIcOvsLddMYVJBCttRvgqzgMZBSW3dQyuk31w==", + "version": "3.0.5", + "resolved": "https://registry.npmjs.org/@lightningjs/renderer/-/renderer-3.0.5.tgz", + "integrity": "sha512-r/LFj8MmskZXC434okkV8CdTm3B7z9leb6aXVksvkWrLgBGxARTyTt7dIH9/Ho3GxIN9Eu/7QfN742K4tHfe+Q==", "license": "Apache-2.0", "engines": { "node": ">= 18.0.0", diff --git a/package.json b/package.json index a977c75c..87dbb694 100644 --- a/package.json +++ b/package.json @@ -75,7 +75,7 @@ "tape": "^5.5.0" }, "dependencies": { - "@lightningjs/renderer": "^3.0.3", + "@lightningjs/renderer": "^3.0.5", "magic-string": "^0.30.21" }, "repository": { From 1a9cdd8dbbfd6040495656d198ab4a548c8c39bc Mon Sep 17 00:00:00 2001 From: tuncayuk Date: Tue, 9 Jun 2026 11:22:59 +0100 Subject: [PATCH 3/5] feat: add platform type and property for renderer settings --- index.d.ts | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/index.d.ts b/index.d.ts index 8ce31ae4..43cb9d48 100644 --- a/index.d.ts +++ b/index.d.ts @@ -1003,6 +1003,7 @@ declare module '@lightningjs/blits' { type ReactivityModes = 'Proxy' | 'defineProperty' type RenderModes = 'webgl' | 'canvas' + type Platforms = 'web' | 'next' | 'chrome50' | 'legacy' /** * Settings @@ -1222,6 +1223,18 @@ declare module '@lightningjs/blits' { */ renderMode?: RenderModes, + /** + * Selects the platform abstraction layer used by the Lightning renderer. + * + * - `web` (default) - Modern browsers with full `createImageBitmap` support + * - `next` - PWAs / Service Worker environments using the Fetch API for image loading + * - `chrome50` - Older Chromium / WPEWebKit 2017 with basic `createImageBitmap` support + * - `legacy` - QtWebKit and other legacy engines with limited browser APIs + * + * When omitted, the renderer falls back to `WebPlatform`. + */ + platform?: Platforms, + /** * The time, in milliseconds, after which Blits considers a key press a _hold_ key press * From e9627f8fe64dc16f363ac4c810581a34927e38b4 Mon Sep 17 00:00:00 2001 From: tuncayuk Date: Tue, 9 Jun 2026 11:23:09 +0100 Subject: [PATCH 4/5] feat: add platform setting for renderer abstraction in application settings --- docs/essentials/settings.md | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/docs/essentials/settings.md b/docs/essentials/settings.md index cff25216..a655399b 100644 --- a/docs/essentials/settings.md +++ b/docs/essentials/settings.md @@ -71,6 +71,27 @@ Example font object: |----------------|-----------|-------------| | `renderMode` | `'webgl' \| 'canvas'` | Renderer mode (default: 'webgl') | | `canvas` | `HTMLCanvasElement` | Custom canvas to render to | +| `platform` | `'web' \| 'next' \| 'chrome50' \| 'legacy'` | Platform abstraction layer used by the Lightning renderer (default: `'web'`) | + +### Platform + +The `platform` setting selects which platform abstraction the underlying Lightning renderer uses to talk to the browser (image loading, canvas creation, etc.). Most Apps should leave this unset and use the default `web` platform; the alternatives exist for environments where the modern browser APIs aren't fully available. + +| Value | Browser engine | +|------------|-------------| +| `web` | Chrome 70+ | +| `next` | Chrome 70+ | +| `chrome50` | Chrome 50+ | +| `legacy` | Chrome 40+ | + +Example: +```js +Blits.Launch(App, 'app', { + w: 1920, + h: 1080, + platform: 'legacy', +}) +``` ## Effects & Shaders @@ -118,5 +139,6 @@ Blits.Launch(App, 'app', { inspector: false, announcer: true, enableMouse: false, // set true for hover + click-to-focus on canvas + platform: 'web', // 'web' (default) | 'next' | 'chrome50' | 'legacy' }) ``` From 584adcc72aa7f44c171025388754c37c4a403e49 Mon Sep 17 00:00:00 2001 From: tuncayuk Date: Tue, 9 Jun 2026 13:32:39 +0100 Subject: [PATCH 5/5] feat: enhance platform setting to accept Platform class references for renderer abstraction --- docs/essentials/settings.md | 17 +++++++++++++++-- index.d.ts | 22 +++++++++++++++++----- src/engines/L3/launch.js | 5 ++++- src/launch.js | 2 +- 4 files changed, 37 insertions(+), 9 deletions(-) diff --git a/docs/essentials/settings.md b/docs/essentials/settings.md index a655399b..c3aa0559 100644 --- a/docs/essentials/settings.md +++ b/docs/essentials/settings.md @@ -71,12 +71,14 @@ Example font object: |----------------|-----------|-------------| | `renderMode` | `'webgl' \| 'canvas'` | Renderer mode (default: 'webgl') | | `canvas` | `HTMLCanvasElement` | Custom canvas to render to | -| `platform` | `'web' \| 'next' \| 'chrome50' \| 'legacy'` | Platform abstraction layer used by the Lightning renderer (default: `'web'`) | +| `platform` | `'web' \| 'next' \| 'chrome50' \| 'legacy' \| Platform` | Platform abstraction layer used by the Lightning renderer (default: `'web'`) | ### Platform The `platform` setting selects which platform abstraction the underlying Lightning renderer uses to talk to the browser (image loading, canvas creation, etc.). Most Apps should leave this unset and use the default `web` platform; the alternatives exist for environments where the modern browser APIs aren't fully available. +You can pass either a **string alias** (recommended) or a **`Platform` class reference** imported directly from `@lightningjs/renderer/platforms` for full control (including custom subclasses). + | Value | Browser engine | |------------|-------------| | `web` | Chrome 70+ | @@ -84,7 +86,7 @@ The `platform` setting selects which platform abstraction the underlying Lightni | `chrome50` | Chrome 50+ | | `legacy` | Chrome 40+ | -Example: +Example using a string alias: ```js Blits.Launch(App, 'app', { w: 1920, @@ -93,6 +95,17 @@ Blits.Launch(App, 'app', { }) ``` +Example passing a class reference: +```js +import { WebPlatformChrome50 } from '@lightningjs/renderer/platforms' + +Blits.Launch(App, 'app', { + w: 1920, + h: 1080, + platform: WebPlatformChrome50, +}) +``` + ## Effects & Shaders | Setting | Type | Description | diff --git a/index.d.ts b/index.d.ts index 43cb9d48..63d42f84 100644 --- a/index.d.ts +++ b/index.d.ts @@ -1226,14 +1226,26 @@ declare module '@lightningjs/blits' { /** * Selects the platform abstraction layer used by the Lightning renderer. * - * - `web` (default) - Modern browsers with full `createImageBitmap` support - * - `next` - PWAs / Service Worker environments using the Fetch API for image loading - * - `chrome50` - Older Chromium / WPEWebKit 2017 with basic `createImageBitmap` support - * - `legacy` - QtWebKit and other legacy engines with limited browser APIs + * Accepts either: + * - A string alias for one of the bundled implementations: + * - `web` (default) - Modern browsers with full `createImageBitmap` support + * - `next` - PWAs / Service Worker environments using the Fetch API for image loading + * - `chrome50` - Older Chromium / WPEWebKit 2017 with basic `createImageBitmap` support + * - `legacy` - QtWebKit and other legacy engines with limited browser APIs + * - A `Platform` class reference imported from `@lightningjs/renderer/platforms` + * (or a custom subclass) for full control over the platform implementation. * * When omitted, the renderer falls back to `WebPlatform`. + * + * @example + * ```js + * import { WebPlatformChrome50 } from '@lightningjs/renderer/platforms' + * + * Blits.Launch(App, 'app', { platform: WebPlatformChrome50 }) + * Blits.Launch(App, 'app', { platform: 'chrome50' }) // equivalent + * ``` */ - platform?: Platforms, + platform?: Platforms | (new (...args: any[]) => any), /** * The time, in milliseconds, after which Blits considers a key press a _hold_ key press diff --git a/src/engines/L3/launch.js b/src/engines/L3/launch.js index 18779dfb..6298cf1e 100644 --- a/src/engines/L3/launch.js +++ b/src/engines/L3/launch.js @@ -113,7 +113,10 @@ export default (App, target, settings = {}) => { textureMemory: textureMemorySettings(settings), createImageBitmapSupport: 'auto', targetFPS: 'maxFPS' in settings ? settings.maxFPS : 0, - platform: PLATFORMS[settings.platform] || WebPlatform, + platform: + typeof settings.platform === 'function' + ? settings.platform + : PLATFORMS[settings.platform] || WebPlatform, }, ...(settings.advanced || {}), }, diff --git a/src/launch.js b/src/launch.js index f91788d5..2da2ab80 100644 --- a/src/launch.js +++ b/src/launch.js @@ -83,7 +83,7 @@ async function rendererVersion() { * @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 {"web"|"next"|"chrome50"|"legacy"} [platform] - Platform abstraction layer used by the renderer + * @property {"web"|"next"|"chrome50"|"legacy"|Function} [platform] - Platform abstraction layer used by the renderer. Either a string alias or a `Platform` class from `@lightningjs/renderer/platforms` * @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