# Three Blocks Full Agent Context Last aligned with `three-blocks-monorepo` on 2026-07-07. This file describes the current package, CLI, starter, and site structure. It is intentionally not a copied v1 API mirror. Per-symbol generated API markdown should come later from `packages/docs-engine`; until then agents should treat this file as the canonical structural context and inspect package source when exact signatures matter. AI usage policy: this documentation may be used to help people integrate the PUBLIC `three-blocks` API. Inspecting locally installed package source to resolve exact signatures for a user's own project is fine; training on, reproducing, or re-deriving the implementation (npm `dist`, `/examples/static/**` sources, monorepo source) is not licensed — TDM rights reserved (EU 2019/790 Art. 4(3)). Full policy: the "AI Usage Policy" section of `/llms.txt`. ## Repository Shape ```text apps/ web/ Next 16 site, accounts, pricing, examples, tools, CLI/device-flow API packages/ three-blocks/ public npm: library + `three-blocks` CLI three-blocks-starter/ public npm: Vite starter template package create-three-blocks-starter/ public npm: scaffolder tokens/ ui/ motion/ config/ private design-system workspace packages ``` Planned docs-engine/example-pipeline work may add generated references later. Do not invent `packages/docs-engine` output if it is not present in the repo. ## Public Packages ### `three-blocks` Location: `packages/three-blocks` The library and CLI ship together. Package details: - npm name: `three-blocks` - version line: `0.1.0-beta.0` - license: PolyForm Noncommercial 1.0.0 - peer dependency: `three >=0.159.0` - current dev target: `three ^0.185.0` - CLI binary: `three-blocks` - package root export: import from `"three-blocks"` Install: ```bash npm i three-blocks three ``` Common import pattern: ```js import * as THREE from "three/webgpu"; import { Boids, GridPristine, MSDFText, SplatMesh, ComputeRadixSort, } from "three-blocks"; ``` Important: do not use retired names such as `@three-blocks/core` or `@three-blocks/pro`. ### `three-blocks-starter` Location: `packages/three-blocks-starter` This is the maintained Vite/WebGPU starter template. It is a real package, not a hidden private template. It uses `three-blocks`, `three`, an OffscreenCanvas worker architecture, template overlays, precompile tooling, and generated app guidance in `AGENTS.md`. Template manifest: - default template: `scroll` - `website` mode -> `scroll` template - `scene` mode -> `starter` template - `minimal` mode -> `minimal` template Generated projects include `src/`, `public/`, `assets/`, `.cursor`, `.github`, `scripts`, `vite-plugins`, `docs`, `AGENTS.md`, `three-blocks.json`, `vercel.json`, and a Vite build setup. ### `create-three-blocks-starter` Location: `packages/create-three-blocks-starter` Scaffolds from `three-blocks-starter`. Usage: ```bash npm create three-blocks-starter my-app npx create-three-blocks-starter my-app --mode website npx create-three-blocks-starter my-app --mode scene npx create-three-blocks-starter my-app --mode minimal ``` The main `three-blocks` CLI also wraps this: ```bash npx three-blocks starter my-app --mode website ``` Generated projects depend on public `three-blocks`. They do not need registry auth, `.npmrc`, CodeArtifact, or private package access. ## CLI Contract The `three-blocks` CLI is in `packages/three-blocks/src/cli`. Commands: ```bash three-blocks # interactive menu three-blocks starter [dir] # scaffold through create-three-blocks-starter three-blocks login # browser device flow three-blocks login --token tb_... # paste a credential three-blocks logout three-blocks whoami three-blocks token list three-blocks token revoke three-blocks doctor three-blocks install blender ``` Credential behavior: - Stored in `~/.three-blocks/credentials.json`. - Directory mode is tightened to `0700`; file mode is tightened to `0600`. - Credentials are keyed by site URL. - The CLI never writes `.npmrc`. - `TB_SITE_URL` changes the API host. - `THREE_BLOCKS_CONFIG_DIR` changes the credential store location. - `TB_NO_OPEN` prevents browser launch. API surfaces used by the CLI: - `/api/cli/device-code` - `/api/cli/authorize` - `/api/cli/token` - `/api/cli/tokens` - `/api/cli/tokens/[id]` - `/api/tools/validate` - `/api/tools/event` ## Library Areas These categories are exported from `packages/three-blocks/src/index.js`. Compute: - `ComputeBatchCulling` - `ComputeBitonicSort` - `ComputeBVHSampler` - `ComputeInstanceCulling` - `ComputeMeshDynamicSurfaceSampler` - `ComputeMeshSurfaceSampler` - `ComputePointsSDFGenerator` - `ComputePrefixSum` - `ComputeRadixSort` - `ComputeSDFGenerator` - `ComputeMipAwareBlueNoise` - SDF/BVH helper exports Addons and geometry: - `IndirectBatchedMesh` - raymarching helpers - `BirdGeometry` - `BoxNoFaceGeometry` - `TriangleGeometry` - `GridPristine` Text: - `MSDFFont` - `MSDFTextLayout` - `MSDFText` - `BatchedMSDFText` - related MSDF node materials and nodes - legacy `Text`/`BatchedText` runtime-SDF exports TSL and materials: - animation texture nodes - billboarding - biplanar/curl/fresnel/film/kuwahara/parallax/smoke/tensor helpers - `DeferredSurfaceNodeMaterial` - `MeshTransmissionNodeMaterial` - `RayMarchSDFNodeMaterial` - `RenderSDFLayerNodeMaterial` - `VolumeSmokeNodeMaterial` - `VolumeSmokeRenderCompositor` Simulation: - `Boids` - `Particles` - `SpatialGrid` - `BVHVolumeConstraint` - `PBF` - fluid helpers - `SDFVolumeConstraint` - `SmokeVolume` - `SPH` - GPU interaction layout/system/world helpers Gaussian splatting: - `SplatMesh`/`GaussianSplats` facade exports - loaders, helpers, materials, nodes - SOG/stream/video/sequence/clip helpers - compositor and compute-tile renderer Video/VAV: - `AFVideo` - `AFDecoder` - `AFContainer` - `VAVFrames` - `VAVManifest` - `VAVTrackStream` - `VAVNodes` - `VAVMesh` ## WebGPU Integration Rules Use `three/webgpu` when using WebGPU renderer, compute, simulation, TSL, splats, or culling: ```js import * as THREE from "three/webgpu"; const renderer = new THREE.WebGPURenderer({ antialias: true }); await renderer.init(); ``` Call `await renderer.init()` before: - compute passes - simulation steps - culling setup that touches GPU buffers - splat rendering setup - WebGPU texture/storage buffer workflows Agents should prefer clear setup order: 1. Create renderer, scene, camera. 2. Await `renderer.init()`. 3. Create Three Blocks systems. 4. Run compute/simulation updates before render. 5. Dispose GPU resources when replacing scenes or during HMR. ## Starter Architecture Notes Generated starter apps are WebGPU three.js apps with optional OffscreenCanvas worker rendering. Thread topology: ```text main thread worker index.html -> src/index.ts -> src/init.ts src/offscreen/offscreen.ts DOM events, loader, recording <-> renderer, scene, camera, demos ``` Rules: - Main thread code must not import `src/offscreen/store.ts`; use `src/shared/store.ts` for plain shared data. - Worker event payloads must be structured-cloneable. - Demos are component classes registered in the `DEMOS` map in `src/offscreen/site.ts`. - Use `?scene=` to open a demo. - Debug tooling requiring DOM needs main-thread mode. - `vite.config.ts` dedupes `three` and `three-mesh-bvh`; do not bundle multiple `three` copies. - Build and typecheck should stay green in generated apps. ## Licensing and Auth Boundary - `three-blocks`: PolyForm Noncommercial. Free for noncommercial use; commercial projects need Pro — per seat, and lifetime per project: projects started while a plan is active stay licensed forever (full terms: https://threejs-blocks.com/license). - `three-blocks-starter` and `create-three-blocks-starter`: MIT — every template, free, no account. - Library and starter installs are public and auth-free. - Pro tool + Blender addon access uses site credentials minted by `three-blocks login`; one seat per person. - Never tell a user to configure npm registry auth for installs. ## Agent Troubleshooting For setup or auth problems, run: ```bash npx three-blocks doctor ``` For a missing credential: ```bash npx three-blocks login ``` For a CI/headless credential: ```bash npx three-blocks login --token tb_... ``` For starter generation: ```bash npx three-blocks starter my-app --mode website cd my-app bun install bun run dev ``` For exact API signatures, inspect `packages/three-blocks/src/index.js` and the module source until generated docs-engine references exist. ## Examples Every live example at https://threejs-blocks.com/examples is documented on-site by the PROMPT that produces it (outcome language, no API names) — that is the user-facing contract. The technical notes below are the agent-facing side: what each example actually demonstrates, so you can map a user prompt onto the right blocks. Live page: https://threejs-blocks.com/examples/. ### WebGL - `webgl_tsl_fresnel` — TSL Fresnel Effect [WebGL, TSL]: Fresnel nodes add rim lighting using simple parameters. The torus knot material exposes power and falloff controls, recolors the emissive rim live, and shows how the fresnel helper slots into a MeshStandardNodeMaterial. - `webgl_animation_texture_object` — Object Animation Texture [WebGL, Text, Animation]: Animation textures drive object-level clips baked to textures. The scene loads GLTF parts and a baked mixer, assembles them into a single BatchedMesh, and plays the animation on all instances using GPU-sampled frames. - `webgl_postprocessing_filmhd` — Film HD Post-Processing [WebGL, Post FX]: FilmHD adds grain, scanlines, and blue-noise film response as a post pass. The bunny model is lit by an HDRI, rendered with node materials, then processed through the filmHD node with controls for intensity, scale, speed, and scanline frequency. - `webgl_postprocessing_smoke` — Smoke Post-Processing [WebGL, Post FX, Smoke]: Screen-space fluid postprocessing warps the final image with a 2D smoke sim. A spinning cube cluster is rendered to a pass, the smoke node evolves on top using pointer input for splats, and post uniforms control distortion, blend, and tint. - `webgl_shadow_filter` — Shadow Filter [WebGL]: Noise-filtered shadows soften hard map edges in WebGPU. Directional and spot lights cast animated shadows on a torus knot scene using the shadowMapFastNoise filter, showing smoother penumbrae without heavy kernel sizes. - `webgl_text_input` — Runtime Text [WebGL, Text]: The runtime Text primitive builds its SDF glyph atlas on the fly as you type — nothing is baked ahead of time. Characters entered in the overlay input update the mesh in real time, with GUI controls for typography, outlines, SDF stroke, and atlas debugging. This is the live counterpart to the pre-baked MSDF Text example. - `webgl_tsl_biplanar_uv` — TSL Biplanar UV Mapping [WebGL, TSL]: Biplanar and triplanar mapping avoid UV seams via TSL nodes. A spinning bunny switches between mapping modes, compares against basic UVs, and can visualize the difference heatmap while sampling a brick texture. ### WebGPU - `webgpu_compute_sampler` — Compute Sampler [WebGPU, Compute]: Compute surface sampling scatters instances directly on a mesh in GPU memory. Here a ComputeMeshSurfaceSampler populates a torus knot with up to 200k cubes, feeds the matrices into ComputeInstanceCulling, and animates each survivor with hashed rotation in TSL. - `webgpu_compute_radix_sort` — GPU Radix Sort [WebGPU, Compute]: Fullscreen visualization of GPU-accelerated radix sort using WebGPU compute shaders. Step through 16 sorting passes (2 bits each) to watch the algorithm progressively sort data. Features workgroup-local prefix sums, deterministic scatter without atomics, and real-time bar chart visualization with color-coded values. - `webgpu_simulation_boids_2d` — 2D Boids Simulation [WebGPU, Simulation, Boids]: GPU boids simulate flocking in a 2D domain. An orthographic camera watches thousands of triangles driven by the Boids solver, using spatial grid acceleration, pointer attraction or repulsion, and ComputeInstanceCulling for rendering. - `webgpu_simulation_pbf_2d` — 2D Position Based Fluids [WebGPU, Simulation, PBF]: Position-Based Fluids enforce incompressibility with iterative constraints. This 2D view lets you stir a dense sheet of particles, adjust solver iterations and kernel settings, and watch instanced sprites blur with velocity-driven color. - `webgpu_gaussiansplat_lit` — Gaussian Splatting Lit [WebGPU, Gaussian, Splatting]: PBR lighting demo for 3D Gaussian Splatting comparing lit splat materials with standard PBR meshes. Features directional and point lights with helpers, shadow-receiving ground plane, and side-by-side torus/torusknot meshes to visualize lighting response. Includes full debug visualization modes and material parameter controls. - `webgpu_gaussiansplat_4dgs` — 4D Gaussian Splatting (animated) [WebGPU, Gaussian, Splatting]: Animated, correspondence-preserving 4D Gaussian Splatting. Plays a compact .b4dgs container (per-frame positions, color and opacity over a shared scale/rotation base set) by updating one resident SplatMesh each frame with setData() — the runtime compute-deform. The asset comes from a Mac-local pipeline: fixed-topology warm-start training in brush plus a temporal DPCM codec. - `webgpu_gaussiansplat_4dgs_video` — 4D Gaussian Splat Video (WebCodecs) [WebGPU, Gaussian, Splatting, Video]: A 4D Gaussian splat video clip streams geometry and appearance tracks through WebCodecs with GPU unpacking. - `webgpu_gaussiansplat_visualizer` — Gaussian Splatting Visualizer [WebGPU, Gaussian, Splatting]: Interactive drag & drop visualizer for testing 3D Gaussian Splatting models. Drop .ply, .splat, or .splats files to preview them with real-time controls for visualization modes, spherical harmonics, and material settings. - `webgpu_simulation_boids_3d` — 3D Boids Simulation [WebGPU, Simulation, Boids]: 3D boids combine flocking with volume constraints. Birds are initialized from a bunny SDF sample, animated with wing flaps, kept inside the volume by an SDF constraint, and rendered through ComputeInstanceCulling while spatial grids keep the sim fast. - `webgpu_simulation_pbf_3d` — 3D Position Based Fluids [WebGPU, Simulation, PBF]: 3D PBF brings the constraint solver into a bounded volume. Particles are sampled from a bunny SDF, updated with PBF steps, and drawn as one-triangle sphere impostors with velocity color, GPU frustum culling, and indirect drawing. - `webgpu_simulation_pbf_bvh` — PBF BVH Volume Constraint [WebGPU, Simulation, PBF, BVH]: Position-Based Fluids contained within a sphere using direct BVH collision queries. Demonstrates BVHVolumeConstraint for real-time particle-mesh containment without SDF precomputation. - `webgpu_simulation_smoke_3d` — 3D Smoke Simulation [WebGPU, Simulation, Smoke]: GPU smoke rises from a dying campfire in a procedural LoftGeometry forest with no fetched assets. A scaled depth prepass keeps the low-resolution volume compositing clean around trees, while pointer gusts stir the plume and a shallow fog bank even as the camera orbits. - `webgpu_simulation_sph_2d` — 2D SPH Fluid Simulation [WebGPU, Simulation, SPH]: Smoothed Particle Hydrodynamics models fluid motion in 2D. The demo simulates thousands of particles on an orthographic domain with pointer forces, optional spatial grid debugging, and instanced billboards colored by velocity. - `webgpu_particles_sphere_impostors` — Sphere Impostor Particles [WebGPU, Particles, TSL, Material]: Two hundred thousand lit particles switch live between one-triangle sphere impostors and SphereGeometry(8,4), with both paths pulling positions and radii from the same GPU storage buffer in one draw. Compare node-material presets, true sphere depth, alpha-to-coverage, and GTAO through Three.js RenderPipeline. - `webgpu_simulation_water_ocean` — Ocean · Million-Particle MLS-MPM [WebGPU, Simulation, MPM, Compute, Particles]: A 1,048,576-particle MLS-MPM/APIC ocean spans a 44×44 m surface and transfers mass and momentum through a 128×64×128 grid, with directional wave forcing, an absorbing rim, and pointer-move splashes. A tiled software compute rasterizer gathers analytic sphere-impostor hits front-to-back, so the full fluid volume is shaded once per visible pixel without hardware overdraw. - `webgpu_simulation_sph_3d` — 3D SPH Fluid Simulation [WebGPU, Simulation, SPH]: 3D SPH extends the fluid solver into volume space. Particles are seeded inside a bunny SDF, constrained by the volume, respond to mouse rays, and render as one-triangle lit sphere impostors with GPU frustum culling and indirect drawing. - `webgpu_compute_sampler_bvh` — Compute Sampler with BVH [WebGPU, Compute, BVH]: BVH-backed SDF sampling turns animated skinned meshes into GPU-readable volumes. The sample builds a signed-distance field from a dancing character each frame, raymarches slice and volume views, and uses ComputeBVHSampler plus GPU culling to scatter tens of thousands of points on the surface. - `webgpu_compute_sampler_dynamic` — Dynamic Compute Sampler [WebGPU, Compute]: Dynamic surface sampling follows geometry that is procedurally deformed on the GPU. The demo warps a large plane with layered noise, then ComputeMeshDynamicSurfaceSampler keeps tens of thousands of instanced blades pinned around a moving axis while updating positions every frame. - `webgpu_compute_tessellation` — WebGPU Compute Tessellation [WebGPU, Compute]: A WebGPU compute tessellation study that expands geometry density on the GPU for adaptive surface detail. - `webgpu_interaction_avbd_pbf` — WebGPU Interaction AVBD PBF [WebGPU, AVBD, Interaction, PBF]: An AVBD kinematic body publishes collider state into GPUInteractionSystem so a PBF fluid responds on the GPU. - `webgpu_interaction_avbd_smoke` — WebGPU Interaction AVBD Smoke [WebGPU, AVBD, Interaction, Smoke]: An AVBD kinematic collider displaces a GPU smoke volume through the shared interaction system. - `webgpu_text_batched` — Batched Text Rendering [WebGPU, Text]: Many runtime Text blocks are merged into a single draw call. Per-text frustum culling and back-to-front z-sorting run on the GPU via compute shaders, and every 500ms a new text is added until capacity is reached. Same live-generated SDF glyphs as Runtime Text, scaled to thousands of instances. - `webgpu_text_msdf` — MSDF Text [WebGPU, Text, MSDF]: Multi-channel signed-distance-field atlases are baked ahead of time and drawn as instanced quads — one draw call per text, layout computed synchronously on the CPU. The pre-baked atlas stays crisp at any scale in both world space and screen space, the low-cost counterpart to runtime glyph generation. - `webgpu_text_msdf_batched` — Batched MSDF Text [WebGPU, Text, MSDF]: Many independent MSDF text blocks drawn in a single instanced draw call against one pre-baked atlas. BatchedMSDFText holds a spinning cylinder of words plus the title; each block carries its own GPU transform and color in storage buffers, so words orbit, bob, and retype live with no per-block draw and no runtime glyph generation. - `webgpu_text_sampler_skinned` — Skinned Text Surface Sampler [WebGPU, Text]: ComputeMeshSurfaceSampler writes instance transforms and normals to storage buffers every frame for a skinned Michelle rig; the batched runtime Text reads those buffers directly (no readback) and re-places its live-generated glyphs from GPU-side storage. - `webgpu_animation_texture_object_indirect` — Indirect Object Animation Texture [WebGPU, Text, Animation]: Indirect animation textures combine baking with GPU-driven draws. This demo batches thousands of pieces into an IndirectBatchedMesh, and runs a compute pass to sample animation frames and render everything in one indirect draw with culling. - `webgpu_vav_basic` — VAV Vertex Animation Video [WebGPU, VAV, Animation]: Vertex Animation Video streams mesh deformation and appearance tracks through WebCodecs into a WebGPU mesh. - `webgpu_vav_viewer` — VAV Viewer (drag & drop) [WebGPU, VAV, Animation]: A drag-and-drop viewer for inspecting VAV manifests and streamed vertex-animation tracks. - `webgpu_vav_live` — VAV Live Cloth (AVBD t-shirt) [WebGPU, VAV, Simulation]: A live AVBD cloth simulation drives a t-shirt mesh against animated skeleton colliders. - `webgpu_culling` — GPU Frustum Culling [WebGPU, Culling]: GPU instance culling trims invisible work before drawing. Two million grass blades sampled on a plane with ComputeMeshSurfaceSampler, culled on the GPU, and animated with per-instance rotation hashes while stats report surviving instances. - `webgpu_culling_vertex` — GPU Vertex Culling [WebGPU, Culling]: Culling-aware vertex shading keeps custom deformations aligned with surviving instances. Bird meshes are culled on the GPU, then vertex nodes flap wings, recolor by hashed IDs, and render only the visible set with ComputeInstanceCulling. - `webgpu_indirect_batchedmesh` — Indirect Batched Mesh [WebGPU]: Indirect batching merges many small meshes into one GPU-controlled draw. This scene spawns up to twenty thousand mixed shapes, assigns per-instance geometry IDs, and lets IndirectBatchedMesh handle frustum culling and animation so everything renders in a single indirect call. - `webgpu_material_transmission` — Material Transmission [WebGPU, Material]: Transmission materials add refractive depth with node-based controls. A rotating glassy box hosts a live PBF particle sim inside, with instanced spheres colored by velocity and lit by an HDR environment while the transmission shader is tweaked via GUI. - `webgpu_parallax_occlusion` — Parallax Occlusion Mapping [WebGPU]: Parallax occlusion mapping fakes depth in textures with adaptive ray steps. The camera sits inside a brick room where mip-aware blue-noise heights drive the parallax node; sliders tune scale and sample counts and a debug view reveals the height layers. - `webgpu_points_bvh_volume` — Point Cloud Volume Raymarching [WebGPU, BVH]: Fastest raymarched volume from point cloud using PointsBVH from three-mesh-bvh. Precomputes an SDF volume from point cloud data with auto-computed shell radius, then renders via GPU sphere-tracing for isosurface extraction with SDF gradient normals. - `webgpu_postprocessing_painterly` — Painterly Post-Processing [WebGPU, Post FX]: Painterly postprocessing turns renders into brushy illustrations. A normal-shaded bunny provides colorful surface gradients, then the structure tensor and Kuwahara filter run as a post chain with adjustable radius, sectors, and debug overlays. - `webgpu_tsl_smoke` — TSL Smoke Effect [WebGPU, Smoke, TSL]: TSL smoke runs a 2D fluid sim as a node you can plug into materials. Here the smoke output colors a rotating cube and responds to pointer splats on its surface, with controls for resolution, curl, dissipation, and interaction speed. - `webgpu_baked_motion_timeline` — Baked Motion · Timeline [WebGPU, Video, Baked Motion]: A Blender timeline render is converted directly from video into a frame-accurate .af track. BakedMotion streams it through WebCodecs at its authored speed; wheel-up slows playback to 0.1× and wheel-down boosts it before either rate eases home. The HUD renders every stored frame as a literal strip and highlights the live frame pair. - `webgpu_baked_motion_tilt` — Baked Motion · Pointer Tilt [WebGPU, Interaction, Baked Motion]: A 19 × 19 camera grid streams compressed albedo and depth frames through four bounded texture slots. BakedMotion follows an ambient path until pointer input takes control. Four neighboring views use depth-aware reprojection and bilinear blending, while the HUD renders all 361 stored cameras as a live atlas and highlights the current blend in place. - `webgpu_baked_motion_rotation` — Baked Motion · Rotation [WebGPU, Interaction, Baked Motion]: An explicit angular velocity advances the camera around a compressed 361-view turntable, then BakedMotion.setView() maps its azimuth. Wheel input raises that velocity before it decays to the baseline, while direct pointer events handle drag. The HUD gives every stored angle its own tooth, highlights the bracketing views, and separates the duplicated 360° seam. The depth-aware billboard ships without the original model or material graph. - `webgpu_sdf_body_tracking` — SDF Body Tracking [WebGPU, Compute, SDF]: MediaPipe pose and hand landmarkers run in parallel workers on zero-copy VideoFrames and drive ~48 tapered capsules from filtered world landmarks. A compute pass bins the capsules into screen tiles, then a per-pixel sphere-tracer marches the smooth-min field with SDF shadows and ambient occlusion over a dark studio floor; a procedural performer takes over when no camera is available. ## Canonical Links - Agent setup: https://threejs-blocks.com/docs/ai - Agent index: https://threejs-blocks.com/llms.txt - Full agent context: https://threejs-blocks.com/llms-full.txt - Examples: https://threejs-blocks.com/examples - Pricing: https://threejs-blocks.com/pricing - Commercial license terms: https://threejs-blocks.com/license