Air Renderer

Air's cross-platform retained 2D renderer. The 0.1 compatibility line is pre-1.0 and may make breaking changes only in a new minor release.

A powerful 2D scene renderer designed for rendering highly performant user interfaces on browser-backed TV, mobile, and desktop surfaces. The async factory negotiates WebGPU, WebGL, and Canvas2D in caller-defined order.

It includes physical-device frame-pacing work, packed WebGPU instances, retained WebGL 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

Direct imports use the Air package name:

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

const { renderer, backend, failures } = await createRenderer(
  { backends: ['webgpu', 'webgl', 'canvas'] },
  'app',
);

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. WebGL remains the qualified TV path. WebGPU covers packed color/image quads, clipping, SDF text, render textures, hole-punch, and registered custom WGSL. Canvas remains the broad compatibility fallback.

Native BC, ETC2/EAC, and ASTC containers upload when their WebGPU device feature is enabled. Device loss gets one bounded WebGPU reconstruction using retained scene/resource state, then falls through to the configured WebGL/Canvas order.

Custom WebGPU shaders define air_fragment and pack up to sixteen numeric values per instance without allocating per-node GPU buffers:

import type { WebGpuShaderType } from '@get-air/renderer/webgpu';

const Fade: WebGpuShaderType<{ amount: number }> = {
  props: { amount: 1 },
  update: (props, _node, values) => {
    values[0] = props.amount;
  },
  fragment: `
    fn air_fragment(
      color: vec4f, uv: vec2f, node: vec2f, nodeSize: vec2f,
      custom0: vec4f, custom1: vec4f,
      custom2: vec4f, custom3: vec4f
    ) -> vec4f { return color * custom0.x; }
  `,
};

Backend-neutral descriptors from @get-air/renderer/shaders can be passed directly to stage.shManager.registerShaderType; the manager selects the active implementation once during registration.

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

Air targets current browser/WebView releases on desktop, Android phone, and Android TV. WebGPU is feature-detected and never required when fallback is enabled.

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

Use ?renderMode=webgpu, ?renderMode=webgl, or ?renderMode=canvas to force a backend during manual qualification.

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.