Build "Harbor Jelly" — a single self-contained HTML file (no external requests, no libraries) that renders an interactive 3D diorama with WebGPU/WGSL: a small working container harbor set inside a square block of wobbly, translucent jelly sea, sitting on a paper studio backdrop. It belongs to a series called "Material Studies", so match that look: warm paper background, serif italic display title ("Harbor Jelly."), small uppercase eyebrow "MATERIAL STUDIES", a status pill top-right ("WebGPU · Live"), a frosted control panel on the right, and a "How to play" line bottom-left. English UI. Light theme only, by design.
THE BLOCK
- A 5.2 × 5.2 block seen from a 3/4 orbit camera. The ground and sea are cut flat at the block's sides, so you see candy-coloured soil strata in cross-section, and the sea's cut faces show everything underwater through the jelly.
- The water is a real-time linear shallow-water simulation on a staggered grid (heights at cell centres, velocities on faces) with a little surface tension, so it feels like jelly. Render it with refraction, absorption by depth, caustics projected onto the floor, light shafts, a Fresnel studio reflection, foam (wakes, splashes, a shoreline lace) and a bright meniscus on the cut edges.
- The whole block can be tipped by dragging its side. The water sloshes to the low side, the jelly shears and quivers, then it settles flat again.
THE HARBOR (layout)
- Along the back runs a vertical concrete quay wall, with rubber fenders, bollards, ladders, and mussels and weed crusting it below the waterline.
- Left part: a container terminal. A flat asphalt yard with painted lines, concrete strips with two crane rails, light towers, and a small terminal office. Hundreds of colourful containers are stacked in neat rows. Each is a ribbed steel box with door ends and darker corner posts, drawn as GPU instances in about ten liveries.
- Right part: an old stone fishing quay with a cobbled promenade, a corrugated fish-market shed and lamp posts. A timber pier stands on mussel-covered piles with cross-bracing, with two small fishing boats moored alongside.
- Behind it all, a town climbs a grassy hill: three rows of gabled houses in Nordic harbour colours (falu red, ochre, white, pale blue, mint, pink) with tiled or slate roofs, white-framed windows, doors and chimneys. There is a white church with a green copper spire, and some round trees.
- A rubble breakwater shelters the fishing harbour, with a concrete crown wall. Big rocks sit near the crest, smaller weedy ones tumble down under water. On its head stands a red-and-white banded lighthouse with a gallery and a glass lantern, whose lamp slowly turns.
- In the open basin: two small yachts swinging on their moorings (white hulls, coloured stripe, fin keels visible through the jelly, furled sails), yellow mooring buoys, and a green channel buoy, all bobbing on the waves.
- On the floor: pale sand with drifts of silt, weed tufts, stones, starfish, an old anchor with chain, a lost tyre.
THE SHIP'S DAY (fully automatic loop, about 100 s)
1. A small feeder container ship (navy topsides, red antifouling, white accommodation block at the stern with bridge wings, funnel with a yellow band, turning radar, visible propeller) lies alongside with containers on deck, 6 bays × 4 rows × 2 tiers.
2. Two ship-to-shore gantry cranes on the rails, one red and one blue, each with portal legs, a backreach with a machinery house, an A-frame with forestays, a hinged boom, a trolley with a hanging cab, and a yellow spreader on four wire falls. They lower their booms and swap boxes: unload from the tops of the ship's stacks into yard stacks, then load other boxes aboard. Every move is a smooth sequence: travel, trolley out, lower onto the box (tracking the ship's bobbing), latch, hoist, trolley across, lower, unlatch. Cranes never get closer than their leg width; an idle crane moves out of the other's way.
3. When the work is done the trolleys park, the booms swing up, and a tug comes round to the bow. The tug has a black hull, white and red superstructure, a tyre fender all round, a big bow fender, and puffs of funnel smoke. It passes a tow line and backs away, pulling the bow off the quay while the ship swings out. Then the line is cast off, the tug pivots on the spot and goes home, and the ship sounds her horn.
4. The ship sails a lap of the harbour along a smooth path, past the lighthouse. She rides the water on several sample points (heave, pitch, roll) and hands the displaced water back to the sim, so she leaves a real bow wave, wake and white water.
5. Meanwhile the tug goes out to a standby spot. When the ship stops off the quay, the tug noses in and pushes her sideways onto the fenders, with prop wash churning. Then it backs off, the booms come down, and the cranes start again.
- Keep everything collision-free (ship and tug vs. quay, breakwater, pier, yachts and buoy; no grounding). Check it with a headless node test.
LIFE
- Fish schools (mackerel, herring, small orange wrasse) as boids that stay in the water and under the hulls, scatter from fingers, splashes and moving ships, and come to food.
- Moon jellyfish: glassy pulsing bells with four pink rings, frilly oral arms and a fringe of tentacles. They drift with the water flow.
- Herring gulls (white body, grey mantle, black wingtips, yellow bill with a red spot). They circle, bank and glide, and land on perches: lamps, roof ridges, the church spire, the lighthouse gallery, the crane apexes, the ship's mast, the tug, the yachts' masthead. Perches on moving things move with them. They all take off when the horn sounds, and some dive at food.
- Steam puffs from the ship's funnel on the horn; tiny bubbles caught in the jelly.
CONTROLS (right panel; bottom sheet on phones)
- "Cast off" sends the ship early (cranes finish the box in hand). At sea the button becomes "Call her in" and hurries her home; it greys out while busy.
- "Horn" (also Space) plays a synthesized WebAudio ship horn: two low detuned sawtooth reeds a fifth apart, low-passed, starting only after a user gesture. It also blows steam and scatters the gulls.
- "Feed the fish" scatters pellets off the end of the pier; fish rush in and gulls swoop down.
- Tally: Boxes moved / Voyages / Fed. A ship status line ("Unloading 3 / 8", "Loading", "Booms up", "Tug coming", "Casting off", "At sea 40%", "Coming in", "Berthing"). A small activity meter.
- Flavour swatches change the water colour and strata: Sea glass (teal-mint), Blueberry (deep blue), Lime.
- Sliders: Firmness, Wave damping, Tide (±10 cm; the sea level, ships and floating things follow).
- Buttons: Reset, Pause, Sound on/off, Reset view.
POINTER INTERACTION
- Drag across the water to make waves (with a crosshair cursor).
- Drag the side of the block to tip it.
- Pick up an orange-and-white lifebuoy and throw it. Lifebuoys float flat on the waves, bounce off the pier, buildings and breakwater, and are shoved aside by the ship and tug.
- Drag empty space or right-drag to orbit; scroll or pinch to zoom.
- On phones: touch orbit, pinch zoom, and a collapsible bottom sheet for the controls.
RENDERING DETAILS
- Pipeline: shadow map → caustics pass → opaque scene (with a distance buffer) → back-face pass of the water → water pass over a copy of the scene → tone map + dither.
- Moving rigs are static vertex buffers whose vertices carry an object id; about 24 object transforms (position + quaternion) live in the uniform buffer. Cables are drawn with one end in each object's frame, so they stretch: crane falls, forestays, the tow line.
- Material kinds in the prop shader: matte paint, glass, gloss steel, roof tiles, timber grain, corrugated sheet (normal-perturbed ribs), dressed-stone masonry, rubber, rock, glowing lamps, swaying weed, and hulls with antifouling below a boot-top line.
- The jelly shear and squash wobble applies to everything inside the block.
QUALITY BAR
- Smooth on a laptop; simulation under about 2 ms per frame.
- A friendly fallback screen if WebGPU is missing or the adapter fails.
- No console errors, no page scroll. Respect prefers-reduced-motion.
- Ship it with a headless test of the choreography and a Playwright end-to-end test.
