Add claude docs

.claude/display-text.md

@@ -0,0 +1,115 @@
+# Display -- Text Rendering
+
+Source: `src/dusk/display/text/`
+
+See also: `.claude/display-spritebatch.md`, `.claude/display-texture.md`
+
+---
+
+## Overview
+
+Text rendering is layered on top of the SpriteBatch. Each character
+maps to a glyph tile in a bitmap font atlas; `textDraw` builds the
+corresponding `spritebatchsprite_t` values and pushes them to the
+global `SPRITEBATCH`. The caller is responsible for flushing the batch.
+
+---
+
+## Font type (`font.h`)
+
+```c
+typedef struct {
+  texture_t *texture;   // glyph atlas texture
+  tileset_t *tileset;   // grid describing glyph size + UV layout
+} font_t;
+```
+
+Both pointers are caller-owned. The text system does not allocate or
+free them.
+
+```c
+extern font_t FONT_DEFAULT;
+```
+
+`FONT_DEFAULT` is the engine's built-in bitmap font. It is initialised
+during `textInit()` and available for the engine lifetime.
+
+---
+
+## Character range
+
+```c
+#define TEXT_CHAR_START '!'   // ASCII 33
+```
+
+The glyph atlas begins at `'!'` (ASCII 33). Characters below this value
+-- space, control characters -- are handled specially:
+
+- `' '` (space) advances the cursor by one tile width without drawing.
+- Characters below `TEXT_CHAR_START` other than space are skipped.
+
+---
+
+## API (`text.h`)
+
+```c
+// Initialises the text system and FONT_DEFAULT.
+errorret_t textInit(void);
+
+// Disposes of the text system.
+errorret_t textDispose(void);
+
+// Draw a null-terminated string at (x, y) in screen/world space.
+// Pushes sprites to SPRITEBATCH. Caller must call spriteBatchFlush()
+// after all text has been drawn.
+errorret_t textDraw(
+  const float_t x,
+  const float_t y,
+  const char_t *text,
+  const color_t color,
+  font_t *font
+);
+
+// Measure the bounding box of a string without drawing it.
+void textMeasure(
+  const char_t *text,
+  const font_t *font,
+  int32_t *outWidth,
+  int32_t *outHeight
+);
+
+// Low-level: build a single glyph sprite at position pos.
+// Returns a spritebatchsprite_t ready for spriteBatchBuffer.
+spritebatchsprite_t textGetSprite(
+  const vec2 pos,
+  const char_t c,
+  const font_t *font
+);
+```
+
+---
+
+## Typical usage
+
+```c
+// Inside a render callback:
+errorChain(textDraw(10.0f, 10.0f, "Hello", COLOR_WHITE, &FONT_DEFAULT));
+errorChain(spriteBatchFlush());
+```
+
+If you are also drawing UI frames or other sprites in the same pass,
+batch all the `textDraw` and `spriteBatchBuffer` calls first, then call
+`spriteBatchFlush()` once at the end.
+
+---
+
+## Notes
+
+- Text coordinates are in the same space as the scene render (screen
+  space for UI, or world space if placed in the scene).
+- `textMeasure` returns pixel dimensions based on the font's
+  `tileset.tileWidth` and `tileset.tileHeight`. Use it to centre or
+  right-align text before drawing.
+- For UI-attached text (dialogue, labels), prefer the `uitextbox_t`
+  system which handles word-wrap and paging automatically
+  (see `.claude/ui.md`).