Sprint 3: text3d node type via TextGeometry + FontLoader

Add Text3DNode to scene DSL with fields: text (capped 24 chars, ASCII-only),
size, depth (clamped 0.05-1.0), bevel, plus full material/color/preset/position
fields shared with Obj/ExtrudeNode.

Compiler: FontLoader + TextGeometry addon imports added to the importmap. All
scene construction is now wrapped in an (async()=>{})() IIFE so FontLoader can
be awaited once; the single font load covers all text3d nodes in a scene, then
shadow-traverse and auto-frame run AFTER text is in the group. For no-text
scenes the IIFE resolves synchronously — zero latency change. The r160
TextGeometry parameter is 'height' (renamed to 'depth' at r163); pinned to
unpkg.com/three@0.160.0 for the typeface JSON URL.

text_section_js(): generates the async font-load block. objects_js() skips
Text3DNode (emitted by text_section_js instead). _flatten/_node_axis_size
handle Text3DNode as a leaf. Mixed extrude+text scenes work: extruded star is
mesh0 (sync), PRO text is mesh1 (async after font resolves).

llm.py: SYSTEM updated with text3d schema. Three FEWSHOT examples added:
HELLO word, gold number 1, star badge + PRO text overlay.

compiler.py

@@ -7,10 +7,13 @@ and the "copy code" tab, so what the user sees is exactly what they copy.
 from __future__ import annotations
 
 import base64
+import json
 from typing import Any, Dict
 
 from scene import (Animation, ExtrudeNode, LayoutGrid, LayoutRow, LayoutStack,
-                   Obj, Scene, _shape_extent)
+                   Obj, Scene, Text3DNode, _shape_extent)
+
+FONT_URL = "https://unpkg.com/three@0.160.0/examples/fonts/helvetiker_regular.typeface.json"
 
 
 def _col_str(color: str) -> str:
@@ -139,9 +142,50 @@ def material_js(o: Obj, style: str = "realistic") -> str:
             f"metalness: {o.metalness}, roughness: {o.roughness} }})")
 
 
+def text_section_js(nodes_with_idx: list, style: str = "realistic") -> str:
+    """Generate the async font-load block for all text3d nodes.
+
+    Returns an empty string when there are no text nodes (no font load, no await).
+    All text meshes are built inside a single loadAsync call so the font is fetched once.
+    r160 TextGeometry uses 'height' for extrusion depth (renamed to 'depth' at r163).
+    """
+    if not nodes_with_idx:
+        return ""
+    lines = [
+        f"    const _font = await new FontLoader().loadAsync(",
+        f"      '{FONT_URL}'",
+        f"    );",
+    ]
+    for node, idx in nodes_with_idx:
+        mat = material_js(node, style)
+        txt = json.dumps(node.text)
+        bevel = "true" if node.bevel else "false"
+        px, py, pz = node.position
+        rx, ry, rz = node.rotation
+        sx, sy, sz = node.scale
+        lines += [
+            f"    {{  // text3d: {node.text!r}",
+            f"      const _geo = new TextGeometry({txt}, {{",
+            f"        font: _font, size: {node.size}, height: {node.depth},",
+            f"        curveSegments: 12, bevelEnabled: {bevel},",
+            f"        bevelThickness: 0.02, bevelSize: 0.02, bevelSegments: 3",
+            f"      }});",
+            f"      _geo.center();",
+            f"      const mesh{idx} = new THREE.Mesh(_geo, {mat});",
+            f"      mesh{idx}.position.set({px}, {py}, {pz});",
+            f"      mesh{idx}.rotation.set({rx}, {ry}, {rz});",
+            f"      mesh{idx}.scale.set({sx}, {sy}, {sz});",
+            f"      group.add(mesh{idx});",
+            f"    }}",
+        ]
+    return "\n".join(lines)
+
+
 def objects_js(scene: Scene, style: str = "realistic") -> str:
     lines = []
     for i, node in enumerate(_flatten(scene.objects)):
