Initial NaturalCAD MVP

.gitattributes

@@ -0,0 +1,5 @@
+*.jpg filter=lfs diff=lfs merge=lfs -text
+*.jpeg filter=lfs diff=lfs merge=lfs -text
+*.png filter=lfs diff=lfs merge=lfs -text
+*.gif filter=lfs diff=lfs merge=lfs -text
+*.webp filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -0,0 +1,16 @@
+.DS_Store
+node_modules/
+dist/
+.venv/
+__pycache__/
+*.pyc
+*.pyo
+**/artifacts/*
+!**/artifacts/.gitkeep
+!**/artifacts/runs/
+!**/artifacts/runs/.gitkeep
+!**/artifacts/logs/
+!**/artifacts/logs/.gitkeep
+.env
+.env.*
+.vite/

README.md

@@ -0,0 +1,49 @@
+---
+title: NaturalCAD
+emoji: 🧱
+colorFrom: slate
+colorTo: blue
+sdk: gradio
+sdk_version: 4.44.1
+app_file: app.py
+pinned: false
+---
+
+# NaturalCAD
+
+NaturalCAD is a public prompt-to-CAD demo built around build123d.
+
+The immediate goal is simple: get it in front of people fast, learn from real prompts, and improve from actual usage instead of guessing in a vacuum.
+
+## Current app path
+
+- `app.py` - Hugging Face Space entrypoint
+- `requirements.txt` - Space runtime dependencies
+- `apps/gradio-demo` - primary MVP app
+
+## Other repo areas
+
+- `apps/backend-api` - later-phase backend scaffold if we outgrow a Space-only MVP
+- `apps/web-visualizer` - earlier React/Vite prototype
+- `docs/` - product and deployment planning
+- `archive/` - older or superseded material kept for reference
+
+## Local run
+
+```bash
+pip install -r requirements.txt
+python app.py
+```
+
+## Deployment posture
+
+Right now the priority is a lean Hugging Face Space MVP.
+If the CAD dependency stack or runtime limits become painful, the frontend can stay on Hugging Face while execution moves to a container or VM later.
+
+## Key docs
+
+- `docs/hf-space-mvp.md`
+- `docs/hf-space-deploy-checklist.md`
+- `docs/publish-checklist.md`
+- `docs/backend-v0.md`
+- `docs/security-policy-v0.md`

app.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+import importlib.util
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent
+SOURCE = ROOT / 'apps' / 'gradio-demo' / 'app' / 'main.py'
+
+spec = importlib.util.spec_from_file_location('naturalcad_gradio_main', SOURCE)
+if spec is None or spec.loader is None:
+    raise RuntimeError(f'Could not load NaturalCAD app from {SOURCE}')
+
+module = importlib.util.module_from_spec(spec)
+spec.loader.exec_module(module)
+
+demo = module.build_ui()
+
+if __name__ == '__main__':
+    demo.launch(
+        server_name='0.0.0.0',
+        server_port=7860,
+        css="""
+        #model-viewer {height: 620px !important; border-radius: 18px; overflow: hidden;}
+        .log-box textarea {font-family: 'JetBrains Mono', monospace; font-size: 13px;}
+        .gradio-container {max-width: 1380px !important;}
+        button.primary {font-weight: 700;}
+        """,
+    )

apps/backend-api/README.md

@@ -0,0 +1,39 @@
+# NaturalCAD Backend API
+
+FastAPI backend for NaturalCAD.
+
+## Purpose
+- keep secrets off the Hugging Face Space
+- validate and rate-limit public requests
+- create jobs and track status
+- generate structured CAD specs
+- provide a clean place for worker, DB, and storage integration
+
+## Run locally
+
+```bash
+cd apps/backend-api
+python3 -m venv .venv
+.venv/bin/pip install -r requirements.txt
+.venv/bin/uvicorn app.main:app --reload --port 8010
+```
+
+## Initial endpoints
+- `GET /v1/health`
+- `POST /v1/jobs`
+- `GET /v1/jobs/{job_id}`
+- `POST /v1/generate-spec`
+
+## Current integration state
+- `apps/gradio-demo` now creates backend jobs through `POST /v1/jobs`
+- the backend currently returns a validated in-memory spec
+- the Gradio app still performs local build123d execution for now
+- next step is moving execution from the Gradio app into a real worker
+
+## Notes
+This is the v0 scaffold. It currently uses in-memory storage by default, but now includes a Postgres schema and a repository layer that can switch to `DATABASE_URL` when Supabase is ready.
+
+## Supabase readiness
+- schema file: `db/schema.sql`
+- env placeholders added for `DATABASE_URL` and Supabase keys
+- repository layer falls back to memory until the database is configured

apps/backend-api/app/__init__.py

@@ -0,0 +1 @@
+# NaturalCAD backend package

apps/backend-api/app/config.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+
+from dotenv import load_dotenv
+
+load_dotenv()
+
+
+@dataclass(frozen=True)
+class Settings:
+    app_name: str = "NaturalCAD Backend"
+    app_env: str = os.getenv("APP_ENV", "development")
+    api_shared_secret: str = os.getenv("API_SHARED_SECRET", "")
+    rate_limit_per_hour: int = int(os.getenv("RATE_LIMIT_PER_HOUR", "20"))
+    max_prompt_length: int = int(os.getenv("MAX_PROMPT_LENGTH", "1000"))
+    database_url: str = os.getenv("DATABASE_URL", "")
+    supabase_url: str = os.getenv("SUPABASE_URL", "")
+    supabase_service_role_key: str = os.getenv("SUPABASE_SERVICE_ROLE_KEY", "")
+    supabase_anon_key: str = os.getenv("SUPABASE_ANON_KEY", "")
+
+
+settings = Settings()

apps/backend-api/app/db.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from typing import Any
+
+from .config import settings
+
+try:
+    import psycopg
+except Exception:  # noqa: BLE001
+    psycopg = None
+
+
+@dataclass
+class DatabaseState:
+    enabled: bool
+    reason: str | None = None
+
+
+def get_database_state() -> DatabaseState:
+    if not settings.database_url:
+        return DatabaseState(enabled=False, reason="DATABASE_URL not configured")
+    if psycopg is None:
+        return DatabaseState(enabled=False, reason="psycopg not installed")
+    return DatabaseState(enabled=True)
+
+
+def connect():
+    state = get_database_state()
+    if not state.enabled:
+        raise RuntimeError(state.reason or "Database unavailable")
+    assert psycopg is not None
+    return psycopg.connect(settings.database_url)
+
+
+def serialize_json(value: Any) -> str:
+    return json.dumps(value)

apps/backend-api/app/main.py

@@ -0,0 +1,336 @@
+from __future__ import annotations
+
+import hashlib
+import re
+import time
+from typing import cast
+
+from fastapi import FastAPI, Header, HTTPException, Request
+
+from .config import settings
+from .models import (
+    CadSpec,
+    CadStyle,
+    CreateJobRequest,
+    GenerateSpecRequest,
+    GenerateSpecResponse,
+    HealthResponse,
+    JobRecord,
+    ModeType,
+    OutputType,
+)
+from .repository import get_job as repo_get_job, save_job
+from .store import _CACHE, _JOBS, _REQUESTS
+
+app = FastAPI(title=settings.app_name, version="0.4.0")
+
+
+def _check_auth(header_value: str | None) -> None:
+    if settings.api_shared_secret and header_value != settings.api_shared_secret:
+        raise HTTPException(status_code=401, detail="Invalid shared secret")
+
+
+def _rate_limit_key(request: Request, session_id: str | None) -> str:
+    client_ip = request.client.host if request.client else "unknown"
+    return session_id or client_ip
+
+
+def _enforce_rate_limit(key: str) -> None:
+    now = time.time()
+    cutoff = now - 3600
+    bucket = _REQUESTS[key]
+    while bucket and bucket[0] < cutoff:
+        bucket.popleft()
+    if len(bucket) >= settings.rate_limit_per_hour:
+        raise HTTPException(status_code=429, detail="Rate limit exceeded")
+    bucket.append(now)
+
+
+def _normalize_prompt(prompt: str) -> str:
+    return " ".join(prompt.lower().strip().split())
+
+
+def _assess_prompt(prompt: str) -> tuple[bool, list[str]]:
+    reasons: list[str] = []
+    suspicious_patterns = [
+        r"```",
+        r"\bimport\b",
+        r"\bexec\b",
+        r"\beval\b",
+        r"__import__",
+        r"subprocess",
+        r"os\.system",
+        r"rm\s+-rf",
+        r"curl\s+",
+        r"wget\s+",
+    ]
+    for pattern in suspicious_patterns:
+        if re.search(pattern, prompt):
+            reasons.append(f"matched:{pattern}")
+
+    if len(prompt) > settings.max_prompt_length:
+        reasons.append("too_long")
+
+    if prompt.count("\n") > 20:
+        reasons.append("too_many_lines")
+
+    return bool(reasons), reasons
+
+
+def _prompt_hash(prompt: str, mode: str, output_type: str) -> str:
+    digest = hashlib.sha256(f"{mode}|{output_type}|{prompt}".encode()).hexdigest()
+    return digest[:16]
+
+
+def _extract_number(prompt: str, keywords: list[str], default: float) -> float:
+    for keyword in keywords:
+        pattern = rf"{keyword}\s*(?:of|=|:)?\s*(\d+(?:\.\d+)?)"
+        match = re.search(pattern, prompt)
+        if match:
+            return float(match.group(1))
+    return default
+
+
+def _extract_count(prompt: str, nouns: list[str], default: int) -> int:
+    word_map = {
+        "one": 1,
+        "two": 2,
+        "three": 3,
+        "four": 4,
+        "five": 5,
+        "six": 6,
+        "seven": 7,
+        "eight": 8,
+        "nine": 9,
+        "ten": 10,
+    }
+    for noun in nouns:
+        digit_match = re.search(rf"(\d+)\s+{noun}", prompt)
+        if digit_match:
+            return int(digit_match.group(1))
+        for word, value in word_map.items():
+            if re.search(rf"{word}\s+{noun}", prompt):
+                return value
+    return default
+
+
+def _style_from_prompt(prompt: str, default_family: str) -> CadStyle:
+    heaviness = 0.6
+    family = default_family
+    if any(word in prompt for word in ["heavy", "massive", "thick", "brutal"]):
+        heaviness = 0.85
+    elif any(word in prompt for word in ["light", "slim", "thin", "delicate"]):
+        heaviness = 0.35
+
+    if any(word in prompt for word in ["industrial", "steel", "metal"]):
+        family = "industrial"
+    elif any(word in prompt for word in ["structural", "truss", "frame"]):
+        family = "structural"
+    elif any(word in prompt for word in ["smooth", "soft", "shell", "canopy"]):
+        family = "smooth"
+    elif any(word in prompt for word in ["diagram", "profile", "elevation", "line"]):
+        family = "diagrammatic"
+
+    return CadStyle(family=family, heaviness=heaviness)
+
+
+def _infer_spec(prompt: str, mode: ModeType, output_type: OutputType) -> CadSpec:
+    p = prompt.lower()
+
+    if output_type == "2d_vector" or mode == "sketch":
+        family = "truss_elevation" if any(word in p for word in ["truss", "beam", "frame", "elevation"]) else "plate_profile"
+        if family == "truss_elevation":
+            params = {
+                "span": _extract_number(p, ["span", "length", "width"], 140),
+                "height": _extract_number(p, ["height", "rise"], 24),
+                "panel_count": _extract_count(p, ["panels", "bays", "segments"], 7),
+                "member_size": _extract_number(p, ["member", "thickness", "depth"], 3),
+                "preview_thickness": 1,
+            }
+        else:
+            params = {
+                "width": _extract_number(p, ["width", "span"], 80),
+                "height": _extract_number(p, ["height"], 50),
+                "hole_count": _extract_count(p, ["holes", "bolt holes", "openings"], 4),
+                "hole_diameter": _extract_number(p, ["hole diameter", "hole", "diameter"], 10),
+                "preview_thickness": 1,
+            }
+        return CadSpec(
+            output_type="2d_vector",
+            geometry_family=family,
+            parameters=params,
+            style=_style_from_prompt(p, "diagrammatic"),
+        )
+
+    if output_type == "surface":
+        family = "canopy_surface" if any(word in p for word in ["roof", "canopy", "shell", "surface"]) else "lofted_panel"
+        if family == "canopy_surface":
+            params = {
+                "span": _extract_number(p, ["span", "width"], 160),
+                "depth": _extract_number(p, ["depth", "length"], 90),
+                "peak_height": _extract_number(p, ["peak", "height", "rise"], 38),
+                "thickness": _extract_number(p, ["thickness"], 2),
+            }
+        else:
+            params = {
+                "width": _extract_number(p, ["width", "span"], 80),
+                "depth": _extract_number(p, ["depth", "length"], 50),
+                "rise": _extract_number(p, ["rise", "height"], 18),
+                "thickness": _extract_number(p, ["thickness"], 2),
+            }
+        return CadSpec(
+            output_type="surface",
+            geometry_family=family,
+            parameters=params,
+            style=_style_from_prompt(p, "smooth"),
+        )
+
+    if any(word in p for word in ["truss", "beam", "frame", "girder"]):
+        return CadSpec(
+            output_type="3d_solid",
+            geometry_family="truss_beam",
+            parameters={
+                "span": _extract_number(p, ["span", "length"], 140),
+                "height": _extract_number(p, ["height", "rise"], 24),
+                "panel_count": _extract_count(p, ["panels", "bays", "segments"], 7),
+                "member_size": _extract_number(p, ["member", "thickness", "depth"], 3),
+            },
+            style=_style_from_prompt(p, "structural"),
+        )
+
+    if any(word in p for word in ["tower", "block", "monolith"]):
+        return CadSpec(
+            output_type="3d_solid",
+            geometry_family="tower_block",
+            parameters={
+                "width": _extract_number(p, ["width"], 30),
+                "length": _extract_number(p, ["length", "depth"], 30),
+                "height": _extract_number(p, ["height"], 120),
+                "notch": _extract_number(p, ["notch", "cut"], 10),
+            },
+            style=_style_from_prompt(p, "industrial"),
+        )
+
+    return CadSpec(
+        output_type="3d_solid",
+        geometry_family="bracket_plate",
+        parameters={
+            "width": _extract_number(p, ["width", "span"], 80),
+            "height": _extract_number(p, ["height"], 50),
+            "thickness": _extract_number(p, ["thickness"], 6),
+            "hole_count": _extract_count(p, ["holes", "bolt holes", "openings"], 4),
+            "hole_diameter": _extract_number(p, ["hole diameter", "hole", "diameter"], 10),
+        },
+        style=_style_from_prompt(p, "industrial"),
+    )
+
+
+def _generate_spec(payload: GenerateSpecRequest) -> GenerateSpecResponse:
+    normalized = _normalize_prompt(payload.prompt)
+    suspicious_input, suspicious_reasons = _assess_prompt(payload.prompt)
+    key = _prompt_hash(normalized, payload.mode, payload.output_type)
+
+    if key in _CACHE:
+        cached = dict(_CACHE[key])
+        cached["cached"] = True
+        return GenerateSpecResponse(**cached)
+
+    safe_prompt = normalized
+    fallback_level = "normal"
+    notes = [
+        f"Mode: {payload.mode}",
+        f"Output type: {payload.output_type}",
+    ]
+
+    if suspicious_input:
+        safe_prompt = "simple industrial bracket plate with 4 holes"
+        fallback_level = "guardrailed"
+        notes.extend([
+            "Input looked more like code or hostile instructions than a CAD prompt.",
+            "Using a safe fallback prompt for MVP robustness.",
+            *[f"Guardrail: {reason}" for reason in suspicious_reasons],
+        ])
+    elif len(normalized.split()) < 3:
+        fallback_level = "underspecified"
+        notes.extend([
+            "Prompt was underspecified.",
+            "Using conservative defaults and a simple geometry family.",
+        ])
+
+    spec = _infer_spec(safe_prompt, payload.mode, payload.output_type)
+    response = GenerateSpecResponse(
+        prompt_hash=key,
+        spec=spec,
+        notes=notes + [
+            "Prompt mapped into a structured CAD spec.",
+            "Replace the stub router with a real HF endpoint later.",
+        ],
+        suspicious_input=suspicious_input,
+        fallback_level=fallback_level,
+    )
+    _CACHE[key] = response.model_dump()
+    return response
+
+
+@app.get("/v1/health", response_model=HealthResponse)
+def health() -> HealthResponse:
+    return HealthResponse(
+        status="ok",
+        environment=settings.app_env,
+        rate_limit_per_hour=settings.rate_limit_per_hour,
+        cache_entries=len(_CACHE),
+        jobs_in_memory=len(_JOBS),
+    )
+
+
+@app.post("/v1/generate-spec", response_model=GenerateSpecResponse)
+def generate_spec(payload: GenerateSpecRequest, request: Request, x_api_key: str | None = Header(default=None)) -> GenerateSpecResponse:
+    _check_auth(x_api_key)
+    _enforce_rate_limit(_rate_limit_key(request, payload.session_id))
+    return _generate_spec(payload)
+
+
+@app.post("/v1/jobs", response_model=JobRecord)
+def create_job(payload: CreateJobRequest, request: Request, x_api_key: str | None = Header(default=None)) -> JobRecord:
+    _check_auth(x_api_key)
+    _enforce_rate_limit(_rate_limit_key(request, payload.session_id))
+
+    if len(payload.prompt.strip()) > settings.max_prompt_length:
+        raise HTTPException(status_code=400, detail="Prompt too long")
+
+    spec_response = _generate_spec(GenerateSpecRequest(**payload.model_dump()))
+    job = JobRecord(
+        status="validated",
+        prompt=payload.prompt,
+        mode=payload.mode,
+        output_type=payload.output_type,
+        session_id=payload.session_id,
+        prompt_hash=spec_response.prompt_hash,
+        spec=spec_response.spec,
+        notes=[
+            "Job created in backend scaffold.",
+            "Next step: persist to Supabase and enqueue worker execution.",
+        ],
+    )
+    job.status = cast(str, "queued")
+    save_job(job)
+    return job
+
+
+@app.get("/v1/jobs/{job_id}", response_model=JobRecord)
+def get_job(job_id: str, x_api_key: str | None = Header(default=None)) -> JobRecord:
+    _check_auth(x_api_key)
+    job = repo_get_job(job_id)
+    if not job:
+        raise HTTPException(status_code=404, detail="Job not found")
+    return JobRecord(**job)
+
+
+@app.get("/")
+def root() -> dict[str, str]:
+    return {
+        "message": settings.app_name,
+        "docs": "/docs",
+        "health": "/v1/health",
+        "jobs": "/v1/jobs",
+    }

