# Framework Integration Reference (R3F, TresJS, Mini3) Starter components are **copy-once consumer source files** licensed under **MIT**—not npm subpaths (`ultra-text/r3f`, `ultra-text/tres`, or `ultra-text/mini3` do not exist). Always import runtime code from `ultra-text`, `ultra-text/slug`, `ultra-text/vanilla`, or `ultra-text/slug-vanilla`. ## Starter files (download or copy from the docs site) | Framework | Starter file(s) | Library entry | Notes | | ----------------------------- | ------------------------------------------------------------------------------------- | -------------------- | ---------------------------------------------------------------------------------- | | React Three Fiber v9 (stable) | `https://ultra-text.makio.io/integrations/r3f/UltraText.tsx` | `ultra-text` | Uses `gl={async ({ canvas }) => ...}` and `useThree((s) => s.gl)`. | | React Three Fiber v10 (alpha) | `https://ultra-text.makio.io/integrations/r3f/v10/UltraText.tsx` | `ultra-text` | Uses `renderer={async ({ canvas }) => ...}` and `useThree((s) => s.renderer)`. | | TresJS / Vue 3 | `https://ultra-text.makio.io/integrations/tres/UltraText.vue` & `UltraTextCanvas.vue` | `ultra-text` | Add `vue({ ...templateCompilerOptions })` from `@tresjs/core` in `vite.config.ts`. | | Mini3 | `https://ultra-text.makio.io/integrations/mini3/UltraText.ts` | `ultra-text/vanilla` | Zero Three.js dependency; adopts the WebGPU `GPUTexture` into a Mini3 `Texture`. | Canonical integration guide for coding agents: `https://ultra-text.makio.io/integrations/AGENTS.md` ## Lifecycle & correctness rules for frameworks 1. **Keep source HTML outside the canvas**: render normal semantic HTML (`
`) in the DOM, mark blocks with `data-text-block` (or `data-sdf-block`), and never apply `hidden` or `display: none`. 2. **Await initialization + fonts inside the async effect**: - Wait for `await renderer.init()` (or `Promise.all([gpuRenderer.init(), document.fonts.ready])` in TresJS) before calling `DomText.create`. - Always pass `{ signal: controller.signal }`, check `if (controller.signal.aborted)` before and after every `await`, and call `next.dispose()` immediately if aborted before state assignment (critical for React Strict Mode double-mounting and fast prop swaps). 3. **Clean up on unmount or source change**: - Abort the in-flight `AbortController`. - Detach (`owned?.removeFromParent()`) and dispose (`owned?.dispose()`) the `DomText` instance. - Keep `renderer.dispose()` owned by the canvas wrapper—never dispose the shared renderer from a text component. 4. **Keep `options` reference-stable**: declare `const textOptions = { quality: 'high' } as const` outside the component or wrap in `useMemo`, because a new `options` object identity triggers a full teardown and rebuild. 5. **Account for `pixelsPerUnit: 100` in 3D scenes**: the framework starters default to `100` CSS pixels per world unit so a 600 px card is `6` units wide. Scale Z depths and motion strength accordingly: ```ts const pixelsPerUnit = options?.pixelsPerUnit ?? 100 // e.g. panelDepth: -1 / pixelsPerUnit, motion: { enabled: false, strength: 18 / pixelsPerUnit } ``` 6. **Continuous vs on-demand render loop**: keep `frameloop="always"` (R3F) or `render-mode="always"` (TresJS) when observing live DOM changes or TSL `motion`. If using an on-demand loop, invalidate the frame when mutations or `rebuild()` complete. 7. **SSR frameworks (Next.js, Nuxt, SvelteKit, Astro)**: DOM measurement and WebGPU require a browser. Guard capture and mount `` only on the client. ## Verified baselines - **Three.js**: `>=0.187.0 <0.188.0` (matches `package.json` peer dependency; use one Three.js copy). - **R3F v9**: `@react-three/fiber` 9.8.2 + React 19.3.1. - **R3F v10 alpha**: `@react-three/fiber` 10.0.0-alpha.6 + React 19.3.1 (prerelease APIs subject to change). - **TresJS**: `@tresjs/core` 5.10.0 + Vue 3.5.44. - **Mini3**: `0.1.0-alpha.0` with `ultra-text/vanilla`.