Add v1: English -> 3D translation Space with MCP tools

Dictionary from SimReady and Objaverse assets (primitives only when chosen),
serial ledger with freeze/refine, seeded configurations, simplification
ladder, and back-translation. One Gradio app serves the UI and MCP.

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

README.md

@@ -11,4 +11,4 @@ pinned: false
 short_description: Visualisation and speed of input attempt
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+English → 3D translation with a simplification ladder, usable from the UI and as an MCP server. See [SPEC.md](SPEC.md).

SPEC.md

@@ -0,0 +1,115 @@
+# VisualLearningIdea: v1 spec
+
+Supersedes `visuallearning-handover.html`, which drifted over several HuggingChat
+sessions. `cat-sun-scene.html` stays as the UX reference for the serial reading.
+
+## Idea
+
+3D is a language. The Space **translates English into 3D**, the way you would
+translate English into Japanese. A picture is easier to take in than text, because
+the reader doesn't have to guess the exact picture. Once 3D exists it can be
+materialized (papercraft, origami, …). The **simplification ladder** shows how far
+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.
+
+## Translation terms
+
+| Translation | Here |
+|---|---|
+| Source → target language | English → 3D |
+| Dictionary | Ready assets: SimReady → Objaverse |
+| Grammar words | `the / a / and`: no geometry; a determiner opens a "which?" question |
+| 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 |
+
+## Dictionary
+
+- Tiers, each taken **on rejection**: `simready → objaverse → primitive → generation`.
+- **Available** = a SimReady or Objaverse asset exists (no construction). No asset
+  means not available, with no exceptions. The UI offers only available words, so
+  the user knows before submitting.
+- A missing word can be used only by **explicitly choosing a primitive** for it
+  (`box, sphere, cylinder, cone, plane`). In the UI the user picks one. Over MCP,
+  `check_words` returns `missing` and the user's model (e.g. in HuggingChat) decides:
+  rephrase, or pass `primitives_json` such as `{"sun": "sphere"}`.
+- Assets that **can't be used** are skipped and recorded in `decision.skipped`:
+  no license, NC (non-commercial) or ND (no derivatives; simplification is a
+  derivative), or no geometry.
+- SimReady: package list from `NVIDIA-Omniverse/simready-central/submissions/*`.
+  Only geometry USD + thumbnail are downloaded, because textures are ~98% of each
+  ~1 GB package. Assets are metric, so height comes from the asset.
+- Objaverse: LVIS categories (`lvis-annotations.json.gz`) are the word index; the
+  license comes from `metadata/<shard>.json.gz`. No real scale, so height is a
+  nominal default (an `unresolved` decision the user can set).
+- Light comes from the verb, not from a special word: whatever "shone" becomes the
+  light source and sits in the sky along the light direction.
+- The ground implied by "sat" (with no stated object) is a support plane created by
+  the relation. It is not a typed word, so it needs no asset. To exist, a thing needs
+  a reality to exist in: reading skips this, but visualising exposes it. So the
+  implied ground is also surfaced in `unresolved` ("cat sat on what?", default:
+  ground plane), for the discussion to accept or rephrase.
+
+## Serial side vs configuration side
+
+- **Serial (ledger)**: tokens in reading order, items each word commits, relations,
+  unresolved questions. **Freezing lives here.** Frozen items can't change; the
+  others can be swapped, rejected, resized or rerolled.
+- **Configuration**: once the serial side is resolved, any placement satisfying the
+  relations is valid. `seed` picks one (positions, yaw, sun direction).
+
+### Ledger shape
+
+```jsonc
+{
+  "sentence": "the cat sat and the sun shone",
+  "tokens": [{"index": 2, "text": "sat", "kind": "verb", "commits": ["ground", "r2"], "opens": []}],
+  "items": [
+    {"id": "n1", "kind": "object", "word": "cat", "token": 1, "frozen": false,
+     "decision": {"tier": "objaverse", "chosen": {…}, "alternatives": […],
+                  "rejected_tiers": [], "skipped": [], "label": "cat"},
+     "height_m": {"value": 0.3, "source": "default"}, "license": "by"},
+    {"id": "ground", "kind": "environment", "role": "plane", "implied_by": 2},
+    {"id": "r2", "kind": "relation", "relation": "on", "subject": "n1", "object": "ground"},
+    {"id": "n5", "kind": "object", "word": "sun", "emits_light": true,
+     "decision": {"tier": "primitive", "chosen": {"source": "primitive", "shape": "sphere"}, …}},
+    {"id": "r6", "kind": "relation", "relation": "lights", "subject": "n5", "object": "scene"}
+  ],
+  "unresolved": [{"id": "q0", "about": "n1", "question": "which cat?", "default_chosen": "cat", "alternatives": […]}],
+  "configuration": {"seed": 0, "placements": {"n1": {"position": [0, 0, 0], "yaw_deg": 12}}, "sun": {…}}
+}
+```
+
+Relations: `on, under, beside, near, behind, in_front_of, above, faces, lights`.
+Verbs: `sat/stood/lay/rested` → `on` (ground implied), `shone/glowed` → `lights`
+(shadows only turn on with this coupling), `faced` → `faces`.
+
+## MCP tools
+
+| 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 |
+
+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.
+
+Secrets: `HF_TOKEN` (vision model calls). Optional env: `VLM_MODEL`, `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.
+- 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
+  the ground plane only.

app.py

@@ -0,0 +1,253 @@
+"""VisualLearningIdea: translate English into 3D, then see how far 3D can simplify.
+
+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".
+"""
+import json
+import os
+import re
+import tempfile
+import threading
+
+import gradio as gr
+
+from vli import assets, pipeline, scene, simplify, vlm
+from vli.grammar import check_words as _check_words
+from vli.lexicon import LEXICON, PRIMITIVE_SHAPES
+
+threading.Thread(target=LEXICON.ensure, daemon=True).start()  # warm the dictionary
+
+
+def _fail(e):
+    raise gr.Error(str(e))
+
+
+# ---------------- MCP tools ----------------
+
+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.
+
+    Args:
+        sentence: The English sentence, complete or partly typed.
+        primitives_json: JSON object mapping missing words to shapes, e.g. {"sun": "sphere"}.
+            Shapes: box, sphere, cylinder, cone, plane.
+
+    Returns:
+        JSON string: {"ok", "words": [{text, kind, available_in | primitive}], "missing",
+        "primitive_shapes", "completions"}.
+    """
+    try:
+        return json.dumps(_check_words(sentence, json.loads(primitives_json or "{}")))
+    except Exception as e:
+        _fail(e)
+
+
+def translate_to_scene(sentence: str, primitives_json: str = "{}", seed: int = 0) -> tuple[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).
+
+    Args:
+        sentence: A sentence using available words, e.g. "the cat sat and the sun shone".
+        primitives_json: JSON object mapping missing words to shapes, e.g. {"sun": "sphere"}.
+        seed: Picks one of the configurations that satisfy the ledger (positions, facing, sun).
+
+    Returns:
+        (ledger JSON string, rendered PNG, GLB scene file).
+    """
+    try:
+        return pipeline.translate(sentence, json.loads(primitives_json or "{}"), int(seed))
+    except Exception as e:
+        _fail(e)
+
+
+def refine_scene(ledger_json: str, changes_json: str = "[]", seed: int = 0) -> tuple[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", "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`.
+
+    Args:
+        ledger_json: Ledger JSON from translate_to_scene or a previous refine_scene.
+        changes_json: JSON list of changes, as above.
+        seed: Picks the configuration, and the alternatives for a reroll.
+
+    Returns:
+        (ledger JSON string, rendered PNG, GLB scene file).
+    """
+    try:
+        ledger = json.loads(ledger_json)
+        pipeline.apply_changes(ledger, json.loads(changes_json or "[]"), int(seed))
+        return pipeline.outputs(ledger, int(seed))
+    except Exception as e:
+        _fail(e)
+
+
+def simplify_item(ledger_json: str, item_id: str, check_recognition: bool = False) -> tuple[str, list, list]:
+    """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.
+
+    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 (needs HF_TOKEN; slower).
+
+    Returns:
+        (report JSON string, gallery of rung pictures, GLB file per rung).
+    """
+    try:
+        ledger = json.loads(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_")
+        report, gallery, files = {"item": item_id, "word": item["word"], "rungs": []}, [], []
+        for k, (label, rung) in enumerate(simplify.ladder(mesh)):
+            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)
+                entry["named_as"] = answer
+                entry["recognized"] = item["word"].lower() in answer.lower()
+            report["rungs"].append(entry)
+            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: int = 0) -> 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.
+
+    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:
+        ledger = json.loads(ledger_json)
+        meshes = pipeline.settle_all(ledger)
+        config = scene.configure(ledger, meshes, int(seed))
+        png = scene.render_scene(ledger, meshes, config, os.path.join(tempfile.mkdtemp(), "scene.png"))
+        text = vlm.describe(png)
+        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)
+    except Exception as e:
+        _fail(e)
+
+
+# ---------------- UI-only helpers ----------------
+
+def _suggestions(words_json):
+    data = json.loads(words_json or "{}")
+    marks = []
+    for w in data.get("words", []):
+        if w["kind"] == "unknown":
+            marks.append(f"~~{w['text']}~~")
+        elif w["kind"] == "noun":
+            marks.append(f"**{w['text']}**")
+        elif w["kind"] == "primitive":
+            marks.append(f"_{w['text']}_ ({w['primitive']})")
+        else:
+            marks.append(w["text"])
+    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", [])
+    return (status, gr.update(choices=data.get("completions", []), value=None),
+            gr.update(choices=missing, value=missing[0] if missing else None))
+
+
+def _complete(sentence, choice):
+    if not choice:
+        return sentence
+    return re.sub(r"[A-Za-z]*$", "", sentence) + choice + " "
+
+
+def _use_primitive(primitives_json, word, shape):
+    prims = json.loads(primitives_json or "{}")
+    if word:
+        prims[word] = shape
+    return json.dumps(prims)
+
+
+EXAMPLE_CHANGES = '[\n  {"id": "n1", "freeze": true},\n  {"reroll": true}\n]'
+
+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.")
+    with gr.Row():
+        sentence = gr.Textbox(label="Sentence", placeholder="the cat sat and the sun shone", scale=4)
+        seed = gr.Number(label="Configuration seed", value=0, precision=0, scale=1)
+    status = gr.Markdown()
+    suggest = gr.Radio(label="Suggestions", choices=[], interactive=True)
+    with gr.Row():
+        missing = gr.Dropdown(label="Missing word", choices=[], interactive=True)
+        shape = gr.Dropdown(label="Primitive", choices=PRIMITIVE_SHAPES, value="box", interactive=True)
+        use_prim = gr.Button("Use primitive")
+    primitives = gr.Code(label="Primitives", language="json", value="{}", interactive=True)
+    words = gr.Code(label="Word check", language="json", visible=False)
+    go = gr.Button("Translate", variant="primary")
+    with gr.Row():
+        picture = gr.Image(label="Picture", type="filepath")
+        model = gr.Model3D(label="3D")
+    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)
+        simp = gr.Button("Simplify")
+        ladder_pics = gr.Gallery(label="Rungs", columns=4)
+        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")
+
+if __name__ == "__main__":
+    demo.launch(mcp_server=True)

cat-sun-scene.html

@@ -0,0 +1,476 @@
+
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>The cat sat and the sun shone — serial reading + scene</title>
+<style>
+  :root{--bg:#0e1116;--panel:#151a22e6;--border:#2a3242;--text:#e8ecf4;--muted:#93a0b4;--accent:#ffc857;--accent2:#7ee0a3;--warn:#f0b429}
+  *{box-sizing:border-box;margin:0}
+  body{background:var(--bg);color:var(--text);font:14px/1.55 -apple-system,"Segoe UI",Roboto,sans-serif;overflow:hidden}
+  #scene{position:fixed;inset:0}
+  #panel{position:fixed;top:16px;left:16px;width:352px;max-height:calc(100vh - 32px);overflow-y:auto;background:var(--panel);border:1px solid var(--border);border-radius:12px;padding:14px;backdrop-filter:blur(8px);z-index:10}
+  h1{font-size:15px;margin-bottom:6px}
+  .sub{color:var(--muted);font-size:12px;margin-bottom:10px}
+  .tabs{display:flex;gap:6px;margin-bottom:10px}
+  .tab{flex:1;text-align:center;padding:6px 0;border:1px solid var(--border);border-radius:8px;font-size:12.5px;cursor:pointer;color:var(--muted)}
+  .tab.active{color:var(--accent);border-color:var(--accent);background:#ffc85714}
+  .view{display:none}
+  .view.active{display:block}
+  .cap{min-height:48px;font-size:12.5px;background:#ffc85710;border:1px solid var(--border);border-radius:8px;padding:8px 10px;margin-bottom:10px}
+  .cap b{color:var(--accent)}
+  .btnrow{display:flex;gap:8px;margin-bottom:10px}
+  button{flex:1;background:var(--panel);border:1px solid var(--border);color:var(--text);border-radius:8px;padding:7px 0;font-size:12.5px;cursor:pointer}
+  button:hover{border-color:var(--accent)}
+  button.primary{background:#ffc85722;border-color:var(--accent)}
+  button:disabled{opacity:.4;cursor:default}
+  .section{margin-bottom:10px}
+  .label{font-size:11px;letter-spacing:1px;text-transform:uppercase;color:var(--accent2);margin-bottom:6px}
+  .ledger{display:flex;flex-direction:column;gap:4px}
+  .item{font-size:12px;padding:4px 8px;border-radius:6px;border:1px solid transparent;opacity:.38;transition:all .25s}
+  .item b{color:var(--accent)}
+  .item .alt{color:var(--muted);font-size:11px}
+  .item.done{opacity:1;border-color:var(--border)}
+  .item.active{opacity:1;border-color:var(--accent);background:#ffc85714}
+  .unres{border-left:3px solid var(--warn);padding-left:10px}
+  .unres div{color:var(--muted);font-size:12px;padding:2px 0}
+  .ctrl{margin:8px 0}
+  .ctrl label{display:flex;justify-content:space-between;font-size:12px;color:var(--muted);margin-bottom:3px}
+  input[type=range]{width:100%;accent-color:var(--accent)}
+  select{background:var(--bg);color:var(--text);border:1px solid var(--border);border-radius:6px;padding:4px 8px;font-size:12px;width:100%}
+  .note{font-size:11px;color:var(--muted);border-top:1px solid var(--border);padding-top:8px;margin-top:4px}
+  #hud{position:fixed;bottom:12px;right:16px;color:var(--muted);font-size:11px;background:var(--panel);border:1px solid var(--border);border-radius:8px;padding:6px 10px}
+  /* ---- serial reading: full-bleed linear timeline, starts right of sidebar ---- */
+  #reading{position:fixed;inset:0;display:none;overflow-x:auto;overflow-y:auto;padding:24px 40px 40px 396px}
+  #reading.active{display:block}
+  .railhead{margin-bottom:16px;color:var(--muted);font-size:12px}
+  .railhead b{color:var(--accent2)}
+  .rail{display:flex;align-items:flex-start;min-width:max-content}
+  .tokwrap{display:flex;flex-direction:column;align-items:center;position:relative;padding:0 16px}
+  .tokwrap:not(:last-child)::after{content:'';position:absolute;top:26px;left:calc(50% + 30px);width:calc(100% - 60px);height:2px;background:var(--border)}
+  .tokwrap.committed:not(:last-child)::after{background:var(--accent2)}
+  .tok{width:52px;height:52px;border-radius:50%;border:2px solid var(--border);display:flex;align-items:center;justify-content:center;font-size:12.5px;color:var(--muted);background:var(--panel);position:relative;z-index:1;transition:all .3s}
+  .tok.committed{border-color:var(--accent2);color:var(--text)}
+  .tok.active{border-color:var(--accent);color:var(--accent);background:#ffc85722;box-shadow:0 0 18px #ffc85744}
+  .tok.q::before{content:'?';position:absolute;top:-8px;right:-8px;background:var(--warn);color:#000;font-size:10px;font-weight:700;width:16px;height:16px;border-radius:50%;display:flex;align-items:center;justify-content:center}
+  .model{width:150px;height:112px;margin-top:10px;border:1px solid var(--border);border-radius:10px;background:#10131a;object-fit:cover;display:block}
+  .model.qbox{display:flex;align-items:center;justify-content:center;color:var(--warn);font-size:40px;font-weight:700}
+  .word{margin-top:8px;font-size:16px;color:var(--muted)}
+  .tokwrap.committed .word{color:var(--text)}
+  .tokwrap.active .word{color:var(--accent)}
+  .map{margin-top:4px;font-size:11.5px;color:var(--accent2);text-align:center;max-width:150px}
+  .commits{margin-top:8px;display:flex;flex-direction:column;gap:5px;max-width:150px}
+  .chip{font-size:10.5px;border:1px solid var(--border);border-radius:6px;padding:3px 7px;color:var(--muted);text-align:center;opacity:.35;transition:all .3s}
+  .chip.on{opacity:1;border-color:var(--accent2);color:var(--text)}
+  .chip.rel{border-color:#7eb8e0}
+  .chip.q{border-color:var(--warn);color:var(--warn)}
+</style>
+</head>
+<body>
+<div id="scene"></div>
+<div id="reading">
+  <div class="railhead"><b>SERIAL READING</b> — linear, no camera. Each word shows the model it commits (snapshotted from the same geometry the Scene tab uses). The sidebar no longer overlaps: the timeline starts to its right.</div>
+  <div class="rail" id="rail"></div>
+</div>
+
+<div id="panel">
+  <h1>“The cat sat and the sun shone”</h1>
+  <div class="sub">two independent steppers — serial reading (default) and scene</div>
+
+  <div class="tabs">
+    <div class="tab" id="tabScene">🌐 Scene</div>
+    <div class="tab active" id="tabSerial">📏 Serial reading</div>
+  </div>
+
+  <!-- SERIAL VIEW -->
+  <div class="view active" id="viewSerial">
+    <div class="cap" id="capSerial">Press <b>▶ step</b> — each word commits its models and items in reading order.</div>
+    <div class="btnrow"><button id="rPrev">◀</button><button id="rNext" class="primary">▶ step</button><button id="rAuto">⏩ auto</button></div>
+    <div class="note">Each word card in the timeline shows the <b>model snapshot</b> its commitment produces. Determiners (“the”) commit nothing — they stay <b style="color:var(--warn)">?</b>. “sat” is the compression star: one word, three commits.</div>
+  </div>
+
+  <!-- SCENE VIEW -->
+  <div class="view" id="viewScene">
+    <div class="cap" id="capScene">Scene stepper is independent — press <b>▶ step</b> to build the configuration item by item.</div>
+    <div class="btnrow"><button id="sPrev">◀</button><button id="sNext" class="primary">▶ step</button><button id="sAuto">⏩ auto</button></div>
+    <div class="section">
+      <div class="label">Ledger</div>
+      <div class="ledger" id="ledger">
+        <div class="item" data-i="1"><b>1 · ground_plane</b> — grass (implied by “sat”)</div>
+        <div class="item" data-i="2"><b>2 · form: cat</b> — orange tabby, stylized</div>
+        <div class="item" data-i="3"><b>3 · pose: sat</b> — haunches down, tail curled</div>
+        <div class="item" data-i="4"><b>4 · position</b> — left of center (frame decision)</div>
+        <div class="item" data-i="5"><b>5 · orient</b> — facing the sun (derived from 7)</div>
+        <div class="item" data-i="6"><b>6 · light_source: sun</b> — disc + warm light</div>
+        <div class="item" data-i="7"><b>7 · under-light-of</b> — coupling: shadow computed</div>
+        <div class="item" data-i="8"><b>8 · supported-by</b> — contact: haunches + paws</div>
+      </div>
+    </div>
+    <div class="section">
+      <div class="label">Unresolved</div>
+      <div class="unres">
+        <div>· “the (cat)” — <b style="color:var(--warn)">?</b> defaulted: tabby</div>
+        <div>· “the (sun)” — <b style="color:var(--warn)">?</b> defaulted: late afternoon</div>
+        <div>· ground material? — defaulted: grass</div>
+        <div>· aware of the sun? — defaulted: yes</div>
+      </div>
+    </div>
+    <div class="section">
+      <div class="label">Refinement (post-serial)</div>
+      <div class="ctrl"><label>Sun elevation <span id="elevV">35°</span></label><input type="range" id="elev" min="5" max="85" value="35"></div>
+      <div class="ctrl"><label>Sun azimuth <span id="azV">-40°</span></label><input type="range" id="az" min="-180" max="180" value="-40"></div>
+      <div class="ctrl"><label>Cat orientation</label>
+        <select id="facing">
+          <option value="toward">facing the sun</option>
+          <option value="away">back to the sun</option>
+          <option value="profile">profile to the sun</option>
+        </select>
+      </div>
+    </div>
+  </div>
+</div>
+
+<div id="hud">drag = orbit · scroll = zoom · ◀ ▶ keys step the active tab</div>
+
+<script type="importmap">
+{"imports":{
+  "three":"https://unpkg.com/three@0.160.0/build/three.module.js",
+  "three/addons/":"https://unpkg.com/three@0.160.0/examples/jsm/"
+}}
+</script>
+<script type="module">
+import * as THREE from 'three';
+import {OrbitControls} from 'three/addons/controls/OrbitControls.js';
+
+/* ================= reusable model builders (shared by scene + snapshots) ================= */
+function matFur(){ return new THREE.MeshStandardMaterial({color:0xd9822b, roughness:0.9}); }
+function matDark(){ return new THREE.MeshStandardMaterial({color:0xb5641c, roughness:0.9}); }
+function shadowify(g){ g.traverse(o=>{ if(o.isMesh) o.castShadow = true; }); return g; }
+
+function buildGround(){
+  const g = new THREE.Mesh(new THREE.CircleGeometry(40, 64),
+    new THREE.MeshStandardMaterial({color:0x4d7c3a, roughness:1}));
+  g.rotation.x = -Math.PI/2; g.receiveShadow = true; return g;
+}
+function buildGroundSmall(){
+  const g = new THREE.Mesh(new THREE.CircleGeometry(3.2, 48),
+    new THREE.MeshStandardMaterial({color:0x4d7c3a, roughness:1}));
+  g.rotation.x = -Math.PI/2; g.receiveShadow = true; return g;
+}
+function buildForm(){
+  const fur = matFur(), furDark = matDark();
+  const g = new THREE.Group();
+  const body = new THREE.Mesh(new THREE.SphereGeometry(0.75, 20, 16), fur);
+  body.scale.set(1, 1.25, 0.9); body.position.y = 0.85; g.add(body);
+  const chest = new THREE.Mesh(new THREE.SphereGeometry(0.5, 18, 14), fur);
+  chest.scale.set(0.9, 1.05, 0.7); chest.position.set(0, 0.95, 0.25); g.add(chest);
+  const head = new THREE.Mesh(new THREE.SphereGeometry(0.42, 20, 16), fur);
+  head.scale.set(1, 0.92, 0.95); head.position.set(0, 1.95, 0.18); g.add(head);
+  [-0.28, 0.28].forEach(x=>{
+    const ear = new THREE.Mesh(new THREE.ConeGeometry(0.13, 0.3, 4), furDark);
+    ear.position.set(x, 2.32, 0.15); g.add(ear);
+  });
+  [-0.16, 0.16].forEach(x=>{
+    const eye = new THREE.Mesh(new THREE.SphereGeometry(0.055, 10, 10),
+      new THREE.MeshStandardMaterial({color:0x222a18, emissive:0x0a1400}));
+    eye.position.set(x, 2.0, 0.52); g.add(eye);
+  });
+  for(let i=0;i<3;i++){
+    const s = new THREE.Mesh(new THREE.TorusGeometry(0.72, 0.035, 6, 24, Math.PI*0.7), furDark);
+    s.position.set(0, 0.75+i*0.32, 0); s.rotation.x = Math.PI/2; s.rotation.z = Math.PI*0.15; g.add(s);
+  }
+  return shadowify(g);
+}
+function buildPose(){
+  const fur = matFur(), furDark = matDark();
+  const g = new THREE.Group();
+  [-0.62, 0.62].forEach(x=>{
+    const h = new THREE.Mesh(new THREE.SphereGeometry(0.34, 16, 12), fur);
+    h.scale.set(0.8, 1.1, 1.1); h.position.set(x, 0.5, -0.15); g.add(h);
+  });
+  [-0.28, 0.28].forEach(x=>{
+    const paw = new THREE.Mesh(new THREE.CapsuleGeometry(0.13, 0.3, 6, 10), fur);
+    paw.position.set(x, 0.16, 0.45); g.add(paw);
+  });
+  const curve = new THREE.CatmullRomCurve3([
+    new THREE.Vector3(0.15,0.55,-0.55), new THREE.Vector3(0.75,0.18,-0.25),
+    new THREE.Vector3(0.85,0.1,0.35), new THREE.Vector3(0.35,0.08,0.6)]);
+  g.add(new THREE.Mesh(new THREE.TubeGeometry(curve, 32, 0.09, 8, false), furDark));
+  return shadowify(g);
+}
+function buildSupport(){
+  const m = new THREE.MeshBasicMaterial({color:0x7ee0a3, transparent:true, opacity:0.75});
+  const g = new THREE.Group();
+  [[-0.28,0.45,0.14,0.2],[0.28,0.45,0.14,0.2],[-0.62,-0.15,0.2,0.27],[0.62,-0.15,0.2,0.27]].forEach(([x,z,r1,r2])=>{
+    const ring = new THREE.Mesh(new THREE.RingGeometry(r1, r2, 24), m);
+    ring.rotation.x = -Math.PI/2; ring.position.set(x, 0.02, z); g.add(ring);
+  });
+  return g;
+}
+function buildSunDisc(){
+  return new THREE.Mesh(new THREE.SphereGeometry(1.1, 24, 24), new THREE.MeshBasicMaterial({color:0xffd66b}));
+}
+
+/* ================= token spec (output format of parse_sentence_to_items) ================= */
+const TOKENS = [
+  {word:'the', map:'determiner → ?', unresolved:true, model:'q', commits:[],
+   cap:'<b>“the”</b> — commits nothing; opens a <b style="color:var(--warn)">?</b>: WHICH cat? Reading skipped it; the ledger must not.'},
+  {word:'cat', map:'cat = model (form)', unresolved:false, model:'cat',
+   commits:['form: tabby model','+position default (frame)','unresolved: pose pending'],
+   cap:'<b>“cat”</b> — a model enters. Form defaulted: tabby; placed left of center (frame decision riding along). No pose yet — floating form.'},
+  {word:'sat', map:'sat → pose + implied surface + support', unresolved:false, model:'sat',
+   commits:['ground_plane (implied)','pose: sitting','supported-by: contact'],
+   cap:'<b>“sat”</b> — one word, THREE commits: surface exists (implied), pose becomes geometry, contact established. Serial reading exposes this compression.'},
+  {word:'and', map:'connector — serial join', unresolved:false, model:'and',
+   commits:[], cap:'<b>“and”</b> — no geometry. Its job is serial: binding two clauses into one conversion, promising a second subject.'},
+  {word:'the', map:'determiner → ?', unresolved:true, model:'q', commits:[],
+   cap:'<b>“the”</b> again — another <b style="color:var(--warn)">?</b>. WHICH sun? A second unresolved decision, symmetric with the first.'},
+  {word:'sun', map:'sun = model (light source)', unresolved:false, model:'sun',
+   commits:['light_source: disc + warm light'],
+   cap:'<b>“sun”</b> — the second model enters: a light source. Light exists — but is not yet <i>related to</i> the cat.'},
+  {word:'shone', map:'shone → relation: acting-on-scene', unresolved:false, model:'shone',
+   commits:['under-light-of: coupling ON','orient default: facing sun'],
+   cap:'<b>“shone”</b> — a verb of relation: the sun ACTS on the scene. Shadow now computed from sun↔cat geometry; cat faces the light. <b>Configuration complete.</b>'}
+];
+
+/* ================= snapshot renderer: static model images per word ================= */
+const snapR = new THREE.WebGLRenderer({antialias:true, preserveDrawingBuffer:true});
+snapR.setSize(300, 224);
+snapR.shadowMap.enabled = true;
+snapR.shadowMap.type = THREE.PCFSoftShadowMap;
+
+function snapshot(build, camPos, lookAt){
+  const s = new THREE.Scene();
+  s.background = new THREE.Color(0x10131a);
+  const cam = new THREE.PerspectiveCamera(40, 300/224, 0.1, 200);
+  cam.position.set(...camPos); cam.lookAt(...lookAt);
+  s.add(new THREE.AmbientLight(0xffffff, 0.6));
+  const dl = new THREE.DirectionalLight(0xffffff, 2.2);
+  dl.position.set(4, 6, 5); dl.castShadow = true;
+  dl.shadow.mapSize.set(512, 512);
+  Object.assign(dl.shadow.camera, {left:-6, right:6, top:6, bottom:-6, far:40});
+  s.add(dl);
+  build(s);
+  snapR.render(s, cam);
+  return snapR.domElement.toDataURL();
+}
+function addShadowedLight(s, pos, color, intensity, target){
+  const dl = new THREE.DirectionalLight(color, intensity);
+  dl.position.set(...pos); dl.castShadow = true;
+  dl.shadow.mapSize.set(512, 512);
+  Object.assign(dl.shadow.camera, {left:-6, right:6, top:6, bottom:-6, far:40});
+  if(target) dl.target.position.set(...target);
+  s.add(dl); s.add(dl.target);
+}
+const SNAPSHOTS = {
+  ground: snapshot(s=>s.add(buildGroundSmall()), [3,4,5], [0,0,0]),
+  cat:    snapshot(s=>s.add(buildForm()), [2.2,2.2,3.4], [0,1.1,0]),
+  sat:    snapshot(s=>{
+            const d = buildGroundSmall(); s.add(d);
+            const c = new THREE.Group(); c.add(buildForm()); c.add(buildPose()); c.add(buildSupport()); s.add(c);
+          }, [2.6,2.4,3.8], [0,0.8,0]),
+  and:    snapshot(s=>{
+            const a = new THREE.Mesh(new THREE.SphereGeometry(0.4,16,12), matFur()); a.position.x = -1.1;
+            const b = new THREE.Mesh(new THREE.SphereGeometry(0.4,16,12), new THREE.MeshBasicMaterial({color:0xffd66b})); b.position.x = 1.1;
+            const link = new THREE.Mesh(new THREE.CylinderGeometry(0.06,0.06,2.2,8), new THREE.MeshStandardMaterial({color:0x93a0b4}));
+            link.rotation.z = Math.PI/2;
+            s.add(a, b, link);
+          }, [0,0.6,5], [0,0,0]),
+  sun:    snapshot(s=>s.add(buildSunDisc()), [0,0,4], [0,0,0]),
+  shone:  snapshot(s=>{
+            s.add(buildGroundSmall());
+            const c = new THREE.Group(); c.add(buildForm()); c.add(buildPose()); c.add(buildSupport()); s.add(c);
+            const sun = buildSunDisc(); sun.position.set(4, 2.2, -3); sun.scale.setScalar(0.8); s.add(sun);
+            addShadowedLight(s, [4,2.2,-3], 0xffe3a3, 2.5, [0,0.6,0]);
+          }, [3.2,2.4,4.6], [0,0.7,0])
+};
+
+/* ================= tabs ================= */
+const tabScene = document.getElementById('tabScene'), tabSerial = document.getElementById('tabSerial');
+const viewScene = document.getElementById('viewScene'), viewSerial = document.getElementById('viewSerial');
+function showTab(which){
+  tabScene.classList.toggle('active', which==='scene');
+  tabSerial.classList.toggle('active', which==='serial');
+  viewScene.classList.toggle('active', which==='scene');
+  viewSerial.classList.toggle('active', which==='serial');
+  document.getElementById('scene').style.visibility = which==='scene' ? 'visible' : 'hidden';
+  document.getElementById('reading').classList.toggle('active', which==='serial');
+  document.getElementById('hud').style.visibility = which==='scene' ? 'visible' : 'hidden';
+}
+tabScene.onclick = ()=>showTab('scene');
+tabSerial.onclick = ()=>showTab('serial');
+
+/* ================= build serial rail with models ================= */
+const rail = document.getElementById('rail');
+const tokEls = [];
+TOKENS.forEach((t,i)=>{
+  const wrap = document.createElement('div'); wrap.className='tokwrap';
+  const tok = document.createElement('div'); tok.className='tok'+(t.unresolved?' q':''); tok.textContent=i+1;
+  const model = document.createElement('div');
+  if(t.model === 'q'){ model.className='model qbox'; model.textContent='?'; }
+  else { model.className='model'; const img = document.createElement('img'); img.src = SNAPSHOTS[t.model]; img.style.width='100%'; img.style.height='100%'; img.style.objectFit='cover'; img.style.borderRadius='9px'; model.appendChild(img); }
+  const word = document.createElement('div'); word.className='word'; word.textContent=t.word;
+  const map = document.createElement('div'); map.className='map'; map.textContent=t.map;
+  const commits = document.createElement('div'); commits.className='commits';
+  t.commits.forEach(c=>{
+    const chip = document.createElement('div');
+    chip.className='chip'+(c.startsWith('under')||c.startsWith('supported')?' rel':'');
+    chip.textContent=c; commits.appendChild(chip);
+  });
+  wrap.append(tok, model, word, map, commits);
+  rail.appendChild(wrap);
+  tokEls.push({wrap, tok, chips:[...commits.children]});
+});
+
+/* ================= main scene ================= */
+const scene = new THREE.Scene();
+scene.background = new THREE.Color(0x2a3346);
+scene.fog = new THREE.Fog(0x2a3346, 40, 120);
+const camera = new THREE.PerspectiveCamera(50, innerWidth/innerHeight, 0.1, 300);
+camera.position.set(6, 3.4, 8);
+const renderer = new THREE.WebGLRenderer({antialias:true});
+renderer.setSize(innerWidth, innerHeight);
+renderer.setPixelRatio(Math.min(devicePixelRatio, 2));
+renderer.shadowMap.enabled = true;
+renderer.shadowMap.type = THREE.PCFSoftShadowMap;
+document.getElementById('scene').appendChild(renderer.domElement);
+const controls = new OrbitControls(camera, renderer.domElement);
+controls.target.set(0, 0.8, 0);
+controls.enableDamping = true;
+
+const ground = buildGround(); ground.visible = false; scene.add(ground);
+const cat = new THREE.Group();
+const formG = buildForm(), poseG = buildPose(), supG = buildSupport();
+formG.visible = false; poseG.visible = false; supG.visible = false;
+cat.add(formG, poseG, supG);
+cat.visible = false;
+scene.add(cat);
+
+const sunDisc = buildSunDisc(); sunDisc.scale.setScalar(2); sunDisc.visible = false; scene.add(sunDisc);
+const sunLight = new THREE.DirectionalLight(0xffe3a3, 0);
+sunLight.castShadow = false;
+sunLight.shadow.mapSize.set(2048, 2048);
+Object.assign(sunLight.shadow.camera, {left:-12, right:12, top:12, bottom:-12, far:80});
+scene.add(sunLight);
+const ambient = new THREE.AmbientLight(0x8098c0, 0.85); scene.add(ambient);
+
+/* ================= SERIAL stepper (independent) ================= */
+let serialStep = 0; // 0..7 tokens committed
+function applySerial(){
+  tokEls.forEach((el,i)=>{
+    el.tok.classList.toggle('committed', i < serialStep);
+    el.tok.classList.toggle('active', i === serialStep-1);
+    el.wrap.classList.toggle('committed', i < serialStep);
+    el.wrap.classList.toggle('active', i === serialStep-1);
+    el.chips.forEach(c=>c.classList.toggle('on', i < serialStep));
+  });
+  document.getElementById('capSerial').innerHTML = serialStep === 0
+    ? 'Press <b>▶ step</b> — each word commits its models and items in reading order.'
+    : TOKENS[serialStep-1].cap;
+  document.getElementById('rPrev').disabled = serialStep === 0;
+  document.getElementById('rNext').disabled = serialStep === 7;
+}
+function gotoSerial(n){ serialStep = Math.max(0, Math.min(7, n)); applySerial(); }
+
+/* ================= SCENE stepper (independent) ================= */
+let sceneStep = 0; // 0..8 items
+const catHome = new THREE.Vector3(0,0,0), catPlaced = new THREE.Vector3(-0.6,0,0);
+const targetPos = catHome.clone();
+let targetRotY = 0;
+const SCENE_CAPS = {
+  0:'Scene stepper is independent — press <b>▶ step</b> to build the configuration item by item.',
+  1:'<b>1 · ground_plane</b> — “sat” forces a surface. Defaulted: grass.',
+  2:'<b>2 · form: cat</b> — a body exists. No pose yet: floating form.',
+  3:'<b>3 · pose: sat</b> — haunches drop, tail curls. “Sat” became geometry.',
+  4:'<b>4 · position</b> — frame decision: left of center.',
+  5:'<b>5 · orient</b> — facing the sun (default derived from item 7).',
+  6:'<b>6 · light_source: sun</b> — light enters, sky turns. Not yet coupled.',
+  7:'<b>7 · under-light-of</b> — coupling ON: shadow computed from relations.',
+  8:'<b>8 · supported-by</b> — contact marked. Configuration complete.'
+};
+function applyScene(){
+  ground.visible = sceneStep >= 1;
+  cat.visible = sceneStep >= 2;
+  formG.visible = sceneStep >= 2;
+  poseG.visible = sceneStep >= 3;
+  targetPos.copy(sceneStep >= 4 ? catPlaced : catHome);
+  const sunOn = sceneStep >= 6;
+  sunDisc.visible = sunOn; sunLight.intensity = sunOn ? 3.0 : 0;
+  sunLight.castShadow = sceneStep >= 7;
+  scene.background.set(sunOn ? 0x87b5e0 : 0x2a3346);
+  scene.fog.color.set(sunOn ? 0x87b5e0 : 0x2a3346);
+  ambient.intensity = sunOn ? 0.55 : 0.85;
+  supG.visible = sceneStep >= 8;
+  document.querySelectorAll('#ledger .item[data-i]').forEach(el=>{
+    const i = +el.dataset.i;
+    el.classList.toggle('done', i <= sceneStep);
+    el.classList.toggle('active', i === sceneStep);
+  });
+  document.getElementById('capScene').innerHTML = SCENE_CAPS[sceneStep];
+  document.getElementById('sPrev').disabled = sceneStep === 0;
+  document.getElementById('sNext').disabled = sceneStep === 8;
+}
+function gotoScene(n){ sceneStep = Math.max(0, Math.min(8, n)); applyScene(); applyConfiguration(); }
+
+/* ================= wiring ================= */
+document.getElementById('rNext').onclick = ()=>gotoSerial(serialStep+1);
+document.getElementById('rPrev').onclick = ()=>gotoSerial(serialStep-1);
+document.getElementById('sNext').onclick = ()=>gotoScene(sceneStep+1);
+document.getElementById('sPrev').onclick = ()=>gotoScene(sceneStep-1);
+let autoS = null, autoR = null;
+document.getElementById('rAuto').onclick = ()=>{
+  if(autoR){ clearInterval(autoR); autoR=null; document.getElementById('rAuto').textContent='⏩ auto'; return; }
+  if(serialStep >= 7) gotoSerial(0);
+  document.getElementById('rAuto').textContent='⏸ stop';
+  autoR = setInterval(()=>{ if(serialStep >= 7){ clearInterval(autoR); autoR=null; document.getElementById('rAuto').textContent='⏩ auto'; return; } gotoSerial(serialStep+1); }, 1700);
+};
+document.getElementById('sAuto').onclick = ()=>{
+  if(autoS){ clearInterval(autoS); autoS=null; document.getElementById('sAuto').textContent='⏩ auto'; return; }
+  if(sceneStep >= 8) gotoScene(0);
+  document.getElementById('sAuto').textContent='⏸ stop';
+  autoS = setInterval(()=>{ if(sceneStep >= 8){ clearInterval(autoS); autoS=null; document.getElementById('sAuto').textContent='⏩ auto'; return; } gotoScene(sceneStep+1); }, 1400);
+};
+addEventListener('keydown', e=>{
+  const active = tabSerial.classList.contains('active') ? 'serial' : 'scene';
+  if(e.key==='ArrowRight') active==='serial' ? gotoSerial(serialStep+1) : gotoScene(sceneStep+1);
+  if(e.key==='ArrowLeft')  active==='serial' ? gotoSerial(serialStep-1) : gotoScene(sceneStep-1);
+});
+
+/* refinement controls */
+const DIST = 45;
+function applyConfiguration(){
+  const elev = THREE.MathUtils.degToRad(+document.getElementById('elev').value);
+  const az = THREE.MathUtils.degToRad(+document.getElementById('az').value);
+  const dir = new THREE.Vector3(Math.cos(elev)*Math.sin(az), Math.sin(elev), Math.cos(elev)*Math.cos(az));
+  sunDisc.position.copy(dir).multiplyScalar(DIST);
+  sunLight.position.copy(dir).multiplyScalar(20);
+  sunLight.target.position.set(targetPos.x, 0.5, targetPos.z);
+  scene.add(sunLight.target);
+  document.getElementById('elevV').textContent = document.getElementById('elev').value + '°';
+  document.getElementById('azV').textContent = document.getElementById('az').value + '°';
+}
+const FACINGS = {toward:180, away:0, profile:90};
+function applyFacing(){
+  const v = document.getElementById('facing').value;
+  targetRotY = THREE.MathUtils.degToRad(FACINGS[v] - document.getElementById('az').value);
+}
+['elev','az'].forEach(id=>document.getElementById(id).addEventListener('input', applyConfiguration));
+document.getElementById('facing').addEventListener('change', applyFacing);
+applyConfiguration(); applyFacing(); applySerial(); applyScene();
+
+addEventListener('resize', ()=>{
+  camera.aspect = innerWidth/innerHeight; camera.updateProjectionMatrix();
+  renderer.setSize(innerWidth, innerHeight);
+});
+
+(function animate(){
+  requestAnimationFrame(animate);
+  cat.position.lerp(targetPos, 0.08);
+  cat.rotation.y += (targetRotY - cat.rotation.y) * 0.08;
+  controls.update();
+  renderer.render(scene, camera);
+})();
+</script>
+</body>
+</html>

requirements.txt

@@ -0,0 +1,9 @@
+gradio[mcp]
+huggingface_hub
+requests
+numpy
+scipy
+trimesh>=4.6
+fast-simplification
+matplotlib
+usd-core

visuallearning-handover.html

@@ -0,0 +1,264 @@
+
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>VisualLearningIdea — Setup Handover</title>
+<style>
+  :root{
+    --bg:#0f1117; --panel:#171a23; --panel2:#1d212e; --border:#2a3040;
+    --text:#e6e9f0; --muted:#9aa3b5; --accent:#4f9cf9; --accent2:#7ee0a3;
+    --warn:#f0b429; --danger:#f26d6d; --code:#12141c;
+  }
+  *{box-sizing:border-box}
+  body{margin:0;background:var(--bg);color:var(--text);font:15px/1.6 -apple-system,"Segoe UI",Roboto,Helvetica,Arial,sans-serif;padding:0 0 80px}
+  .wrap{max-width:960px;margin:0 auto;padding:32px 24px}
+  header{border-bottom:1px solid var(--border);padding-bottom:24px;margin-bottom:32px}
+  h1{font-size:26px;margin:0 0 6px}
+  .sub{color:var(--muted);font-size:14px}
+  .badge{display:inline-block;background:var(--panel2);border:1px solid var(--border);border-radius:6px;padding:2px 10px;font-size:12px;color:var(--muted);margin-right:6px;margin-top:8px}
+  h2{font-size:20px;margin:40px 0 12px;padding-bottom:6px;border-bottom:1px solid var(--border)}
+  h3{font-size:16px;margin:24px 0 8px;color:var(--accent)}
+  p{margin:8px 0}
+  .panel{background:var(--panel);border:1px solid var(--border);border-radius:10px;padding:16px 20px;margin:16px 0}
+  .warn{border-left:4px solid var(--warn)}
+  .ok{border-left:4px solid var(--accent2)}
+  .info{border-left:4px solid var(--accent)}
+  table{width:100%;border-collapse:collapse;margin:14px 0;font-size:14px}
+  th,td{text-align:left;border:1px solid var(--border);padding:8px 12px;vertical-align:top}
+  th{background:var(--panel2);color:var(--muted);font-weight:600}
+  code{background:var(--code);border:1px solid var(--border);border-radius:4px;padding:1px 6px;font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,monospace;font-size:13px;color:#a8d3ff}
+  pre{background:var(--code);border:1px solid var(--border);border-radius:8px;padding:14px 16px;overflow-x:auto;font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,monospace;font-size:13px;line-height:1.55;color:#d7e3f4}
+  pre code{background:none;border:none;padding:0;color:inherit}
+  .task{display:flex;gap:10px;align-items:flex-start;padding:8px 0;border-bottom:1px dashed var(--border)}
+  .task:last-child{border-bottom:none}
+  .task input{margin-top:4px;accent-color:var(--accent2)}
+  .task label{cursor:pointer}
+  .task .why{color:var(--muted);font-size:13px;display:block}
+  .phase{color:var(--muted);font-size:12px;letter-spacing:1px;text-transform:uppercase;margin:20px 0 4px}
+  a{color:var(--accent);text-decoration:none}
+  a:hover{text-decoration:underline}
+  ul{margin:8px 0;padding-left:22px}
+  .kicker{color:var(--accent2);font-weight:600}
+  .flow{display:flex;flex-wrap:wrap;gap:8px;align-items:center;margin:14px 0}
+  .flow .node{background:var(--panel2);border:1px solid var(--border);border-radius:8px;padding:8px 12px;font-size:13px}
+  .flow .arrow{color:var(--muted)}
+  footer{margin-top:48px;color:var(--muted);font-size:12px;border-top:1px solid var(--border);padding-top:16px}
+</style>
+</head>
+<body>
+<div class="wrap">
+
+<header>
+  <h1>🐠 VisualLearningIdea — Setup Handover</h1>
+  <div class="sub">Handover doc for Claude Code / Codex · Owner: <b>KwabsHug</b> · Prepared 2026-10-23</div>
+  <span class="badge">hf.co/spaces/KwabsHug/VisualLearningIdea</span>
+  <span class="badge">SDK: Gradio 6.27.0</span>
+  <span class="badge">Python 3.12</span>
+  <span class="badge">MCP target</span>
+</header>
+
+<h2>1. Mission</h2>
+<div class="panel info">
+<p><span class="kicker">Core idea:</span> treat the <b>morphism between representations as a language</b> — i.e., comprehension. A natural-language sentence goes in; the system returns a <b>serial, ordered list of decision items</b>; that serial form is discussable/refinable in conversation; and it ultimately resolves into a <b>natural 3D configuration</b>.</p>
+<p><span class="kicker">The comprehension gradient (why this matters):</span> take <i>"the cat sat and the sun shone."</i></p>
+<ul>
+<li><b>Reading is decision-free</b> — comprehension happens implicitly. Every mini-decision (how big is the cat? facing where? how high is the sun?) is resolved silently by convention, defaults, and priors. Nothing surfaces.</li>
+<li><b>Drawing forces decisions to surface</b> — you cannot make a mark without committing to position, pose, scale, proportion. The drawing is a ledger of forced decisions.</li>
+<li><b>3D goes further: it allows configurations, not separate images.</b> A 3D scene is a web of relations where decisions propagate. A cat on a ground plane plus a sun in the sky become <i>coupled</i>: the sun's elevation fixes the shadow's direction; the cat's orientation determines the shadow's shape; support and occlusion relations emerge that the sentence never stated and no individual 2D view could contain. The 3D result holds information beyond any single rendering of it.</li>
+</ul>
+<pre><code>Sentence → DECISION LEDGER (serial, ordered, dependency-aware, with unresolved choices surfaced)
+        → [discussion / refinement loop: interrogate the unresolved decisions]
+        → 3D CONFIGURATION  (the UNDERSTANDING PROXY: relational scene — geometry + light +
+                             support + orientation — not separate images)
+        → MATERIALIZATION   (the LAST step: physical items for each word / the whole scene —
+                             papercraft nets, origami crease patterns, printable parts,
+                             electronic components + wiring, or a mix)</code></pre>
+<p>The serial order is not cosmetic — it is the <b>narrative order the sentence itself imposes</b> (and folding is inherently sequential too). The item list IS the intermediate representation (IR) of the language: a record of the decisions that reading hides. The 3D configuration must be derivable from the serial form alone — and it must encode <b>relations between items</b>, not just items.</p>
+<p><span class="kicker">Materialization is downstream of understanding, not part of it:</span> origami/papercraft is a <b>reality output</b> — one fabrication channel chosen <i>after</i> the 3D proxy has done its job of making comprehension inspectable. The same ledger can materialize differently: pure papercraft (fold a net per item), an Arduino project with papercraft/origami props (electronic components for behavior + folded sheets for form), 3D-printed parts, or a mix. The ledger must therefore stay materialization-agnostic; materialization routes are chosen per item in the final stage.</p>
+</div>
+
+<h2>2. Current state (verified 2026-10-23)</h2>
+<table>
+<tr><th>Item</th><th>Status</th></tr>
+<tr><td>Space repo exists</td><td><code>hf://spaces/KwabsHug/VisualLearningIdea</code></td></tr>
+<tr><td>README</td><td><code>sdk: gradio</code>, <code>sdk_version: 6.27.0</code>, <code>python_version: '3.12'</code>, <code>app_file: app.py</code>, pinned: false. Short description: "Visualisation and speed of input attempt" (may be updated).</td></tr>
+<tr><td>app.py</td><td><b>Does not exist yet</b> — repo contains only README + .gitattributes</td></tr>
+<tr><td>Owner account</td><td>PRO account → ZeroGPU available (40 min/day quota), can host up to 10 ZeroGPU Spaces</td></tr>
+<tr><td>Existing assets to reuse</td><td>Sibling Space <code>KwabsHug/GameConfigIdea</code> (Gradio, ZeroGPU, uses gradio_client + InferenceClient + local Kokoro) — reference for patterns that already work on this account</td></tr>
+</table>
+
+<h2>3. Target tool surface (MCP)</h2>
+<p>The Space must launch with <code>demo.launch(mcp_server=True)</code> so each public function becomes an MCP tool callable from HuggingChat / Claude / Codex. Tool exposure is controlled by <b>type hints + docstrings</b> (they become the tool description the LLM reads). Set <code>api_name=False</code> on every helper function that should NOT become a tool.</p>
+
+<h3>Planned tools (v1 contract)</h3>
+<pre><code>def parse_sentence_to_items(sentence: str) -> str:
+    """Decompose a natural-language sentence into a serial, ordered ledger
+    (the intermediate representation of the morphism). The output drives BOTH
+    views of the reference UI: a flat serial token reading and a 3D scene.
+    Structure (shaped by the cat-sun reference build — see section 9):
+      tokens:    [{word, index, commits: [item_indices], opens: [question_ids]}]
+                 — per-token attribution. Determiners commit nothing but open
+                 unresolved "?" entries. One word may commit several items
+                 (lexical compression: "sat" → surface + pose + support).
+      items:     [{index, kind, description,
+                   decision: {chosen, alternatives_considered},
+                   params, depends_on, stage_direction}]
+                 — stage_direction is the reveal payload the renderer plays:
+                 {action: "spawn"|"move"|"orient"|"couple"|"mark",
+                  target, from, to, couples: [item_indices], ...}.
+                 Without it the player must be hand-coded per sentence.
+      unresolved:[{id, token_index, question, default_chosen, alternatives}]
+                 — the discussion loop's agenda.
+    Args:
+        sentence: A plain-English sentence or scene description.
+    Returns:
+        JSON string with keys: tokens, items, unresolved.
+    """
+
+def items_to_fold(items_json: str) -> str:
+    """Convert serial construction items into a crease pattern in FOLD format.
+    Args:
+        items_json: JSON string produced by parse_sentence_to_items.
+    Returns:
+        JSON string: {"fold": {...FOLD document...}, "warnings": [...]}
+    """
+
+def simulate_fold(fold_json: str) -> str:
+    """Simulate folding a FOLD-format crease pattern and export the folded
+    3D state as OBJ/STL (plus a foldability report).
+    Args:
+        fold_json: FOLD-format JSON (from items_to_fold or user upload URL).
+    Returns:
+        File path/URL of the folded mesh + foldability diagnostics.
+    """
+
+def unfold_mesh_to_papercraft(mesh_url: str) -> str:
+    """Reverse morphism: unfold a 3D mesh (STL/OBJ/PLY/OFF URL) into a
+    2D papercraft net (SVG files with fold direction markings).
+    Args:
+        mesh_url: Public http(s) URL to the mesh file.
+    Returns:
+        File paths/URLs of the generated SVG components.
+    """
+
+def materialize_scene(items_json: str, route: str = "papercraft") -> str:
+    """Materialize a validated scene ledger into physical outputs — the LAST
+    step of the morphism: real items for each word / the whole scene.
+    Args:
+        items_json: JSON string produced by parse_sentence_to_items (or refined
+            via the discussion loop).
+        route: fabrication route — "papercraft" (unfold nets from the 3D
+            configuration and lay out sheets), "origami" (crease patterns),
+            "print3d" (STL per item), "electronics" (component list + wiring
+            notes for Arduino-type props), or "mixed".
+    Returns:
+        JSON string: {"parts": [{item_index, route, files: [urls], notes}],
+        "bom": [...bill of materials for electronic/physical components...]}
+    """</code></pre>
+
+<div class="panel warn">
+<b>File I/O rule:</b> MCP clients pass files as <b>public http(s) URLs</b>, never local paths. Every tool must download its input itself and return files (Gradio converts outputs to URLs automatically). Return formats: JSON strings or file outputs — avoid bare numpy arrays.
+</div>
+
+<h2>4. Architecture</h2>
+<div class="flow">
+  <div class="node">Sentence</div><div class="arrow">→</div>
+  <div class="node">parse_sentence_to_items<br><small>LLM (InferenceClient) → serial IR</small></div><div class="arrow">→</div>
+  <div class="node">items_to_fold<br><small>deterministic → FOLD doc</small></div><div class="arrow">→</div>
+  <div class="node">simulate_fold<br><small>OrigamiSimulator solver → STL/OBJ</small></div>
+</div>
+<div class="flow">
+  <div class="node">Mesh (STL/OBJ URL)</div><div class="arrow">→</div>
+  <div class="node">unfold_mesh_to_papercraft<br><small>paperfoldmodels → SVGs</small></div>
+</div>
+<p><b>FOLD format is the interchange hub</b> (OrigamiSimulator reads/writes it; rtori converts it; Ori Studio imports/exports it). Every pipeline becomes "X → FOLD → Y".</p>
+
+<h2>5. Phased work plan</h2>
+
+<div class="phase">Phase 0 — Scaffolding</div>
+<div class="task"><input type="checkbox" id="t1"><label for="t1"><b>Create <code>app.py</code></b> with a trivial Gradio UI + <code>demo.launch(mcp_server=True)</code><span class="why">Verify MCP badge appears on the Space page before adding real logic. Check endpoint: <code>https://kwabshug-visuallearningidea.hf.space/gradio_api/mcp/schema</code></span></label></div>
+<div class="task"><input type="checkbox" id="t2"><label for="t2"><b>Create <code>requirements.txt</code></b>: <code>gradio[mcp]</code>, <code>numpy</code>, <code>networkx</code>, <code>openmesh</code>, <code>huggingface_hub</code><span class="why">openmesh needs CMake + C++ at build time; if pip build fails on Spaces, pin a prebuilt wheel or vendor OpenMesh bindings (see pitfalls)</span></label></div>
+<div class="task"><input type="checkbox" id="t3"><label for="t3"><b>Vendor or pip-install <code>paperfoldmodels</code></b> (felixfeliz/paperfoldmodels, MIT) — copy the module into the repo for reproducibility<span class="why">3 deps only: numpy, OpenMesh, networkx. Algorithm: MST of dual graph → unfold → cut self-intersections</span></label></div>
+
+<div class="phase">Phase 1 — Reverse morphism first (easiest, no GPU)</div>
+<div class="task"><input type="checkbox" id="t4"><label for="t4"><b>Implement <code>unfold_mesh_to_papercraft(mesh_url)</code></b><span class="why">Download mesh URL → OpenMesh load → unfold → return SVG file(s). Test input: Stanford bunny STL. Prefer OBJ polygonal input over STL (see pitfalls)</span></label></div>
+<div class="task"><input type="checkbox" id="t5"><label for="t5"><b>Acceptance test:</b> call the tool via MCP from HuggingChat with a bunny OBJ URL; receive valid SVG(s)<span class="why">This alone makes the Space useful and proves the whole MCP chain</span></label></div>
+
+<div class="phase">Phase 2 — The language: sentence → serial items</div>
+<div class="task"><input type="checkbox" id="t6"><label for="t6"><b>Define the serial-item IR schema</b> (JSON) — a <b>decision ledger</b>, not an assembly list. Each item: <code>{index, kind, description, decision: {chosen, alternatives_considered}, params, depends_on}</code><span class="why">kinds v1: <code>sheet</code>, <code>fold</code> (mountain/valley, angle), <code>join</code> (glue/tab), <code>attach</code>, <code>repeat</code> — plus <b>scene-configuration kinds</b>: <code>ground_plane</code>, <code>light_source</code> (position/elevation), <code>pose</code>, <code>orient</code>, <code>relation</code> (<code>on</code>, <code>near</code>, <code>facing</code>, <code>under-light-of</code>, <code>supported-by</code>). Keep the vocabulary SMALL — it is the grammar of the language. Every implicit choice the sentence skipped becomes an explicit decision item or an <code>unresolved</code> entry.</span></label></div>
+<div class="task"><input type="checkbox" id="t7"><label for="t7"><b>Implement <code>parse_sentence_to_items</code></b> using <code>InferenceClient</code> (pattern already proven in GameConfigIdea)<span class="why">Prompt the LLM to emit ONLY the IR schema; return <code>unresolved</code> ambiguities so the chat can discuss them — this is the "discussion → more natural 3D" loop entry point</span></label></div>
+<div class="task"><input type="checkbox" id="t8"><label for="t8"><b>Unit-test determinism:</b> same sentence + same seed → identical item list</td></label></div>
+<div class="task"><input type="checkbox" id="t16"><label for="t16"><b>Add a ledger validator step</b> before items_to_fold / scene build<span class="why">Lesson from the reference build: the hand-written ledger missed a propagation decision (sky color stayed daytime-blue when sun elevation dropped to 5°). An LLM-generated ledger will have similar gaps. The validator checks that every parameter affected by a coupling (item 7) is either declared in some item's stage_direction or explicitly marked independent — and fails loudly otherwise</span></label></div>
+
+<div class="phase">Phase 3 — Serial items → FOLD → 3D</div>
+<div class="task"><input type="checkbox" id="t9"><label for="t9"><b>Implement <code>items_to_fold</code></b>: deterministic mapper item-kind → FOLD geometry<span class="why">Start with prisms/boxes/waterbomb base; grow the mapping table item-by-item</span></label></div>
+<div class="task"><input type="checkbox" id="t10"><label for="t10"><b>Implement <code>simulate_fold</code></b>: port or wrap the OrigamiSimulator FOLD solver (amandaghassei/OrigamiSimulator, MIT) — or shell out to <code>rtori-cli simulate</code><span class="why">GPU shaders → consider ZeroGPU <code>@spaces.GPU(duration=…)</code> with realistic durations; CPU fallback acceptable for v1</span></label></div>
+<div class="task"><input type="checkbox" id="t11"><label for="t11"><b>Acceptance tests:</b> (a) "make a box with a lid" → items → FOLD → folded OBJ opens in a viewer; (b) <b>"the cat sat and the sun shone"</b> → decision ledger containing: <code>ground_plane</code> (implicit!), cat <code>sheet/form</code> + <code>pose: sat</code> + <code>position</code> + <code>orient/facing</code>, <code>light_source: sun</code> with elevation, and a <code>relation</code> coupling sun↔cat that derives shadow direction in the 3D stage. The <code>unresolved</code> list must name the skipped mini-decisions (which cat form? facing where? sun elevation?) — that list is the discussion loop's agenda<span class="why">Test (b) is the conceptual acceptance test: if the 3D stage can compute shadow direction FROM the ledger's relations without extra prompt information, the configuration idea is working</span></label></div>
+
+<div class="phase">Phase 4 — Materialization (reality output)</div>
+<div class="task"><input type="checkbox" id="t13"><label for="t13"><b>Implement <code>materialize_scene</code> route "papercraft" first</b>: take the 3D configuration (from simulate_fold / scene stage), run unfold per item, lay out sheets, return SVGs<span class="why">This reuses Phase 1's unfolding work — but now driven by the scene, not a raw mesh URL. The 3D proxy output feeds the fabricator</span></label></div>
+<div class="task"><input type="checkbox" id="t14"><label for="t14"><b>Extend the IR with a <code>component</code> kind</b> for physical/electronic parts implied by the scene (LED, servo, motor, buzzer…)<span class="why">Enables the Arduino-with-papercraft-props case: the ledger names components ("glowing collar" → LED + battery), materialize_scene emits a BOM + wiring notes, and papercraft props come from the geometry items</span></label></div>
+<div class="task"><input type="checkbox" id="t15"><label for="t15"><b>Acceptance test:</b> "the cat sat and the sun shone" with route "papercraft" → one papercraft sheet-set covering cat + ground plane (+ optional sun disc), with fold markings; route "mixed" additionally returns a BOM if a light-emitting variant is requested</label></div>
+
+<div class="phase">Phase 5 — Hub integration</div>
+<div class="task"><input type="checkbox" id="t12"><label for="t12"><b>Add VisualLearningIdea to HF MCP settings</b> (huggingface.co/settings/mcp) and/or a future ToolHub Space alongside <code>GameConfigIdea</code> (gradio_client proxy) and <code>Language-Learn-Idea</code> (Docker — REST proxy)<span class="why">Once registered, chat agents can chain: sentence → items → FOLD → 3D → unfold → papercraft SVG</span></label></div>
+
+<h2>6. Known pitfalls (discovered this session)</h2>
+<div class="panel">
+<ul>
+<li><b>Coplanar triangles are NOT merged</b> by paperfoldmodels — an octagon face becomes 6 triangles with useless virtual fold lines (<a href="https://github.com/felixfeliz/paperfoldmodels/issues/4">repo issue #4</a>). <b>Accept OBJ with polygonal facets first</b>; STL suffers most. Coplanar merging is a later enhancement (reference: osresearch/papercraft unfold.c).</li>
+<li><b>No glue tabs</b> — paperfoldmodels only flattens. Tabs are a separate step (Inkscape Tabgen pattern) — plan as a <code>kind: join</code> item in the IR.</li>
+<li><b>OpenMesh build</b> — <code>pip install openmesh</code> requires cmake + g++ + pybind11. If the Space build fails, pin prebuilt binaries (Inkscape MightyScape docs document per-OS workarounds).</li>
+<li><b>Tool flooding</b> — every API endpoint becomes an MCP tool. Explicitly set <code>api_name=False</code> on all internal helpers. Keep the public tool count ≤ 6.</li>
+<li><b>ZeroGPU quota attribution</b> — GPU calls inside the Space consume the caller's quota (PRO = 40 min/day). Declare realistic <code>@spaces.GPU(duration=N)</code> values; quota is reserved per <i>requested</i> duration, not actual runtime. Reset is 24h from first GPU use.</li>
+<li><b>Return JSON strings, not objects</b> — Gradio MCP converts outputs; strings and files are the reliable formats.</li>
+<li><b>Queue</b> — set <code>queue=True</code> on long-running events (progress notifications), <code>queue=False</code> for fast ones (10× throughput).</li>
+</ul>
+</div>
+
+<h2>7. Key references</h2>
+<table>
+<tr><th>Resource</th><th>URL</th></tr>
+<tr><td>Gradio MCP server guide</td><td><a href="https://gradio.app/guides/building-mcp-server-with-gradio">gradio.app/guides/building-mcp-server-with-gradio</a></td></tr>
+<tr><td>Spaces as MCP servers (HF docs)</td><td><a href="https://huggingface.co/docs/hub/en/spaces-mcp-servers">huggingface.co/docs/hub/en/spaces-mcp-servers</a></td></tr>
+<tr><td>paperfoldmodels</td><td><a href="https://github.com/felixfeliz/paperfoldmodels">github.com/felixfeliz/paperfoldmodels</a></td></tr>
+<tr><td>OrigamiSimulator (FOLD solver)</td><td><a href="https://github.com/amandaghassaei/OrigamiSimulator/">github.com/amandaghassaei/OrigamiSimulator</a></td></tr>
+<tr><td>osresearch/papercraft (coplanar reference)</td><td><a href="https://github.com/osresearch/papercraft">github.com/osresearch/papercraft</a></td></tr>
+<tr><td>rtori (FOLD convert/simulate CLI)</td><td><a href="https://github.com/origami-code/rtori">github.com/origami-code/rtori</a></td></tr>
+<tr><td>Ori Studio (UX reference)</td><td><a href="https://oristudio.dev/">oristudio.dev</a></td></tr>
+</table>
+
+<h2>8. Verification checklist for the coding agent</h2>
+<div class="panel ok">
+<ol>
+<li>Space builds and UI loads at <code>kwabshug-visuallearningidea.hf.space</code></li>
+<li><code>/gradio_api/mcp/schema</code> lists exactly the 4 planned tools (no helper leakage)</li>
+<li><code>unfold_mesh_to_papercraft</code> on a bunny OBJ returns valid SVG(s)</li>
+<li><code>parse_sentence_to_items("make a box with a lid")</code> returns valid serial IR with ≥1 <code>unresolved</code> ambiguity note</li>
+<li><code>items_to_fold</code> on that IR produces a FOLD doc that <code>simulate_fold</code> accepts</li>
+<li>Tool appears in HuggingChat MCP panel after adding the Space in settings</li>
+</ol>
+</div>
+
+<h2>9. Lessons from the reference UI build (serial player + scene artifact)</h2>
+<div class="panel">
+<p>The cat-sun demo (serial reading tab + scene tab, Three.js) was built end-to-end in the preview sandbox. These lessons are now folded into the contract above:</p>
+<ul>
+<li><b>The serial reading is the product, not a sidebar.</b> The flat token→item timeline ("the → ?", "cat = model", "sat → pose + surface + support") is the deliverable format of <code>parse_sentence_to_items</code>; the 3D scene is downstream. Both views render from the <b>same ledger</b>; each view has its own independent stepper. Default view: serial.</li>
+<li><b>Every item needs a <code>stage_direction</code>.</b> The demo's choreography was hand-coded — possible only because the sentence was known in advance. A generic player requires each item to carry its reveal payload (spawn / move / orient / couple / mark). Now in the tool contract.</li>
+<li><b>Model builders must be factories, not sculptures.</b> The demo shares <code>buildForm / buildPose / buildSupport</code> between the live scene and per-word snapshot images. The Space equivalent must be data-driven parameterization (item params → geometry). Otherwise every new sentence requires hand-modeling — <b>the biggest current gap</b> and the reason Phase 2's IR schema must be designed for buildability, not just describability.</li>
+<li><b>Per-word model snapshots are cheap and powerful.</b> Static images rendered once via an offscreen renderer give each token card a visible model (form-only cat for "cat", posed cat on ground for "sat", sun disc for "sun", full shadowed configuration for "shone"). The Space can pre-render snapshots server-side, or the static front end renders them client-side from the same builders.</li>
+<li><b>Attribute commits to tokens.</b> "sat" commits three items; determiners commit none but open unresolved "?" entries. Without per-token attribution the serial view is unreadable — this is why <code>tokens</code> is now a first-class output key.</li>
+<li><b>Separate "exists" from "relates".</b> The demo deliberately pauses between "sun exists" (item 6) and "shone → coupling ON" (item 7): light without relation is not a configuration. Keep these as distinct items — the pause is where 2D and 3D thinking diverge.</li>
+<li><b>LLM ledgers will be incomplete → validator needed.</b> The demo's sky color did not follow sun elevation. A schema check catches this deterministically; hence the new validator task.</li>
+<li><b>Unresolved "?" entries are the discussion agenda.</b> Each determiner opened a question with a recorded default and alternatives — that list is what the conversation loop interrogates before trusting the 3D.</li>
+<li><b>Front end is covered; deploy it as <code>sdk: static</code>.</b> The player UI is proven in-browser (Three.js via CDN works in both the preview sandbox and static Spaces, which are free and run no compute). The Space's only job is to emit the items the browser cannot make. See companion doc: General Tool Space handover (artifact: toolhub-handover).</li>
+</ul>
+</div>
+
+<footer>Generated from a working session between KwabsHug and HuggingChat · Facts verified against live HF Hub state on 2026-10-23 · Revised after reference UI build · Checkbox state is session-local (reloads reset it)</footer>
+</div>
+</body>
+</html>

vli/__init__.py

@@ -0,0 +1 @@
+"""English -> 3D translation: lexicon, grammar, assets, scene, simplification."""

vli/assets.py

@@ -0,0 +1,215 @@
+"""Target-language lexicon entries: load a ledger item's chosen asset as a mesh.
+
+Every mesh comes back normalized the same way, whatever its tier:
+Y-up (glTF convention), metres, centred on x/z, resting on y = 0.
+"""
+import glob
+import gzip
+import json
+import os
+from functools import lru_cache
+
+import numpy as np
+import trimesh
+from huggingface_hub import hf_hub_download, snapshot_download
+
+from .grammar import DEFAULT_HEIGHT_M, NOMINAL_HEIGHT_M, candidate_label
+from .lexicon import LEXICON
+
+SCENE_FACE_BUDGET = 20000  # per object, for the configured scene
+
+
+class UnusableAsset(Exception):
+    """License or content rules out this candidate; the next one is tried."""
+
+
+def license_ok(license_str):
+    s = (license_str or "").lower()
+    return bool(s) and "nc" not in s.replace("-", " ").split() and "nd" not in s.replace("-", " ").split()
+
+
+def _normalize(mesh, meters_per_unit=1.0, z_up=False):
+    mesh = mesh.copy()
+    mesh.apply_scale(meters_per_unit)
+    if z_up:
+        mesh.apply_transform(trimesh.transformations.rotation_matrix(-np.pi / 2, [1, 0, 0]))
+    lo, hi = mesh.bounds
+    mesh.apply_translation([-(lo[0] + hi[0]) / 2, -lo[1], -(lo[2] + hi[2]) / 2])
+    return mesh
+
+
+def _flatten(loaded):
+    if isinstance(loaded, trimesh.Scene):
+        to_geometry = getattr(loaded, "to_geometry", None)
+        loaded = to_geometry() if to_geometry else loaded.dump(concatenate=True)
+    if hasattr(loaded.visual, "to_color"):
+        loaded.visual = loaded.visual.to_color()
+    return loaded
+
+
+# ---------------- simready (OpenUSD, metric) ----------------
+
+def _simready_files(cand):
+    """Geometry + thumbnail only: textures are ~98% of a package (~1 GB)."""
+    name = cand["name"]
+    root = snapshot_download(
+        repo_id=cand["repo"], repo_type="dataset", revision=cand["revision"],
+        allow_patterns=[f"{name}/com.nvidia.simready.packaging.json",
+                        f"{name}/simready_usd/*.usd", f"{name}/simready_usd/*.usda",
+                        f"{name}/simready_usd/*.usdc", f"{name}/simready_usd/.thumbs/256x256/*.usd.png"])
+    return os.path.join(root, name)
+
+
+def _usd_mesh(usd_path):
+    from pxr import Usd, UsdGeom
+
+    stage = Usd.Stage.Open(usd_path)
+    mpu = UsdGeom.GetStageMetersPerUnit(stage) or 0.01
+    z_up = UsdGeom.GetStageUpAxis(stage) == UsdGeom.Tokens.z
+    cache = UsdGeom.XformCache()
+    parts = []
+    for prim in Usd.PrimRange.Stage(stage, Usd.TraverseInstanceProxies()):
+        if not prim.IsA(UsdGeom.Mesh):
+            continue
+        path = str(prim.GetPath()).lower()
+        if "collision" in path or "collider" in path:
+            continue
+        img = UsdGeom.Imageable(prim)
+        if img.ComputeVisibility() == UsdGeom.Tokens.invisible or img.ComputePurpose() in (
+                UsdGeom.Tokens.guide, UsdGeom.Tokens.proxy):
+            continue
+        geom = UsdGeom.Mesh(prim)
+        points = geom.GetPointsAttr().Get()
+        counts = geom.GetFaceVertexCountsAttr().Get()
+        indices = geom.GetFaceVertexIndicesAttr().Get()
+        if points is None or counts is None or len(points) == 0 or len(counts) == 0:
+            continue
+        pts = np.asarray(points, dtype=np.float64)
+        xf = np.array(cache.GetLocalToWorldTransform(prim), dtype=np.float64)  # row-vector convention
+        pts = (np.c_[pts, np.ones(len(pts))] @ xf)[:, :3]
+        idx = np.asarray(indices, dtype=np.int64)
+        counts = np.asarray(counts, dtype=np.int64)
+        if np.all(counts == 3):
+            faces = idx.reshape(-1, 3)
+        else:
+            faces, at = [], 0
+            for c in counts:  # fan-triangulate polygons
+                faces.extend((idx[at], idx[at + k], idx[at + k + 1]) for k in range(1, c - 1))
+                at += c
+            faces = np.asarray(faces, dtype=np.int64)
+        parts.append(trimesh.Trimesh(pts, faces, process=False))
+    if not parts:
+        raise UnusableAsset(f"no visible mesh geometry in {os.path.basename(usd_path)}")
+    return _normalize(trimesh.util.concatenate(parts), mpu, z_up)
+
+
+def load_simready(cand):
+    folder = _simready_files(cand)
+    with open(os.path.join(folder, "com.nvidia.simready.packaging.json"), encoding="utf-8") as f:
+        lic = json.load(f).get("license")
+    if not license_ok(lic):
+        raise UnusableAsset(f"license {lic!r}")
+    roots = sorted(glob.glob(os.path.join(folder, "simready_usd", "*.usd*")))
+    if not roots:
+        raise UnusableAsset("no root USD file")
+    thumbs = glob.glob(os.path.join(folder, "simready_usd", ".thumbs", "256x256", "*.usd.png"))
+    return _usd_mesh(roots[0]), {"license": lic, "metric": True, "thumbnail": thumbs[0] if thumbs else None}
+
+
+# ---------------- objaverse (GLB, no real-world scale) ----------------
+
+def _objaverse_license(uid, shard):
+    path = hf_hub_download("allenai/objaverse", f"metadata/{shard}.json.gz", repo_type="dataset")
+    with gzip.open(path, "rt", encoding="utf-8") as f:
+        return json.load(f).get(uid, {}).get("license")
+
+
+def load_objaverse(cand):
+    rel = LEXICON.object_path(cand["uid"])  # glbs/000-023/<uid>.glb
+    lic = _objaverse_license(cand["uid"], rel.split("/")[1])
+    if not license_ok(lic):
+        raise UnusableAsset(f"license {lic!r}")
+    path = hf_hub_download("allenai/objaverse", rel, repo_type="dataset")
+    mesh = _flatten(trimesh.load(path, force="scene"))
+    if len(mesh.faces) == 0:
+        raise UnusableAsset("empty mesh")
+    return _normalize(mesh), {"license": lic, "metric": False, "thumbnail": None}
+
+
+# ---------------- construction tiers ----------------
+
+def load_primitive(cand, word):
+    h = NOMINAL_HEIGHT_M.get(word, DEFAULT_HEIGHT_M)
+    shape = cand.get("shape", "box")
+    if shape == "sphere":
+        mesh = trimesh.creation.icosphere(subdivisions=3, radius=h / 2)
+    elif shape in ("cylinder", "cone"):
+        make = trimesh.creation.cylinder if shape == "cylinder" else trimesh.creation.cone
+        mesh = make(radius=h / 2, height=h, sections=32)
+        mesh.apply_transform(trimesh.transformations.rotation_matrix(-np.pi / 2, [1, 0, 0]))  # axis z -> y
+    elif shape == "plane":
+        mesh = trimesh.creation.box([4 * h, 0.01, 4 * h])
+    else:
+        mesh = trimesh.creation.box([h, h, h])
+    return _normalize(mesh), {"license": None, "metric": False, "thumbnail": None}
+
+
+def load_generation(cand, word):
+    raise UnusableAsset("generation tier is not wired up yet")
+
+
+# ---------------- entry points ----------------
+
+@lru_cache(maxsize=64)
+def _load(key):
+    cand = json.loads(key)
+    word = cand.pop("_word")
+    source = cand["source"]
+    if source == "simready":
+        return load_simready(cand)
+    if source == "objaverse":
+        return load_objaverse(cand)
+    if source == "primitive":
+        return load_primitive(cand, word)
+    return load_generation(cand, word)
+
+
+def load_candidate(cand, word):
+    mesh, info = _load(json.dumps({**cand, "_word": word}, sort_keys=True))
+    return mesh.copy(), info
+
+
+def settle(item):
+    """Make the item's chosen candidate loadable, skipping ones that can't be used.
+
+    Returns the full-detail mesh. Skips are recorded on the ledger so the
+    discussion can see what was passed over and why.
+    """
+    dec = item["decision"]
+    while True:
+        try:
+            mesh, info = load_candidate(dec["chosen"], item["word"])
+            break
+        except UnusableAsset as e:
+            dec["skipped"].append({"candidate": candidate_label(dec["chosen"]), "reason": str(e)})
+            if not dec["alternatives"]:
+                raise UnusableAsset(f"no usable {dec['tier']} asset for '{item['word']}' ({e})")
+            dec["chosen"] = dec["alternatives"].pop(0)
+    item["license"] = info["license"]
+    item["thumbnail"] = info["thumbnail"]
+    height = item["height_m"]
+    native = float(mesh.extents[1]) or 1.0
+    if height["source"] == "user":
+        pass
+    elif info["metric"]:
+        height.update(value=round(native, 3), source="asset")
+    else:
+        height.update(value=NOMINAL_HEIGHT_M.get(item["word"], DEFAULT_HEIGHT_M), source="default")
+    mesh.apply_scale(height["value"] / native)
+    return mesh
+
+
+def scene_mesh(mesh):
+    """A lighter copy for the configured scene; the ladder keeps full detail."""
+    from .simplify import decimate
+    return decimate(mesh, SCENE_FACE_BUDGET) if len(mesh.faces) > SCENE_FACE_BUDGET else mesh

vli/grammar.py

@@ -0,0 +1,252 @@
+"""Source-language side: tokenize a controlled English sentence and build the
+serial ledger (the decisions reading hides, in reading order).
+
+Nouns come from the lexicon, verbs are relations between meshes, and glue
+words (the, a, and) commit no geometry -- determiners open a "which?" question.
+A word with no asset is not available unless the caller maps it to a primitive.
+"""
+import re
+
+from .lexicon import ASSET_TIERS, LEXICON, PRIMITIVE_SHAPES, TIERS
+
+DETERMINERS = {"the", "a", "an"}
+CONJUNCTIONS = {"and", "then"}
+COPULAS = {"is", "was", "are", "were"}
+
+# verb -> (relation, implied object when none is stated)
+VERBS = {}
+for v in ("sat", "sits", "sit", "stood", "stands", "lay", "lies", "rested", "rests"):
+    VERBS[v] = ("on", "ground")
+for v in ("shone", "shines", "glowed", "glows"):
+    VERBS[v] = ("lights", None)  # the subject becomes the light source
+for v in ("faced", "faces"):
+    VERBS[v] = ("faces", None)
+
+PREPOSITIONS = {
+    "in front of": "in_front_of", "next to": "beside", "on top of": "on",
+    "on": "on", "under": "under", "beneath": "under", "beside": "beside",
+    "near": "near", "behind": "behind", "above": "above",
+}
+
+# Nominal heights (m) for assets that carry no real-world scale (Objaverse, primitives).
+NOMINAL_HEIGHT_M = {"cat": 0.3, "dog": 0.55, "chair": 0.9, "table": 0.75, "car": 1.5,
+                    "tree": 5.0, "person": 1.7, "house": 6.0, "cup": 0.1, "bird": 0.2}
+DEFAULT_HEIGHT_M = 0.5
+
+
+def grammar_words():
+    return sorted(DETERMINERS | CONJUNCTIONS | COPULAS | set(VERBS) | set(PREPOSITIONS))
+
+
+def parse_primitives(primitives):
+    """{"sun": "sphere"} -> validated dict of word -> shape."""
+    out = {}
+    for word, shape in (primitives or {}).items():
+        if shape not in PRIMITIVE_SHAPES:
+            raise ValueError(f"unknown primitive {shape!r} for {word!r}; use one of {PRIMITIVE_SHAPES}")
+        out[word.lower().strip()] = shape
+    return out
+
+
+def tokenize(sentence, primitives=None):
+    """Greedy longest match over words: prepositions and lexicon phrases can span words."""
+    primitives = primitives or {}
+    words = re.findall(r"[a-z]+", sentence.lower())
+    max_n = max(3, LEXICON.max_phrase_words())
+    tokens, i = [], 0
+    while i < len(words):
+        for n in range(min(max_n, len(words) - i), 0, -1):
+            text = " ".join(words[i:i + n])
+            kind = classify(text) if n == 1 else classify_phrase(text)
+            if kind:
+                tokens.append({"index": len(tokens), "text": text, "kind": kind})
+                i += n
+                break
+        else:
+            kind = "primitive" if words[i] in primitives else "unknown"
+            tokens.append({"index": len(tokens), "text": words[i], "kind": kind})
+            i += 1
+    return tokens
+
+
+def classify_phrase(text):
+    if text in PREPOSITIONS:
+        return "preposition"
+    if LEXICON.available(text):
+        return "noun"
+    return None
+
+
+def classify(word):
+    if word in DETERMINERS:
+        return "determiner"
+    if word in CONJUNCTIONS:
+        return "conjunction"
+    if word in COPULAS:
+        return "copula"
+    if word in VERBS:
+        return "verb"
+    if word in PREPOSITIONS:
+        return "preposition"
+    if LEXICON.available(word):
+        return "noun"
+    return None
+
+
+# ---------------- ledger ----------------
+
+def primitive_candidate(shape="box"):
+    return {"source": "primitive", "shape": shape}
+
+
+def _object_decision(word, shape=None):
+    """Assets first, in tier order; a primitive only when the caller chose one."""
+    if shape:
+        return {"tier": "primitive", "chosen": primitive_candidate(shape), "alternatives": [],
+                "rejected_tiers": [], "skipped": []}
+    found = LEXICON.lookup(word)
+    for tier in ASSET_TIERS:
+        cands = found.get(tier, [])
+        if cands:
+            return {"tier": tier, "chosen": cands[0], "alternatives": cands[1:9],
+                    "rejected_tiers": [], "skipped": []}
+    raise ValueError(f"'{word}' has no asset")
+
+
+def next_tier(decision, word):
+    """Rejection: simready -> objaverse -> primitive -> generation."""
+    found = LEXICON.lookup(word)
+    start = TIERS.index(decision["tier"]) + 1
+    for tier in TIERS[start:]:
+        if tier in ASSET_TIERS:
+            cands = found.get(tier, [])
+            if not cands:
+                continue
+            return {"tier": tier, "chosen": cands[0], "alternatives": cands[1:9]}
+        if tier == "primitive":
+            return {"tier": tier, "chosen": primitive_candidate(), "alternatives": []}
+        return {"tier": tier, "chosen": {"source": "generation", "prompt": word}, "alternatives": []}
+    raise ValueError(f"'{word}' has no tier left after {decision['tier']}")
+
+
+def candidate_label(cand):
+    return cand.get("name") or cand.get("category") or cand.get("shape") or cand.get("prompt") or "?"
+
+
+def build_ledger(sentence, primitives=None):
+    primitives = parse_primitives(primitives)
+    tokens = tokenize(sentence, primitives)
+    unknown = [t["text"] for t in tokens if t["kind"] == "unknown"]
+    if unknown:
+        raise ValueError(f"Not available (no asset): {', '.join(unknown)}. "
+                         f"Rephrase, or map each to a primitive: {PRIMITIVE_SHAPES}")
+    for t in tokens:
+        t["commits"], t["opens"] = [], []
+
+    items, unresolved = [], []
+    by_id = {}
+
+    def add_item(item, token):
+        items.append(item)
+        by_id[item["id"]] = item
+        token["commits"].append(item["id"])
+        return item
+
+    clauses, current = [], []
+    for t in tokens:
+        if t["kind"] == "conjunction":
+            clauses.append(current)
+            current = []
+        else:
+            current.append(t)
+    clauses.append(current)
+
+    pending_q = None
+    for clause in clauses:
+        subject, verb_rel, implied_obj, prep_rel, obj, verb_tok = None, None, None, None, None, None
+        for t in clause:
+            kind = t["kind"]
+            if kind == "determiner":
+                pending_q = {"id": f"q{t['index']}", "token": t["index"], "about": None}
+                t["opens"].append(pending_q["id"])
+                unresolved.append(pending_q)
+            elif kind in ("noun", "primitive"):
+                # height is settled with the asset: metric for simready, nominal otherwise
+                item = add_item({"id": f"n{t['index']}", "kind": "object", "word": t["text"],
+                                 "token": t["index"],
+                                 "decision": _object_decision(t["text"], primitives.get(t["text"])),
+                                 "height_m": {"value": None, "source": "pending"},
+                                 "frozen": False}, t)
+                if pending_q is not None:
+                    pending_q["about"] = item["id"]
+                    pending_q["question"] = f"which {t['text']}?"
+                    pending_q = None
+                if verb_rel is None and prep_rel is None:
+                    subject = item
+                else:
+                    obj = item
+            elif kind == "verb":
+                verb_rel, implied_obj = VERBS[t["text"]]
+                verb_tok = t
+            elif kind == "copula":
+                verb_tok = t
+            elif kind == "preposition":
+                prep_rel = PREPOSITIONS[t["text"]]
+                verb_tok = t
+        if subject is None:
+            raise ValueError("Each clause needs a subject noun")
+        relation = prep_rel or verb_rel
+        if relation is None:
+            continue
+        if obj is None and relation == "on" and implied_obj:
+            # Existing needs a reality: the verb implies a support the sentence never
+            # names. Visualising exposes it, so it is surfaced as a decision too.
+            obj = by_id.get(implied_obj)
+            if obj is None:
+                obj = add_item({"id": implied_obj, "kind": "environment", "role": "plane", "word": implied_obj,
+                                "token": verb_tok["index"], "implied_by": verb_tok["index"],
+                                "frozen": False}, verb_tok)
+                q = {"id": f"q{verb_tok['index']}i", "token": verb_tok["index"], "about": obj["id"],
+                     "question": f"{subject['word']} {verb_tok['text']} on what?",
+                     "default_chosen": "ground plane", "implied": True,
+                     "alternatives": [f"rephrase: '{verb_tok['text']} on the <noun>'"]}
+                verb_tok["opens"].append(q["id"])
+                unresolved.append(q)
+        if relation == "lights":
+            subject["emits_light"] = True
+            obj = {"id": "scene"}
+        if obj is None:
+            raise ValueError(f"'{relation}' needs an object noun")
+        add_item({"id": f"r{verb_tok['index']}", "kind": "relation", "relation": relation,
+                  "subject": subject["id"], "object": obj["id"], "token": verb_tok["index"],
+                  "frozen": False}, verb_tok)
+
+    for q in unresolved:
+        if q["about"] is None:
+            q["question"] = "determiner without a noun"
+    return {"version": 1, "sentence": sentence, "primitives": primitives,
+            "tokens": tokens, "items": items, "unresolved": unresolved}
+
+
+def check_words(sentence, primitives=None):
+    """Per-word status, the words with no asset, and completions for the word being typed."""
+    primitives = parse_primitives(primitives)
+    tokens = tokenize(sentence, primitives)
+    words = []
+    for t in tokens:
+        entry = {"text": t["text"], "kind": t["kind"]}
+        if t["kind"] == "noun":
+            entry["available_in"] = LEXICON.counts(t["text"])
+        elif t["kind"] == "primitive":
+            entry["primitive"] = primitives[t["text"]]
+        words.append(entry)
+    completions = []
+    if sentence and not sentence[-1].isspace():
+        last = re.findall(r"[a-z]+", sentence.lower())
+        if last:
+            prefix = last[-1]
+            completions = [w for w in grammar_words() if w.startswith(prefix)][:6]
+            completions += LEXICON.complete(prefix, 12)
+    missing = [t["text"] for t in tokens if t["kind"] == "unknown"]
+    return {"ok": bool(tokens) and not missing, "words": words, "missing": missing,
+            "primitive_shapes": PRIMITIVE_SHAPES, "completions": completions}

vli/lexicon.py

@@ -0,0 +1,168 @@
+"""The dictionary: which words exist as ready-made assets, and where they live.
+
+Tiers, in fallback order (rejecting an item moves it to the next tier):
+    simready -> objaverse -> primitive -> generation
+A word is *available* only when a simready or objaverse asset exists for it;
+primitive and generation are construction, so they never make a word available.
+A missing word can still be used if the caller explicitly maps it to a primitive.
+"""
+import bisect
+import gzip
+import json
+import os
+import re
+import threading
+
+import requests
+from huggingface_hub import hf_hub_download
+
+CACHE_DIR = os.environ.get("VLI_CACHE", "cache")
+TIERS = ["simready", "objaverse", "primitive", "generation"]
+ASSET_TIERS = ["simready", "objaverse"]
+PRIMITIVE_SHAPES = ["box", "sphere", "cylinder", "cone", "plane"]
+
+SIMREADY_TREE = "https://api.github.com/repos/NVIDIA-Omniverse/simready-central/git/trees/main?recursive=1"
+SIMREADY_RAW = "https://raw.githubusercontent.com/NVIDIA-Omniverse/simready-central/main/"
+SIMREADY_FALLBACK = ["submissions/nvidia/simready-assets"]
+PACKAGE_URL = re.compile(
+    r"https://huggingface\.co/datasets/([^/\s]+)/([^/\s]+)/resolve/([0-9a-f]{40})/([^/\s]+)/"
+    r"com\.nvidia\.simready\.packaging\.json"
+)
+VARIANT = re.compile(r"[a-z]?\d+")  # a01, b02, 01
+
+
+def _split_part(part):
+    """'handDryer' -> ['hand', 'dryer']"""
+    return re.sub(r"([a-z])([A-Z])", r"\1 \2", part).lower().split()
+
+
+def simready_phrases(name):
+    """Words an asset name like 'appliance_handDryer_automatic_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).
+    """
+    parts = [p for p in name.split("_") if p and not VARIANT.fullmatch(p)]
+    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
+
+
+def objaverse_word(category):
+    """LVIS category 'bow_(weapon)' -> 'bow'"""
+    return re.sub(r"_?\(.*?\)", "", category).replace("_", " ").strip().lower()
+
+
+class Lexicon:
+    def __init__(self):
+        self._lock = threading.Lock()
+        self._index = None  # word -> {tier: [candidate, ...]}
+        self._words = []
+        self._object_paths = None
+
+    # ---------- building ----------
+    def _cached_json(self, name, build):
+        path = os.path.join(CACHE_DIR, name)
+        if os.path.exists(path):
+            with open(path, encoding="utf-8") as f:
+                return json.load(f)
+        data = build()
+        os.makedirs(CACHE_DIR, exist_ok=True)
+        with open(path, "w", encoding="utf-8") as f:
+            json.dump(data, f)
+        return data
+
+    def _simready_packages(self):
+        try:
+            tree = requests.get(SIMREADY_TREE, timeout=30).json()["tree"]
+            files = [t["path"] for t in tree if t["type"] == "blob" and t["path"].startswith("submissions/")]
+        except Exception:
+            files = SIMREADY_FALLBACK
+        packages = []
+        for f in files:
+            try:
+                text = requests.get(SIMREADY_RAW + f, timeout=30).text
+            except Exception:
+                continue
+            for ns, ds, rev, name in PACKAGE_URL.findall(text):
+                packages.append({"source": "simready", "repo": f"{ns}/{ds}", "revision": rev, "name": name})
+        return packages
+
+    def _objaverse_lvis(self):
+        path = hf_hub_download("allenai/objaverse", "lvis-annotations.json.gz", repo_type="dataset")
+        with gzip.open(path, "rt", encoding="utf-8") as f:
+            return json.load(f)
+
+    def _build(self):
+        index = {}
+
+        def add(word, tier, cand, rank=0):
+            index.setdefault(word, {}).setdefault(tier, []).append((rank, cand))
+
+        for pkg in self._cached_json("simready_packages.json", self._simready_packages):
+            for phrase, rank in simready_phrases(pkg["name"]):
+                add(phrase, "simready", pkg, rank)
+        for category, uids in self._cached_json("objaverse_lvis.json", self._objaverse_lvis).items():
+            for uid in uids:
+                add(objaverse_word(category), "objaverse", {"source": "objaverse", "uid": uid, "category": category})
+
+        for tiers in index.values():
+            for tier, ranked in tiers.items():
+                ranked.sort(key=lambda rc: (rc[0], len(rc[1].get("name", ""))))
+                tiers[tier] = [c for _, c in ranked]
+        self._index = index
+        self._words = sorted(index)
+
+    def ensure(self):
+        with self._lock:
+            if self._index is None:
+                self._build()
+
+    # ---------- queries ----------
+    def lookup(self, word):
+        """{tier: [candidates]} for a word (plural 's' stripped as a fallback)."""
+        self.ensure()
+        if word in self._index:
+            return self._index[word]
+        if word.endswith("s") and word[:-1] in self._index:
+            return self._index[word[:-1]]
+        return {}
+
+    def available(self, word):
+        return any(self.lookup(word).get(t) for t in ASSET_TIERS)
+
+    def counts(self, word):
+        found = self.lookup(word)
+        return {t: len(found.get(t, [])) for t in ASSET_TIERS}
+
+    def complete(self, prefix, limit=12):
+        self.ensure()
+        i = bisect.bisect_left(self._words, prefix)
+        out = []
+        while i < len(self._words) and self._words[i].startswith(prefix) and len(out) < limit:
+            out.append(self._words[i])
+            i += 1
+        return out
+
+    def max_phrase_words(self):
+        self.ensure()
+        return max((len(w.split()) for w in self._words), default=1)
+
+    def object_path(self, uid):
+        """Objaverse uid -> 'glbs/000-023/<uid>.glb'"""
+        with self._lock:
+            if self._object_paths is None:
+                path = hf_hub_download("allenai/objaverse", "object-paths.json.gz", repo_type="dataset")
+                with gzip.open(path, "rt", encoding="utf-8") as f:
+                    self._object_paths = json.load(f)
+        return self._object_paths[uid]
+
+
+LEXICON = Lexicon()

vli/pipeline.py

@@ -0,0 +1,95 @@
+"""Ties the stages together: ledger -> settled meshes -> configuration -> files.
+
+Refining happens on the serial side: frozen items keep their decisions,
+everything else may change. Configuration is always free (seeded).
+"""
+import json
+import os
+import tempfile
+
+import numpy as np
+
+from . import assets, scene
+from .grammar import build_ledger, candidate_label, next_tier, parse_primitives, primitive_candidate
+
+
+def _workdir():
+    return tempfile.mkdtemp(prefix="vli_")
+
+
+def settle_all(ledger):
+    """Load every object's mesh; unusable candidates are skipped and recorded."""
+    meshes = {}
+    for it in ledger["items"]:
+        if it["kind"] == "object":
+            full = assets.settle(it)
+            meshes[it["id"]] = assets.scene_mesh(full)
+            it["decision"]["label"] = candidate_label(it["decision"]["chosen"])
+    for q in ledger["unresolved"]:
+        about = next((i for i in ledger["items"] if i["id"] == q.get("about")), None)
+        if about and about["kind"] == "object":
+            q["default_chosen"] = about["decision"]["label"]
+            q["alternatives"] = [candidate_label(c) for c in about["decision"]["alternatives"]]
+    return meshes
+
+
+def outputs(ledger, seed):
+    meshes = settle_all(ledger)
+    config = scene.configure(ledger, meshes, seed)
+    ledger["configuration"] = config
+    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
+
+
+def translate(sentence, primitives=None, seed=0):
+    return outputs(build_ledger(sentence, primitives), seed)
+
+
+def apply_changes(ledger, changes, seed=0):
+    """changes: list of
+        {"id": ..., "freeze": true|false}
+        {"id": ..., "use": <index into alternatives>}
+        {"id": ..., "reject": true}          -> next tier
+        {"id": ..., "height_m": 0.4}
+        {"id": ..., "shape": "sphere"}       -> primitive tier with that shape
+        {"reroll": true}                     -> every unfrozen object takes a random alternative
+    """
+    by_id = {i["id"]: i for i in ledger["items"]}
+    rng = np.random.default_rng(seed)
+    for ch in changes:
+        if ch.get("reroll"):
+            for it in ledger["items"]:
+                dec = it.get("decision")
+                if it["kind"] == "object" and not it["frozen"] and dec["alternatives"]:
+                    k = int(rng.integers(len(dec["alternatives"])))
+                    dec["alternatives"][k], dec["chosen"] = dec["chosen"], dec["alternatives"][k]
+            continue
+        it = by_id.get(ch.get("id"))
+        if it is None:
+            raise ValueError(f"no item with id {ch.get('id')!r}")
+        if "freeze" in ch:
+            it["frozen"] = bool(ch["freeze"])
+            continue
+        if it["frozen"]:
+            raise ValueError(f"{it['id']} is frozen; unfreeze it first")
+        if it["kind"] != "object":
+            raise ValueError(f"{it['id']} is a {it['kind']}; only object decisions can change")
+        dec = it["decision"]
+        if "use" in ch:
+            k = int(ch["use"])
+            dec["alternatives"][k], dec["chosen"] = dec["chosen"], dec["alternatives"][k]
+        if ch.get("reject"):
+            dec["rejected_tiers"].append(dec["tier"])
+            dec.update(next_tier(dec, it["word"]))
+            if it["height_m"]["source"] != "user":
+                it["height_m"] = {"value": None, "source": "pending"}
+        if "shape" in ch:
+            shape = parse_primitives({it["word"]: ch["shape"]})[it["word"]]
+            if dec["tier"] != "primitive":
+                dec["rejected_tiers"].append(dec["tier"])
+            dec.update(tier="primitive", chosen=primitive_candidate(shape), alternatives=[])
+        if "height_m" in ch:
+            it["height_m"] = {"value": float(ch["height_m"]), "source": "user"}
+    return ledger