apps/backend-api/app/models.py

@@ -0,0 +1,69 @@
+from __future__ import annotations
+
+from typing import Literal
+from uuid import uuid4
+
+from pydantic import BaseModel, Field
+
+ModeType = Literal["part", "assembly", "sketch"]
+OutputType = Literal["2d_vector", "surface", "3d_solid"]
+JobStatus = Literal["submitted", "validated", "queued", "running", "completed", "failed"]
+
+
+class GenerateSpecRequest(BaseModel):
+    prompt: str = Field(min_length=3, max_length=1000)
+    mode: ModeType = "part"
+    output_type: OutputType = "3d_solid"
+    session_id: str | None = None
+
+
+class CreateJobRequest(BaseModel):
+    prompt: str = Field(min_length=3, max_length=1000)
+    mode: ModeType = "part"
+    output_type: OutputType = "3d_solid"
+    session_id: str | None = None
+
+
+class CadStyle(BaseModel):
+    family: str = "industrial"
+    heaviness: float = 0.6
+
+
+class CadSpec(BaseModel):
+    output_type: OutputType
+    geometry_family: str
+    units: str = "mm"
+    parameters: dict[str, int | float | str]
+    style: CadStyle
+
+
+class GenerateSpecResponse(BaseModel):
+    ok: bool = True
+    cached: bool = False
+    prompt_hash: str
+    spec: CadSpec
+    notes: list[str] = []
+    model: str = "stub/template-router"
+    suspicious_input: bool = False
+    fallback_level: str = "normal"
+
+
+class JobRecord(BaseModel):
+    id: str = Field(default_factory=lambda: str(uuid4()))
+    status: JobStatus = "submitted"
+    prompt: str
+    mode: ModeType = "part"
+    output_type: OutputType = "3d_solid"
+    session_id: str | None = None
+    prompt_hash: str | None = None
+    spec: CadSpec | None = None
+    notes: list[str] = []
+    error: str | None = None
+
+
+class HealthResponse(BaseModel):
+    status: str
+    environment: str
+    rate_limit_per_hour: int
+    cache_entries: int
+    jobs_in_memory: int

apps/backend-api/app/repository.py

@@ -0,0 +1,85 @@
+from __future__ import annotations
+
+from typing import Any
+
+from .db import connect, get_database_state, serialize_json
+from .models import JobRecord
+from .store import _JOBS
+
+
+def save_job(job: JobRecord) -> None:
+    db_state = get_database_state()
+    if not db_state.enabled:
+        _JOBS[job.id] = job.model_dump()
+        return
+
+    with connect() as conn:
+        with conn.cursor() as cur:
+            cur.execute(
+                """
+                insert into jobs (
+                    id, status, prompt, mode, output_type, client_session_id,
+                    prompt_hash, spec_json, notes_json, error_text
+                )
+                values (%s, %s, %s, %s, %s, %s, %s, %s::jsonb, %s::jsonb, %s)
+                on conflict (id) do update set
+                    status = excluded.status,
+                    prompt = excluded.prompt,
+                    mode = excluded.mode,
+                    output_type = excluded.output_type,
+                    client_session_id = excluded.client_session_id,
+                    prompt_hash = excluded.prompt_hash,
+                    spec_json = excluded.spec_json,
+                    notes_json = excluded.notes_json,
+                    error_text = excluded.error_text,
+                    updated_at = now()
+                """,
+                (
+                    job.id,
+                    job.status,
+                    job.prompt,
+                    job.mode,
+                    job.output_type,
+                    job.session_id,
+                    job.prompt_hash,
+                    serialize_json(job.spec.model_dump() if job.spec else None),
+                    serialize_json(job.notes),
+                    job.error,
+                ),
+            )
+        conn.commit()
+
+
+def get_job(job_id: str) -> dict[str, Any] | None:
+    db_state = get_database_state()
+    if not db_state.enabled:
+        return _JOBS.get(job_id)
+
+    with connect() as conn:
+        with conn.cursor() as cur:
+            cur.execute(
+                """
+                select id, status, prompt, mode, output_type, client_session_id,
+                       prompt_hash, spec_json, notes_json, error_text
+                from jobs
+                where id = %s
+                """,
+                (job_id,),
+            )
+            row = cur.fetchone()
+            if not row:
+                return None
+
+    id_, status, prompt, mode, output_type, client_session_id, prompt_hash, spec_json, notes_json, error_text = row
+    return {
+        "id": str(id_),
+        "status": status,
+        "prompt": prompt,
+        "mode": mode,
+        "output_type": output_type,
+        "session_id": client_session_id,
+        "prompt_hash": prompt_hash,
+        "spec": spec_json,
+        "notes": notes_json or [],
+        "error": error_text,
+    }

apps/backend-api/app/store.py

@@ -0,0 +1,7 @@
+from __future__ import annotations
+
+from collections import defaultdict, deque
+
+_REQUESTS: dict[str, deque[float]] = defaultdict(deque)
+_CACHE: dict[str, dict] = {}
+_JOBS: dict[str, dict] = {}

apps/backend-api/db/README.md

@@ -0,0 +1,12 @@
+# NaturalCAD backend database
+
+This folder holds the first Postgres schema for NaturalCAD v0.
+
+## Target
+- Supabase Postgres
+
+## Files
+- `schema.sql` - initial jobs, artifacts, audit_events, and rate_limits tables
+
+## Notes
+This is the first persistence layer replacing the in-memory backend store. Apply this schema to Supabase once the project/account is ready.

apps/backend-api/db/schema.sql

@@ -0,0 +1,59 @@
+-- NaturalCAD Backend v0 schema
+-- Target: Supabase Postgres
+
+create extension if not exists pgcrypto;
+
+create table if not exists jobs (
+    id uuid primary key default gen_random_uuid(),
+    created_at timestamptz not null default now(),
+    updated_at timestamptz not null default now(),
+    status text not null check (status in ('submitted', 'validated', 'queued', 'running', 'completed', 'failed')),
+    prompt text not null,
+    normalized_prompt text,
+    mode text not null,
+    output_type text not null,
+    client_session_id text,
+    prompt_hash text,
+    spec_json jsonb,
+    error_text text,
+    model_info_json jsonb,
+    notes_json jsonb not null default '[]'::jsonb
+);
+
+create index if not exists idx_jobs_status on jobs (status);
+create index if not exists idx_jobs_created_at on jobs (created_at desc);
+create index if not exists idx_jobs_prompt_hash on jobs (prompt_hash);
+
+create table if not exists artifacts (
+    id uuid primary key default gen_random_uuid(),
+    created_at timestamptz not null default now(),
+    job_id uuid not null references jobs(id) on delete cascade,
+    kind text not null check (kind in ('stl', 'step', 'preview', 'log')),
+    storage_key text not null,
+    size_bytes bigint,
+    expires_at timestamptz
+);
+
+create index if not exists idx_artifacts_job_id on artifacts (job_id);
+create index if not exists idx_artifacts_kind on artifacts (kind);
+
+create table if not exists audit_events (
+    id uuid primary key default gen_random_uuid(),
+    created_at timestamptz not null default now(),
+    job_id uuid references jobs(id) on delete cascade,
+    event_type text not null,
+    details_json jsonb not null default '{}'::jsonb
+);
+
+create index if not exists idx_audit_events_job_id on audit_events (job_id);
+create index if not exists idx_audit_events_event_type on audit_events (event_type);
+
+create table if not exists rate_limits (
+    id uuid primary key default gen_random_uuid(),
+    created_at timestamptz not null default now(),
+    key text not null,
+    window_start timestamptz not null,
+    request_count integer not null default 0
+);
+
+create index if not exists idx_rate_limits_key_window on rate_limits (key, window_start desc);

