Threejs 3d sdk

Three.js 3D SDK

Build the smallest professional 3D system that satisfies the measured scene. Keep reusable rendering mechanics free of product and domain semantics.

Start from evidence

1. Read the nearest repository guidance and inspect the package manager, manifests, lockfile, build, tests, and installed three revision.
2. Trace the real path from input data or assets through scene construction, transient state, frame scheduling, rendering, interaction, and disposal.
3. Run node scripts/audit-three-project.mjs <project-root> for a fast lead map. Verify every reported lead in source; the script does not establish behavior.
4. Resolve APIs from the installed package exports and matching official Three.js documentation first. Then check release notes and the migration guide. Use format or platform specifications for interoperability claims and the owning library's documentation for optional dependencies. Never use a sharing article to establish an API signature.
5. Read references/coverage-index.md, then use references/capability-map.md to route the request to the smallest correct capability set.
6. Read references/scene-assessment.md and produce a decision record before proposing architecture or editing production code.

Separate verified facts, assumptions, constraints, failed premises, and verification targets. Ask before expensive profiling, paid assets or services, external writes, deployment, or visible browser control unless already authorized.

Route capabilities quickly

Use this sequence for every task:

1. Identify the observable result: render, model, load, animate, simulate, interact, edit, export, stream, diagnose, or recover.
2. Select the default in references/capability-map.md; escalate only when its stated trigger is present.
3. Open only the task-specific reference and live documentation for the installed revision.
4. Implement one lifecycle-complete closure and retain typed access to the underlying Three.js objects.
5. Run the validation listed for that capability plus the shared gates in references/validation.md.

Do not load an optional library merely because it appears in the source notes. First prove the missing capability or measured bottleneck, then verify version compatibility, module side effects, worker/CSP requirements, bundle cost, license, disposal, and fallback.

Select the scene strategy

Choose from measured requirements, not fashion:

• Use on-demand rendering for mostly static scenes; use a continuous loop only for persistent animation, simulation, XR, or time-dependent shaders.
• Use ordinary meshes for independently changing objects, InstancedMesh for one geometry/material with many transforms, and BatchedMesh or merged geometry for compatible heterogeneous geometry. Preserve stable logical-id mappings for interaction.
• Use WebGLRenderer for mature WebGL 2 compatibility and existing GLSL or EffectComposer pipelines. Treat WebGPURenderer, node materials, and TSL as a separately verified architecture while the official guide calls the renderer experimental.
• Prefer glTF 2.0 for runtime models. Treat geometry compression, texture compression, baking, LOD, streaming, and decoding as an offline/runtime asset pipeline with explicit compatibility tests.
• Add dynamic shadows, transparency, post-processing, high pixel ratio, GPU picking, spatial indexes, workers, or custom shaders only when the scene and evidence require their cost.

Use the matrices in references/scene-assessment.md for model viewer, editor, technical drawing, dense repeated geometry, streaming world, full-screen shader, and XR scenarios.

Freeze SDK boundaries

Read references/sdk-architecture.md before creating or changing reusable wrappers.

Keep these contracts explicit where applicable:

• renderer backend and capability contract;
• scene/world ownership and coordinate, unit, layer, and precision conventions;
• frame source, update phases, invalidation reasons, delta-time policy, and error behavior;
• asset request, progress, cancellation, cache key, decode, ownership, and release semantics;
• camera pose, controls, fit/framing, resize, and projection semantics;
• picking result, logical identity, hover/selection/drag gesture arbitration, and accessibility bridge;
• plugin identity, dependencies, order, setup, frame hooks, failure isolation, and reverse-order teardown;
• requested renderer, actual backend, capability/limit snapshot, asynchronous readiness, diagnostics, context/device-loss behavior, and quality degradation policy.

Keep product data and rules outside the SDK. Map them through project adapters into geometry, material, transform, visibility, identity, and interaction contracts. Never place project names, product vocabulary, or domain decisions in the global kernel.

Avoid a giant facade that mirrors all of Three.js. Expose the underlying Three.js objects as typed escape hatches, while owning only the lifecycle and guarantees the SDK declares.

Implement minimal closures

