--- name: ultra-text description: >- Guides coding agents integrating ultra-text for runtime DOM-to-WebGPU 3D text in Three.js WebGPURenderer, TSL shaders, React Three Fiber (R3F), TresJS (Vue), Mini3, and vanilla WebGPU engines. Use when installing, configuring, styling, reflowing, animating, or debugging ultra-text, ultra-text/slug, ultra-text/vanilla, or ultra-text/slug-vanilla. --- # ultra-text `ultra-text` captures real HTML/CSS laid out by the browser and renders it as retained WebGPU instanced geometry—either from a compact single-channel SDF atlas or analytic Slug/Windfoil quadratic outlines—with zero DOM reads in the render loop. ## Choose the right entry point Never import internal module paths or `THREE.WebGLRenderer` (unsupported). Do not invent framework subpaths like `ultra-text/r3f`, `ultra-text/tres`, or `ultra-text/mini3`. | Entry point | Stack | Renderer / device | Coverage backend | | ------------------------- | --------------------------- | --------------------------------- | -------------------------------------------------------------- | | `ultra-text` | Three.js / R3F / TresJS | `WebGPURenderer` (`three/webgpu`) | SDF (GPU JFA / CPU EDT), plus optional `windfoil` or `slug` | | `ultra-text/slug` | Three.js Slug-only apps | `WebGPURenderer` (`three/webgpu`) | Pure analytic Slug (zero SDF code, `DomSlug` / `SlugText`) | | `ultra-text/vanilla` | Mini3 & custom engines | `GPUDevice` (Three.js-free) | SDF atlas + packed typed-array instance buffers | | `ultra-text/slug-vanilla` | Mini3 & custom Slug engines | `GPUDevice` (Three.js-free) | Pure analytic Slug + `SLUG_WGSL` / `createVanillaSlugPipeline` | - Install Three.js within `ultra-text`'s peer range (`three` `>=0.187.0 <0.188.0`) and keep a single Three.js instance across the app. - For Three-free engines, `three` is an optional peer dependency and does not need to be installed. ## Non-negotiable DOM & lifecycle invariants 1. **Await renderer init and fonts before capture**: run `await renderer.init()` and `await document.fonts.ready` so CSS faces and line metrics settle before reading the DOM. 2. **Keep the source connected, accessible, and measurable**: pass a real element with a non-zero layout box. Never use `display: none` or the `hidden` attribute on the captured source; keep semantic HTML in the accessibility tree and mark the WebGPU `