+        if isinstance(node, Text3DNode):
+            continue  # built in the async text section
         if isinstance(node, ExtrudeNode):
             lines.extend(extrude_js(node, i, style))
         else:
@@ -394,6 +438,12 @@ def _node_axis_size(node: Any, axis: int) -> float:
         return _shape_extent(node.shape, node.params)[axis]
     if isinstance(node, ExtrudeNode):
         return 1.5  # normalised to 1.5-unit max dimension at render time
+    if isinstance(node, Text3DNode):
+        if axis == 0:  # x: rough width (0.6 units per char at size 1)
+            return max(node.size * len(node.text) * 0.6, node.size)
+        if axis == 1:  # y: cap height
+            return node.size * 1.2
+        return node.depth + 0.05  # z
     if isinstance(node, LayoutStack):
         ai = {"x": 0, "y": 1, "z": 2}.get(node.axis, 1)
         sizes = [_node_axis_size(c, ai) for c in node.children]
@@ -405,7 +455,7 @@ def _flatten(items: list, ox: float = 0.0, oy: float = 0.0, oz: float = 0.0) ->
     """Recursively resolve layout containers into a flat list of positioned leaf nodes."""
     result = []
     for item in items:
-        if isinstance(item, (Obj, ExtrudeNode)):
+        if isinstance(item, (Obj, ExtrudeNode, Text3DNode)):
             result.append(item.model_copy(update={
                 "position": [item.position[0] + ox,
                              item.position[1] + oy,
@@ -482,6 +532,8 @@ TEMPLATE = """<!DOCTYPE html>
   import { OutputPass }         from 'three/addons/postprocessing/OutputPass.js';
   import { RoundedBoxGeometry } from 'three/addons/geometries/RoundedBoxGeometry.js';
   import { RoomEnvironment }    from 'three/addons/environments/RoomEnvironment.js';
+  import { FontLoader }         from 'three/addons/loaders/FontLoader.js';
+  import { TextGeometry }       from 'three/addons/geometries/TextGeometry.js';
 
   const scene = new THREE.Scene();
   scene.background = new THREE.Color('__BG__');
@@ -517,43 +569,8 @@ TEMPLATE = """<!DOCTYPE html>
   // ---- model accent point-lights ----
       __ACCENT_LIGHTS__
 
-  // ---- objects ----
-      __OBJECTS__
-
-  // ---- shadow casting on every mesh ----
-  if (__USE_SHADOWS__) {
-    group.traverse(o => { if (o.isMesh) { o.castShadow = true; o.receiveShadow = true; } });
-  }
-
-  // ---- auto-frame camera + contact-shadow ground plane ----
-  const _box = new THREE.Box3().setFromObject(group);
-  if (!_box.isEmpty()) {
-    const _sz  = _box.getSize(new THREE.Vector3());
-    const _ctr = _box.getCenter(new THREE.Vector3());
-    const maxDim = Math.max(_sz.x, _sz.y, _sz.z) || 1;
-    const fov  = camera.fov * (Math.PI / 180);
-    const dist = (maxDim / 2) / Math.tan(fov / 2) * 1.6;
-    camera.position.set(_ctr.x + dist * 0.7, _ctr.y + dist * 0.45, _ctr.z + dist);
-    camera.near = dist / 100;
-    camera.far  = dist * 100;
-    camera.updateProjectionMatrix();
-    controls.target.copy(_ctr);
-    controls.update();
-
-    if (__USE_SHADOWS__) {
-      const gnd = new THREE.Mesh(
-        new THREE.PlaneGeometry(maxDim * 8, maxDim * 8),
-        new THREE.ShadowMaterial({ opacity: 0.35, transparent: true })
-      );
-      gnd.rotation.x    = -Math.PI / 2;
-      gnd.position.y    = _box.min.y - 0.005;
-      gnd.receiveShadow = true;
-      scene.add(gnd);
-    }
-  }
-
   // ---- bloom + output post-processing ----
-  const USE_BLOOM     = __USE_BLOOM__;
+  const USE_BLOOM      = __USE_BLOOM__;
   const BLOOM_STRENGTH = __BLOOM_STRENGTH__;
   const composer = new EffectComposer(renderer);
   composer.addPass(new RenderPass(scene, camera));
@@ -572,7 +589,6 @@ TEMPLATE = """<!DOCTYPE html>
     if (USE_BLOOM) composer.render();
     else renderer.render(scene, camera);
   }
-  animate();
 
   window.addEventListener('resize', () => {
     camera.aspect = window.innerWidth / window.innerHeight;
@@ -580,6 +596,47 @@ TEMPLATE = """<!DOCTYPE html>
     renderer.setSize(window.innerWidth, window.innerHeight);
     composer.setSize(window.innerWidth, window.innerHeight);
   });
+
+  // ---- build scene (async so FontLoader can be awaited for text3d nodes) ----
+  (async () => {
+    // ---- sync objects (primitives + extrude) ----
+      __OBJECTS__
+
+__TEXT_SECTION__
+    // ---- shadow casting on every mesh ----
+    if (__USE_SHADOWS__) {
+      group.traverse(o => { if (o.isMesh) { o.castShadow = true; o.receiveShadow = true; } });
+    }
+
+    // ---- auto-frame camera + contact-shadow ground plane ----
+    const _box = new THREE.Box3().setFromObject(group);
+    if (!_box.isEmpty()) {
+      const _sz  = _box.getSize(new THREE.Vector3());
+      const _ctr = _box.getCenter(new THREE.Vector3());
+      const maxDim = Math.max(_sz.x, _sz.y, _sz.z) || 1;
+      const fov  = camera.fov * (Math.PI / 180);
+      const dist = (maxDim / 2) / Math.tan(fov / 2) * 1.6;
+      camera.position.set(_ctr.x + dist * 0.7, _ctr.y + dist * 0.45, _ctr.z + dist);
+      camera.near = dist / 100;
+      camera.far  = dist * 100;
+      camera.updateProjectionMatrix();
+      controls.target.copy(_ctr);
+      controls.update();
+
+      if (__USE_SHADOWS__) {
+        const gnd = new THREE.Mesh(
+          new THREE.PlaneGeometry(maxDim * 8, maxDim * 8),
+          new THREE.ShadowMaterial({ opacity: 0.35, transparent: true })
+        );
+        gnd.rotation.x    = -Math.PI / 2;
+        gnd.position.y    = _box.min.y - 0.005;
+        gnd.receiveShadow = true;
+        scene.add(gnd);
+      }
+    }
+
+    animate();
+  })().catch(console.error);
 </script>
 </body>
 </html>
@@ -594,11 +651,15 @@ def compile_html(
     lighting: str = "studio",
     shadows: bool = True,
 ) -> str:
+    flat = _flatten(scene.objects)
+    text_nodes = [(n, i) for i, n in enumerate(flat) if isinstance(n, Text3DNode)]
+
     html = TEMPLATE
     html = html.replace("__BG__",            scene.background)
     html = html.replace("__PRESET_LIGHTS__", _preset_lights_js(lighting, shadows))
     html = html.replace("__ACCENT_LIGHTS__", _accent_lights_js(scene))
     html = html.replace("__OBJECTS__",       objects_js(scene, style))
+    html = html.replace("__TEXT_SECTION__",  text_section_js(text_nodes, style))
     html = html.replace("__ANIM__",          animation_js(scene.animation))
     html = html.replace("__USE_BLOOM__",     "true" if glow else "false")
     html = html.replace("__BLOOM_STRENGTH__", str(float(glow_strength)))

llm.py

@@ -62,6 +62,22 @@ For stars, badges, shields, hearts, hexagons, coins, logos, or emblems use an EX
   "position": [x, y, z]
 }
 
+For 3D text (words, numbers, short labels) use a TEXT3D object (Latin chars only, max 24 chars):
+{
+  "type": "text3d",
+  "text": "HELLO",
+  "size": 0.8,
+  "depth": 0.2,
+  "bevel": true,
+  "color": "#RRGGBB",
+  "preset": "gold|chrome|glass|neon|matte|plastic",
+  "metalness": 0.0-1.0,
+  "roughness": 0.0-1.0,
+  "position": [x, y, z]
+}
+Use text3d for: single words, numbers, initials, short labels (max 2 text objects per scene).
+Combine text3d with extrude for badges with text (position text slightly in front: z+0.3).
+
 Material preset notes:
 - gold/chrome: use for shiny metallic looks; color overrides the base hue
 - glass: transparent refractive; color adds a tint
@@ -264,6 +280,58 @@ FEWSHOT = [
         ],
         "animation": {"type": "rotate", "speed": 0.6, "axis": "y"},
     })},