apps/backend-api/requirements.txt

@@ -0,0 +1,6 @@
+fastapi>=0.115.0
+uvicorn[standard]>=0.30.0
+pydantic>=2.8.0
+python-dotenv>=1.0.1
+httpx>=0.27.0
+psycopg[binary]>=3.2.0

apps/gradio-demo/.gitignore

@@ -0,0 +1,5 @@
+.venv/
+__pycache__/
+artifacts/model.stl
+artifacts/model.step
+artifacts/runs/

apps/gradio-demo/HF_SPACE_NOTES.md

@@ -0,0 +1,21 @@
+# NaturalCAD HF Space Notes
+
+## Current intent
+- Public-facing NaturalCAD app
+- build123d-backed execution loop
+- Noah will wire a service endpoint for LLM generation later
+
+## Current prototype state
+- Gradio UI
+- real build123d execution
+- STL preview
+- STL + STEP downloads
+- starter sample picker
+- prompt note field for future LLM integration
+- archived per-run artifacts under `artifacts/runs/`
+
+## Next likely steps
+- add endpoint config pattern for external LLM service
+- convert prompt note into real prompt-to-code flow
+- improve public-facing examples
+- add safe execution constraints for Spaces

apps/gradio-demo/README.md

@@ -0,0 +1,54 @@
+# NaturalCAD
+
+Gradio prototype for NaturalCAD, a public natural-language CAD modeler built on build123d.
+
+## Purpose
+
+- Fast Hugging Face Spaces deployment
+- Test prompt → spec → CAD loop
+- Validate interaction model before deeper productization
+- Keep the MVP portable enough to offload execution later if Space limits become a problem
+
+## Features
+
+- Prompt-driven model generation through the NaturalCAD backend when available
+- Local fallback generation if the backend is unavailable
+- Run build123d geometry and see STL preview
+- Download STL and STEP exports
+- View backend + execution logs
+- Lightweight run logging for MVP testing data (`artifacts/logs/runs.jsonl`)
+
+## Run locally
+
+Start the backend first:
+
+```bash
+cd ../backend-api
+python3 -m venv .venv
+.venv/bin/pip install -r requirements.txt
+.venv/bin/uvicorn app.main:app --reload --port 8010
+```
+
+Then run the Gradio app:
+
+```bash
+pip install -r requirements.txt
+python app/main.py
+```
+
+Current Space-oriented dependency note:
+- `build123d==0.10.0` is now declared directly in `requirements.txt`
+- if Hugging Face Space cannot reliably support the CAD dependency stack, we can keep the UI there and offload execution to a container or VM later without changing the product direction
+
+Optional environment variables:
+- `NATURALCAD_BACKEND_URL` (leave unset for a pure Space-only MVP, or set it to enable backend-assisted spec generation)
+- `NATURALCAD_API_KEY`
+- `NATURALCAD_BACKEND_TIMEOUT` (default `4` seconds)
+- `BUILD123D_PYTHON` (defaults to the current Python runtime, which is better for Hugging Face Space deployment)
+
+Runtime artifacts:
+- latest files in `artifacts/`
+- archived runs in `artifacts/runs/`
+- lightweight run logs in `artifacts/logs/runs.jsonl`
+
+Open http://localhost:7860

apps/gradio-demo/app/main.py

