Return a mini HTML page with every picture; drop the Space's vision model

The Space visualises and the chat discusses: translate, refine and simplify
now also return a self-contained Three.js page with inline low-poly geometry
for the calling model to build on. Removes describe_scene, the recognition
check, the login button (which leaked an MCP tool) and hf_oauth.

Also from the HuggingChat test: SimReady names no longer index lone
modifiers ("sun" found a sun visor), check_words shows what each noun maps
to, renders frame on the objects, light both faces, and the light glows.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

README.md

@@ -8,9 +8,6 @@ sdk_version: 6.27.0
 python_version: '3.12'
 app_file: app.py
 pinned: false
-hf_oauth: true
-hf_oauth_scopes:
-  - inference-api
 short_description: Visualisation and speed of input attempt
 ---
 

SPEC.md

@@ -14,6 +14,11 @@ a mesh can be reduced and still mean its word, and that is a main output.
 One Gradio Space serves people (UI) and models (`demo.launch(mcp_server=True)`).
 HuggingChat models can't run tools, which is why this Space exists.
 
+**The Space visualises; discussion happens in the chat** (e.g. HuggingChat over MCP).
+The calling model already sees the picture, so the Space runs no vision model of
+its own and stores no token. Because HTML is the final destination, every picture
+comes back with a **mini HTML page** the model can read, edit and build on.
+
 ## Translation terms
 
 | Translation | Here |
@@ -24,7 +29,7 @@ HuggingChat models can't run tools, which is why this Space exists.
 | Verbs | Relations between meshes |
 | Word alignment | `tokens[].commits`: reading order differs from build order |
 | Forced choices | `unresolved`: which asset, how big |
-| Back-translation | `describe_scene`: a vision model reads the picture back |
+| Back-translation | The chat model reading the picture: done in the discussion, not by the Space |
 
 ## Dictionary
 
