Stage3d: the three.js tier
The lazy three.js tier (decision 0017): loadThree() imports three only when a live 3D drawing is about to be seen, and resolves null if it cannot; webglAvailable(), liteDevice() and watchVisible() choose and pause the tier; the pure core chooses live, 2D or still, reprojects a photo with a depth map so a moving camera…
npx @susegad/cli add stage3d
The prompt
the prompt
The three.js tier: loaded late, and only when a live 3D drawing is about to be seen.
A small module every stage3d element uses to decide whether to draw live in 3D, draw in 2D, or show a still, and to load three.js only for the first. The maths it shares (reprojecting a photo with a depth map, fitting a camera window to any frame, a dolly path) is pure and tested in Node.
import { loadThree, webglAvailable, liteDevice, watchVisible, chooseTier } from 'susegad/stage3d/stage3d.js';
const tier = chooseTier({ webgl: webglAvailable(), motion: 'ambient', lite: liteDevice() });
const THREE = tier === 'live' ? await loadThree() : null; // null: draw the 2D still
The prompt
Make a small ES module that is the only place three.js enters a front-end library whose core has no dependencies. Load three with a dynamic import('three'), once, cached, and resolve null instead of rejecting when it is blocked, missing or throws, with one console warning that says what happened. Let a page swap the loader for a vendored copy. Test for WebGL2 once and release the test context. Treat Save-Data and 1 GB of memory or less as a lite device. Watch an element's visibility and the tab's, so a stage pauses off screen. In a separate pure module, choose the tier from what the device can do and what the reader asked for: reduced motion and the quiet register always draw in 2D and never download three; no WebGL, no three or a lite device draw in 2D; otherwise live; an explicit renderer attribute wins. Put the camera maths there too: map depth to distance linearly in inverse distance, put each photo point on the rest camera's ray so the rest view reproduces the photo exactly, compute the frustum window that covers any viewport like object-fit: cover while keeping a chosen point in view, and move the camera along a dolly path with a clamped pointer lean.
Then give it words in z-space (decision 0029): the type tier lays the lines, this tier only paints them. Turn a 3D object's silhouette on the screen into a shape for the type tier (a function of a band of lines, and a polygon descriptor for the text gate), and with the same lines make a textured quad for each line in the object's own scene and camera, so the words stand beside it with real depth. Draw each line's texture with the font string the layout measured, at the screen's density, again only when its text changes; ask the engine where it puts a baseline rather than computing it. The words stay in the page as real text, and a canvas only repeats them, never replaces them: their ink goes transparent only while the quads are on screen, and comes back the moment they are not (forced colours, a lost context, a failed load). Never import the type tier from here.
Words to code
| When you say | Technique | What happens |
|---|---|---|
| once, cached | a shared promise | loadThree() keeps one promise; setThreeLoader(fn) replaces the loader and resets it. |
resolve null instead of rejecting | fail soft | The loader's rejection is caught; the element reads null and builds the 2D renderer. The sg-tier event carries the reason. |
| never download three | tier choice | chooseTier({ motion: 'still' | 'state' }) returns '2d' before anything else is considered. |
| on the rest camera's ray | reprojection | reproject(u, v, d, tanX, tanY) and projectPoint(); a test proves the round trip at rest. |
like object-fit: cover | frustum window | coverWindow(va, pa, tanY, { keep, overscan }) crops the long side and clamps the kept point so the window never leaves the photo. |
| a shape for the type tier | occlusion | extentIn, flowShape(col, extent, pad) (a function for layIntoShape), silhouetteOf(screen) (a polygon descriptor for shapeOf and the gate), hugFloat(screen, col) (a CSS float and shape-outside polygon for the still). Pure, occlusion.core.js; projectMeshes in occlusion.live.js reads a mesh's vertices through a camera. |
| words with depth | textured quads | createTextQuads(THREE, { scene, camera }) in text.live.js: set(plan, frame) for each line from quadPlan(lineBoxes(lines, col), …); one canvas texture per line, redrawn only when its key changes; visible for the caller to flip with the spans' ink. |
| one layout, two painters | line boxes | lineBoxes(lines, col) once; spanStyle for the DOM spans and quadPlan for the quads read the same boxes, so their texts and positions are the same by construction. |
Budget
stage3d.js 4.4 KB and stage3d.core.js 5.6 KB, budgeted apart from the dependency-free layers (decision 0017). three itself is recorded per story, as bundled.
The three.js tier (decision 0017). Core, engine, tokens and components never import three; a stage3d element does, through this module, and only when it will draw live.
Install
node <path-to-susegad-ui>/packages/cli/bin/susegad.mjs add depth-photo # brings stage3d with it
npm install # add wrote three 0.186.1 into package.json
susegad add puts three into your package.json for you (its manifest declares npmDependencies). It is pinned exactly: three changes its API most months.
Then either let your bundler resolve import('three'), or give the page an import map:
<script type="importmap">{ "imports": { "three": "/node_modules/three/build/three.module.js" } }</script>
Or load it from anywhere with setThreeLoader(() => import('/vendor/three.js')).
API
| Export | What it does |
|---|---|
loadThree() | three's namespace, loaded once; resolves null if it cannot load (one console warning). |
setThreeLoader(fn) | Replace the loader. |
webglAvailable() | WebGL2, tested once. |
liteDevice() | Save-Data, or 1 GB of memory or less. |
watchVisible(el, cb) | cb(visible) as the element enters and leaves the viewport or the tab hides; returns an unwatch. |
decoded(src) | An image loaded and decoded, as a fixed-size ImageBitmap (an <img> with a srcset can change size under a texture). |
chooseTier({ webgl, three, motion, lite, forced }) | 'live', '2d' or 'still'. Pure. |
depthToZ, reproject, projectPoint, coverWindow, cameraAt, follow, parseVec | The camera maths. Pure. |
Words in z-space
Pure (occlusion.core.js, text.core.js): extentIn, flowShape, rowsOf, silhouetteOf, hugFloat, cssPolygon (a silhouette in, a shape for the type tier out); lineBoxes, spanStyle, quadPlan, baselineOf, frameCovering, worldAt, frustumOf (line boxes and the camera arithmetic that puts a quad on the pixels its span occupies). Live (occlusion.live.js, text.live.js, loaded by dynamic import() on the live tier only): projectMeshes(THREE, camera, meshes, frame) and createTextQuads(THREE, { scene, camera }). The quads are pictures of words that are already in the page as real text: they repeat the DOM words and never replace them. None of these lays or measures a line; the type tier does (packages/type/README.md, "Words in z-space"). The veranda's turning pot is the worked example (scenes/veranda/matka-view.js).
The tiers
| Tier | When | Downloads three |
|---|---|---|
live | WebGL2, three loaded, motion allowed (warm or playful, no reduced motion), not a lite device | yes |
2d | quiet, reduced motion, Save-Data, 1 GB or less, no WebGL, three failed | no |
still | forced, or the images failed to load | no |
Bytes
A page with no live 3D pays nothing for three. packages/stage3d/stage3d.check.mjs proves it from the request log: scene pages, the docs home, and the depth photo in quiet, under reduced motion and without WebGL request nothing from /node_modules/three, and a control run on the live tier must see three requested.
What three costs when a page does use it, bundled and minified by esbuild 0.28.2 (measured on 29 September 2026 for the veranda staged in 3D):
| What is bundled | Minified | gzip | brotli |
|---|---|---|---|
import('three'), the whole module, as loadThree() does today | 745,430 B | 192,931 B | 156,241 B |
only the 16 names depth-photo.gl.js uses (WebGLRenderer, Texture, ShaderMaterial, PerspectiveCamera and the rest), tree-shaken | 529,357 B | 133,181 B | 109,570 B |
depth-photo.gl.js on its own, minified | 11,422 B |
WebGLRenderer carries most of three, so naming imports saves about 30%, not most of it. A page that ships the named-import bundle through setThreeLoader() gets the smaller figure. The tier's own code stays in its declared budget: stage3d 10,076 of 12,288 bytes, depth-photo 45,800 of 46,080.