🐠 VisualLearningIdea — Setup Handover

1. Mission

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)

2. Current state (verified 2026-10-23)

3. Target tool surface (MCP)

The Space must launch with demo.launch(mcp_server=True) so each public function becomes an MCP tool callable from HuggingChat / Claude / Codex. Tool exposure is controlled by type hints + docstrings (they become the tool description the LLM reads). Set api_name=False on every helper function that should NOT become a tool.

Planned tools (v1 contract)

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...]}
    """

4. Architecture

FOLD format is the interchange hub (OrigamiSimulator reads/writes it; rtori converts it; Ori Studio imports/exports it). Every pipeline becomes "X → FOLD → Y".

5. Phased work plan

6. Known pitfalls (discovered this session)

7. Key references

8. Verification checklist for the coding agent

9. Lessons from the reference UI build (serial player + scene artifact)