Web 3D

The gate — design-law still rules

Live 3D is a HERO MOMENT: at most ONE per page, serving the story, obeying the project's tokens (palette, lighting mood, restraint). A gratuitous spinning cube is anti-slop. prefers-reduced-motion, low-end mobile, and loading states all get a static webp poster — always ship the fallback.

Choose the tool (ladder — stop at the first rung that holds)

Spline embed (the fast path — this IS the integration; ignore "Spline MCP" servers, Spline has no public API)

React/Next.js: npm i @splinetool/react-spline @splinetool/runtime

import { lazy, Suspense } from 'react';
const Spline = lazy(() => import('@splinetool/react-spline'));
// inside the hero, below an IntersectionObserver or next/dynamic ssr:false:
<Suspense fallback={<img src="/poster.webp" alt="" />}>
  <Spline scene="https://prod.spline.design/<id>/scene.splinecode"
          onLoad={(app) => appRef.current = app} />
</Suspense>

Vanilla: new Application(canvas).load(url) from @splinetool/runtime. Control at runtime: app.findObjectByName('Cube') (then mutate .position/.rotation/.scale), app.emitEvent('mouseHover', 'Cube'), app.setVariable(name, value). Scene URL comes from the Spline editor → Export → Code Export. Community scenes: study technique, never copy paid assets.

R3F skeleton (the laws are in the props)

<Canvas dpr={[1, 2]} frameloop="demand" gl={{ antialias: true }}>
  <Environment preset="studio" />
  <MyModel /> {/* useGLTF('/model.glb') — drei caches + disposes */}
  <OrbitControls enableZoom={false} />
</Canvas>

frameloop="demand" for scenes that only move on interaction; drop it only for continuous animation. Threlte mirrors this: <Canvas> from @threlte/core, helpers from @threlte/extras (<GLTF>, <OrbitControls>).

Performance laws (non-negotiable)

• Lazy-load ALL 3D: dynamic import behind IntersectionObserver — never in the initial bundle.
• Clamp dpr to [1, 2]; one WebGL context per page.
• GLB budget < 2 MB: compress with npx gltf-transform optimize in.glb out.glb (draco + prune + resize).
• Dispose on unmount (drei/Threlte handle it; raw three.js: geometry.dispose(), material.dispose(), renderer.dispose()).
• Poster fallback (webp via asset-pipeline) for reduced-motion, mobile, and load — the page must read perfectly with 3D absent.

Scroll narrative composition

Use three depth planes at most: a slow atmospheric backdrop, the primary frame sequence or 3D subject, and crisp semantic copy/chrome. Map all planes to one normalized scroll progress; vary distance and easing instead of adding unrelated animations. Pin only while the scene advances, then return to normal document flow. Avoid scroll hijacking, wheel interception, and fake smooth-scroll latency.

Choose rendered frames for photoreal materials, fluid simulation, cinematic lighting, or model-heavy scenes that do not need object interaction. Choose live 3D only when the user must rotate, select, configure, or inspect the object. Never run live WebGL behind a full frame sequence. On mobile, reduce parallax, serve a deliberate crop, and shorten the pinned distance. Follow the detailed loading, poster, accessibility, and SEO contract in asset-pipeline.

Live-scene debugging (optional MCP companion)

Register npx threejs-devtools-mcp with the current host's MCP setup — inspects and edits a RUNNING three.js/R3F scene (59 tools, MIT) through a WebSocket bridge; needs the project dev server up. Offer with yes/no confirmation per bootstrap — useful only in 3D-heavy projects. Host integration: read the runtime contract for plugin/project paths, host command names and capabilities. Explicit user instructions and repository conventions take precedence over these defaults.