Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 21 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
name: CI

on:
push:
branches: [main]
pull_request:

jobs:
check:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v5
- uses: actions/setup-node@v5
with:
node-version: 24
cache: npm
- run: npm ci
- name: Type check
run: npm run typecheck
- name: Figure checks and flight-model test
run: npm run check
38 changes: 38 additions & 0 deletions .github/workflows/deploy.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,38 @@
# Deploy https://air.pla.ne from main (npm run deploy: build the site, upload it with wrangler). Needs the repository
# secrets CLOUDFLARE_API_TOKEN (Workers Scripts and Workers Routes edit, Zone read) and CLOUDFLARE_ACCOUNT_ID; without
# them the job is skipped. The link-preview images are captured in headless Chrome on SwiftShader (no GPU here).
name: Deploy

on:
push:
branches: [main]
workflow_dispatch:

concurrency:
group: deploy
cancel-in-progress: false

jobs:
deploy:
runs-on: ubuntu-latest
env:
CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
steps:
- name: Skip without Cloudflare credentials
if: env.CLOUDFLARE_API_TOKEN == ''
run: echo "CLOUDFLARE_API_TOKEN is not set; nothing deployed."
- uses: actions/checkout@v5
if: env.CLOUDFLARE_API_TOKEN != ''
- uses: actions/setup-node@v5
if: env.CLOUDFLARE_API_TOKEN != ''
with:
node-version: 24
cache: npm
- if: env.CLOUDFLARE_API_TOKEN != ''
run: npm ci
- name: Build and deploy
if: env.CLOUDFLARE_API_TOKEN != ''
env:
DRIVE_ANGLE: swiftshader
run: npm run deploy
25 changes: 25 additions & 0 deletions .github/workflows/release.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
# On a version tag (v1.2.0): build both single-file pages and attach them to a GitHub release, for use offline.
name: Release

on:
push:
tags: ["v*"]

permissions:
contents: write