1. Establish renderer, scene, camera, resize, frame scheduling, failure handling, and teardown first.
2. Add one independently verifiable rendering closure at a time: geometry, asset, interaction, effect, streaming, or diagnostics.
3. Keep immutable source data separate from transient interaction state and derived visual state.
4. Batch writes, mark the matching buffer attributes dirty, recompute affected bounds, and update only changed instances or ranges.
5. Use generation tokens or abort signals for asynchronous scene or asset replacement. Build into staging state and commit only the current generation.
6. Track resource ownership at creation or acquisition time. Do not dispose a shared geometry, material, texture, render target, control, or renderer until its owning scope releases it.
7. Remove listeners, observers, frame callbacks, timers, workers, GPU queries, controls, passes, render targets, resources, and DOM overlays symmetrically.

Read the task-specific references:

• Complete public-capability routing and live API resolution: references/coverage-index.md
• Fast routing across rendering, modeling, assets, animation, interaction, effects, editors, XR, debugging, and recovery: references/capability-map.md
• Renderer lifecycle, cameras, viewports, targets, readback, scene composition, and frame submission: references/runtime-rendering.md
• Geometry, curves, lines, text, sprites, helpers, measurements, and procedural work: references/modeling-drawing.md
• Clips, actions, mixers, skeletal animation, morph targets, skinning, and deformation: references/animation-deformation.md
• Camera, projection, controls, picking, gestures, and state-to-visual mapping: references/interaction-camera.md
• Models, loaders, color, PBR, lighting, shaders, effects, and backend migration: references/assets-materials-effects.md
• Image, compressed, data, array, 3D, depth, canvas, video, and external textures: references/textures-data-media.md
• Format selection, addon loaders and exporters, validation, and round trips: references/extended-io.md
• Points, particles, sprites, volume data, simulation, and GPU-driven drawing: references/particles-volumes.md
• WebGPU renderer, node materials, TSL, render pipelines, storage, compute, and readback: references/webgpu-tsl-compute.md
• XR, audio, CSS/SVG renderers, workers, OffscreenCanvas, and physics adapters: references/platform-specialized.md
• Draw-call strategy, LOD, scheduling, profiling, ownership, disposal, and recovery: references/performance-lifecycle.md

Use the SDK starter

Create a clean TypeScript SDK package only after the contracts are decision-complete:

node scripts/scaffold-sdk.mjs <target-directory> --name <package-name> --three-range <project-three-range>

The script refuses non-empty targets and never overwrites files. The starter supplies a small runtime, render-driver boundary, coalesced frame scheduler, dependency-checked plugin registry, explicit disposable scope, pointer normalization, and WebGL diagnostics. Extend it in the target project; do not turn the global starter into a project-specific framework.

Verify at the changed boundary

Read references/validation.md. Record every applicable gate as PASS, FAIL, BLOCKED, NOT_RUN, or NOT_APPLICABLE with a reason.

At minimum:

1. Run typecheck, lint, focused tests, direct package build, and the original failing path plus a nearby non-failing path.
2. Render representative success, empty, loading, partial, error, resize, high-DPI, and cleanup states where applicable.
3. For visual or interaction changes, compare rendered evidence with the approved design across required viewports and input methods.
4. Measure CPU frame time, GPU frame time when available, input latency, draw calls, primitives, active resources, asset/decode time, and memory trend against the frozen budgets.
5. Exercise repeated mount/unmount or scene replacement, cancellation, context loss/restoration, and degradation/rollback where applicable.

A lower-level pass never overrides a missing visual, integration, performance, compatibility, or lifecycle gate.

Deliver the development proposal

Lead with:

1. recommended strategy and why it fits the measured scene;
2. controlling evidence, assumptions, constraints, and explicit non-goals;
3. renderer, scene, asset, interaction, extension, ownership, and diagnostics contracts;
4. minimal verifiable implementation closures and dependency order;
5. normal, edge, failure, compatibility, performance, visual, accessibility, and recovery acceptance;
6. alternatives rejected with concrete tradeoffs;
7. gate ledger, blockers, and decisions still required.

Use references/source-notes.md to rank source authority and trace pattern provenance. Recheck live official sources for consequential or drift-prone decisions.