vli/scene.py

@@ -0,0 +1,219 @@
+"""Configuration side: once the serial ledger is resolved, any placement that
+satisfies its relations is valid. The seed picks one configuration.
+"""
+import math
+
+import matplotlib
+
+matplotlib.use("Agg")
+import matplotlib.pyplot as plt  # noqa: E402
+import numpy as np  # noqa: E402
+import trimesh  # noqa: E402
+from mpl_toolkits.mplot3d.art3d import Poly3DCollection  # noqa: E402
+from scipy.spatial import ConvexHull  # noqa: E402
+
+from .simplify import base_color, decimate  # noqa: E402
+
+GAP = 0.1
+RENDER_FACE_BUDGET = 3000
+
+
+def _half_width(mesh):
+    return 0.5 * max(mesh.extents[0], mesh.extents[2])
+
+
+def sun_direction(sun):
+    el, az = math.radians(sun["elevation_deg"]), math.radians(sun["azimuth_deg"])
+    return np.array([math.cos(el) * math.sin(az), math.sin(el), math.cos(el) * math.cos(az)])
+
+
+def configure(ledger, meshes, seed=0):
+    """Place every object so the ledger's relations hold. Returns a JSON-able dict."""
+    rng = np.random.default_rng(seed)
+    items = ledger["items"]
+    relations = [i for i in items if i["kind"] == "relation"]
+    lights = [i for i in items if i.get("emits_light")]
+    objects = [i for i in items if i["kind"] == "object" and not i.get("emits_light")]
+
+    place, x = {}, 0.0
+    for it in objects:  # unrelated objects stand in a loose row
+        hw = _half_width(meshes[it["id"]])
+        place[it["id"]] = {"position": [x + hw, 0.0, float(rng.uniform(-0.5, 0.5) * hw)],
+                           "yaw_deg": float(rng.uniform(-180, 180))}
+        x += 2 * hw + 4 * GAP
+    for p in place.values():
+        p["position"][0] -= x / 2
+
+    sun = None
+    if lights:
+        sun = {"id": lights[0]["id"], "elevation_deg": float(rng.uniform(20, 70)),
+               "azimuth_deg": float(rng.uniform(-150, 150)),
+               "shadows": any(r["relation"] == "lights" for r in relations)}
+
+    def height(oid):
+        return float(meshes[oid].extents[1])
+
+    for _ in range(2):  # second pass lets chains (a on b on c) settle
+        for r in relations:
+            a, b, rel = r["subject"], r["object"], r["relation"]
+            if a not in place:
+                continue
+            pa = place[a]["position"]
+            if b not in place:  # environment object: ground, sun, scene
+                if rel == "on":
+                    pa[1] = 0.0
+                elif rel == "faces" and sun and b == sun["id"]:
+                    place[a]["yaw_deg"] = sun["azimuth_deg"]
+                continue
+            pb = place[b]["position"]
+            hwa, hwb = _half_width(meshes[a]), _half_width(meshes[b])
+            if rel == "on":
+                slack = max(0.0, hwb - hwa)
+                ang = rng.uniform(0, 2 * math.pi)
+                pa[0], pa[2] = pb[0] + slack * math.cos(ang) * 0.5, pb[2] + slack * math.sin(ang) * 0.5
+                pa[1] = pb[1] + height(b)
+            elif rel == "under":
+                pa[0], pa[1], pa[2] = pb[0], 0.0, pb[2]
+            elif rel in ("beside", "near"):
+                side = rng.choice([-1, 1])
+                gap = GAP if rel == "beside" else 3 * GAP + hwa
+                pa[0], pa[1], pa[2] = pb[0] + side * (hwa + hwb + gap), pb[1], pb[2]
+            elif rel in ("behind", "in_front_of"):
+                sign = -1 if rel == "behind" else 1
+                pa[0], pa[1], pa[2] = pb[0], pb[1], pb[2] + sign * (hwa + hwb + GAP)
+            elif rel == "above":
+                pa[0], pa[2] = pb[0], pb[2]
+                pa[1] = pb[1] + height(b) + 0.3 * max(height(a), height(b))
+            elif rel == "faces":
+                place[a]["yaw_deg"] = math.degrees(math.atan2(pb[0] - pa[0], pb[2] - pa[2]))
+
+    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 it in lights:
+            place[it["id"]] = {"position": [float(c) for c in pos], "yaw_deg": 0.0, "light": True}
+    return {"seed": seed, "placements": place, "sun": sun}
+
+
+def transform(p):
+    t = trimesh.transformations.rotation_matrix(math.radians(p["yaw_deg"]), [0, 1, 0])
+    t[:3, 3] = p["position"]
+    return t
+
+
+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])
+    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])
+    g.visual = trimesh.visual.ColorVisuals(g, face_colors=np.tile([77, 124, 58, 255], (len(g.faces), 1)))
+    return g
+
+
+def placed_meshes(ledger, meshes, config):
+    out = {}
+    for oid, p in config["placements"].items():
+        m = meshes[oid].copy()
+        m.apply_transform(transform(p))
+        out[oid] = m
+    return out
+
+
+def export_glb(ledger, meshes, config, path):
+    placed = placed_meshes(ledger, meshes, config)
+    scene = trimesh.Scene()
+    for oid, m in placed.items():
+        scene.add_geometry(m, node_name=oid)
+    ground = _ground(ledger, placed)
+    if ground is not None:
+        scene.add_geometry(ground, node_name="ground")
+    scene.export(path)
+    return path
+
+
+# ---------------- picture (headless, for people and for models) ----------------
+
+def _sky(sun):
+    if not sun:
+        return "#2a3346"
+    t = min(1.0, max(0.0, (sun["elevation_deg"] - 5) / 40))  # low sun -> warm sky
+    low, high = np.array([0.95, 0.62, 0.38]), np.array([0.53, 0.71, 0.88])
+    return tuple(low + (high - low) * t)
+
+
+def _to_axes(v):
+    """Y-up scene coords -> matplotlib Z-up axes (a proper rotation)."""
+    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)
+    rgb = np.clip(color[:3] / 255.0 * k[:, None], 0, 1)
+    return np.c_[rgb, np.ones(len(rgb))]
+
+
+def render(meshes_by_id, path, sun=None, ground=None, title=None):
+    light = sun_direction(sun) if sun else np.array([0.4, 0.8, 0.45]) / np.linalg.norm([0.4, 0.8, 0.45])
+    fig = plt.figure(figsize=(6.4, 4.8), dpi=110)
+    fig.patch.set_facecolor(_sky(sun))
+    ax = fig.add_subplot(projection="3d", computed_zorder=False)
+    ax.set_facecolor(_sky(sun))
+    pts = []
+
+    if ground is not None:
+        v = ground.vertices
+        top = v[(v[:, 1] > -0.005) & (np.hypot(v[:, 0], v[:, 2]) > 1e-6)]  # top cap rim
+        ring = top[np.argsort(np.arctan2(top[:, 2], top[:, 0]))]
+        ax.add_collection3d(Poly3DCollection([_to_axes(ring)], facecolors=[(0.30, 0.49, 0.23, 1)], zorder=0))
+        pts.append(ring)
+
+    if sun and sun.get("shadows") and light[1] > 0.05:
+        for oid, m in meshes_by_id.items():
+            if oid == sun["id"]:
+                continue
+            v = m.vertices if len(m.vertices) < 4000 else m.vertices[:: len(m.vertices) // 4000 + 1]
+            flat = v - np.outer(v[:, 1] / light[1], light)
+            try:
+                hull = ConvexHull(flat[:, [0, 2]])
+            except Exception:
+                continue
+            poly = flat[hull.vertices]
+            poly[:, 1] = 0.002
+            ax.add_collection3d(Poly3DCollection([_to_axes(poly)], facecolors=[(0, 0, 0, 0.35)], zorder=1))
+
+    tris, colors = [], []
+    for m in meshes_by_id.values():
+        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))
+        pts.append(r.vertices)
+    if tris:
+        ax.add_collection3d(Poly3DCollection(_to_axes(np.concatenate(tris)), facecolors=np.concatenate(colors),
+                                             linewidths=0, zorder=2))
+
+    allp = _to_axes(np.concatenate(pts)) if pts else np.zeros((1, 3))
+    lo, hi = allp.min(axis=0), allp.max(axis=0)
+    span = max((hi - lo).max(), 1e-3)
+    mid = (lo + hi) / 2
+    ax.set_xlim(mid[0] - span / 2, mid[0] + span / 2)
+    ax.set_ylim(mid[1] - span / 2, mid[1] + span / 2)
+    ax.set_zlim(max(lo[2], mid[2] - span / 2), max(lo[2], mid[2] - span / 2) + span)
+    ax.set_box_aspect((1, 1, 1))
+    ax.view_init(elev=22, azim=-60)
+    ax.set_axis_off()
+    if title:
+        ax.set_title(title, color="white", fontsize=10)
+    fig.savefig(path, facecolor=fig.get_facecolor(), bbox_inches="tight")
+    plt.close(fig)
+    return path
+
+
+def render_scene(ledger, meshes, config, path):
+    placed = placed_meshes(ledger, meshes, config)
+    return render(placed, path, sun=config["sun"], ground=_ground(ledger, placed))