jobs:
pages:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v5
- uses: actions/setup-node@v5
with:
node-version: 24
- run: npm run build
- name: Attach the pages to the release
env:
GH_TOKEN: ${{ github.token }}
run: |
gh release view "$GITHUB_REF_NAME" >/dev/null 2>&1 || gh release create "$GITHUB_REF_NAME" --generate-notes
gh release upload "$GITHUB_REF_NAME" a380/a380.html a380/a380-light.html --clobber
3 changes: 3 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -5,3 +5,6 @@ a380/dist/
a380/*-verify.html
*.log
.env
# the built single-file pages (npm run build); releases carry them
a380/a380.html
a380/a380-light.html
43 changes: 43 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,43 @@
# Contributing

Thanks for looking. Issues and pull requests are welcome: a wrong number, a light that behaves unlike the real
aircraft, a procedure out of order, a rendering glitch on your device, or a performance win.

## Getting started

```sh
npm install # dev tools only (TypeScript, Wrangler); the figure itself needs nothing installed
npm run build # a380/a380.html and a380/a380-light.html, about 25 s each
npm run check # the figure's checks and the flight-model test (CI runs these)
npm run typecheck # tsc over the files marked // @ts-check (CI runs this)
npm run site # the hosted one-page site in a380/dist, then `npm run serve` to try it on 127.0.0.1:8741
```

Open the built page in a browser; it runs from `file://`. The browser checks in `a380/README.md` (frame times,
captures, audits) need a local Chrome or Chromium; set `CHROME_PATH` if it isn't found.

## Where things live

- `a380/model.mjs`: the truth model. Every size, rate and rule the figure shows comes from here.
- `a380/truth.md`: where each of those numbers comes from.
- `a380/parts/`: the airframe, cabin, gear, lights and stage, as the build draws them.
- `a380/gl/`: the WebGL programs (`shaders.mjs` writes the GLSL) and the per-frame passes.
- `a380/live.js`: the page runtime: interaction, the flight phases, the readout.
- `a380/DESIGN.md`: the design and the decisions behind it. Decision 0 matters most: features are never removed to
meet a performance budget; find speed elsewhere.
- `kit/`: the drawing kit from the Anatomy skill, with the 3D turn runtime and the WebGL painter.

## Rules of the road

- **Sources.** A new number goes in `model.mjs` with a tag: `[S]` read from a cited document, `[D]` derived from
sourced numbers, `[E]` an estimate or a figure decision, with the reason. Add the source to `truth.md`.
- **Both themes, both painters.** A visual change should look right in the dark and light themes, and with WebGL off
(`?painter=canvas`, or a browser without WebGL): the fallback draws what the shaders draw.
- **Comments.** The code explains why in its comments; keep that voice and density.
- **Types.** New or heavily changed modules should start with `// @ts-check` and carry JSDoc on what they export.
- **Commits.** Use [Conventional Commits](https://www.conventionalcommits.org/): `fix(lights): …`, `perf(gl): …`,
`docs: …`. Rebuilt pages are not committed; releases carry them.

## Licence

By contributing you agree that your work is released under the MIT licence in [`LICENSE`](LICENSE).
21 changes: 21 additions & 0 deletions LICENSE
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
MIT License

Copyright (c) 2026 Charlie Joseph

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
24 changes: 17 additions & 7 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,24 +14,30 @@ self-contained web page.

## Try it

Open `a380/a380.html` (dark) or `a380/a380-light.html` (light) in a browser. Each page is a single file with no
network requests, for use offline. The hosted site (`node a380/tools/build-site.mjs`) is one page, `index.html`, with a
The live site is https://air.pla.ne. For use offline, download `a380.html` (dark) or `a380-light.html` (light) from
the [latest release](https://github.com/entity/pla.ne/releases/latest), or build them with `npm run build`. Each page is
a single file with no network requests. The hosted site (`node a380/tools/build-site.mjs`) is one page, `index.html`, with a
System / Light / Dark switch that changes the theme in place without losing the flight, the view or the turntable.

Controls: drag to turn · `1`–`7` flight phases · `C` cutaway · `D` doors · `I` / `Shift+I` close-up views ·
`Space` pause · `Esc` back. The full list is in [`a380/README.md`](a380/README.md).

## Build it

Requires Node.js 20.10 or later; there is nothing to install.
Requires Node.js 20.10 or later. The figure itself needs nothing installed; `npm install` adds only the
development tools (TypeScript for the type check, Wrangler for the deploy).

```sh
node a380/build.mjs # a380/a380.html
node a380/build.mjs --light # a380/a380-light.html
node a380/build.mjs --check # the figure's own checks
node a380/tools/build-site.mjs # a380/dist/: the one-page static site with the theme switch (a380/site/DEPLOY.md)
npm run build # a380/a380.html and a380/a380-light.html, the single-file pages
npm run check # the figure's own checks and the flight-model test
npm run typecheck # tsc over the files marked // @ts-check
npm run site # a380/dist/: the one-page static site with the theme switch (a380/site/DEPLOY.md)
npm run serve # serve a380/dist on http://127.0.0.1:8741/ the way a host would
npm run deploy # build the site and upload it to Cloudflare (wrangler.jsonc)
```

Each script is a plain `node` command (see `package.json`), so they also run without npm.

The audits and browser checks (headless Chromium) are described in [`a380/README.md`](a380/README.md).

## Layout
Expand All @@ -42,5 +48,9 @@ The audits and browser checks (headless Chromium) are described in [`a380/README
turn runtime and the WebGL painter (MIT, see `kit/LICENSE`).
- `scripts/`: headless-browser capture, drive and check scripts from the same skill.

## Licence

MIT, see [`LICENSE`](LICENSE). The drawing kit in `kit/` keeps its own MIT licence (`kit/LICENSE`).

Not affiliated with or endorsed by Airbus. Dimensions and procedures come from public Airbus and EASA documents;
values marked as estimates in `a380/truth.md` are estimates.
4 changes: 4 additions & 0 deletions a380/DESIGN.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,9 @@
# A380 figure: design (revision 2)

> References to `notes/` (status, audits, kit patches, the module contract, follow-up packages) point to the
> working notes kept while the figure was built. They are not part of this repository; the code and these
> documents carry the decisions that matter.

This is the design for `a380/a380.html` (dark) and `a380/a380-light.html` (light), written by
`node a380/build.mjs [--light]`. It replaces revision 1 after three critics' reviews (feasibility, fidelity, craft).
Every finding and how it was resolved is in §12. The work is done by these roles:
Expand Down
38 changes: 34 additions & 4 deletions a380/README.md
Original file line number Diff line number Diff line change
@@ -1,13 +1,18 @@
# Airbus A380-800 · Fig 1

> References to `notes/` (status, audits, kit patches, the module contract, follow-up packages) point to the
> working notes kept while the figure was built. They are not part of this repository; the code and these
> documents carry the decisions that matter.

An interactive, true-3D cutaway drawing of an Airbus A380-800 on a turntable, built with the Anatomy skill's 3D mode
(`kit/turn-build.mjs`, `kit/turn.mjs`) and WebGL (`kit/gl.mjs`) for every light, glow and effect. It is one
self-contained HTML page with no network requests:

- `a380/a380.html`: dark theme (night, the lights carry the picture);
- `a380/a380-light.html`: light theme (daylight; lenses read as glints, no bloom).

Both are written by `node a380/build.mjs` and work offline. The hosted site (`a380/tools/build-site.mjs`, see Host
Both are written by `node a380/build.mjs` (`npm run build`) and work offline. They are not kept in git; each GitHub
release carries them. The hosted site (`a380/tools/build-site.mjs`, see Host
below) is one page, `index.html`, with a System / Light / Dark switch that swaps the theme in place. Every size, rate and rule comes from `a380/model.mjs`, which is sourced
in `a380/truth.md` (Airbus airport-planning drawings, EASA type certificates, Airbus Safety First and the other
sources listed there). Numbers marked as estimates in the truth sheet are engineering estimates.
Expand Down Expand Up @@ -340,6 +345,28 @@ Before is the release at 02ab044 (its two pages and the redirecting index); afte
| `build.mjs --check`, `scripts/lines.mjs` | | check passed (both themes); line ends 0 of 630 float (both pages and the site page) |
| `site-check --layout` / `--nojs` | | passed, both themes, 320 × 568 to 1440 × 900 (44 px touch targets) |

### Measured: GL start-up (perf/gl-light-uniforms, 2026-10-12, forge, Radeon 8060S through ANGLE GL, headless Chrome)

The window pieces, wash targets and nacelles now draw from uniform tables set on each pass (one program a family, not
a function a piece with its numbers as literals), the drawn cockpit program no longer carries the build-constant passes,
and the runway, volumes and ground programs carry both themes' rules under `uLight`: every program is the same source
in both themes. Before is aa17152.

| | Before | After |
|---|---|---|
| Programs compiled; GLSL (payload `gl.effects` fragments, dark) | 25; 677 KB (632 KB compiled) | 10; 184 KB (139 KB compiled) |
| Sources differing between the themes | 5 programs | none |
| Uniform vectors, largest program | 99 | 167 (windows) |
| Cold load, `site-check --timing` medians, desktop: mounted / first light | 293 / 6,532 ms | 287 / 4,996 ms |
| Cold load, phone (390, 4× CPU, 4G): mounted / first light | 1,731 / 9,868 ms | 1,587 / 6,766 ms |
| Every program linked, after the mount (desktop, 3 runs); then the fade to glShare 0.999 | 2.24–2.41 s; 3.7 s | 0.98–1.06 s; 3.7 s |
| A switch (prefetched), dark to light at 1440: new figure / programs linked / lights whole | 0.15 / 1.59–1.62 / 5.35–5.39 s | 0.15–0.17 / 0.75–0.77 / 4.30–4.54 s |
| Parity (`--reduced`, paused, no dither; gate ×2, doors ×2, cutaway, Inspect Cockpit, Upper deck, Engine 2, push, taxi, line-up ×2, take-off ×2, climb; `png-diff` over 8 levels) | run against run: 0 px (max 8) | 0 px in 28 of 30 shots (max 8); dark doors b100 and Inspect Upper deck 4 px each (one 2 × 2 spot at a window edge, max 15 and 21) |
| `build.mjs --check` (both themes), `model-test`, `site-check --layout`, `?painter=canvas`, no WebGL | passed | passed; console clean |

After a switch the programs come from the browser's shader cache, but at one in flight they still take two frames
each; most of the switch's time to whole lights, and of first light, is now the fade.

## Measured: the finished figure (2026-10-11, 22:52–23:45 UTC)

The shipping pages and `a380/dist/` were checked against `main` at 5f7c95b (sources identical to 92d6ad6:
Expand Down Expand Up @@ -508,8 +535,11 @@ round's larger deck (2,463 live elements against 1,690). The Node frame is 0.1
(`jointCaps`) is not adopted yet; the pylon flank is a flat face, shaded flat. The intake lip's gradients use 2
pieces while the figure moves and 4 at rest (about 25–30% less lip draw time). A 1 px fin/rudder strip shows at 219°
(the fin's trailing-edge face passing edge-on).
- **Lights and WebGL.** First light takes 9–11 s under machine load: the 25 programs compile one at a time in the GPU
process (profiled; nothing in the page's code is left to cut). The heat haze is drawn in both themes with WebGL and
- **Lights and WebGL.** The 10 programs (perf/gl-light-uniforms: 25 before, 632 KB of GLSL now 139 KB) link about
1 s after the mount at 1440; most of first light is now the fade from the fallbacks to GL (`settle(glShare, 1, dt,
0.4)`, critically damped: half way in 0.65 s, at 0.999 after 3.7 s), which runs again after a theme switch. The
windows program holds 72 hull planes a pass: 167 uniform vectors (99 before), within the 221–224 of the smallest
common WebGL 1 limit but not of a 128-vector one. The heat haze is drawn in both themes with WebGL and
not at all without it. Without WebGL the night washes, pools, beams and runway lights are screen-blended as the GL
canvases are, and the lamp lenses use the GL mask's cover rule (the nose-strut lens blob at b10 is gone); still: each
beam is a flat banded shaft, the logo bands show faint contour seams at DPR 2, at DPR 1 the runway lights lack GL's
Expand Down Expand Up @@ -559,6 +589,6 @@ Features the figure does not have yet, each costed in `notes/followup/PLAN.md`
- `parts/` (stage, nose, fuselage, skin, wings, tail, engines, gear, cabin with `cabin-plan.mjs` and
`cabin-furniture.mjs`, lights, tug), `gl/` (shaders, passes, mask, runway);
- `tools/` (model test, stowed-gear test, the sharded full audit, path checks, captures);
- `DESIGN.md`, `truth.md`, `notes/` (status, audits, kit patches, GL and 3D cookbooks, the module contract).
- `DESIGN.md`, `truth.md`.
- Captures of the finishing round's merge are in `shots/f3-merge/` (each track's in `shots/f3/<track>/`), of the release in `shots/final-3/` and of the finished figure in `shots/final-4/` locally, those of the follow-up merges in `shots/sort-merge/`,
`shots/followup-ship/` and `shots/followup-merge-1/` (`a380/shots/` is not committed).
Loading
Loading