@@ -0,0 +1,496 @@
+#!/usr/bin/env python3
+"""Gradio app for live build123d geometry execution and export."""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import subprocess
+import sys
+import tempfile
+import time
+import traceback
+import uuid
+from datetime import datetime, timezone
+from pathlib import Path
+from urllib import error, request
+
+import gradio as gr
+
+BUILD123D_PYTHON = os.getenv("BUILD123D_PYTHON", sys.executable)
+BACKEND_URL = os.getenv("NATURALCAD_BACKEND_URL", os.getenv("NL_CAD_BACKEND_URL", "")).strip()
+BACKEND_API_KEY = os.getenv("NATURALCAD_API_KEY", os.getenv("NL_CAD_API_KEY", ""))
+BACKEND_TIMEOUT_SECONDS = float(os.getenv("NATURALCAD_BACKEND_TIMEOUT", "4"))
+ARTIFACTS_DIR = Path(__file__).parent.parent / "artifacts"
+RUNS_DIR = ARTIFACTS_DIR / "runs"
+LOGS_DIR = ARTIFACTS_DIR / "logs"
+RUN_LOG_PATH = LOGS_DIR / "runs.jsonl"
+ARTIFACTS_DIR.mkdir(parents=True, exist_ok=True)
+RUNS_DIR.mkdir(parents=True, exist_ok=True)
+LOGS_DIR.mkdir(parents=True, exist_ok=True)
+
+EXAMPLE_PROMPTS = [
+    ["Heavy steel bracket with 4 bolt holes, 90 mm wide, 8 mm thick", "part", "3d_solid"],
+    ["Light structural truss beam with 9 panels and a 180 mm span", "part", "3d_solid"],
+    ["Industrial notched tower block, 140 mm tall", "part", "3d_solid"],
+    ["Smooth roof canopy surface, 200 mm span, shallow rise", "part", "surface"],
+    ["Bracket plate profile with 6 holes for a laser-cut sketch", "sketch", "2d_vector"],
+]
+
+DEFAULT_CODE = '''from build123d import *
+
+width = 80
+height = 50
+thickness = 6
+hole_diameter = 10
+
+with BuildPart() as bp:
+    with BuildSketch(Plane.XY) as base:
+        Rectangle(width, height)
+        with GridLocations(width * 0.6, height * 0.6, 2, 2):
+            Circle(hole_diameter / 2)
+    extrude(amount=thickness)
+
+result = bp.part
+'''
+
+
+def render_code_from_spec(spec: dict) -> str:
+    geometry_family = spec.get("geometry_family", "bracket_plate")
+    output_type = spec.get("output_type", "3d_solid")
+    params = spec.get("parameters", {})
+
+    if geometry_family == "tower_block":
+        width = params.get("width", 30)
+        length = params.get("length", 30)
+        height = params.get("height", 120)
+        notch = params.get("notch", 10)
+        return f'''from build123d import *
+
+width = {width}
+length = {length}
+height = {height}
+notch = {notch}
+
+with BuildPart() as bp:
+    Box(width, length, height)
+    with Locations((0, 0, height / 4), (0, 0, -height / 4)):
+        Box(width + 2, notch, notch, mode=Mode.SUBTRACT)
+        Box(notch, length + 2, notch, mode=Mode.SUBTRACT)
+
+result = bp.part
+'''
+
+    if geometry_family == "truss_beam":
+        span = params.get("span", 140)
+        height = params.get("height", 24)
+        panel_count = max(3, int(params.get("panel_count", 7)))
+        member_size = params.get("member_size", 3)
+        return f'''from build123d import *
+
+span = {span}
+height = {height}
+chord = {member_size}
+post = {member_size}
+panel_count = {panel_count}
+
+with BuildPart() as bp:
+    with Locations((0, 0, chord / 2)):
+        Box(span, chord, chord)
+    with Locations((0, 0, height - chord / 2)):
+        Box(span, chord, chord)
+
+    panel = span / panel_count
+    post_locations = [(-span / 2 + i * panel, 0, height / 2) for i in range(panel_count + 1)]
+    with Locations(*post_locations):
+        Box(post, chord, height)
+
+result = bp.part
+'''
+
+    if geometry_family == "truss_elevation":
+        span = params.get("span", 140)
+        height = params.get("height", 24)
+        panel_count = max(3, int(params.get("panel_count", 7)))
+        member_size = params.get("member_size", 3)
+        preview_thickness = params.get("preview_thickness", 1)
+        return f'''from build123d import *
+
+span = {span}
+height = {height}
+panel_count = {panel_count}
+member_size = {member_size}
+preview_thickness = {preview_thickness}
+
+with BuildPart() as bp:
+    with BuildSketch(Plane.XY) as sk:
+        Rectangle(span, member_size, align=(Align.CENTER, Align.CENTER))
+        with Locations((0, height)):
+            Rectangle(span, member_size, align=(Align.CENTER, Align.CENTER))
+        panel = span / panel_count
+        for i in range(panel_count + 1):
+            x = -span / 2 + i * panel
+            with Locations((x, height / 2)):
+                Rectangle(member_size, height, align=(Align.CENTER, Align.CENTER))
+    extrude(amount=preview_thickness)
+
+result = bp.part
+'''
+
+    if geometry_family in {"canopy_surface", "lofted_panel"} or output_type == "surface":
+        if geometry_family == "canopy_surface":
+            span = params.get("span", 160)
+            depth = params.get("depth", 90)
+            peak_height = params.get("peak_height", 38)
+            thickness = params.get("thickness", 2)
+            return f'''from build123d import *
+
+span = {span}
+depth = {depth}
+peak_height = {peak_height}
+thickness = {thickness}
+
+with BuildPart() as bp:
+    with BuildSketch(Plane.XY.offset(0)) as s1:
+        Rectangle(span, depth)
+    with BuildSketch(Plane.XY.offset(peak_height)) as s2:
+        Rectangle(span * 0.65, depth * 0.65)
+    loft()
+    offset(amount=thickness)
+
+result = bp.part
+'''
+        width = params.get("width", 80)
+        depth = params.get("depth", 50)
+        rise = params.get("rise", 18)
+        thickness = params.get("thickness", 2)
+        return f'''from build123d import *
+
+width = {width}
+depth = {depth}
+rise = {rise}
+thickness = {thickness}
+
+with BuildPart() as bp:
+    with BuildSketch(Plane.XY.offset(0)) as s1:
+        Rectangle(width, depth)
+    with BuildSketch(Plane.XY.offset(rise)) as s2:
+        Rectangle(width * 0.55, depth * 0.55)
+    loft()
+    offset(amount=thickness)
+
+result = bp.part
+'''
+
+    width = params.get("width", 80)
+    height = params.get("height", 50)
+    hole_count = max(1, int(params.get("hole_count", 4)))
+    hole_diameter = params.get("hole_diameter", 10)
+    x_count = max(1, round(hole_count ** 0.5))
+    y_count = max(1, (hole_count + x_count - 1) // x_count)
+
+    if output_type == "2d_vector":
+        preview_thickness = params.get("preview_thickness", 1)
+        return f'''from build123d import *
+
+width = {width}
+height = {height}
+hole_diameter = {hole_diameter}
+preview_thickness = {preview_thickness}
+
+with BuildPart() as bp:
+    with BuildSketch(Plane.XY) as base:
+        Rectangle(width, height)
+        with GridLocations(width * 0.6, height * 0.6, {x_count}, {y_count}):
+            Circle(hole_diameter / 2, mode=Mode.SUBTRACT)
+    extrude(amount=preview_thickness)
+
+result = bp.part
+'''
+
+    thickness = params.get("thickness", 6)
+    return f'''from build123d import *
+
+width = {width}
+height = {height}
+thickness = {thickness}
+hole_diameter = {hole_diameter}
+
+with BuildPart() as bp:
+    with BuildSketch(Plane.XY) as base:
+        Rectangle(width, height)
+        with GridLocations(width * 0.6, height * 0.6, {x_count}, {y_count}):
+            Circle(hole_diameter / 2, mode=Mode.SUBTRACT)
+    extrude(amount=thickness)
+
+result = bp.part
+'''
+
+
+def create_job(prompt: str, mode: str, output_type: str) -> tuple[dict | None, str]:
+    if not prompt.strip():
+        return None, ""
+
+    if not BACKEND_URL:
+        return None, json.dumps({"info": "backend disabled", "detail": "No NATURALCAD_BACKEND_URL configured."}, indent=2)
+
+    payload = json.dumps({"prompt": prompt, "mode": mode, "output_type": output_type}).encode()
+    headers = {"Content-Type": "application/json"}
+    if BACKEND_API_KEY:
+        headers["x-api-key"] = BACKEND_API_KEY
+
+    req = request.Request(
+        f"{BACKEND_URL.rstrip('/')}/v1/jobs",
+        data=payload,
+        headers=headers,
+        method="POST",
+    )
+
+    try:
+        with request.urlopen(req, timeout=BACKEND_TIMEOUT_SECONDS) as response:
+            data = json.loads(response.read().decode())
+            return data, json.dumps(data, indent=2)
+    except error.HTTPError as exc:
+        detail = exc.read().decode() if exc.fp else str(exc)
+        return None, json.dumps({"error": f"backend http {exc.code}", "detail": detail}, indent=2)
+    except Exception as exc:  # noqa: BLE001
+        return None, json.dumps({"error": f"backend unavailable: {exc}"}, indent=2)
+
+
+def _append_run_log(entry: dict) -> None:
+    with RUN_LOG_PATH.open("a", encoding="utf-8") as fh:
+        fh.write(json.dumps(entry) + "\n")
+
+
+def run_build123d(code: str, prompt: str = "") -> tuple[str | None, str | None, str, str, str | None, float]:
+    if not code or not code.strip():
+        return None, None, "No code provided.", "No geometry was generated.", None, 0.0
+
+    logs: list[str] = []
+    stl_path: str | None = None
+    step_path: str | None = None
+    started_at = time.time()
+    run_id = uuid.uuid4().hex[:8]
+
+    with tempfile.TemporaryDirectory() as tmpdir:
+        source_file = Path(tmpdir) / "user_script.py"
+        source_file.write_text(code)
+        stl_file = RUNS_DIR / f"{run_id}.stl"
+        step_file = RUNS_DIR / f"{run_id}.step"
+
+        logs.append(f"Run ID: {run_id}")
+        if prompt.strip():
+            logs.append(f"Prompt: {prompt.strip()}")
+        logs.append("Running build123d script...")
+
+        runner_code = f'''
+import sys
+from pathlib import Path
+from build123d import export_stl, export_step
+
+source_path = Path(r"{source_file}")
+user_globals = {{}}
+exec(compile(source_path.read_text(), str(source_path), "exec"), user_globals)
+
+candidate = user_globals.get("result")
+if candidate is None:
+    sys.exit("No `result` geometry found after execution.")
+
+def coerce_shape(obj):
+    if obj is None:
+        return None
+    if hasattr(obj, "wrapped"):
+        return obj
+    for attr in ("part", "shape", "solid", "obj"):
+        value = getattr(obj, attr, None)
+        if value is not None and not callable(value):
+            obj = value
+            if hasattr(obj, "wrapped"):
+                return obj
+    return obj
+
+shape = coerce_shape(candidate)
+if shape is None:
+    sys.exit("Could not extract exportable shape from `result`.")
+
+export_stl(shape, r"{stl_file}")
+export_step(shape, r"{step_file}")
+print("STL exported to {stl_file}")
+print("STEP exported to {step_file}")
+'''
+
+        runner_file = Path(tmpdir) / "_runner.py"
+        runner_file.write_text(runner_code)
+
+        try:
+            result = subprocess.run(
+                [BUILD123D_PYTHON, str(runner_file)],
+                capture_output=True,
+                text=True,
+                timeout=60,
+            )
+            if result.stdout:
+                logs.append(result.stdout.strip())
+            if result.stderr:
+                logs.append(f"[stderr] {result.stderr.strip()}")
+            if result.returncode == 0 and stl_file.exists() and step_file.exists():
+                latest_stl = ARTIFACTS_DIR / "model.stl"
+                latest_step = ARTIFACTS_DIR / "model.step"
+                shutil.copy2(stl_file, latest_stl)
+                shutil.copy2(step_file, latest_step)
+                stl_path = str(latest_stl)
+                step_path = str(latest_step)
+                logs.append(f"Export successful. Archived artifacts at runs/{run_id}.*")
+            else:
+                logs.append(f"Runner exited with code {result.returncode}.")
+        except subprocess.TimeoutExpired:
+            logs.append("Execution timed out after 60 seconds.")
+        except Exception as exc:  # noqa: BLE001
+            logs.append(f"Execution error: {exc}")
+            logs.append(traceback.format_exc())
+
+    duration = time.time() - started_at
+    summary = f"Model ready in {duration:.2f}s."
+    return stl_path, step_path, "\n".join(logs), summary, run_id, duration
+
+
+def generate_from_prompt(prompt: str, mode: str, output_type: str):
+    started_at = time.time()
+    backend_ok = True
+    client_notice = None
+    fallback_level = "normal"
+    suspicious_input = False
+    job_data, backend_log = create_job(prompt, mode, output_type)
+    if job_data is None:
+        backend_ok = False
+        backend_log = backend_log or "Backend request failed."
+        spec = {
+            "output_type": output_type,
+            "geometry_family": "bracket_plate",
+            "parameters": {},
+        }
+        client_notice = "Backend was unavailable or disabled, so NaturalCAD used a simple local fallback."
+        fallback_level = "backend_unavailable"
+    else:
+        spec = job_data.get("spec")
+        suspicious_input = bool(job_data.get("suspicious_input", False))
+        fallback_level = job_data.get("fallback_level", "normal")
+        if suspicious_input:
+            client_notice = "Your prompt looked partly like code or unsafe instructions, so NaturalCAD used a safer interpretation for this run."
+        elif fallback_level == "underspecified":
+            client_notice = "Your prompt was pretty open-ended, so NaturalCAD filled in conservative defaults for this run."
+
+        if not spec:
+            _append_run_log({
+                "timestamp": datetime.now(timezone.utc).isoformat(),
+                "prompt": prompt,
+                "mode": mode,
+                "output_type": output_type,
+                "backend_ok": backend_ok,
+                "success": False,
+                "error": "Backend created no CAD spec.",
+            })
+            return None, None, None, backend_log, "Backend created no CAD spec."
+
+    code = render_code_from_spec(spec)
+    stl_path, step_path, logs, summary, run_id, execution_seconds = run_build123d(code, prompt)
+    combined_logs = "\n\n".join([
+        "Backend job created:" if backend_ok else "Backend unavailable, using local fallback:",
+        backend_log,
+        "Local execution log:",
+        logs,
+    ])
+    success = bool(stl_path)
+    _append_run_log({
+        "timestamp": datetime.now(timezone.utc).isoformat(),
+        "run_id": run_id,
+        "prompt": prompt,
+        "mode": mode,
+        "output_type": output_type,
+        "geometry_family": spec.get("geometry_family"),
+        "backend_ok": backend_ok,
+        "suspicious_input": suspicious_input,
+        "fallback_level": fallback_level,
+        "success": success,
+        "runtime_seconds": round(time.time() - started_at, 3),
+        "execution_seconds": round(execution_seconds, 3),
+        "error": None if success else "Generation failed.",
+    })
+    if not stl_path:
+        return None, None, None, combined_logs, "Generation failed. Try a simpler prompt or an example."
+
+    final_summary = summary if not client_notice else f"{summary}\n\n⚠️ {client_notice}"
+    return stl_path, stl_path, step_path, combined_logs, final_summary
+
+
+def use_example(prompt: str, mode: str, output_type: str):
+    return prompt, mode, output_type
+
+
+def build_ui() -> gr.Blocks:
+    with gr.Blocks(title="NaturalCAD", theme=gr.themes.Base()) as demo:
+        gr.Markdown(
+            "# NaturalCAD\n"
+            "Turn a natural-language prompt into a downloadable CAD result."
+        )
+        gr.Markdown(
+            "**Best for demo:** one-shot parts, frames, blocks, canopies, and simple profiles."
+        )
+
+        with gr.Row(equal_height=True):
+            with gr.Column(scale=1, min_width=360):
+                prompt_input = gr.Textbox(
+                    label="Describe what you want",
+                    placeholder="A heavy steel bracket with 4 bolt holes, 90 mm wide and 8 mm thick",
+                    lines=6,
+                )
+                with gr.Row():
+                    mode_picker = gr.Dropdown(choices=["part", "assembly", "sketch"], value="part", label="Mode")
+                    output_picker = gr.Dropdown(choices=["3d_solid", "surface", "2d_vector"], value="3d_solid", label="Output")
+                generate_btn = gr.Button("Generate Model", variant="primary")
+                gr.Markdown("### Try one of these")
+                gr.Examples(
+                    examples=EXAMPLE_PROMPTS,
+                    inputs=[prompt_input, mode_picker, output_picker],
+                    fn=use_example,
+                    outputs=[prompt_input, mode_picker, output_picker],
+                    cache_examples=False,
+                )
+
+            with gr.Column(scale=2, min_width=520):
+                model_viewer = gr.Model3D(label="Preview", elem_id="model-viewer", display_mode="solid")
+                with gr.Row():
+                    stl_download = gr.File(label="Download STL")
+                    step_download = gr.File(label="Download STEP")
+                status_output = gr.Markdown("Ready. Use the mouse to orbit, pan, and zoom the model.")
+
+        log_output = gr.Textbox(
+            label="Run log",
+            lines=7,
+            max_lines=20,
+            interactive=False,
+            elem_classes=["log-box"],
+        )
+
+        generate_btn.click(
+            fn=generate_from_prompt,
+            inputs=[prompt_input, mode_picker, output_picker],
+            outputs=[model_viewer, stl_download, step_download, log_output, status_output],
+        )
+
+    return demo
+
+
+if __name__ == "__main__":
+    app = build_ui()
+    app.launch(
+        server_name="0.0.0.0",
+        server_port=7860,
+        css="""
+        #model-viewer {height: 620px !important; border-radius: 18px; overflow: hidden;}
+        .log-box textarea {font-family: 'JetBrains Mono', monospace; font-size: 13px;}
+        .gradio-container {max-width: 1380px !important;}
+        button.primary {font-weight: 700;}
+        """,
+    )

apps/gradio-demo/requirements.txt

@@ -0,0 +1,3 @@
+gradio>=4.0.0
+trimesh
+build123d==0.10.0

apps/viewer/README.md

@@ -0,0 +1,8 @@
+# Viewer App
+
+Main application shell for the live visualizer.
+
+Planned regions:
+- left: prompt/editor/parameters
+- center: viewport
+- bottom or right: terminal/logs

apps/web-visualizer/README.md

@@ -0,0 +1,49 @@
+# build123d Live Visualizer Prototype
+
+This prototype pairs a lightweight Express runner with a Vite + React front-end that streams runner logs and renders generated STL files inside a browser-based viewport.
+
+## Prerequisites
+
+- Node.js 18+
+- Access to the existing `build123d` Python environment at `/Users/noahk/.openclaw/workspace/skills/build123d-cad/.venv/bin/python` (automatically used by the server).
+
+## Getting Started
+
+```bash
+npm install
+npm run dev
+```
+
+The shortcut above launches both the Express runner (`http://localhost:4000`) and the Vite dev server (`http://localhost:5173`).
+
+### Manual split
+
+```bash
+npm run dev:server # terminal 1
+npm run dev:client # terminal 2
+```
+
+The front-end proxies `/api` and `/artifacts` calls to the Express server when running in dev mode.
+
+## Using the Prototype
+
+1. Paste or edit build123d code inside the left panel. Ensure your geometry is assigned to a variable called `result`.
+2. Click **Run & Stream**. The server writes your code to a scratch file, executes it inside the configured `build123d` virtualenv, and exports STL and STEP artifacts into `./artifacts`.
+3. Logs and errors stream into the right-hand panel. When the export succeeds, the STL is loaded into the three.js viewport and download links become available for both STL and STEP.
+
+### Sample Snippet
+
+```python
+from build123d import *
+
+with BuildPart() as bp:
+    with BuildSketch(Plane.XY) as base:
+        Rectangle(40, 20)
+        Locations((0, 0))
+        Circle(6)
+    extrude(amount=12)
+
+result = bp.part
+```
+
+All exported artifacts live inside the `artifacts/` folder, which is served statically for browser fetching.

apps/web-visualizer/docs/architecture.md

@@ -0,0 +1,26 @@
+# build123d Live Visualizer — Architecture Notes
+
+## Live Update Loop
+- **Front-end trigger** – `Run & Stream` button encodes the textarea contents into an SSE request (`/api/run?code=...`).
+- **Server orchestration** – Express writes the snippet to `artifacts/<job>.py`, spawns the dedicated build123d Python interpreter, and relays stdout/stderr as Server-Sent Events (`log` events).
+- **Completion signal** – When the Python runner finishes, Express emits a `complete` event containing the STL path (or an error message). The client loads the STL via `three.js` and refreshes the viewer.
+- **Resilience** – Each run is isolated via UUIDs, making the log stream and artifacts easy to correlate while enabling multiple sequential runs without restarts.
+
+## Artifact Flow
+1. Client sends code → Express persists under `artifacts/<job>.py`.
+2. Python runner executes snippet, requiring a `result` variable and exporting to `artifacts/<job>.stl`.
+3. Express serves `/artifacts` statically so the browser can fetch STL files immediately.
+4. Front-end STL loader retrieves the file, renders it, and exposes a download link; artifacts remain on disk for inspection or later cleanup.
+
+## LLM Integration Options
+- **OpenClaw Orchestrator** – Keep the current human-in-the-loop workflow where OpenClaw agents call the `/api/run` endpoint, enabling prompt-to-geometry iteration without exposing provider keys to the prototype.
+- **Direct Provider Calls** – Embed provider SDK (OpenAI, Anthropic, etc.) within the server. The Express layer would accept natural-language prompts, forward them to an LLM, and pipe the generated build123d script straight into the runner before streaming results back.
+- **Local Coding Agent** – Bundle a lightweight model (e.g., `llama.cpp`) or a deterministic templating agent that runs locally, translating UI prompts to build123d code without external network usage—aligned with offline or air-gapped deployments.
+
+## Next-Step Roadmap
+- Add job queueing plus cancellation support per run id (currently a single in-memory stream).
+- Persist structured job metadata (prompt, status, artifact path) for replay and auditing.
+- Harden sandboxing by running the Python process inside a constrained container or Firejail profile.
+- Expand the viewer with assembly overlays (multiple STL layers, color coding, exploded views).
+- Wire optional LLM prompt templates + history so designers can iterate conversationally.
+- Author smoke tests covering the SSE endpoint and sample runner invocation.

apps/web-visualizer/docs/milestone-01.md

@@ -0,0 +1,34 @@
+# Milestone 01 - Stable Live Modeling Loop
+
+## Goal
+
+Turn the prototype into a dependable first product loop.
+
+## Scope
+
+- edit build123d code in-app
+- run geometry through the local build123d runtime
+- stream logs/errors live
+- preview geometry in a live viewport via STL
+- export both STL and STEP from the same run
+
+## Why this first
+
+This locks the core modeling runtime before deeper LLM integration.
+If the live loop is weak, the AI layer becomes brittle and frustrating.
+
+## Definition of done
+
+- code changes run reliably from the UI
+- viewport updates consistently after successful runs
+- STL download works
+- STEP download works
+- errors are readable in the log pane
+- repo is clean enough to keep building on
+
+## Next after this
+
+- parameter controls and editable variables
+- document model and adapter contract
+- LLM edit/apply flow
+- vector and graphic-mass display modes

apps/web-visualizer/index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <link rel="icon" type="image/svg+xml" href="/vite.svg" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>build123d Live Visualizer</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

apps/web-visualizer/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "build123d-live-visualizer",
+  "version": "0.1.0",
+  "private": true,
+  "scripts": {
+    "dev": "concurrently \"npm:dev:server\" \"npm:dev:client\"",
+    "dev:server": "node server/index.js",
+    "dev:client": "vite",
+    "build": "vite build",
+    "preview": "vite preview",
+    "lint": "echo 'Add linting as needed'"
+  },
+  "dependencies": {
+    "cors": "^2.8.5",
+    "express": "^4.18.2",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "three": "^0.161.0"
+  },
+  "devDependencies": {
+    "@types/express": "^4.17.21",
+    "@types/node": "^20.10.5",
+    "@types/react": "^18.2.48",
+    "@types/react-dom": "^18.2.18",
+    "@vitejs/plugin-react": "^4.2.0",
+    "concurrently": "^8.2.1",
+    "typescript": "^5.3.3",
+    "vite": "^5.0.0"
+  }
+}

