Flight

Flight is a modular TypeScript SDK for building interactive applications — designed to be read and written by AI coding agents as well as people. Its more than 150 tree-shakable packages span 2D and 3D graphics, physics, animation, media, input, asset formats, application lifecycle, and desktop/mobile platform APIs.

The API is cellular: explicit passes over plain data, self-identifying names, clear ownership, and no work at import time. A function can be understood in isolation; an application can import one capability without inheriting an engine. Those same properties keep the codebase grepable for agents, portable to compiled targets, and small in production builds.

Build a scene once and choose a renderer — Canvas 2D, DOM, WebGL 2, or WebGPU — by registering only the implementations it uses. Compose the same small primitives into a game, visualization, media experience, desktop tool, or mobile application.

Try It

See Flight render its own live introduction, browse the examples gallery, compare ports from established frameworks, or run the gallery locally:

npm install
npm run examples

Getting Started

npm install @flighthq/sdk

Create a display-object scene, register the renderer kinds you use, update the render graph, then draw:

import { webCanvasRenderSurfaceCreator } from '@flighthq/host-web';
import {
  addNodeChild,
  beginCanvasRenderPass,
  createCanvasElement,
  createCanvasRenderState,
  createCanvasRenderSurface,
  createCanvasScreenRenderTarget,
  createCanvasTextureResolvers,
  createDisplayObject,
  createSprite,
  createTexture,
  canvasSpriteRenderer,
  endCanvasRenderPass,
  getCanvasRenderStateTextureResolvers,
  loadImageResourceFromUrl,
  prepareScene2DRender,
  registerCanvasImageTextureResolver,
  registerNodeRenderer,
  renderCanvasScene2D,
  scene2DCanvasPipeline,
  SpriteKind,
} from '@flighthq/sdk';

const pixelRatio = window.devicePixelRatio || 1;
const canvas = createCanvasElement(webCanvasRenderSurfaceCreator, 550, 400, pixelRatio);
document.body.appendChild(canvas);

// Where the frame lands is a render target; how it is drawn is the render state. They are separate
// values, joined for the duration of a pass.
const screen = createCanvasScreenRenderTarget(
  createCanvasRenderSurface(webCanvasRenderSurfaceCreator, canvas, {
    height: canvas.height / pixelRatio,
    pixelRatio,
    width: canvas.width / pixelRatio,
  }),
);
const state = createCanvasRenderState(
  scene2DCanvasPipeline,
  createCanvasTextureResolvers(webCanvasRenderSurfaceCreator),
  { sceneGraphSyncPolicy: 'requiresInvalidation' },
);
// The background is what the pass clears to — a per-pass colour in linear float RGBA, not a field the
// render state carries around.
const screenClear = { color: [0xee / 0xff, 0xdd / 0xff, 0xcc / 0xff, 1] } as const;

registerCanvasImageTextureResolver(getCanvasRenderStateTextureResolvers(state));
registerNodeRenderer(state, SpriteKind, canvasSpriteRenderer);

const root = createDisplayObject();
root.scaleX = pixelRatio;
root.scaleY = pixelRatio;

const sprite = createSprite();
const image = await loadImageResourceFromUrl('assets/wabbit_alpha.png');
sprite.data.texture = createTexture({ dimension: '2d', source: image });
addNodeChild(root, sprite);

function enterFrame(): void {
  if (prepareScene2DRender(state, root)) {
    const pass = beginCanvasRenderPass(state, screen, screenClear);
    renderCanvasScene2D(pass, root);
    endCanvasRenderPass(pass);
  }

  requestAnimationFrame(enterFrame);
}

enterFrame();

The same scene renders through DOM, WebGL2, or WebGPU by creating the matching render state and registering that backend's renderers — no change to the scene graph itself. The display objects stay plain data; backend work remains explicit.

Animation

The application package provides a request-animation-frame loop with typed update and render signals. Host implementations are explicit; in a browser, pass the web host when starting the application:

npm install @flighthq/host-web

import { webHost } from '@flighthq/host-web';
import {
  connectSignal,
  createAppLoop,
  createTween,
  createTweenManager,
  easeOutElastic,
  invalidateNodeRender,
  startAppLoop,
  updateTweens,
} from '@flighthq/sdk';

const manager = createTweenManager();

const tween = createTween(manager, sprite, 1000, { x: 400, alpha: 0 }, { ease: easeOutElastic });
connectSignal(tween.onUpdate, () => invalidateNodeRender(sprite));

const app = createAppLoop();
connectSignal(app.onUpdate, (delta) => updateTweens(manager, delta));
connectSignal(app.onRender, () => {
  if (prepareScene2DRender(state, root)) {
    const pass = beginCanvasRenderPass(state, screen, screenClear);
    renderCanvasScene2D(pass, root);
    endCanvasRenderPass(pass);
  }
});

