@get-air/renderer

Air Renderer

Very experimental. This is Air's performance fork of the SolidTV / Lightning 3 renderer. It is published only on npm's experimental channel; APIs and defaults may change before a stable release.

A powerful 2D scene renderer designed for rendering highly performant user interfaces on browser-backed TV, mobile, and desktop surfaces using WebGL, with an inherited Canvas fallback for less capable environments.

The fork currently tracks the public API of @solidtv/renderer 1.6.4. It adds physical-device frame-pacing work, retained damage rendering, shader prewarming, render-texture fixes, bounded texture scheduling, and negotiated GPU-compressed artwork. See Embedded UI Performance.

Install

pnpm add @get-air/renderer@experimental

Direct imports use the Air package name:

import { RendererMain } from '@get-air/renderer';
import { WebGlCoreRenderer, SdfTextRenderer } from '@get-air/renderer/webgl';
import { CanvasTextRenderer } from '@get-air/renderer/canvas';

For a SolidTV application that must keep its existing imports, install it as an npm alias:

{
  "dependencies": {
    "@solidtv/renderer": "npm:@get-air/renderer@0.0.1"
  }
}

The optional Effect entrypoint wraps renderer initialization in a typed error:

import { Effect } from 'effect';
import { createRenderer } from '@get-air/renderer/effect';

const program = Effect.gen(function* () {
  return yield* createRenderer(settings, target);
});

Mobile currently means a browser/WebView-backed application; desktop means a browser, Tauri, or Electron-style surface. This is not yet a native React Native or Kotlin/Compose renderer. WebGL is the qualified path for this release. The Canvas backend remains experimental: its unit tests pass, but its shared visual baseline suite is not yet release-qualified.

Setup & Commands

# Install renderer + example dependencies
pnpm install

# Build Renderer
pnpm build

# Build Renderer (watch mode)
pnpm watch

# Run unit tests
pnpm test

# Run Visual Regression Tests
pnpm test:visual

# Build API Documentation (builds into ./typedocs folder)
pnpm typedoc

# Launch Example Tests in dev mode (includes Build Renderer (watch mode))
pnpm start

# Launch Example Tests in production mode
# IMPORTANT: To run test examples on embedded devices that use older browser versions
# you MUST run the examples in this mode.
pnpm start:prod

Browser Targets

The SolidTV Renderer's goal is to work with the following browser versions and above:

• Chrome v38 (Released October 7, 2014)

Any JavaScript language features or browser APIs that cannot be automatically transpiled or polyfilled by industry standard transpilers (such as Babel) to target these versions must be carefully considered before use.

For a more detailed and comprehensive list of browsers and their features please see browsers.

For renderer-level frame pacing, cheap cached fades, and shader warm-up on TV hardware, see Embedded UI Performance.

Example Tests

The Example Tests sub-project define a set of tests for various Renderer features. This is NOT an automated test. The command below will launch a web server which can be accessed by a web browser for manual testing. However, many of the Example Tests define Snapshots for the Visual Regression Test Runner (see below).

The Example Tests can be launched with:

pnpm start

This supports modern browsers as well as Chrome 38 and above through a legacy build.

See examples/README.md for more info.

Visual Regression Tests

In order to prevent bugs on existing Renderer features when new features or bug fixes are added, the Renderer includes a Visual Regression Test Runner along with a set of certified snapshot files that are checked into the repository.

These tests can be launched with:

pnpm test:visual

The captured Snapshots of these tests are optionally defined in the individual Example Tests.

See visual-regression/README.md for more info.

Manual Regression Tests

See [docs/ManualRegressionTests.md].

Release Procedure

See RELEASE.md

Installing Fonts

Fonts can be installed into the Font Manager exposed by the Renderer's Stage. There are two types of fonts that you can install, Web/Canvas2D fonts (WebTrFontFace) and SDF fonts (SdfTrFontFace). Install that fonts that your applications needs at start up so they are ready when your application is rendered.

import { RendererMain } from '@get-air/renderer';

import { WebGlCoreRenderer, SdfTextRenderer } from '@get-air/renderer/webgl';
import { CanvasTextRenderer } from '@get-air/renderer/canvas';

const renderer = new RendererMain(
  {
    appWidth: 1920,
    appHeight: 1080,
    renderEngine: WebGlCoreRenderer,
    fontEngines: [SdfTextRenderer, CanvasTextRenderer],
    // ...Other Renderer Config
  },
  'app', // id of div to insert Canvas.
);

// Load fonts by explicitly specifying the renderer type
await stage.loadFont('canvas', {
  fontFamily: 'myWebFont',
  fontUrl: '/fonts/my-font.ttf',
});

await stage.loadFont('sdf', {
  fontFamily: 'mySdfFont',
  atlasUrl: '/fonts/my-font-atlas.png',
  atlasDataUrl: '/fonts/my-font-data.json',
});

For more information see Font Loading

Migration Guide

Upgrading from Lightning 3 v2.x? See the Migration Guide for detailed information about breaking changes and how to update your code.