apps/web-visualizer/server/index.js

@@ -0,0 +1,93 @@
+const express = require('express');
+const cors = require('cors');
+const { spawn } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+const { randomUUID } = require('crypto');
+
+const PYTHON_BIN = process.env.BUILD123D_PYTHON || '/Users/noahk/.openclaw/workspace/skills/build123d-cad/.venv/bin/python';
+const PORT = process.env.PORT || 4000;
+const ARTIFACT_DIR = path.join(__dirname, '..', 'artifacts');
+const RUNNER_PATH = path.join(__dirname, 'runner.py');
+const DIST_PATH = path.join(__dirname, '..', 'dist');
+
+fs.mkdirSync(ARTIFACT_DIR, { recursive: true });
+
+const app = express();
+app.use(cors());
+app.use(express.json({ limit: '1mb' }));
+app.use('/artifacts', express.static(ARTIFACT_DIR));
+
+if (fs.existsSync(DIST_PATH)) {
+  app.use(express.static(DIST_PATH));
+}
+
+const sendSse = (res, event, data) => {
+  res.write(`event: ${event}\n`);
+  res.write(`data: ${JSON.stringify(data)}\n\n`);
+};
+
+app.get('/api/run', (req, res) => {
+  const code = req.query.code;
+  if (typeof code !== 'string' || !code.trim()) {
+    res.status(400).json({ error: 'Missing code parameter.' });
+    return;
+  }
+
+  res.setHeader('Content-Type', 'text/event-stream');
+  res.setHeader('Cache-Control', 'no-cache');
+  res.setHeader('Connection', 'keep-alive');
+
+  const jobId = randomUUID();
+  const codeFile = path.join(ARTIFACT_DIR, `${jobId}.py`);
+  const stlFile = path.join(ARTIFACT_DIR, `${jobId}.stl`);
+  const stepFile = path.join(ARTIFACT_DIR, `${jobId}.step`);
+
+  fs.writeFileSync(codeFile, code);
+  sendSse(res, 'log', { message: `Job ${jobId} accepted.` });
+
+  const pythonArgs = [RUNNER_PATH, '--source', codeFile, '--stl-output', stlFile, '--step-output', stepFile];
+  const child = spawn(PYTHON_BIN, pythonArgs, { env: process.env });
+
+  req.on('close', () => {
+    if (!child.killed) {
+      child.kill('SIGINT');
+    }
+  });
+
+  child.stdout.on('data', (chunk) => {
+    sendSse(res, 'log', { message: chunk.toString().trim() });
+  });
+
+  child.stderr.on('data', (chunk) => {
+    sendSse(res, 'log', { message: chunk.toString().trim(), level: 'error' });
+  });
+
+  child.on('error', (error) => {
+    sendSse(res, 'log', { message: `Runner error: ${error.message}`, level: 'error' });
+    sendSse(res, 'complete', { success: false, error: error.message });
+    res.end();
+  });
+
+  child.on('close', (code) => {
+    const success = code === 0;
+    if (success) {
+      sendSse(res, 'complete', {
+        success: true,
+        stlPath: `/artifacts/${path.basename(stlFile)}`,
+        stepPath: `/artifacts/${path.basename(stepFile)}`
+      });
+    } else {
+      sendSse(res, 'complete', { success: false, error: `Runner exited with ${code}` });
+    }
+    res.end();
+  });
+});
+
+app.get('/api/health', (_req, res) => {
+  res.json({ status: 'ok', python: PYTHON_BIN });
+});
+
+app.listen(PORT, () => {
+  console.log(`build123d live runner listening on http://localhost:${PORT}`);
+});

apps/web-visualizer/server/runner.py

@@ -0,0 +1,85 @@
+#!/usr/bin/env python3
+"""Simple build123d runner with STL and STEP export."""
+
+from __future__ import annotations
+
+import argparse
+import pathlib
+import sys
+import traceback
+
+
+def coerce_shape(candidate):
+    """Try to pull an exportable shape from the user namespace."""
+    if candidate is None:
+        return None
+
+    if hasattr(candidate, "wrapped"):
+        return candidate
+
+    for attr in ("part", "shape", "solid", "obj"):
+        value = getattr(candidate, attr, None)
+        if value is not None and not callable(value):
+            candidate = value
+            if hasattr(candidate, "wrapped"):
+                return candidate
+    return candidate
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Run build123d code and export artifacts")
+    parser.add_argument("--source", required=True, help="Path to user code file")
+    parser.add_argument("--stl-output", required=True, help="Path for the STL output")
+    parser.add_argument("--step-output", required=False, help="Path for the STEP output")
+    args = parser.parse_args()
+
+    source_path = pathlib.Path(args.source)
+    stl_output_path = pathlib.Path(args.stl_output)
+    step_output_path = pathlib.Path(args.step_output) if args.step_output else None
+    stl_output_path.parent.mkdir(parents=True, exist_ok=True)
+    if step_output_path:
+        step_output_path.parent.mkdir(parents=True, exist_ok=True)
+
+    try:
+        code = source_path.read_text()
+    except OSError as exc:
+        print(f"Failed to read code: {exc}", file=sys.stderr)
+        return 1
+
+    user_globals: dict[str, object] = {}
+    try:
+        exec(compile(code, str(source_path), "exec"), user_globals)
+    except Exception as exec_error:  # noqa: BLE001
+        print("Execution error:", file=sys.stderr)
+        traceback.print_exception(exec_error, file=sys.stderr)
+        return 1
+
+    candidate = user_globals.get("result")
+    candidate = coerce_shape(candidate)
+
+    if candidate is None:
+        print("No `result` geometry found after execution.", file=sys.stderr)
+        return 2
+
+    try:
+        from build123d import export_stl, export_step
+    except Exception as exc:  # noqa: BLE001
+        print(f"Unable to import build123d exporters: {exc}", file=sys.stderr)
+        return 3
+
+    try:
+        export_stl(candidate, str(stl_output_path))
+        print(f"STL exported to {stl_output_path}")
+        if step_output_path:
+            export_step(candidate, str(step_output_path))
+            print(f"STEP exported to {step_output_path}")
+    except Exception as export_error:  # noqa: BLE001
+        print("Export failed:", file=sys.stderr)
+        traceback.print_exception(export_error, file=sys.stderr)
+        return 4
+
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

apps/web-visualizer/src/App.tsx