+    {"role": "user", "content": "the word HELLO in 3D"},
+    {"role": "assistant", "content": json.dumps({
+        "background": "#0b0e14",
+        "objects": [{
+            "type": "text3d", "text": "HELLO",
+            "size": 0.8, "depth": 0.2, "bevel": True,
+            "color": "#88ccff", "metalness": 0.3, "roughness": 0.4,
+            "position": [0, 0, 0],
+        }],
+        "lights": [
+            {"type": "ambient", "intensity": 0.4},
+            {"type": "directional", "color": "#ffffff", "intensity": 2.0, "position": [5, 8, 5]},
+        ],
+        "animation": {"type": "rotate", "speed": 0.5, "axis": "y"},
+    })},
+    {"role": "user", "content": "a gold 3D number 1"},
+    {"role": "assistant", "content": json.dumps({
+        "background": "#1a1205",
+        "objects": [{
+            "type": "text3d", "text": "1",
+            "size": 1.2, "depth": 0.3, "bevel": True,
+            "color": "#ffd700", "preset": "gold",
+            "position": [0, 0, 0],
+        }],
+        "lights": [
+            {"type": "ambient", "intensity": 0.3},
+            {"type": "directional", "color": "#fff8e0", "intensity": 2.5, "position": [4, 6, 4]},
+        ],
+        "animation": {"type": "rotate", "speed": 0.5, "axis": "y"},
+    })},
+    {"role": "user", "content": "a star badge with the text PRO"},
+    {"role": "assistant", "content": json.dumps({
+        "background": "#0d1117",
+        "objects": [
+            {
+                "type": "extrude", "shape": "star", "depth": 0.15, "bevel": True,
+                "color": "#3a6bc4", "metalness": 0.7, "roughness": 0.2,
+                "position": [0, 0, 0],
+            },
+            {
+                "type": "text3d", "text": "PRO",
+                "size": 0.35, "depth": 0.1, "bevel": True,
+                "color": "#ffffff", "metalness": 0.1, "roughness": 0.4,
+                "position": [0, -0.15, 0.3],
+            },
+        ],
+        "lights": [
+            {"type": "ambient", "intensity": 0.4},
+            {"type": "directional", "color": "#ffffff", "intensity": 2.0, "position": [3, 5, 4]},
+        ],
+        "animation": {"type": "rotate", "speed": 0.5, "axis": "y"},
+    })},
 ]
 
 _tok = None

