BUILD: single-file Three.js diorama. One ultra-detailed cherry blossom bonsai in
a tokonoma alcove. Macro scale, museum lighting, Japanese interface design done
with restraint. This is a quiet piece, not a spectacle. The bar is "a still
frame is indistinguishable from a product photograph, and the UI looks like it
was designed by someone who has actually read Kenya Hara."
=== HARD CONSTRAINTS ===
One .html file. No build step, no bundler.
three r170 via importmap (CDN ESM). Addons allowed from the same version.
ZERO external assets. Every mesh, texture, LUT, font fallback and sound
generated in code. No CDN fonts, no data-URI blobs pasted in.
No truncation, no TODOs, no "// rest of implementation here". Ship the file.
UPPERCASE section header comments dividing the file.
Desktop 60fps, working mobile path.
Report at the end: tri count, draw calls, techniques.
=== SCALE ===
Tree ~45cm tall. Pot ~35cm wide. Camera 0.4m to 2m out. Near plane 0.02, far
plane 20. Single frustum: at this depth range there is no precision problem and
no reason for split cameras or log depth. Spend the entire budget on surface
detail, because at macro distance every surface is a hero surface.
=== THE TREE (this is 70% of the work) ===
Species: Prunus incisa 'Kojo-no-mai', the fuji cherry, which is what an actual
sakura bonsai is. Not somei yoshino, which does not reduce.
Style: moyogi (informal upright) with real movement, or shakan (slanting).
Never a straight trunk. The trunk should change direction 3 or 4 times, each
turn tightening as it rises.
NEBARI: surface root flare spreading radially into the soil. This is the
single strongest signal of an old bonsai and it is what everyone omits.
Roots emerge visibly, radiate outward, taper into the akadama.
TAPER: aggressive. Trunk caliper at nebari to apex should drop by 10x or more.
A cylinder reads as a stick with flowers on it.
RAMIFICATION: fine division at the tips, 2 or 3 branchlets per node, 5 or 6
orders deep. Age lives in the twigs, not the trunk.
Kojo-no-mai grows in ZIGZAGS. Twigs change direction at each node. Build this
into the skeleton generator, it is free character.
PAD STRUCTURE: flowers and twigs mass into discrete horizontal pads with real
negative space between them. You should see sky through the tree. A solid
pink blob is the failure state.
Bark: fissured, with horizontal lenticels, moss in the crotches, healed
pruning scars, faint wire spiral marks on one or two older branches. At this
distance use real displacement or parallax occlusion, not a normal map alone.
Blossoms: 2500 to 6000, not 80k. Each one is on screen at 2cm across, so build
a real flower: 5 notched petals, visible stamens, sepals, a bud state, a
spent-and-browning state on a few percent. Per-instance hue jitter white
through pale pink, per-instance open amount.
Blooms before leaf-out. A handful of bronze new leaves at most.
=== POT, SOIL, STAGING ===

Glazed stoneware pot, shallow oval or soft rectangle, pale celadon or cream
with crazing and pooling in the recesses. Feet, a proper lip profile, wire
tie-down holes, visible drainage mesh.
Soil: instanced akadama granules, angular and red-brown, mixed pumice.
Moss: shell layers or instanced strands, two colour populations, thicker at
the pot edge and the nebari crotches.
Fallen petals on the soil, the pot rim, the stand and the floor.
TOKONOMA: raised wooden floor, pale clay back wall, dark lacquered display
stand (shoku), a hanging scroll (kakejiku) with a single ink gesture, tatami
edge in frame. A low accent plant (kusamono) offset to one side.
ASYMMETRY IS MANDATORY. Never centre the tree in the alcove or the frame.
=== LIGHT ===

