# ultra-text integration instructions for coding agents

These starter components and their framework guides are MIT licensed, copyright 2026
David Ronai. You may use, copy, adapt and redistribute them, including in commercial apps
and through coding agents. Keep the copyright and MIT permission notice with copies or
substantial portions; the accompanying `LICENSE` contains the full terms.

This permission covers the library, documentation and integration examples. The gallery,
HTML/SDF showcase and text-effects scenes have a separate all-rights-reserved license;
create your own scenes with the library and these examples.

## Setup

- Copy the Vue files from `tres/`, the React file from `r3f/` (`r3f/v10/` on the React Three
  Fiber 10 alpha), or the Mini3 file from `mini3/` into your app. These are consumer components,
  not `ultra-text/tres`, `ultra-text/r3f`, or `ultra-text/mini3` npm exports.
- Import Three.js runtime and types from the public `ultra-text` root, or import the
  Three.js-free vanilla runtime and types from `ultra-text/vanilla` for Mini3 and custom
  WebGPU/Canvas engines.
- Verified on 28 October 2026: TresJS 5.10.0 / Vue 3.5.44 (`vue-tsc` 3.3.13 on TypeScript
  6.0.3); R3F 9.8.2 / React 19.3.1; Three.js 0.186.1 / `@types/three` 0.186.0. Verified on
  19 October 2026: Mini3 0.1.0-alpha.0 with `ultra-text/vanilla` (zero Three.js dependency).
- The R3F 10 alpha takes a WebGPU renderer through `renderer`, not `gl`, and reads it from
  `state.renderer`: use `r3f/v10/UltraText.tsx` there only. Verified on 28 October 2026 with
  R3F 10.0.0-alpha.6 / React 19.3.1; alpha APIs can change before the stable release.
- Check current stable releases when updating. Respect ultra-text's Three.js peer range
  (`>=0.186.0 <0.187.0`) and use one Three.js installation when using the Three.js entry. Do
  not substitute prerelease framework APIs for stable ones or widen the peer range without
  testing the library.
- Use `WebGPURenderer` from `three/webgpu` for Three.js; the classic `WebGLRenderer` is
  unsupported. The canvas starters initialize the renderer and own its lifetime.
- Vue/Vite apps need `vue({ ...templateCompilerOptions })`, importing
  `templateCompilerOptions` from `@tresjs/core`. Mount browser canvases on the client in SSR apps.

## Capture and updates

- Keep source HTML outside the canvas, connected, accessible and measurable. Use
  `data-sdf-block` to mark text. Do not use `hidden` or `display: none` on the source.
- The helpers await fonts and use library observers for DOM text and layout updates.
  Change normal Vue/React/DOM source content; do not create or rebuild a capture every frame.
- Keep an optional `options` object stable. Replacing the source or options replaces the
  capture. Default starter motion is off; enable it explicitly through `options.motion`.
- `pixelsPerUnit` scales captured X/Y, not Z or motion. The starters provide small depths
  and motion strength for their default 100 CSS pixels per world unit.
- Keep the abort, source-replacement, late-result disposal and unmount cleanup when adapting
  these components. React must also tolerate Strict Mode's setup/cleanup cycle.
- Let `DomText.dispose()` release its generated resources and observers. Keep renderer
  disposal with the canvas that owns it; do not dispose shared caller resources from the text.
- Keep continuous rendering for automatic updates or animation. A demand canvas requires
  explicit invalidation after content changes.

## Verify changes

Typecheck the actual copied files with the consumer's framework and matching engine types.
In a WebGPU browser, check initial text, a normal source edit, source replacement and unmount.
Check mobile layout and accessibility, and keep the source HTML meaningful. Use the framework
guides at https://ultra-text.netlify.app/docs-tres,
https://ultra-text.netlify.app/docs-r3f, and
https://ultra-text.netlify.app/docs-mini3 alongside the public API at
https://ultra-text.netlify.app/docs.