@@ -92,26 +97,36 @@ Verbs: `sat/stood/lay/rested` → `on` (ground implied), `shone/glowed` → `lig
 | Tool | In → out |
 |---|---|
 | `check_words` | sentence, primitives → per-word status, missing words, completions |
-| `translate_to_scene` | sentence, primitives, seed → ledger, PNG, GLB |
-| `refine_scene` | ledger, changes, seed → ledger, PNG, GLB |
-| `simplify_item` | ledger, item id, check_recognition → report, rung PNGs, rung GLBs |
-| `describe_scene` | ledger, seed → back-translation JSON |
+| `translate_to_scene` | sentence, primitives, seed → ledger, PNG, GLB, mini HTML |
+| `refine_scene` | ledger, changes, seed → ledger, PNG, GLB, mini HTML |
+| `simplify_item` | ledger, item id → report, rung PNGs, rung GLBs, mini HTML |
+
+`check_words` also returns `maps_to` per noun (the asset it would get), so a word
+that exists but maps to the wrong thing shows up before submitting.
 
 Ladder rungs: original → 20k / 5k / 1k / 250 / 60 faces → convex hull → oriented
-box. With `check_recognition`, a vision model names each rung, and
-`simplest_recognized` is the lowest rung that still reads as the word.
+box. Where the object stops reading as its word is judged in the discussion.
+
+### Mini HTML
+
+A self-contained page: Three.js (`three@0.160.0` from unpkg) plus one inline `D`
+data object holding the sentence, the reading (word → commits), relations,
+unresolved questions, sun, ground, and each object's position, yaw and colour.
+Each object also has either inline low-poly geometry (≤400 faces in a scene,
+rungs ≤1000 faces in a ladder) or a primitive spec. The geometry is inline, so the
+page works after Gradio's temporary file URLs expire, and it stays small enough
+for a model's context.
 
-**No secrets.** The Space is public, so it stores no token. Datasets are public
-and download without one. Vision-model calls (back-translation, recognition) use
-the **caller's** token: HF sign-in in the UI (`hf_oauth`, `inference-api` scope),
-or a Bearer `Authorization` header from MCP clients. Optional env: `VLM_MODEL`, `VLI_CACHE`.
+**No secrets.** The Space is public and stores no token; the datasets are public
+and download without one. Optional env: `VLI_CACHE`.
 
 ## Known gaps / open questions
 
 - **Materialization** (papercraft from a low rung) is not built yet.
 - **Generation tier** is a stub: rejecting a primitive errors out.
-- SimReady names → words is a heuristic: the second `_` part is the head word
-  (`appliance_refrigerator_a01` → refrigerator). Some names will mis-index.
+- SimReady names → words is a heuristic: the name after its category is indexed
+  as a whole phrase plus its final part (`interiorPart_sun_visor_a01` → "sun visor",
+  "visor"; never "sun" alone). `maps_to` makes the remaining misses visible.
 - Objaverse "front" direction is unknown, so `faces` assumes +Z forward.
 - `on` uses the bounding-box top, so objects on irregular tops may float or sink.
 - Renders are matplotlib (headless, CPU): approximate shading and a flat shadow on

app.py

@@ -2,7 +2,10 @@
 
 One Space for people (this UI) and for models (every public event below is an
 MCP tool: demo.launch(mcp_server=True)). Helper events are api_visibility="private".
+The Space only visualises; discussion happens in the chat that calls it. Every
+picture comes back with a mini HTML page, because HTML is the final destination.
 """
+import html as html_lib
 import json
 import os
 import re
@@ -12,7 +15,7 @@ import threading
 import spaces  # ZeroGPU: import before any CUDA-touching library
 import gradio as gr
 
-from vli import assets, pipeline, scene, simplify, vlm
+from vli import assets, html, pipeline, scene, simplify
 from vli.grammar import check_words as _check_words
 from vli.lexicon import LEXICON, PRIMITIVE_SHAPES
 
@@ -35,14 +38,6 @@ def _json(text, name, default=None):
         raise ValueError(f"{name} is not valid JSON")
 
 
-def _user_token(oauth_token, request):
-    """The caller's own token: from HF sign-in (UI) or a Bearer header (MCP). Never the Space's."""
-    if oauth_token is not None and oauth_token.token:
-        return oauth_token.token
-    auth = (request.headers.get("authorization", "") if request is not None else "")
-    return auth[7:].strip() if auth.lower().startswith("bearer ") else None
-
-
 def _seed(value):
     """Seeds arrive as strings (some MCP clients can't send numbers)."""
     try:
@@ -66,11 +61,11 @@ def generate_mesh(prompt):
 def check_words(sentence: str, primitives_json: str = "{}") -> str:
     """Check which words of a sentence exist in the 3D vocabulary, and complete the word being typed.
 
-    A word is available only when a ready asset (SimReady or Objaverse) exists for it.
-    Words with no asset are listed in "missing": rephrase them, or map each one to a
-    primitive shape in primitives_json. Verbs (sat, stood, lay, shone, faced) and
-    prepositions (on, under, beside, near, behind, in front of, above) are relations
-    between meshes; whatever "shone" becomes the light source.
+    A word is available only when a ready asset (SimReady or Objaverse) exists for it;
+    "maps_to" names the asset it would get. Words with no asset are listed in "missing":
+    rephrase them, or map each one to a primitive shape in primitives_json. Verbs (sat,
+    stood, lay, shone, faced) and prepositions (on, under, beside, near, behind, in front
+    of, above) are relations between meshes; whatever "shone" becomes the light source.
 
     Args:
         sentence: The English sentence, complete or partly typed.
@@ -78,7 +73,7 @@ def check_words(sentence: str, primitives_json: str = "{}") -> str:
             Shapes: box, sphere, cylinder, cone, plane.
 
     Returns:
-        JSON string: {"ok", "words": [{text, kind, available_in | primitive}], "missing",
+        JSON string: {"ok", "words": [{text, kind, available_in, maps_to | primitive}], "missing",
         "primitive_shapes", "completions"}.
     """
     try:
@@ -87,13 +82,14 @@ def check_words(sentence: str, primitives_json: str = "{}") -> str:
         _fail(e)
 
 
-def translate_to_scene(sentence: str, primitives_json: str = "{}", seed: str = "0") -> tuple[str, str, str]:
+def translate_to_scene(sentence: str, primitives_json: str = "{}", seed: str = "0") -> tuple[str, str, str, str]:
     """Translate an English sentence into a 3D scene.
 
     Produces the serial ledger (tokens in reading order, the items each word commits,
-    and the unresolved "which?" questions), one configuration of that ledger chosen by
-    `seed`, a rendered picture and a GLB model. Words with no asset must be mapped to a
-    primitive in primitives_json (call check_words first to see which are missing).
+    and the unresolved questions), one configuration of that ledger chosen by `seed`,
+    a rendered picture, a GLB model and a mini HTML page. The HTML is a self-contained
+    Three.js scene with inline low-poly geometry: read it, edit it, build on it. Words
+    with no asset must be mapped to a primitive in primitives_json (see check_words).
 
     Args:
         sentence: A sentence using available words, e.g. "the cat sat and the sun shone".
@@ -101,7 +97,7 @@ def translate_to_scene(sentence: str, primitives_json: str = "{}", seed: str = "
         seed: Picks one of the configurations that satisfy the ledger (positions, facing, sun).
 
     Returns:
-        (ledger JSON string, rendered PNG, GLB scene file).
+        (ledger JSON string, rendered PNG, GLB scene file, mini HTML page).
     """
     try:
         return pipeline.translate(sentence, _json(primitives_json, "primitives_json", {}), _seed(seed))
@@ -109,17 +105,19 @@ def translate_to_scene(sentence: str, primitives_json: str = "{}", seed: str = "
         _fail(e)
 
 
-def refine_scene(ledger_json: str, changes_json: str = "[]", seed: str = "0") -> tuple[str, str, str]:
+def refine_scene(ledger_json: str, changes_json: str = "[]", seed: str = "0") -> tuple[str, str, str, str]:
     """Refine a ledger: freeze some decisions and change the others, then re-render.
 
     Changes are a JSON list of:
         {"id": "n1", "freeze": true}      lock an item (false unlocks)
-        {"id": "n1", "use": 2}            pick alternatives[2] as the asset
+        {"id": "n1", "use": 2}            swap in alternatives[2]; the old choice takes slot 2,
+                                          so using 2 again swaps back (other slots don't move)
         {"id": "n1", "reject": true}      reject the tier: simready -> objaverse -> primitive -> generation
         {"id": "n1", "height_m": 0.4}     set the object's height in metres
         {"id": "n1", "shape": "sphere"}   use a primitive (box, sphere, cylinder, cone, plane)
         {"reroll": true}                  every unfrozen object takes a random alternative
-    Frozen items cannot be changed. The configuration (placement) is always re-chosen from `seed`.
+    Frozen items cannot be changed. The configuration (placement, sun angle) is always
+    re-chosen from `seed`: change the seed for another valid configuration.
 
     Args:
         ledger_json: Ledger JSON from translate_to_scene or a previous refine_scene.
@@ -127,7 +125,7 @@ def refine_scene(ledger_json: str, changes_json: str = "[]", seed: str = "0") ->
         seed: Picks the configuration, and the alternatives for a reroll.
 
     Returns:
-        (ledger JSON string, rendered PNG, GLB scene file).
+        (ledger JSON string, rendered PNG, GLB scene file, mini HTML page).
     """
     try:
         ledger = _json(ledger_json, "ledger_json")
@@ -137,80 +135,39 @@ def refine_scene(ledger_json: str, changes_json: str = "[]", seed: str = "0") ->
         _fail(e)
 
 
-def simplify_item(ledger_json: str, item_id: str, check_recognition: bool = False,
-                  oauth_token: gr.OAuthToken | None = None, request: gr.Request = None) -> tuple[str, list, list]:
+def simplify_item(ledger_json: str, item_id: str) -> tuple[str, list, list, str]:
     """Build the simplification ladder for one object: full asset -> fewer faces -> convex hull -> box.
 
-    With check_recognition, a vision model names each rung's picture; the lowest rung
-    still named as the word is the simplest form that keeps its meaning.
+    Look at where the object stops reading as its word: that rung is the least geometry
+    that still carries the meaning, and the low rungs are the ones that can be made
+    physically (fewer faces = fewer papercraft pieces).
 
     Args:
         ledger_json: Ledger JSON from translate_to_scene or refine_scene.
         item_id: The object item to simplify, e.g. "n1".
-        check_recognition: Ask a vision model to name each rung (slower; runs on the caller's
-            own HF account, so it needs sign-in or a Bearer token).
 
     Returns:
-        (report JSON string, gallery of rung pictures, GLB file per rung).
+        (report JSON string, gallery of rung pictures, GLB file per rung,
+        mini HTML page with the low rungs side by side).
     """
     try:
-        token = _user_token(oauth_token, request) if check_recognition else None
-        if check_recognition and not token:
-            raise ValueError(vlm.SIGN_IN)  # before any heavy work
         ledger = _json(ledger_json, "ledger_json")
         item = next((i for i in ledger["items"] if i["id"] == item_id), None)
         if item is None or item["kind"] != "object":
             raise ValueError(f"{item_id!r} is not an object item in this ledger")
         mesh = assets.settle(item)
         work = tempfile.mkdtemp(prefix="vli_ladder_")
+        rungs = simplify.ladder(mesh)
         report, gallery, files = {"item": item_id, "word": item["word"], "rungs": []}, [], []
-        for k, (label, rung) in enumerate(simplify.ladder(mesh)):
+        for k, (label, rung) in enumerate(rungs):
             png = scene.render({item_id: rung}, os.path.join(work, f"{k}.png"), title=label)
             slug = re.sub(r"\W+", "_", label)
             glb = os.path.join(work, f"{k}_{slug}.glb")
             rung.export(glb)
-            entry = {"rung": label, **simplify.stats(rung)}
-            if check_recognition:
-                answer = vlm.name_object(png, token)
-                entry["named_as"] = answer
-                entry["recognized"] = item["word"].lower() in answer.lower()
-            report["rungs"].append(entry)
+            report["rungs"].append({"rung": label, **simplify.stats(rung)})
             gallery.append((png, label))
             files.append(glb)
-        if check_recognition:
-            kept = [r for r in report["rungs"] if r["recognized"]]
-            report["simplest_recognized"] = kept[-1]["rung"] if kept else None
-        return json.dumps(report, indent=1), gallery, files
-    except Exception as e:
-        _fail(e)
-
-
-def describe_scene(ledger_json: str, seed: str = "0",
-                   oauth_token: gr.OAuthToken | None = None, request: gr.Request = None) -> str:
-    """Back-translate: render the ledger's scene and have a vision model describe it in English.
-
-    Comparing the description with the original sentence checks the translation.
-    The vision model runs on the caller's own HF account (sign-in or Bearer token).
-
-    Args:
-        ledger_json: Ledger JSON from translate_to_scene or refine_scene.
-        seed: Which configuration to render.
-
-    Returns:
-        JSON string: {"original", "back_translation", "nouns_recovered": {word: bool}}.
-    """
-    try:
-        token = _user_token(oauth_token, request)
-        if not token:
-            raise ValueError(vlm.SIGN_IN)  # before any heavy work
-        ledger = _json(ledger_json, "ledger_json")
-        meshes = pipeline.settle_all(ledger)
-        config = scene.configure(ledger, meshes, _seed(seed))
-        png = scene.render_scene(ledger, meshes, config, os.path.join(tempfile.mkdtemp(), "scene.png"))
-        text = vlm.describe(png, token)
-        nouns = [i["word"] for i in ledger["items"] if i["kind"] == "object"]
-        return json.dumps({"original": ledger["sentence"], "back_translation": text,
-                           "nouns_recovered": {n: n in text.lower() for n in nouns}}, indent=1)
+        return json.dumps(report, indent=1), gallery, files, html.ladder_page(item, rungs)
     except Exception as e:
         _fail(e)
 
@@ -224,12 +181,12 @@ def _suggestions(words_json):
         if w["kind"] == "unknown":
             marks.append(f"~~{w['text']}~~")
         elif w["kind"] == "noun":
-            marks.append(f"**{w['text']}**")
+            marks.append(f"**{w['text']}** → {w.get('maps_to', '?')}")
         elif w["kind"] == "primitive":
             marks.append(f"_{w['text']}_ ({w['primitive']})")
         else:
             marks.append(w["text"])
-    status = " ".join(marks) or "_start typing_"
+    status = " · ".join(marks) or "_start typing_"
     if data.get("missing"):
         status += "  \n_Struck-through words have no asset: pick a suggestion, rephrase, or choose a primitive._"
     missing = data.get("missing", [])
@@ -250,10 +207,22 @@ def _use_primitive(primitives_json, word, shape):
     return json.dumps(prims)
 
 
+def _html_views(page):
+    """Live preview (sandboxed iframe) and a downloadable .html file."""
+    if not page:
+        return "", None
+    path = os.path.join(tempfile.mkdtemp(prefix="vli_html_"), "scene.html")
+    with open(path, "w", encoding="utf-8") as f:
+        f.write(page)
+    frame = (f'<iframe sandbox="allow-scripts" srcdoc="{html_lib.escape(page, quote=True)}" '
+             'style="width:100%;height:460px;border:0;border-radius:8px"></iframe>')
+    return frame, path
+
+
 EXAMPLE_CHANGES = '[\n  {"id": "n1", "freeze": true},\n  {"reroll": true}\n]'
 
 DATASETS_MD = """
-**Dictionary (public datasets, read-only):**
+**Dictionary (public datasets, read-only, no account needed):**
 1. [NVIDIA SimReady](https://github.com/NVIDIA-Omniverse/simready-central): metric OpenUSD assets,
    e.g. [nvidia/simready-assets](https://huggingface.co/datasets/nvidia/simready-assets). License per package
    (e.g. CC-BY-4.0). Only geometry and the thumbnail are downloaded, not the ~1 GB of textures.
@@ -261,17 +230,14 @@ DATASETS_MD = """
    License per object; non-commercial (NC) and no-derivatives (ND) objects are skipped.
 3. Missing words: a primitive you choose (box, sphere, cylinder, cone, plane). Generation comes later.
 
-**Why sign in?** Building scenes needs no account: the datasets are public. Only *Back-translation* and
-*Check recognition* call a vision model ([Qwen2.5-VL](https://huggingface.co/Qwen/Qwen2.5-VL-7B-Instruct)
-via HF Inference), and those calls run on **your own** Hugging Face account. This Space stores no token,
-so nobody's credits are spent but the caller's.
+This Space only visualises and stores no token. Discuss the results in your chat
+(e.g. HuggingChat via MCP): every picture comes with a mini HTML page to build on.
 """
 
 with gr.Blocks(title="VisualLearningIdea") as demo:
     gr.Markdown("# English → 3D\nType with the words the 3D dictionary has. **Bold** = an object asset; "
                 "verbs and prepositions are relations between meshes.")
     gr.Markdown(DATASETS_MD)
-    gr.LoginButton()
     with gr.Row():
         sentence = gr.Textbox(label="Sentence", placeholder="the cat sat and the sun shone", scale=4)
         seed = gr.Textbox(label="Configuration seed", value="0", scale=1)
@@ -287,33 +253,37 @@ with gr.Blocks(title="VisualLearningIdea") as demo:
     with gr.Row():
         picture = gr.Image(label="Picture", type="filepath")
         model = gr.Model3D(label="3D")
+    with gr.Accordion("Mini HTML", open=False):
+        scene_preview = gr.HTML()
+        scene_file = gr.File(label="Download .html")
+        scene_html = gr.Code(label="HTML", language="html")
     with gr.Accordion("Ledger: freeze and change (serial side)", open=False):
         ledger = gr.Code(label="Ledger", language="json", interactive=True)
         changes = gr.Code(label="Changes", language="json", value=EXAMPLE_CHANGES, interactive=True)
         refine = gr.Button("Refine")
     with gr.Accordion("Simplification ladder", open=False):
-        with gr.Row():
-            item_id = gr.Textbox(label="Object item id", value="n1")
-            recog = gr.Checkbox(label="Check recognition with a vision model", value=False)
+        item_id = gr.Textbox(label="Object item id", value="n1")
         simp = gr.Button("Simplify")
         ladder_pics = gr.Gallery(label="Rungs", columns=4)
+        ladder_preview = gr.HTML()
+        ladder_html = gr.Code(label="HTML", language="html")
         ladder_report = gr.Code(label="Report", language="json")
         ladder_files = gr.File(label="GLB per rung", file_count="multiple")
-    with gr.Accordion("Back-translation", open=False):
-        back = gr.Button("Describe the scene")
-        back_out = gr.Code(label="Back-translation", language="json")
 
     gr.on([sentence.change, primitives.change], check_words, [sentence, primitives], words,
           api_name="check_words", trigger_mode="always_last") \
         .then(_suggestions, words, [status, suggest, missing], api_visibility="private")
     suggest.select(_complete, [sentence, suggest], sentence, api_visibility="private")
     use_prim.click(_use_primitive, [primitives, missing, shape], primitives, api_visibility="private")
-    go.click(translate_to_scene, [sentence, primitives, seed], [ledger, picture, model],
-             api_name="translate_to_scene")
-    refine.click(refine_scene, [ledger, changes, seed], [ledger, picture, model], api_name="refine_scene")
-    simp.click(simplify_item, [ledger, item_id, recog], [ladder_report, ladder_pics, ladder_files],
-               api_name="simplify_item")
-    back.click(describe_scene, [ledger, seed], back_out, api_name="describe_scene")
+    go.click(translate_to_scene, [sentence, primitives, seed], [ledger, picture, model, scene_html],
+             api_name="translate_to_scene") \
+        .then(_html_views, scene_html, [scene_preview, scene_file], api_visibility="private")
+    refine.click(refine_scene, [ledger, changes, seed], [ledger, picture, model, scene_html],
+                 api_name="refine_scene") \
+        .then(_html_views, scene_html, [scene_preview, scene_file], api_visibility="private")
+    simp.click(simplify_item, [ledger, item_id], [ladder_report, ladder_pics, ladder_files, ladder_html],
+               api_name="simplify_item") \
+        .then(lambda page: _html_views(page)[0], ladder_html, ladder_preview, api_visibility="private")
 
 if __name__ == "__main__":
     demo.launch(mcp_server=True)

vli/grammar.py

@@ -237,6 +237,7 @@ def check_words(sentence, primitives=None):
         entry = {"text": t["text"], "kind": t["kind"]}
         if t["kind"] == "noun":
             entry["available_in"] = LEXICON.counts(t["text"])
+            entry["maps_to"] = candidate_label(_object_decision(t["text"])["chosen"])  # what you'd get
         elif t["kind"] == "primitive":
             entry["primitive"] = primitives[t["text"]]
         words.append(entry)

vli/html.py

@@ -0,0 +1,199 @@
+"""Mini HTML returned next to every picture.
+
+HTML is the final destination: a chat model reads this page, edits it and
+builds its own on it. The page is self-contained Three.js. Geometry is inlined
+at low poly (a rung of the simplification ladder), so it outlives Gradio's
+temporary file URLs and stays small enough for a model's context.
+"""
+import json
+
+import numpy as np
+
+from .scene import GLOW, _sky
+from .simplify import base_color, decimate
+
+THREE = "https://unpkg.com/three@0.160.0/"
+SCENE_FACE_BUDGET = 400   # per object in a scene page
+LADDER_MAX_FACES = 1000   # rungs above this are left to the GLB files
+
+
+def _hex(rgb):
+    return "#%02x%02x%02x" % tuple(int(c) for c in rgb[:3])
+
+
+def _sky_hex(sun):
+    sky = _sky(sun)
+    return sky if isinstance(sky, str) else _hex([c * 255 for c in sky])
+
+
+def _geometry(mesh, budget):
+    m = decimate(mesh, budget) if len(mesh.faces) > budget else mesh
+    return {"faces": int(len(m.faces)),
+            "p": np.round(m.vertices, 3).ravel().tolist(),
+            "i": m.faces.ravel().astype(int).tolist()}
+
+
+def _object(oid, word, mesh, position, yaw_deg, cand=None, glow=False, budget=SCENE_FACE_BUDGET, label=None):
+    o = {"id": oid, "word": word, "label": label, "position": [round(float(c), 3) for c in position],
+         "yaw_deg": round(float(yaw_deg), 1), "color": _hex(GLOW if glow else base_color(mesh)),
+         "emits_light": glow}
+    if cand and cand.get("source") == "primitive":
+        o["primitive"] = {"shape": cand["shape"], "size": [round(float(e), 3) for e in mesh.extents]}
+    else:
+        o["mesh"] = _geometry(mesh, budget)
+    return o
+
+
+def scene_page(ledger, meshes, config):
+    sun = config["sun"]
+    objects = []
+    for it in ledger["items"]:
+        p = config["placements"].get(it["id"])
+        if it["kind"] != "object" or p is None:
+            continue
+        dec = it["decision"]
+        objects.append(_object(it["id"], it["word"], meshes[it["id"]], p["position"], p["yaw_deg"],
+                               cand=dec["chosen"], glow=bool(p.get("light")), label=dec.get("label")))
+    ground = None
+    if any(i["kind"] == "environment" and i["role"] == "plane" for i in ledger["items"]):
+        reach = max([abs(c) for o in objects if not o["emits_light"] for c in (o["position"][0], o["position"][2])]
+                    + [0.3])
+        ground = {"radius": round(1.6 * reach + 0.5, 3)}
+    data = {
+        "title": ledger["sentence"],
+        "reading": [{"word": t["text"], "kind": t["kind"], "commits": t["commits"]} for t in ledger["tokens"]],
+        "relations": [{"subject": i["subject"], "relation": i["relation"], "object": i["object"]}
+                      for i in ledger["items"] if i["kind"] == "relation"],
+        "unresolved": [{"question": q.get("question"), "default": q.get("default_chosen")}
+                       for q in ledger["unresolved"]],
+        "sky": _sky_hex(sun), "sun": sun, "ground": ground, "objects": objects,
+    }
+    return page(data)
+
+
+def ladder_page(item, rungs):
+    """Rungs left to right, from the most detailed embeddable one down to the box."""
+    objects, x = [], 0.0
+    for label, rung in rungs:
+        if len(rung.faces) > LADDER_MAX_FACES:
+            continue
+        hw = 0.5 * max(rung.extents[0], rung.extents[2])
+        objects.append(_object(f"rung{len(objects)}", item["word"], rung, [x + hw, 0, 0], 0,
+                               budget=LADDER_MAX_FACES, label=label))
+        x += 2 * hw + 0.3 * max(rung.extents[1], 0.1)
+    for o in objects:
+        o["position"][0] = round(o["position"][0] - x / 2, 3)
+    data = {"title": f"{item['word']}: simplification ladder",
+            "caption": "left → right: " + " · ".join(o["label"] for o in objects),
+            "sky": "#2a3346", "sun": None, "ground": None, "objects": objects}
+    return page(data)
+
+
+def page(data):
+    payload = json.dumps(data, separators=(",", ":")).replace("</", "<\\/")
+    return TEMPLATE.replace("__THREE__", THREE).replace("__TITLE__", _escape(data["title"])) \
+        .replace("__DATA__", payload)
+
+
+def _escape(s):
+    return s.replace("&", "&amp;").replace("<", "&lt;").replace(">", "&gt;")
+
+
+TEMPLATE = """<!doctype html>
+<html><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
+<title>__TITLE__</title>
+<style>html,body{margin:0;height:100%;overflow:hidden;font:13px system-ui,sans-serif}
+#cap{position:fixed;left:12px;bottom:12px;color:#fff;background:#0008;padding:6px 10px;border-radius:6px}</style>
+<script type="importmap">{"imports":{"three":"__THREE__build/three.module.js","three/addons/":"__THREE__examples/jsm/"}}</script>
+</head><body><div id="cap"></div>
+<script type="module">
+import * as THREE from "three";
+import {OrbitControls} from "three/addons/controls/OrbitControls.js";
+
+// Scene data from VisualLearningIdea: positions in metres, Y up, yaw about Y.
+// Objects carry inline low-poly geometry ("mesh") or a primitive spec.
+const D = __DATA__;
+
+const renderer = new THREE.WebGLRenderer({antialias: true});
+renderer.setPixelRatio(Math.min(devicePixelRatio, 2));
+renderer.setSize(innerWidth, innerHeight);
+renderer.shadowMap.enabled = true;
+document.body.appendChild(renderer.domElement);
+const scene = new THREE.Scene();
+scene.background = new THREE.Color(D.sky);
+scene.add(new THREE.HemisphereLight(0xffffff, 0x445533, 0.9));
+const camera = new THREE.PerspectiveCamera(45, innerWidth / innerHeight, 0.01, 1000);
+
+function geometryOf(o) {
+  if (o.primitive) {
+    const [w, h, d] = o.primitive.size;
+    const g = {sphere: () => new THREE.SphereGeometry(h / 2, 24, 16),
+               cylinder: () => new THREE.CylinderGeometry(w / 2, w / 2, h, 24),
+               cone: () => new THREE.ConeGeometry(w / 2, h, 24),
+               plane: () => new THREE.BoxGeometry(w, h, d),
+               box: () => new THREE.BoxGeometry(w, h, d)}[o.primitive.shape]();
+    g.translate(0, h / 2, 0);  // rest on y = 0 like every asset
+    return g;
+  }
+  const g = new THREE.BufferGeometry();
+  g.setAttribute("position", new THREE.Float32BufferAttribute(o.mesh.p, 3));
+  g.setIndex(o.mesh.i);
+  g.computeVertexNormals();
+  return g;
+}
+
+const frame = new THREE.Box3();
+for (const o of D.objects) {
+  const mat = o.emits_light
+    ? new THREE.MeshBasicMaterial({color: o.color})
+    : new THREE.MeshStandardMaterial({color: o.color, roughness: 0.85, flatShading: true, side: THREE.DoubleSide});
+  const m = new THREE.Mesh(geometryOf(o), mat);
+  m.name = o.id;
+  m.position.fromArray(o.position);
+  m.rotation.y = THREE.MathUtils.degToRad(o.yaw_deg);
+  m.castShadow = !o.emits_light;
+  m.receiveShadow = true;
+  scene.add(m);
+  if (!o.emits_light) frame.expandByObject(m);
+}
+if (frame.isEmpty()) frame.setFromCenterAndSize(new THREE.Vector3(), new THREE.Vector3(1, 1, 1));
+const center = frame.getCenter(new THREE.Vector3());
+const radius = Math.max(frame.getSize(new THREE.Vector3()).length(), 0.3);
+
+if (D.ground) {
+  const g = new THREE.Mesh(new THREE.CircleGeometry(D.ground.radius, 64),
+                           new THREE.MeshStandardMaterial({color: 0x4d7c3a, roughness: 1}));
+  g.rotation.x = -Math.PI / 2;
+  g.receiveShadow = true;
+  scene.add(g);
+}
+
+const sun = new THREE.DirectionalLight(0xfff1d0, 2.2);
+if (D.sun) {
+  const el = THREE.MathUtils.degToRad(D.sun.elevation_deg), az = THREE.MathUtils.degToRad(D.sun.azimuth_deg);
+  const dir = new THREE.Vector3(Math.cos(el) * Math.sin(az), Math.sin(el), Math.cos(el) * Math.cos(az));
+  sun.position.copy(center).addScaledVector(dir, radius * 3);
+  sun.castShadow = !!D.sun.shadows;
+} else {
+  sun.position.copy(center).add(new THREE.Vector3(radius, radius * 2, radius * 1.2));
+}
+sun.target.position.copy(center);
+Object.assign(sun.shadow.camera, {left: -radius * 1.5, right: radius * 1.5, top: radius * 1.5,
+                                  bottom: -radius * 1.5, far: radius * 8});
+sun.shadow.mapSize.set(1024, 1024);
+scene.add(sun, sun.target);
+
+camera.position.set(center.x + radius * 0.9, center.y + radius * 0.6, center.z + radius * 1.2);
+const controls = new OrbitControls(camera, renderer.domElement);
+controls.target.copy(center);
+controls.update();
+
+document.getElementById("cap").textContent = D.caption || D.title;
+addEventListener("resize", () => {
+  camera.aspect = innerWidth / innerHeight;
+  camera.updateProjectionMatrix();
+  renderer.setSize(innerWidth, innerHeight);
+});
+renderer.setAnimationLoop(() => { controls.update(); renderer.render(scene, camera); });
+</script></body></html>
+"""

vli/lexicon.py

@@ -37,22 +37,24 @@ def _split_part(part):
 
 
 def simready_phrases(name):
-    """Words an asset name like 'appliance_handDryer_automatic_a01' can be looked up by.
+    """Words an asset name like 'interiorPart_sun_visor_a01' can be looked up by.
 
-    SimReady names read category_object_modifiers, so the second part is the
-    best match (rank 0); every other part is a weaker match (rank 1).
+    Names read category_object..., where the object can span several parts
+    ('sun_visor'). Only whole phrases and the final part are indexed, never a
+    lone modifier: 'sun' must not find a sun visor.
     """
     parts = [p for p in name.split("_") if p and not VARIANT.fullmatch(p)]
+    body = parts[1:] or parts  # drop the category prefix
     out = []
-    for i, part in enumerate(parts):
-        words = _split_part(part)
-        if not words:
-            continue
-        rank = 0 if (i == 1 or len(parts) == 1) else 1
-        out.append((" ".join(words), rank))
-        if len(words) > 1:
-            out.append((words[-1], rank + 1))
-    return out
+    phrase = " ".join(w for p in body for w in _split_part(p))
+    if phrase:
+        out.append((phrase, 0))  # 'sun visor', 'hand dryer automatic'
+    final = _split_part(body[-1]) if body else []
+    if final:
+        out.append((" ".join(final), 0))  # 'visor', 'bucky table'
+        if len(final) > 1:
+            out.append((final[-1], 1))  # 'table' from 'buckyTable': weaker
+    return list(dict.fromkeys(out))
 
 
 def objaverse_word(category):

vli/pipeline.py

@@ -9,7 +9,7 @@ import tempfile
 
 import numpy as np
 
-from . import assets, scene
+from . import assets, html, scene
 from .grammar import build_ledger, candidate_label, next_tier, parse_primitives, primitive_candidate
 
 
@@ -40,7 +40,7 @@ def outputs(ledger, seed):
     work = _workdir()
     png = scene.render_scene(ledger, meshes, config, os.path.join(work, "scene.png"))
     glb = scene.export_glb(ledger, meshes, config, os.path.join(work, "scene.glb"))
-    return json.dumps(ledger, indent=1), png, glb
+    return json.dumps(ledger, indent=1), png, glb, html.scene_page(ledger, meshes, config)
 
 
 def translate(sentence, primitives=None, seed=0):

vli/scene.py

@@ -15,6 +15,7 @@ from scipy.spatial import ConvexHull  # noqa: E402
 from .simplify import base_color, decimate  # noqa: E402
 
 GAP = 0.1
+GLOW = [255, 214, 107, 255]
 RENDER_FACE_BUDGET = 3000
 
 
@@ -46,7 +47,7 @@ def configure(ledger, meshes, seed=0):
 
     sun = None
     if lights:
-        sun = {"id": lights[0]["id"], "elevation_deg": float(rng.uniform(20, 70)),
+        sun = {"id": lights[0]["id"], "elevation_deg": float(rng.uniform(25, 65)),
                "azimuth_deg": float(rng.uniform(-150, 150)),
                "shadows": any(r["relation"] == "lights" for r in relations)}
 
@@ -89,9 +90,10 @@ def configure(ledger, meshes, seed=0):
 
     if sun:  # whatever shone sits in the sky along the light direction
         reach = max([abs(c) + _half_width(meshes[o]) for o, p in place.items()
-                     for c in (p["position"][0], p["position"][2])] + [1.0])
-        pos = sun_direction(sun) * 1.3 * reach  # shadows use the direction; distance is only for the view
+                     for c in (p["position"][0], p["position"][2])] + [0.3])
         for it in lights:
+            # shadows use the direction; distance only frames the view
+            pos = sun_direction(sun) * (1.5 * reach + 2 * _half_width(meshes[it["id"]]))
             place[it["id"]] = {"position": [float(c) for c in pos], "yaw_deg": 0.0, "light": True}
     return {"seed": seed, "placements": place, "sun": sun}
 
@@ -106,7 +108,7 @@ def _ground(ledger, placed):
     if not any(i["kind"] == "environment" and i["role"] == "plane" for i in ledger["items"]):
         return None
     lights = {i["id"] for i in ledger["items"] if i.get("emits_light")}
-    reach = max([np.abs(m.bounds[:, [0, 2]]).max() for oid, m in placed.items() if oid not in lights] + [1.0])
+    reach = max([np.abs(m.bounds[:, [0, 2]]).max() for oid, m in placed.items() if oid not in lights] + [0.3])
     g = trimesh.creation.cylinder(radius=reach * 1.6, height=0.01, sections=48)
     g.apply_transform(trimesh.transformations.rotation_matrix(math.pi / 2, [1, 0, 0]))
     g.apply_translation([0, -0.005, 0])
@@ -119,6 +121,8 @@ def placed_meshes(ledger, meshes, config):
     for oid, p in config["placements"].items():
         m = meshes[oid].copy()
         m.apply_transform(transform(p))
+        if p.get("light"):  # a light source glows: warm, flat colour
+            m.visual = trimesh.visual.ColorVisuals(m, face_colors=np.tile(GLOW, (len(m.faces), 1)))
         out[oid] = m
     return out
 
@@ -150,9 +154,11 @@ def _to_axes(v):
     return np.stack([v[..., 0], -v[..., 2], v[..., 1]], axis=-1)
 
 
-def _shade(mesh, light, color):
-    n = mesh.face_normals
-    k = 0.35 + 0.65 * np.clip(n @ light, 0, 1)
+def _shade(mesh, light, color, glow=False):
+    if glow:
+        k = np.ones(len(mesh.faces))
+    else:  # two-sided: Objaverse meshes often have flipped faces
+        k = 0.45 + 0.55 * np.abs(mesh.face_normals @ light)
     rgb = np.clip(color[:3] / 255.0 * k[:, None], 0, 1)
     return np.c_[rgb, np.ones(len(rgb))]
 
@@ -187,11 +193,11 @@ def render(meshes_by_id, path, sun=None, ground=None, title=None):
             ax.add_collection3d(Poly3DCollection([_to_axes(poly)], facecolors=[(0, 0, 0, 0.35)], zorder=1))
 
     tris, colors = [], []
-    for m in meshes_by_id.values():
+    for oid, m in meshes_by_id.items():
         color = base_color(m)
         r = decimate(m, RENDER_FACE_BUDGET) if len(m.faces) > RENDER_FACE_BUDGET else m
         tris.append(r.triangles)
-        colors.append(_shade(r, light, color))
+        colors.append(_shade(r, light, color, glow=bool(sun) and oid == sun["id"]))
         pts.append(r.vertices)
     if tris:
         ax.add_collection3d(Poly3DCollection(_to_axes(np.concatenate(tris)), facecolors=np.concatenate(colors),

vli/vlm.py

@@ -1,35 +0,0 @@
-"""Back-translation: a vision model reads the picture back into English.
-
-Calls always use the *caller's* token, never one stored on the Space, so a
-public Space can't spend its owner's inference credits.
-"""
-import base64
-import os
-
-from huggingface_hub import InferenceClient
-
-VLM_MODEL = os.environ.get("VLM_MODEL", "Qwen/Qwen2.5-VL-7B-Instruct")
-SIGN_IN = ("The vision model runs on your own Hugging Face account: sign in first "
-           "(MCP callers: send your HF token as a Bearer Authorization header).")
-
-
-def ask(image_path, prompt, token, max_tokens=80):
-    if not token:
-        raise ValueError(SIGN_IN)
-    with open(image_path, "rb") as f:
-        data = base64.b64encode(f.read()).decode()
-    client = InferenceClient(token=token)
-    resp = client.chat_completion(
-        model=VLM_MODEL, max_tokens=max_tokens,
-        messages=[{"role": "user", "content": [
-            {"type": "image_url", "image_url": {"url": f"data:image/png;base64,{data}"}},
-            {"type": "text", "text": prompt}]}])
-    return resp.choices[0].message.content.strip()
-
-
-def describe(image_path, token):
-    return ask(image_path, "Describe this 3D scene in one short plain sentence.", token)
-
-
-def name_object(image_path, token):
-    return ask(image_path, "What single object is this? Answer with one or two words.", token, max_tokens=10)