@@ -0,0 +1,270 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+import * as THREE from 'three';
+import { OrbitControls } from 'three/examples/jsm/controls/OrbitControls.js';
+import { STLLoader } from 'three/examples/jsm/loaders/STLLoader.js';
+
+const SAMPLE_SNIPPET = `from build123d import *
+
+# Simple parametric puck
+radius = 15
+height = 8
+
+with BuildPart() as bp:
+    with BuildSketch(Plane.XY) as base:
+        Circle(radius)
+        PolarLocations(radius / 2, 6)
+        Circle(radius / 6)
+    extrude(amount=height)
+
+result = bp.part`;
+
+type LogEntry = {
+  id: string;
+  message: string;
+  level: 'info' | 'error';
+};
+
+const loader = new STLLoader();
+
+export default function App() {
+  const [code, setCode] = useState(SAMPLE_SNIPPET);
+  const [logs, setLogs] = useState<LogEntry[]>([]);
+  const [status, setStatus] = useState<'idle' | 'running' | 'done' | 'error'>('idle');
+  const [artifactUrl, setArtifactUrl] = useState<string | null>(null);
+  const [stepUrl, setStepUrl] = useState<string | null>(null);
+  const viewerRef = useRef<HTMLDivElement | null>(null);
+  const eventSourceRef = useRef<EventSource | null>(null);
+  const rendererRef = useRef<THREE.WebGLRenderer | null>(null);
+  const sceneRef = useRef<THREE.Scene | null>(null);
+  const meshRef = useRef<THREE.Mesh | null>(null);
+  const cameraRef = useRef<THREE.PerspectiveCamera | null>(null);
+  const controlsRef = useRef<OrbitControls | null>(null);
+
+  const appendLog = useCallback((message: string, level: 'info' | 'error' = 'info') => {
+    setLogs((prev) => [...prev, { id: crypto.randomUUID(), message, level }]);
+  }, []);
+
+  useEffect(() => {
+    if (!viewerRef.current) return;
+
+    const width = viewerRef.current.clientWidth;
+    const height = viewerRef.current.clientHeight;
+    const scene = new THREE.Scene();
+    scene.background = new THREE.Color(0x020617);
+
+    const camera = new THREE.PerspectiveCamera(45, width / height, 0.1, 1000);
+    camera.position.set(60, 45, 60);
+
+    const renderer = new THREE.WebGLRenderer({ antialias: true });
+    renderer.setSize(width, height);
+    renderer.setPixelRatio(window.devicePixelRatio);
+
+    const controls = new OrbitControls(camera, renderer.domElement);
+    controls.enableDamping = true;
+
+    const ambient = new THREE.AmbientLight(0xffffff, 0.6);
+    const dir = new THREE.DirectionalLight(0xffffff, 0.8);
+    dir.position.set(50, 80, 30);
+
+    const grid = new THREE.GridHelper(120, 20, 0x172554, 0x1e293b);
+
+    scene.add(ambient);
+    scene.add(dir);
+    scene.add(grid);
+
+    viewerRef.current.appendChild(renderer.domElement);
+
+    sceneRef.current = scene;
+    rendererRef.current = renderer;
+    cameraRef.current = camera;
+    controlsRef.current = controls;
+
+    const animate = () => {
+      controls.update();
+      renderer.render(scene, camera);
+      requestAnimationFrame(animate);
+    };
+    animate();
+
+    const handleResize = () => {
+      if (!viewerRef.current || !rendererRef.current || !cameraRef.current) return;
+      const newWidth = viewerRef.current.clientWidth;
+      const newHeight = viewerRef.current.clientHeight;
+      rendererRef.current.setSize(newWidth, newHeight);
+      cameraRef.current.aspect = newWidth / newHeight;
+      cameraRef.current.updateProjectionMatrix();
+    };
+
+    window.addEventListener('resize', handleResize);
+
+    return () => {
+      window.removeEventListener('resize', handleResize);
+      renderer.dispose();
+      controls.dispose();
+    };
+  }, []);
+
+  useEffect(() => {
+    if (!artifactUrl || !sceneRef.current) return;
+
+    loader.load(
+      artifactUrl,
+      (geometry) => {
+        if (meshRef.current) {
+          sceneRef.current!.remove(meshRef.current);
+          meshRef.current.geometry.dispose();
+        }
+        geometry.center();
+        geometry.computeVertexNormals();
+        const material = new THREE.MeshStandardMaterial({
+          color: 0x38bdf8,
+          metalness: 0.1,
+          roughness: 0.4
+        });
+        const mesh = new THREE.Mesh(geometry, material);
+        meshRef.current = mesh;
+        sceneRef.current!.add(mesh);
+        appendLog('STL loaded in viewer.');
+        setStatus('done');
+      },
+      undefined,
+      (error) => {
+        appendLog(`Viewer load error: ${error.message}`, 'error');
+        setStatus('error');
+      }
+    );
+  }, [artifactUrl, appendLog]);
+
+  const handleRun = () => {
+    if (!code.trim()) {
+      appendLog('Add some build123d code before running.', 'error');
+      return;
+    }
+
+    if (eventSourceRef.current) {
+      eventSourceRef.current.close();
+    }
+
+    setLogs([]);
+    setStatus('running');
+    setArtifactUrl(null);
+    setStepUrl(null);
+
+    const url = `/api/run?ts=${Date.now()}&code=${encodeURIComponent(code)}`;
+    const source = new EventSource(url);
+    eventSourceRef.current = source;
+
+    source.addEventListener('log', (event) => {
+      const payload = JSON.parse((event as MessageEvent).data) as { message: string; level?: 'info' | 'error' };
+      appendLog(payload.message, payload.level ?? 'info');
+    });
+
+    source.addEventListener('complete', (event) => {
+      const payload = JSON.parse((event as MessageEvent).data) as { success: boolean; stlPath?: string; stepPath?: string; error?: string };
+      if (payload.success && payload.stlPath) {
+        const finalUrl = `${payload.stlPath}?v=${Date.now()}`;
+        appendLog('Runner completed; STL ready.');
+        if (payload.stepPath) {
+          appendLog('STEP export ready.');
+          setStepUrl(`${payload.stepPath}?v=${Date.now()}`);
+        }
+        setArtifactUrl(finalUrl);
+      } else {
+        appendLog(payload.error ?? 'Runner failed.', 'error');
+        setStatus('error');
+      }
+      source.close();
+    });
+
+    source.onerror = () => {
+      appendLog('Connection interrupted.', 'error');
+      setStatus('error');
+      source.close();
+    };
+  };
+
+  const handleStop = () => {
+    if (eventSourceRef.current) {
+      eventSourceRef.current.close();
+      eventSourceRef.current = null;
+      appendLog('Stream closed by user.');
+      setStatus('idle');
+    }
+  };
+
+  useEffect(() => {
+    return () => {
+      if (eventSourceRef.current) {
+        eventSourceRef.current.close();
+      }
+      if (rendererRef.current) {
+        rendererRef.current.dispose();
+      }
+      if (controlsRef.current) {
+        controlsRef.current.dispose();
+      }
+    };
+  }, []);
+
+  return (
+    <div className="app-shell layout-landscape">
+      <section className="panel panel-editor">
+        <h2>build123d Prompt</h2>
+        <div className="controls">
+          <button onClick={handleRun} disabled={status === 'running'}>
+            {status === 'running' ? 'Running…' : 'Run & Stream'}
+          </button>
+          <button onClick={handleStop}>Stop</button>
+        </div>
+        <textarea
+          className="editor"
+          value={code}
+          onChange={(e) => setCode(e.target.value)}
+          spellCheck={false}
+        />
+        <p style={{ fontSize: '0.8rem', color: '#94a3b8', marginTop: '0.5rem' }}>
+          Tip: assign your geometry to a variable named <code>result</code> so the runner can export it.
+        </p>
+      </section>
+
+      <section className="panel panel-viewer">
+        <div className="panel-header-row">
+          <h2>Live Model</h2>
+          <div className="status-inline">
+            <span>Status: {status}</span>
+          </div>
+        </div>
+        <div className="viewer-container viewer-container-large">
+          <div className="viewer-canvas" ref={viewerRef} />
+        </div>
+        {(artifactUrl || stepUrl) && (
+          <div className="status-row">
+            <span>Exports Ready</span>
+            <div style={{ display: 'flex', gap: '0.75rem' }}>
+              {artifactUrl && (
+                <a href={artifactUrl} download="model.stl" style={{ color: '#38bdf8' }}>
+                  Download STL
+                </a>
+              )}
+              {stepUrl && (
+                <a href={stepUrl} download="model.step" style={{ color: '#f59e0b' }}>
+                  Download STEP
+                </a>
+              )}
+            </div>
+          </div>
+        )}
+      </section>
+
+      <section className="panel panel-logs">
+        <div className="panel-header-row">
+          <h2>Runner Logs</h2>
+          <span className="log-count">{logs.length} entries</span>
+        </div>
+        <div className="logs">
+          {logs.length === 0 ? 'Awaiting output…' : logs.map((log) => `${log.level === 'error' ? '✖' : '•'} ${log.message}`).join('\n')}
+        </div>
+      </section>
+    </div>
+  );
+}

apps/web-visualizer/src/main.tsx

@@ -0,0 +1,10 @@
+import React from 'react';
+import ReactDOM from 'react-dom/client';
+import App from './App';
+import './styles.css';
+
+ReactDOM.createRoot(document.getElementById('root')!).render(
+  <React.StrictMode>
+    <App />
+  </React.StrictMode>
+);

apps/web-visualizer/src/styles.css

@@ -0,0 +1,169 @@
+:root {
+  font-family: 'Inter', system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
+  color: #e5e5e5;
+  background: #0f172a;
+}
+
+* {
+  box-sizing: border-box;
+}
+
+body,
+html,
+#root {
+  margin: 0;
+  padding: 0;
+  width: 100%;
+  height: 100%;
+}
+
+body {
+  background: #0f172a;
+}
+
+.app-shell {
+  display: grid;
+  gap: 0.75rem;
+  height: 100%;
+  padding: 0.75rem;
+  background: radial-gradient(circle at top, rgba(15, 23, 42, 0.95), rgba(2, 6, 23, 0.98));
+}
+
+.layout-landscape {
+  grid-template-columns: minmax(320px, 0.8fr) minmax(720px, 1.8fr);
+  grid-template-rows: minmax(0, 1fr) 180px;
+  grid-template-areas:
+    'editor viewer'
+    'editor logs';
+}
+
+.panel {
+  border: 1px solid rgba(148, 163, 184, 0.15);
+  background: rgba(15, 23, 42, 0.8);
+  border-radius: 0.75rem;
+  padding: 0.75rem;
+  display: flex;
+  flex-direction: column;
+  min-height: 0;
+}
+
+.panel-editor {
+  grid-area: editor;
+}
+
+.panel-viewer {
+  grid-area: viewer;
+}
+
+.panel-logs {
+  grid-area: logs;
+}
+
+.panel h2 {
+  margin: 0 0 0.5rem 0;
+  font-size: 1rem;
+  letter-spacing: 0.03em;
+  text-transform: uppercase;
+  color: #94a3b8;
+}
+
+.editor {
+  flex: 1;
+  resize: none;
+  background: rgba(15, 23, 42, 0.9);
+  color: #f8fafc;
+  border: 1px solid rgba(148, 163, 184, 0.2);
+  border-radius: 0.5rem;
+  font-family: 'JetBrains Mono', 'SFMono-Regular', ui-monospace, monospace;
+  font-size: 0.9rem;
+  padding: 0.75rem;
+  line-height: 1.4;
+}
+
+.controls {
+  display: flex;
+  gap: 0.5rem;
+  margin-bottom: 0.5rem;
+}
+
+button {
+  border: none;
+  background: linear-gradient(135deg, #2563eb, #7c3aed);
+  color: white;
+  border-radius: 0.5rem;
+  padding: 0.5rem 0.75rem;
+  cursor: pointer;
+  font-weight: 600;
+  font-size: 0.85rem;
+  transition: opacity 0.2s ease;
+}
+
+button:disabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+}
+
+.viewer-container {
+  flex: 1;
+  position: relative;
+  min-height: 0;
+}
+
+.viewer-container-large {
+  min-height: 520px;
+}
+
+.viewer-canvas {
+  width: 100%;
+  height: 100%;
+  border-radius: 0.5rem;
+  background: #020617;
+}
+
+.logs {
+  flex: 1;
+  background: rgba(2, 6, 23, 0.8);
+  border-radius: 0.5rem;
+  padding: 0.5rem;
+  font-family: 'JetBrains Mono', 'SFMono-Regular', ui-monospace, monospace;
+  font-size: 0.8rem;
+  overflow-y: auto;
+  border: 1px solid rgba(148, 163, 184, 0.2);
+  white-space: pre-wrap;
+}
+
+.panel-header-row {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 1rem;
+}
+
+.status-inline,
+.log-count {
+  font-size: 0.8rem;
+  color: #93c5fd;
+}
+
+.status-row {
+  display: flex;
+  justify-content: space-between;
+  font-size: 0.8rem;
+  color: #93c5fd;
+  margin-bottom: 0.5rem;
+}
+
+@media (max-width: 1200px) {
+  .layout-landscape {
+    grid-template-columns: 1fr;
+    grid-template-rows: auto minmax(420px, 1fr) 200px;
+    grid-template-areas:
+      'editor'
+      'viewer'
+      'logs';
+  }
+
+  .viewer-container-large {
+    min-height: 420px;
+  }
+}

apps/web-visualizer/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "useDefineForClassFields": true,
+    "lib": ["ES2020", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "skipLibCheck": true,
+    "moduleResolution": "Bundler",
+    "allowImportingTsExtensions": false,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noEmit": true,
+    "jsx": "react-jsx",
+    "strict": true,
+    "types": ["vite/client"]
+  },
+  "include": ["src"],
+  "references": [{ "path": "./tsconfig.node.json" }]
+}

apps/web-visualizer/tsconfig.node.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "composite": true,
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "allowSyntheticDefaultImports": true,
+    "esModuleInterop": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "types": ["node"]
+  },
+  "include": ["vite.config.ts"]
+}

apps/web-visualizer/vite.config.ts

@@ -0,0 +1,16 @@
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+
+export default defineConfig({
+  plugins: [react()],
+  server: {
+    port: 5173,
+    proxy: {
+      '/api': 'http://localhost:4000',
+      '/artifacts': 'http://localhost:4000'
+    }
+  },
+  build: {
+    outDir: 'dist'
+  }
+});

archive/README.md

@@ -0,0 +1,62 @@
+# Live Visualizer
+
+A custom live modeling environment for LLM-assisted geometry workflows.
+
+## Core idea
+
+This project is for a modeling tool that combines:
+- live model viewing
+- editable variables and code
+- terminal/log feedback
+- LLM-assisted model generation and editing
+- multiple visual modes from the same scene state
+
+## Position on build123d
+
+`build123d` should be treated as an important geometry backend, but not baked so deeply into the app that the entire product becomes impossible to evolve.
+
+So the architecture should be:
+- custom app shell
+- custom scene/state/visualization pipeline
+- pluggable geometry adapters
+- build123d as the first and best-supported adapter
+
+That keeps the project flexible while still embracing the current best geometry engine for this workflow.
+
+## Initial product shape
+
+Three-pane interface:
+- editor / prompt / parameter control
+- live viewport
+- terminal / logs / agent output
+
+## Near-term goals
+
+1. Create a custom app shell
+2. Support build123d as the first geometry adapter
+3. Enable live regeneration from script or parameter changes
+4. Separate display modes:
+   - viewport shaded
+   - graphic mass
+   - technical/vector
+5. Define LLM integration layer:
+   - OpenClaw-driven
+   - provider-agnostic fallback
+
+## Proposed repo layout
+
+- `apps/viewer` - main app shell
+- `packages/core` - scene graph, document model, orchestration types
+- `packages/renderer` - viewport and render mode logic
+- `packages/llm` - LLM session/provider integration
+- `packages/session` - terminal/process/runtime session management
+- `packages/ui` - reusable interface components
+- `examples/build123d` - test scripts and adapter examples
+
+## Principles
+
+- model first, render second
+- one source of geometric truth
+- multiple display modes from the same scene
+- user can steer with language, numbers, and code
+- terminal remains a first-class part of the workflow