scene.py

@@ -439,9 +439,91 @@ class ExtrudeNode(BaseModel):
         return out
 
 
+class Text3DNode(BaseModel):
+    """3-D text rendered via Three.js TextGeometry + FontLoader (Latin chars only)."""
+    type: Literal["text3d"] = "text3d"
+    text: str = "TEXT"
+    size: float = 0.6
+    depth: float = 0.2
+    bevel: bool = True
+    color: str = "#88ccff"
+    material: str = "standard"
+    preset: Optional[str] = None
+    metalness: float = 0.3
+    roughness: float = 0.4
+    emissive: str = "#000000"
+    position: List[float] = Field(default_factory=lambda: [0.0, 0.0, 0.0])
+    rotation: List[float] = Field(default_factory=lambda: [0.0, 0.0, 0.0])
+    scale: List[float] = Field(default_factory=lambda: [1.0, 1.0, 1.0])
+
+    @field_validator("text")
+    @classmethod
+    def _text(cls, v: Any) -> str:
+        v = "".join(c for c in str(v).strip() if c.isprintable() and ord(c) < 128)[:24]
+        return v or "TEXT"
+
+    @field_validator("size")
+    @classmethod
+    def _size(cls, v: Any) -> float:
+        try:
+            return _clamp(float(v), 0.1, 4.0)
+        except Exception:
+            return 0.6
+
+    @field_validator("depth")
+    @classmethod
+    def _depth(cls, v: Any) -> float:
+        try:
+            return _clamp(float(v), 0.05, 1.0)
+        except Exception:
+            return 0.2
+
+    @field_validator("color", "emissive")
+    @classmethod
+    def _hex(cls, v: Any, info) -> str:
+        default = "#88ccff" if info.field_name == "color" else "#000000"
+        return _sanitize_color(str(v), default)
+
+    @field_validator("material")
+    @classmethod
+    def _material(cls, v: Any) -> str:
+        v = str(v)
+        return v if v in MATERIALS else "standard"
+
+    @field_validator("preset")
+    @classmethod
+    def _preset_field(cls, v: Any) -> Optional[str]:
+        if v is None:
+            return None
+        v = str(v).lower().strip()
+        return v if v in PRESET_NAMES else None
+
+    @field_validator("metalness", "roughness")
+    @classmethod
+    def _unit(cls, v: Any) -> float:
+        try:
+            return _clamp(float(v), 0.0, 1.0)
+        except Exception:
+            return 0.4
+
+    @field_validator("position", "rotation", "scale")
+    @classmethod
+    def _vec3(cls, v: Any, info) -> List[float]:
+        fill = 1.0 if info.field_name == "scale" else 0.0
+        out: List[float] = []
+        try:
+            for x in list(v)[:3]:
+                out.append(float(x))
+        except Exception:
+            out = []
+        while len(out) < 3:
+            out.append(fill)
+        return out
+
+
 def _parse_scene_item(v: Any) -> Any:
     """Parse a dict (or existing model) into the correct scene node type."""
-    if isinstance(v, (Obj, LayoutStack, LayoutRow, LayoutGrid, ExtrudeNode)):
+    if isinstance(v, (Obj, LayoutStack, LayoutRow, LayoutGrid, ExtrudeNode, Text3DNode)):
         return v
     if not isinstance(v, dict):
         return Obj()
@@ -455,6 +537,8 @@ def _parse_scene_item(v: Any) -> Any:
             return LayoutGrid(**v)
         if t == "extrude":
             return ExtrudeNode(**v)
+        if t == "text3d":
+            return Text3DNode(**v)
         return Obj(**v)
     except Exception:
         return Obj()
@@ -517,7 +601,7 @@ TEMPLATES: Dict[str, Any] = {
 
 class Scene(BaseModel):
     background: str = "#0b0e14"
-    objects: List[Union[Obj, LayoutStack, LayoutRow, LayoutGrid, ExtrudeNode]] = Field(default_factory=list)
+    objects: List[Union[Obj, LayoutStack, LayoutRow, LayoutGrid, ExtrudeNode, Text3DNode]] = Field(default_factory=list)
     lights: List[Light] = Field(default_factory=list)
     animation: Animation = Field(default_factory=Animation)