Key: daylight through a shoji screen off to one side. Large area source, soft
wrap, subtly cool. This one choice carries the entire Japanese read.
Bounce: warm reflection off tatami and wood into the shadow side.
Build the environment analytically (shoji panel + wall + floor as emissive
areas), bake to a small cube, and project to SH9 on the CPU for ambient. Same
integral drives the key colour. No PMREM: no GPU readback, works headless.
PETAL TRANSLUCENCY. Wrap plus back-transmission with a red shift, so blossoms
between the camera and the shoji glow and the ones facing you stay matte.
Position the default camera so a good number of blossoms are backlit.
Soft shadows with contact hardening. At 45cm the penumbra from a window is
wide and soft, and twig shadows on the soil should be nearly diffuse while
the nebari contact shadow stays tight.
Optional single warm practical (paper lantern) for the night preset.
=== ANIMATION ===
Restraint. This is air moving in a room, not weather.
One global breath field, sum of sines plus curl noise, very low amplitude,
long period. Everything samples it.
Vertex-shader sway weighted by distance from nebari and branch order. Tips
move a few millimetres. The trunk does not move at all.
Occasional single petal releases and falls: tumble plus glide on a slow
descending spiral with a phase-flipped face normal so it flashes as it turns.
One petal falling well beats a hundred falling badly.
Petals land and stay. Accumulate over the session.
Camera: slow drift with handheld noise, plus damped orbit constrained to the
alcove (you can circle the tree, you cannot fly through the wall).
=== MACRO OPTICS AND POST ===
90mm-equivalent macro. Aperture control from f/2.8 to f/11 that actually
changes the CoC. Thin focus plane, visible falloff across the pot.
Bokeh with a real iris shape and highlights that resolve into discs, not
gaussian mush. Blossom specular in the out-of-focus foreground is the shot.
Focus pull on interaction and a rack-focus preset.
ACES filmic, exposure solved per lighting preset from measured luminance.
Hand-rolled dual-filter bloom, threshold driven from exposure.
Halation on petal highlights, fine grain applied AFTER the transfer curve and
weighted to midtones, light vignette, near-zero chromatic aberration.
TAA or 2x supersample. Twig geometry at this density crawls without it.
=== UX AND FEEL (first-class, not a control panel bolted on) ===
Design principles, in order: ma (negative space), restraint, asymmetry, one
accent colour used exactly once.
The screen is mostly empty. Default state shows the diorama and a single thin
vertical rail at one edge. Nothing else.
Palette: sumi black, washi off-white, three greys. Vermilion appears once,
on the active state only. No pink UI. No gradients.
Paper: a generated washi grain and a faint deckle edge on panel surfaces.
Generate the texture in code to a canvas, no image files.
Type: system Japanese stack (Hiragino Mincho, Yu Mincho, Noto Serif JP) with
a serif latin fallback, and it must still look correct when none are present.
Labels are kanji with small romaji beneath: 光 hikari, 風 kaze, 花 hana,
時 toki, 景 kei, 音 oto.
One vertical-writing label group using writing-mode: vertical-rl.
Motion: panels slide like fusuma from one edge, one at a time, never stacked.
Easing cubic-bezier(0.22, 0.61, 0.36, 1), 450 to 700ms, long tail, NO bounce
and no spring overshoot. Everything decelerates into place.
Presets named by time: 朝 asa, 昼 hiru, 夕 yugure, 夜 yoru. Changing preset
cross-fades the light over about 2 seconds rather than cutting.
Photo mode (撮): all UI fades out, a hairline framing guide fades in, one
keypress or long-press to enter and exit.
Loading: a single sumi brush stroke drawn once, or an ink dot blooming into
the paper. No spinner, no progress bar, no percentage.
BANNED, because they are what "Japanese-inspired" usually degrades into:
sakura-pink background gradients, emoji, glassmorphism, neon, torii icons,
brush-script latin fonts, drop shadows on everything, rounded pills.
=== AUDIO (optional, off by default, one toggle) ===
Synthesized only. Room tone, a suikinkutsu water drip at irregular intervals,
a furin chime that rings only when the breath field peaks. Quiet enough that
the toggle feels like a decision, not a feature.
=== PERF ===
Instance everything: blossoms, granules, moss, petals. State a draw call budget
and hit it. DPR clamp. FPS governor that walks render scale, then shadow
resolution, then bloom quality, and never reduces blossom or twig count.
=== CARRY-FORWARD RULES (known failure modes, do not rediscover) ===
Swept-tube branches must start as a near-point ring buried inside the parent.
A bare tube has no cap, and every shallow-angle child shows a dark angular
wedge you can see straight into.
Sway displacement must be a function of world position and weight ONLY.
Never localT, branch depth or anchor: all three are discontinuous at exactly
the joint the mesh has to stay welded across. Weight continuity alone will
not save you. Compile the identical sway function into the bark, twig and
blossom shaders and assert that it references none of the three.
Bark lenticels and fissures author in tube UV space (u wraps, v runs along),
not world triplanar, so "horizontal" tracks the branch whichever way it points.
Chromatic aberration strength is in UV units. Clamp the sample UV or
clamp-to-edge smears the border texel into parallel streaks.
Bloom threshold in absolute radiance breaks at every exposure but the tuned
one. Derive it from exposure.
Grain before the transfer curve turns shadows into coloured confetti.
Encode linear view distance in every material's alpha channel. One buffer
then serves DoF CoC and any depth-aware upsample, with no prepass and no MRT.
=== VALIDATION ===
Before delivering:
Static GLSL pass over every composed ShaderMaterial: duplicate uniform,
varying and function declarations, redeclaration of three's injected builtins
(modelMatrix, position, instanceMatrix), attributes in fragment stages, brace
and paren balance, and any uXxx token with no declaration in that stage. This
catches chunk-assembly bugs no frame driver will.
Extract the module, shim three so math and geometry stay real but
WebGLRenderer, PMREMGenerator and post addons are stubbed. Stub the renderer's
render() to traverse and count visible meshes for a real draw-call number.
In Node, define navigator with Object.defineProperty, not assignment.
Drive a few thousand frames: no NaN in instance matrices, sway bounded,
fallen-petal pool recycles instead of leaking, camera stays inside the alcove,
shadow matrices finite, SH coefficients finite across all four presets.
Assert the exposure solve lands every preset within range rather than trusting
authored constants.
Report what you ran and what it found.
=== FAILURE MODES TO CHECK YOURSELF AGAINST ===
Solid pink canopy with no negative space. Straight tapered trunk. No nebari.
Flowers too small and too many, so it reads as noise. Pot that looks like a
cereal bowl. Centred composition. UI that is a dark translucent panel with
sliders. Wind that looks like outdoor weather indoors.