archive/gradio-demo-backend-legacy/API_CONTRACT.md

@@ -0,0 +1,53 @@
+# API Contract Sketch
+
+## POST `/v1/generate-spec`
+
+Request:
+
+```json
+{
+  "prompt": "make a heavy steel bracket with 4 bolt holes",
+  "mode": "part",
+  "output_type": "3d_solid",
+  "session_id": "optional-client-session"
+}
+```
+
+Response:
+
+```json
+{
+  "ok": true,
+  "cached": false,
+  "prompt_hash": "8a41b50d23f1b3de",
+  "spec": {
+    "output_type": "3d_solid",
+    "geometry_family": "bracket_plate",
+    "units": "mm",
+    "parameters": {
+      "width": 80,
+      "height": 50,
+      "thickness": 6,
+      "hole_count": 4,
+      "hole_diameter": 10
+    },
+    "style": {
+      "family": "industrial",
+      "heaviness": 0.8
+    }
+  },
+  "notes": [
+    "This is a scaffolded template/spec response.",
+    "Next step: route this through an actual HF model endpoint."
+  ],
+  "model": "stub/template-router"
+}
+```
+
+## GET `/v1/health`
+Simple health check for the Space.
+
+## Intended evolution
+- add actual HF endpoint call inside `generate_spec`
+- keep prompt normalization, caching, and rate limiting in this backend
+- convert returned JSON spec into build123d code inside the Gradio app

archive/gradio-demo-backend-legacy/README.md

@@ -0,0 +1,26 @@
+# NaturalCAD Backend Scaffold
+
+Thin private backend for the NaturalCAD Hugging Face Space.
+
+## Purpose
+- keep secrets off the Space
+- rate limit and cache requests
+- normalize prompts
+- return structured CAD specs
+- leave room for future provider routing
+
+## Run
+
+```bash
+cd backend
+python3 -m venv .venv
+.venv/bin/pip install -r requirements.txt
+.venv/bin/uvicorn app.main:app --reload --port 8010
+```
+
+## Planned flow
+1. Space sends prompt to `/v1/generate-spec`
+2. Backend validates + rate limits
+3. Backend returns structured JSON spec
+4. Gradio app converts spec into build123d code
+5. Space executes build123d and returns STL/STEP

archive/gradio-demo-backend-legacy/app/__init__.py

@@ -0,0 +1 @@
+# backend package

archive/gradio-demo-backend-legacy/app/main.py

@@ -0,0 +1,272 @@
+from __future__ import annotations
+
+import hashlib
+import os
+import re
+import time
+from collections import defaultdict, deque
+from typing import Literal
+
+from dotenv import load_dotenv
+from fastapi import FastAPI, Header, HTTPException, Request
+from pydantic import BaseModel, Field
+
+load_dotenv()
+
+APP_NAME = "NaturalCAD Backend"
+API_SHARED_SECRET = os.getenv("API_SHARED_SECRET", "")
+RATE_LIMIT_PER_HOUR = int(os.getenv("RATE_LIMIT_PER_HOUR", "20"))
+
+app = FastAPI(title=APP_NAME, version="0.3.0")
+
+_REQUESTS: dict[str, deque[float]] = defaultdict(deque)
+_CACHE: dict[str, dict] = {}
+
+ModeType = Literal["part", "assembly", "sketch"]
+OutputType = Literal["2d_vector", "surface", "3d_solid"]
+
+
+class GenerateSpecRequest(BaseModel):
+    prompt: str = Field(min_length=3, max_length=1000)
+    mode: ModeType = "part"
+    output_type: OutputType = "3d_solid"
+    session_id: str | None = None
+
+
+class CadStyle(BaseModel):
+    family: str = "industrial"
+    heaviness: float = 0.6
+
+
+class CadSpec(BaseModel):
+    output_type: OutputType
+    geometry_family: str
+    units: str = "mm"
+    parameters: dict[str, int | float | str]
+    style: CadStyle
+
+
+class GenerateSpecResponse(BaseModel):
+    ok: bool = True
+    cached: bool = False
+    prompt_hash: str
+    spec: CadSpec
+    notes: list[str] = []
+    model: str = "stub/template-router"
+
+
+class HealthResponse(BaseModel):
+    status: str
+    rate_limit_per_hour: int
+    cache_entries: int
+
+
+def _check_auth(header_value: str | None) -> None:
+    if API_SHARED_SECRET and header_value != API_SHARED_SECRET:
+        raise HTTPException(status_code=401, detail="Invalid shared secret")
+
+
+def _rate_limit_key(request: Request, session_id: str | None) -> str:
+    client_ip = request.client.host if request.client else "unknown"
+    return session_id or client_ip
+
+
+def _enforce_rate_limit(key: str) -> None:
+    now = time.time()
+    cutoff = now - 3600
+    bucket = _REQUESTS[key]
+    while bucket and bucket[0] < cutoff:
+        bucket.popleft()
+    if len(bucket) >= RATE_LIMIT_PER_HOUR:
+        raise HTTPException(status_code=429, detail="Rate limit exceeded")
+    bucket.append(now)
+
+
+def _normalize_prompt(prompt: str) -> str:
+    return " ".join(prompt.lower().strip().split())
+
+
+def _prompt_hash(prompt: str, mode: str, output_type: str) -> str:
+    digest = hashlib.sha256(f"{mode}|{output_type}|{prompt}".encode()).hexdigest()
+    return digest[:16]
+
+
+def _extract_number(prompt: str, keywords: list[str], default: float) -> float:
+    for keyword in keywords:
+        pattern = rf"{keyword}\s*(?:of|=|:)?\s*(\d+(?:\.\d+)?)"
+        match = re.search(pattern, prompt)
+        if match:
+            return float(match.group(1))
+    return default
+
+
+def _extract_count(prompt: str, nouns: list[str], default: int) -> int:
+    word_map = {
+        "one": 1,
+        "two": 2,
+        "three": 3,
+        "four": 4,
+        "five": 5,
+        "six": 6,
+        "seven": 7,
+        "eight": 8,
+        "nine": 9,
+        "ten": 10,
+    }
+    for noun in nouns:
+        digit_match = re.search(rf"(\d+)\s+{noun}", prompt)
+        if digit_match:
+            return int(digit_match.group(1))
+        for word, value in word_map.items():
+            if re.search(rf"{word}\s+{noun}", prompt):
+                return value
+    return default
+
+
+def _style_from_prompt(prompt: str, default_family: str) -> CadStyle:
+    heaviness = 0.6
+    family = default_family
+    if any(word in prompt for word in ["heavy", "massive", "thick", "brutal"]):
+        heaviness = 0.85
+    elif any(word in prompt for word in ["light", "slim", "thin", "delicate"]):
+        heaviness = 0.35
+
+    if any(word in prompt for word in ["industrial", "steel", "metal"]):
+        family = "industrial"
+    elif any(word in prompt for word in ["structural", "truss", "frame"]):
+        family = "structural"
+    elif any(word in prompt for word in ["smooth", "soft", "shell", "canopy"]):
+        family = "smooth"
+    elif any(word in prompt for word in ["diagram", "profile", "elevation", "line"]):
+        family = "diagrammatic"
+
+    return CadStyle(family=family, heaviness=heaviness)
+
+
+def _infer_spec(prompt: str, mode: ModeType, output_type: OutputType) -> CadSpec:
+    p = prompt.lower()
+
+    if output_type == "2d_vector" or mode == "sketch":
+        family = "truss_elevation" if any(word in p for word in ["truss", "beam", "frame", "elevation"]) else "plate_profile"
+        if family == "truss_elevation":
+            params = {
+                "span": _extract_number(p, ["span", "length", "width"], 140),
+                "height": _extract_number(p, ["height", "rise"], 24),
+                "panel_count": _extract_count(p, ["panels", "bays", "segments"], 7),
+                "member_size": _extract_number(p, ["member", "thickness", "depth"], 3),
+                "preview_thickness": 1,
+            }
+        else:
+            params = {
+                "width": _extract_number(p, ["width", "span"], 80),
+                "height": _extract_number(p, ["height"], 50),
+                "hole_count": _extract_count(p, ["holes", "bolt holes", "openings"], 4),
+                "hole_diameter": _extract_number(p, ["hole diameter", "hole", "diameter"], 10),
+                "preview_thickness": 1,
+            }
+        return CadSpec(
+            output_type="2d_vector",
+            geometry_family=family,
+            parameters=params,
+            style=_style_from_prompt(p, "diagrammatic"),
+        )
+
+    if output_type == "surface":
+        family = "canopy_surface" if any(word in p for word in ["roof", "canopy", "shell", "surface"]) else "lofted_panel"
+        if family == "canopy_surface":
+            params = {
+                "span": _extract_number(p, ["span", "width"], 160),
+                "depth": _extract_number(p, ["depth", "length"], 90),
+                "peak_height": _extract_number(p, ["peak", "height", "rise"], 38),
+                "thickness": _extract_number(p, ["thickness"], 2),
+            }
+        else:
+            params = {
+                "width": _extract_number(p, ["width", "span"], 80),
+                "depth": _extract_number(p, ["depth", "length"], 50),
+                "rise": _extract_number(p, ["rise", "height"], 18),
+                "thickness": _extract_number(p, ["thickness"], 2),
+            }
+        return CadSpec(
+            output_type="surface",
+            geometry_family=family,
+            parameters=params,
+            style=_style_from_prompt(p, "smooth"),
+        )
+
+    if any(word in p for word in ["truss", "beam", "frame", "girder"]):
+        return CadSpec(
+            output_type="3d_solid",
+            geometry_family="truss_beam",
+            parameters={
+                "span": _extract_number(p, ["span", "length"], 140),
+                "height": _extract_number(p, ["height", "rise"], 24),
+                "panel_count": _extract_count(p, ["panels", "bays", "segments"], 7),
+                "member_size": _extract_number(p, ["member", "thickness", "depth"], 3),
+            },
+            style=_style_from_prompt(p, "structural"),
+        )
+
+    if any(word in p for word in ["tower", "block", "monolith"]):
+        return CadSpec(
+            output_type="3d_solid",
+            geometry_family="tower_block",
+            parameters={
+                "width": _extract_number(p, ["width"], 30),
+                "length": _extract_number(p, ["length", "depth"], 30),
+                "height": _extract_number(p, ["height"], 120),
+                "notch": _extract_number(p, ["notch", "cut"], 10),
+            },
+            style=_style_from_prompt(p, "industrial"),
+        )
+
+    return CadSpec(
+        output_type="3d_solid",
+        geometry_family="bracket_plate",
+        parameters={
+            "width": _extract_number(p, ["width", "span"], 80),
+            "height": _extract_number(p, ["height"], 50),
+            "thickness": _extract_number(p, ["thickness"], 6),
+            "hole_count": _extract_count(p, ["holes", "bolt holes", "openings"], 4),
+            "hole_diameter": _extract_number(p, ["hole diameter", "hole", "diameter"], 10),
+        },
+        style=_style_from_prompt(p, "industrial"),
+    )
+
+
+@app.get("/v1/health", response_model=HealthResponse)
+def health() -> HealthResponse:
+    return HealthResponse(status="ok", rate_limit_per_hour=RATE_LIMIT_PER_HOUR, cache_entries=len(_CACHE))
+
+
+@app.post("/v1/generate-spec", response_model=GenerateSpecResponse)
+def generate_spec(payload: GenerateSpecRequest, request: Request, x_api_key: str | None = Header(default=None)) -> GenerateSpecResponse:
+    _check_auth(x_api_key)
+    _enforce_rate_limit(_rate_limit_key(request, payload.session_id))
+
+    normalized = _normalize_prompt(payload.prompt)
+    key = _prompt_hash(normalized, payload.mode, payload.output_type)
+
+    if key in _CACHE:
+        cached = dict(_CACHE[key])
+        cached["cached"] = True
+        return GenerateSpecResponse(**cached)
+
+    spec = _infer_spec(normalized, payload.mode, payload.output_type)
+    response = GenerateSpecResponse(
+        prompt_hash=key,
+        spec=spec,
+        notes=[
+            f"Mode: {payload.mode}",
+            f"Output type: {payload.output_type}",
+            "Prompt mapped into a structured CAD spec.",
+            "Replace the stub router with a real HF endpoint later.",
+        ],
+    )
+    _CACHE[key] = response.model_dump()
+    return response
+
+
+@app.get("/")
+def root() -> dict[str, str]:
+    return {"message": APP_NAME, "docs": "/docs", "health": "/v1/health"}

archive/gradio-demo-backend-legacy/requirements.txt

@@ -0,0 +1,5 @@
+fastapi>=0.115.0
+uvicorn[standard]>=0.30.0
+pydantic>=2.8.0
+python-dotenv>=1.0.1
+httpx>=0.27.0

archive/package.json