startAppLoop(webHost, app);

Interaction

Wire up pointer events on any scene node. Register a hit-test strategy once, then create an interaction manager and connect it to the input system:

import {
  attachPointerInput,
  connectInputToInteraction,
  connectInteractionSignal,
  createInputManager,
  createInteractionManager,
  invalidateNodeRender,
  registerDefaultHitTests,
  setNodeHitTestEnabled,
} from '@flighthq/sdk';

registerDefaultHitTests();
setNodeHitTestEnabled(sprite, true);

const interaction = createInteractionManager(root);
const input = createInputManager();
attachPointerInput(input, canvas);
connectInputToInteraction(input, interaction, pixelRatio);

connectInteractionSignal(interaction, sprite, 'onPointerDown', () => {
  sprite.alpha = 0.5;
  invalidateNodeRender(sprite);
});
connectInteractionSignal(interaction, sprite, 'onPointerUp', () => {
  sprite.alpha = 1;
  invalidateNodeRender(sprite);
});

Sound

Load an audio resource with fallback formats, then play it:

import { loadAudioResourceFromUrls, playAudioResource } from '@flighthq/sdk';

const audioContext = new AudioContext();
const sound = await loadAudioResourceFromUrls(audioContext, [{ url: 'assets/click.ogg' }, { url: 'assets/click.mp3' }]);

connectInteractionSignal(interaction, sprite, 'onPointerDown', () => {
  playAudioResource(audioContext, sound);
});

Rendering Model

Flight separates authored data from backend work:

1. Build a graph from display objects, sprites, text, shapes, tilemaps, particles, or 3D scene nodes.
2. Create a backend render state for Canvas 2D, DOM, WebGL2, or WebGPU.
3. Register only the renderers and effect backends the scene needs.
4. Run the explicit prepare/update pass.
5. Draw through the selected backend.

Canvas and DOM are lightweight host-web paths. WebGL2 and WebGPU add GPU render targets, cached pipelines, shader/material registries, post-processing, clipping, masking, velocity, render caches, 2D batching, and 3D forward renderers with a 20-material Cook-Torrance PBR + classic/NPR/debug shader library.

Platform Scope

Flight currently spans more than 150 independently importable, publishable packages. The public API can be inspected with:

npm run api
npm run api -- --json

Major areas:

All packages are published under @flighthq/. Applications and examples usually import from @flighthq/sdk:

import { addNodeChild, createBitmap, createShape } from '@flighthq/sdk';

Library code should prefer the smallest package root that provides the needed API:

import { createTween, updateTweens } from '@flighthq/tween';

Platform Host values are explicit. Browser applications pass the ready-made webHost or the narrow webHost* values they need; Tauri and Capacitor applications construct tauriHost or capacitorHost from their injected native APIs. The application-facing API remains stable across those hosts.

Engineering Confidence

Flight is pre-release software, so confidence comes from the engineering path behind each change. Code changes are exercised by two unit-test lanes, a full TypeScript build, package and public-API validation, bundle-size budgets, and browser-render smoke and parity checks across DOM, Canvas, WebGL, and WebGPU. Nightly runs add coverage thresholds and generated API-surface checks.

main is a machine-managed known-good pointer: it advances only to commits whose CI run succeeded. Version releases verify that exact tagged commit passed CI before publishing the complete package graph to npm with provenance.

The repository also keeps reliability concerns visible in the design: imports are side-effect-free, feature families use explicit registries, resource ownership and allocation are named, format importers report structured diagnostics, source stays inside a checked compiled-target-portable subset, and render output is tested across interchangeable backends.

Examples

The gallery includes focused examples for shapes, text, interaction, animation, tilemaps, particles, collision, application flow, audio/video, file-format loading, and 3D scenes covering materials, picking, and fire. Where a capability is shared, the gallery lets you switch the same scene among supported renderers.

Build a specific example:

npm run build --workspace=examples/packages/shapes

Run a renderer-specific example dev server:

npm run dev:canvas --workspace=examples/packages/shapes
npm run dev:dom --workspace=examples/packages/shapes
npm run dev:webgl --workspace=examples/packages/shapes
npm run dev:webgpu --workspace=examples/packages/scene3d

Repository

git clone https://github.com/flighthq/flight.git
cd flight
npm install

packages/      Workspace packages published as @flighthq/*
examples/      Standalone Vite example apps
conformance/   Import fixtures and structured conformance checks
tools/         Gallery, functional scenes, capture harness, and repo utilities
scripts/       Validation, API, coverage, ordering, size, and build scripts

Useful checks:

npm run check              # package, type, API, export, portability, docs, and style gates
npm run test               # unit tests across all packages
npm run size               # gzip output size against committed budgets
npm run test:smoke         # fail on browser/runtime/render errors
npm run test:parity        # compare output across render backends
npm run test:regression    # compare output against committed fingerprints