vli/simplify.py

@@ -0,0 +1,55 @@
+"""The simplification ladder: how far a mesh can be reduced and still read as its word.
+
+Rungs run from the full asset down to an oriented box. The low rungs are the
+ones that can be materialized (fewer faces = fewer papercraft pieces).
+"""
+import numpy as np
+import trimesh
+
+FACE_LEVELS = [20000, 5000, 1000, 250, 60]
+
+
+def base_color(mesh):
+    """Mean RGBA of a mesh's colours, or neutral grey."""
+    vis = getattr(mesh, "visual", None)
+    if isinstance(vis, trimesh.visual.ColorVisuals):
+        try:
+            cols = vis.vertex_colors if vis.kind == "vertex" else vis.face_colors
+            if cols is not None and len(cols):
+                return np.asarray(cols, dtype=np.float64).mean(axis=0).astype(np.uint8)
+        except Exception:
+            pass
+    return np.array([180, 180, 180, 255], dtype=np.uint8)
+
+
+def decimate(mesh, faces):
+    color = base_color(mesh)
+    try:
+        out = mesh.simplify_quadric_decimation(face_count=faces)
+    except TypeError:  # older trimesh signature
+        out = mesh.simplify_quadric_decimation(faces)
+    out.visual = trimesh.visual.ColorVisuals(out, face_colors=np.tile(color, (len(out.faces), 1)))
+    return out
+
+
+def _recolor(mesh, color):
+    mesh.visual = trimesh.visual.ColorVisuals(mesh, face_colors=np.tile(color, (len(mesh.faces), 1)))
+    return mesh
+
+
+def ladder(mesh):
+    color = base_color(mesh)
+    rungs = [("original", mesh)]
+    for n in FACE_LEVELS:
+        if n < 0.8 * len(rungs[-1][1].faces):
+            rungs.append((f"{n} faces", decimate(mesh, n)))
+    rungs.append(("convex hull", _recolor(mesh.convex_hull, color)))
+    box = mesh.bounding_box_oriented
+    rungs.append(("bounding box", _recolor(trimesh.Trimesh(box.vertices, box.faces), color)))
+    return rungs
+
+
+def stats(mesh):
+    return {"faces": int(len(mesh.faces)), "vertices": int(len(mesh.vertices)),
+            "watertight": bool(mesh.is_watertight), "convex": bool(mesh.is_convex),
+            "surface_area_m2": round(float(mesh.area), 4)}

vli/vlm.py

@@ -0,0 +1,27 @@
+"""Back-translation: a vision model reads the picture back into English."""
+import base64
+import os
+
+from huggingface_hub import InferenceClient
+
+VLM_MODEL = os.environ.get("VLM_MODEL", "Qwen/Qwen2.5-VL-7B-Instruct")
+
+
+def ask(image_path, prompt, max_tokens=80):
+    with open(image_path, "rb") as f:
+        data = base64.b64encode(f.read()).decode()
+    client = InferenceClient(token=os.environ.get("HF_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):
+    return ask(image_path, "Describe this 3D scene in one short plain sentence.")
+
+
+def name_object(image_path):
+    return ask(image_path, "What single object is this? Answer with one or two words.", max_tokens=10)