@@ -0,0 +1,9 @@
+{
+  "name": "live-visualizer",
+  "private": true,
+  "version": "0.1.0",
+  "workspaces": [
+    "apps/*",
+    "packages/*"
+  ]
+}

docs/HF_SPACE_NOTES.md

@@ -0,0 +1,21 @@
+# NaturalCAD HF Space Notes
+
+## Current intent
+- Public-facing NaturalCAD app
+- build123d-backed execution loop
+- Noah will wire a service endpoint for LLM generation later
+
+## Current prototype state
+- Gradio UI
+- real build123d execution
+- STL preview
+- STL + STEP downloads
+- starter sample picker
+- prompt note field for future LLM integration
+- archived per-run artifacts under `artifacts/runs/`
+
+## Next likely steps
+- add endpoint config pattern for external LLM service
+- convert prompt note into real prompt-to-code flow
+- improve public-facing examples
+- add safe execution constraints for Spaces

docs/architecture.md

@@ -0,0 +1,26 @@
+# build123d Live Visualizer — Architecture Notes
+
+## Live Update Loop
+- **Front-end trigger** – `Run & Stream` button encodes the textarea contents into an SSE request (`/api/run?code=...`).
+- **Server orchestration** – Express writes the snippet to `artifacts/<job>.py`, spawns the dedicated build123d Python interpreter, and relays stdout/stderr as Server-Sent Events (`log` events).
+- **Completion signal** – When the Python runner finishes, Express emits a `complete` event containing the STL path (or an error message). The client loads the STL via `three.js` and refreshes the viewer.
+- **Resilience** – Each run is isolated via UUIDs, making the log stream and artifacts easy to correlate while enabling multiple sequential runs without restarts.
+
+## Artifact Flow
+1. Client sends code → Express persists under `artifacts/<job>.py`.
+2. Python runner executes snippet, requiring a `result` variable and exporting to `artifacts/<job>.stl`.
+3. Express serves `/artifacts` statically so the browser can fetch STL files immediately.
+4. Front-end STL loader retrieves the file, renders it, and exposes a download link; artifacts remain on disk for inspection or later cleanup.
+
+## LLM Integration Options
+- **OpenClaw Orchestrator** – Keep the current human-in-the-loop workflow where OpenClaw agents call the `/api/run` endpoint, enabling prompt-to-geometry iteration without exposing provider keys to the prototype.
+- **Direct Provider Calls** – Embed provider SDK (OpenAI, Anthropic, etc.) within the server. The Express layer would accept natural-language prompts, forward them to an LLM, and pipe the generated build123d script straight into the runner before streaming results back.
+- **Local Coding Agent** – Bundle a lightweight model (e.g., `llama.cpp`) or a deterministic templating agent that runs locally, translating UI prompts to build123d code without external network usage—aligned with offline or air-gapped deployments.
+
+## Next-Step Roadmap
+- Add job queueing plus cancellation support per run id (currently a single in-memory stream).
+- Persist structured job metadata (prompt, status, artifact path) for replay and auditing.
+- Harden sandboxing by running the Python process inside a constrained container or Firejail profile.
+- Expand the viewer with assembly overlays (multiple STL layers, color coding, exploded views).
+- Wire optional LLM prompt templates + history so designers can iterate conversationally.
+- Author smoke tests covering the SSE endpoint and sample runner invocation.

docs/backend-v0.md

@@ -0,0 +1,254 @@
+# NaturalCAD Backend v0
+
+## Goal
+
+Build a low-cost backend for NaturalCAD that is safe enough for an MVP:
+- public UI on Hugging Face Spaces
+- hosted inference on Hugging Face
+- no important execution on Noah's laptop
+- no public arbitrary code execution
+- logs, metadata, and artifacts stored off-machine
+
+## Guiding priorities
+
+1. Keep costs low
+2. Prevent spam and abuse
+3. Keep secrets off the frontend
+4. Avoid exposing raw Python execution to the public
+5. Keep the system simple enough to actually ship
+
+## Recommended stack
+
+### Frontend
+- Hugging Face Space
+- current Gradio app is the fastest path
+
+### Backend API
+- FastAPI deployed on Fly.io
+- reason: build123d and worker logic are already Python-adjacent, so this reduces stack complexity while giving us a sturdier app host for API + worker processes
+
+### Inference
+- Hugging Face Inference Endpoint or hosted HF model endpoint
+- prefer free or low-cost model path for MVP
+
+### Database
+- Supabase Postgres
+- reason: structured job records, artifact metadata, and status transitions fit naturally in Postgres, and Supabase gives a good hosted dashboard with low MVP friction
+
+### Object storage
+- hosted object storage, not local disk
+- S3-compatible storage is preferred
+
+### Worker
+- isolated Python worker for geometry generation
+- build123d execution should happen here, not in the public frontend tier
+
+## Trust boundaries
+
+### Hugging Face Space
+Allowed:
+- collect prompts
+- submit jobs to backend
+- display status and results
+
+Not allowed:
+- store backend secrets
+- directly execute build123d jobs
+- write directly to database with privileged credentials
+- be the source of truth for rate limiting or audit policy
+
+### Backend API
+Responsible for:
+- request validation
+- rate limiting
+- job creation
+- inference calls
+- schema validation
+- queue handoff
+- database writes
+- artifact metadata
+- audit logs
+
+### Worker
+Responsible for:
+- consuming approved jobs
+- generating structured CAD outputs
+- optionally translating internal spec to build123d code
+- exporting STL/STEP
+- uploading artifacts to hosted storage
+- updating job status
+
+### Database
+Store:
+- job records
+- prompt text
+- derived structured spec
+- status transitions
+- artifact metadata
+- session or user metadata
+- audit events
+- rate-limit counters if needed
+
+### Object storage
+Store:
+- STL files
+- STEP files
+- previews
+- log blobs if needed
+
+## Public input model
+
+### Public API rule
+Public users submit prompts, not arbitrary code.
+
+That means:
+- user sends prompt text
+- backend calls model
+- model returns structured data or a constrained internal representation
+- worker generates geometry from approved internal data
+
+### Internal flexibility
+Internally, NaturalCAD may still generate build123d code if that helps implementation.
+But code generation should stay behind the backend/worker boundary, not exposed as a public execution surface.
+
+## Job lifecycle
+
+Use these statuses:
+- `submitted`
+- `validated`
+- `queued`
+- `running`
+- `completed`
+- `failed`
+
+Optional later:
+- `blocked`
+- `expired`
+- `canceled`
+
+## Minimal API shape
+
+### `POST /jobs`
+Create a job.
+
+Input:
+- prompt
+- optional session id
+- optional client metadata
+
+Server actions:
+- validate payload
+- apply rate limit
+- create job record
+- call inference or enqueue pre-inference flow
+
+Returns:
+- job id
+- status
+
+### `GET /jobs/{job_id}`
+Fetch job status.
+
+Returns:
+- current status
+- error info if failed
+- artifact metadata if completed
+
+### `GET /jobs/{job_id}/artifacts`
+Return artifact metadata and signed URLs if applicable.
+
+### `GET /health`
+Basic health check.
+
+## Suggested Postgres tables
+
+### `jobs`
+Columns:
+- `id`
+- `created_at`
+- `updated_at`
+- `status`
+- `prompt`
+- `normalized_prompt`
+- `spec_json`
+- `error_text`
+- `client_session_id`
+- `ip_hash`
+- `model_info_json`
+
+### `artifacts`
+Columns:
+- `id`
+- `job_id`
+- `kind` (`stl`, `step`, `preview`, `log`)
+- `storage_key`
+- `size_bytes`
+- `created_at`
+- `expires_at`
+
+### `audit_events`
+Columns:
+- `id`
+- `job_id`
+- `event_type`
+- `created_at`
+- `details_json`
+
+### `rate_limits`
+Optional if not handled elsewhere.
+
+## Queue strategy
+
+For MVP, keep it simple.
+
+Options:
+1. DB-backed queue with polling
+2. lightweight Redis queue later if needed
+
+Recommendation:
+- start with a DB-backed queue and one worker
+- upgrade only when traffic justifies it
+
+## Low-cost implementation order
+
+### Phase 0
+- keep Gradio frontend
+- do not deploy public raw code execution
+
+### Phase 1
+- create FastAPI service on Fly.io
+- add `POST /jobs` and `GET /jobs/{job_id}`
+- connect Supabase Postgres
+- add simple rate limiting
+
+### Phase 2
+- connect HF inference endpoint
+- store prompt, status, and response metadata
+- validate returned structured output
+
+### Phase 3
+- add Python worker
+- generate artifacts
+- upload artifacts to hosted storage
+- return signed artifact links
+
+### Phase 4
+- tighten retention, add auth tiers, add cancellation, add preview generation
+
+## What not to do in v0
+
+- no public arbitrary Python execution
+- no local laptop as production backend
+- no secrets in frontend code
+- no unlimited artifact retention
+- no complicated microservice split
+
+## Default recommendation
+
+NaturalCAD v0 should ship as:
+- Hugging Face Space frontend
+- FastAPI backend on Fly.io
+- Supabase Postgres
+- hosted object storage
+- one Python worker
+- strict prompt-only public interface

docs/hf-space-deploy-checklist.md

@@ -0,0 +1,34 @@
+# NaturalCAD Hugging Face Space Deploy Checklist
+
+## Minimum checklist
+
+- [ ] Gradio app runs cleanly from `apps/gradio-demo/app/main.py`
+- [ ] `requirements.txt` contains everything needed for Space runtime, including `build123d`
+- [ ] prompt-to-model flow works without requiring local-only paths that break in Space
+- [ ] example prompts produce valid outputs
+- [ ] timeouts are in place
+- [ ] artifacts are bounded and not unbounded temp junk
+- [ ] lightweight run logging is enabled
+- [ ] README explains local run and Space intent clearly
+
+## MVP notes
+
+For public testing, the demo should degrade gracefully.
+If the backend is unavailable, the app should still be able to produce a simple local fallback result rather than fully dying.
+
+For the lean MVP, backend use should be optional, not assumed. If `NATURALCAD_BACKEND_URL` is unset, the Space should stay usable without waiting on a dead localhost request.
+
+If the Hugging Face Space runtime cannot support the CAD dependency stack cleanly, keep the Space as the frontend and offload execution to a container or VM.
+
+## Data to capture
+
+- timestamp
+- run id
+- prompt
+- mode
+- output type
+- geometry family
+- backend available or not
+- success or failure
+- runtime seconds
+- error string if any

docs/hf-space-mvp.md

@@ -0,0 +1,96 @@
+# NaturalCAD Hugging Face Space MVP
+
+## Goal
+
+Ship NaturalCAD quickly as a public testable demo.
+
+Primary goals:
+- get real users testing the interaction
+- collect prompt/result data
+- learn what people actually want
+- defer heavier backend infrastructure until the product proves itself
+
+## Product strategy
+
+This MVP is intentionally simple.
+
+NaturalCAD v0 should be:
+- a Hugging Face Space
+- a Gradio app
+- a prompt-to-geometry demo
+- a data-gathering surface
+
+It should not yet be:
+- a full distributed backend system
+- a polished production SaaS
+- a heavily abstracted multi-service platform
+
+## What we keep now
+
+- `apps/gradio-demo`
+- prompt input
+- stub/backend-assisted spec generation if useful
+- build123d execution path
+- STL preview
+- STL and STEP downloads
+- lightweight run logging
+- examples and clean presentation
+
+## What we defer
+
+- Fly.io deployment
+- Supabase integration
+- hosted object storage
+- worker separation
+- full job queue
+- advanced auth system
+- fine-grained persistence and audit pipeline
+
+## Minimal requirements before public testing
+
+1. The Space must run reliably
+2. The demo must generate models from prompts
+3. The UI must be clear and attractive enough for strangers to try
+4. We should capture lightweight feedback and run metadata
+5. We should avoid obvious abuse vectors where possible
+
+## Recommended lightweight data capture
+
+For each run, capture only what helps learning:
+- timestamp
+- prompt
+- mode
+- output type
+- inferred geometry family
+- success or failure
+- runtime duration
+- optional notes or error string
+
+This can begin as flat-file logging inside the Space or another lightweight mechanism, then migrate later.
+
+## Security posture for MVP
+
+Keep it simple:
+- no public arbitrary code input
+- prompt input only
+- keep prompts length-limited
+- keep timeouts in place
+- keep generated artifacts bounded
+- do not expose secrets in frontend code
+
+This is not full production hardening. It is enough to ship a controlled public demo.
+
+## Phase model
+
+### Phase 1
+Ship the Hugging Face Space and gather usage.
+
+### Phase 2
+If traction appears, add external persistence and better job tracking.
+
+### Phase 3
+If usage justifies it, move to hosted backend, storage, scaling, and eventually model fine-tuning.
+
+## Decision
+
+NaturalCAD should optimize for public testing first, and infrastructure maturity second.