# Lettra for agents.

> What Lettra is, when to use it, how to start, and where the source is.

## Words belong in the world.

Lettra is a TypeScript library for MSDF text in Three.js: baked font atlases, kerned layout and composable TSL materials. Made by JOYCO. This site shows it off in one journey: a tree canopy, a lake, a sheet of paper on it, and a stack of TVs.

lettra handles font data and layout; lettra/three turns it into geometry, materials and effects. You install it in your project. No account or API key.

## When to use Lettra

- Text that lives in a Three.js scene: a camera path, a screen, a sign, a label.
- Latin display type that stays sharp as the camera, scale and angle change.
- Text effects composed in TSL: wipes, dissolves, scrambles, input-driven animation.

For regular page copy, use HTML. Lettra has no complex-script shaping, bidi or color emoji. Check that the atlas covers your characters. Requires three/webgpu, also for the WebGL2 fallback.

## Start with a font and an idea.

Give your agent a font you’re allowed to use, the words, and the scene. Say how the text should move, appear, disappear or react to input.

```bash
npx skills add joyco-studio/lettra
```

```bash
pnpm add lettra three
```

Bake the font first. Lettra loads a metrics JSON and an MSDF atlas PNG, not a font file. Check the filenames, glyph coverage and kerning report.

```bash
npx lettra bake font.ttf --charset latin-es --size 64 --pxrange 8 --out public/fonts/display
```

Import from lettra/three and use the three/webgpu renderer. Load the metrics and atlas, create the text, add text.mesh to the scene, and warm it up before showing it. Check the docs for your installed version.

## Open source. MIT licensed.

MIT License, © 2026 joyco.studio. Use, modify and distribute it, commercially too, as long as you keep the copyright notice. No warranty. See the license for exact terms.

Fonts have their own licenses. Lettra’s license doesn’t let you redistribute a third-party font.

- [Lettra MIT License](https://github.com/joyco-studio/lettra/blob/main/LICENSE): The license file in the repo.

## Give your agent a direction.

```text
Build a Three.js scene using Lettra and the supplied font.
Use the text: “Words you can walk through.”
Bake and load a matching MSDF atlas and font metrics.
Place the words between objects so depth and occlusion are visible.
Add a cursor-driven response and a keyboard-accessible control.
Keep semantic HTML for reading and navigation.
Respect reduced motion and provide a fallback if graphics fail.
Check the installed Lettra documentation before choosing APIs.
```

## What this site demonstrates

- Canopy: type between branches as the camera moves through.
- Perspective: leaves falling in front of and behind the letters.
- Lake: cursor trails and ripples bend the text.
- Rich text: a sheet on the pond in several weights and italics, editable live.
- Televisions: the sheet scene on a screen, then a camera ride along a cable.

## Go to the source.

- [Lettra documentation](https://lettra-landing.vercel.app/docs): Reference, examples and font workflow.
- [Lettra source and README](https://github.com/joyco-studio/lettra): Source, install and current API.
- [Lettra agent skill](https://github.com/joyco-studio/lettra): Install the Lettra skill in your agent.
- [JOYCO experiments](https://hub.joyco.studio/lab?tag=lettra): More work from the studio.

## Read without the canvas.

Send Accept: text/markdown to get Markdown, or use the .md URLs. llms.txt indexes the same content; sitemap.xml lists the HTML pages.

- [Agent index](https://lettra-landing.vercel.app/llms.txt): Site map for agents.
- [This guide as Markdown](https://lettra-landing.vercel.app/ai.md): This guide in Markdown.
- [Developer resources](https://lettra-landing.vercel.app/developers): Integration notes and endpoints.