Skip to content

elithril/blender-kiln / plugin

Makes and fixes 3D assets in Blender, for games, the web and AR. Use when the user wants a 3D model, prop, character or GLB/glTF/FBX/USDZ file made — from a text brief, a reference image, a free marketplace (PolyHaven, Sketchfab) or AI generation — AND when they bring an existing 3D file to fix: too heavy or too many polygons (optimize, compress, LODs), broken normals, scale or origin, materials lost on glTF export, conversion between GLB, FBX and USDZ, texturing, rigging for animation, animating it (walk and idle cycles, text-to-motion, looping clips, articulated props), or inspection. Drives Blender through a Blender MCP server (ahujasid's or the official Blender Lab one). Batch mode produces many consistent assets unattended. Kiln Studio (`/kiln studio`) opens the project's models in the browser, where the user reviews them and pins notes for Claude to act on.

FileKindSize
.claude-plugin/plugin.jsonconfig1.2 KB
.mcp.jsonconfig236 B
LICENSEother1.0 KB
NOTICEother2.5 KB
SKILL.mdskill md29.0 KB
references/ai-generation.mdmarkdown21.0 KB
references/animation.mdmarkdown21.6 KB
references/batch-mode.mdmarkdown19.5 KB
references/blender-mcp.mdmarkdown9.4 KB
references/characters.mdmarkdown52.8 KB
references/cli-tools.mdmarkdown6.5 KB
references/commands.mdmarkdown10.7 KB
references/export-targets.mdmarkdown14.3 KB
references/log-format.mdmarkdown2.2 KB
references/naming-conventions.mdmarkdown5.8 KB
references/photo-projection.mdmarkdown6.3 KB
references/pipeline-brief.mdmarkdown4.2 KB
references/pipeline-import-cleanup.mdmarkdown6.3 KB
references/pipeline-optimize-export.mdmarkdown6.4 KB
references/pipeline-rig-animate.mdmarkdown5.8 KB
references/pipeline-source.mdmarkdown9.7 KB
references/print.mdmarkdown41.5 KB
references/reference-fidelity.mdmarkdown31.8 KB
references/review-rounds.mdmarkdown10.4 KB
references/setup-install.mdmarkdown2.8 KB
references/setup.mdmarkdown9.2 KB
references/sourcing-strategy.mdmarkdown6.1 KB
references/studio.mdmarkdown38.9 KB
references/texturing-strategy.mdmarkdown14.4 KB
references/topology-rules.mdmarkdown3.9 KB
references/uv-materials.mdmarkdown6.8 KB
references/validation-checklist.mdmarkdown10.5 KB
studio/approval_hook.pyscript14.2 KB
studio/blender_live.pyscript2.3 KB
studio/checks.pyscript38.1 KB
studio/estimate.pyscript4.2 KB
studio/example/barrel/barrel_final.glbbinary111.9 KB
studio/example/barrel/barrel_log.mdmarkdown445 B
studio/handoff.pyscript17.8 KB
studio/mcp_server.pyscript32.7 KB
studio/phoneshare.pyscript17.1 KB
studio/server.pyscript47.9 KB
studio/setup_status.pyscript7.5 KB
studio/static/app.jsscript241.4 KB
studio/static/apple-touch-icon.pngbinary20.6 KB
studio/static/fonts/OFL-JetBrainsMono.txtmarkdown4.3 KB
studio/static/fonts/OFL-Sora.txtmarkdown4.3 KB
studio/static/fonts/jetbrains-mono-latin-ext.woff2binary11.3 KB
studio/static/fonts/jetbrains-mono-latin.woff2binary30.6 KB
studio/static/fonts/sora-latin-ext.woff2binary11.8 KB
studio/static/fonts/sora-latin.woff2binary24.6 KB
studio/static/i18n.jsscript6.2 KB
studio/static/i18n/fr.jsonconfig101.2 KB
studio/static/icon-32.pngbinary2.6 KB
studio/static/icon-64.pngbinary6.6 KB
studio/static/icon-96.pngbinary12.8 KB
studio/static/index.htmlother39.5 KB
studio/static/style.cssother114.5 KB
studio/static/tutorial.jsscript49.0 KB
studio/static/tutorial/barrel_after.glbbinary117.3 KB
studio/static/tutorial/barrel_before.glbbinary111.9 KB
studio/static/tutorial/fixtures.jsonconfig13.5 KB
studio/static/tutorial/lantern_1_blockout.glbbinary83.1 KB
studio/static/tutorial/lantern_2_details.glbbinary101.8 KB
studio/static/tutorial/lantern_3_materials.glbbinary102.0 KB
studio/static/tutorial/lantern_4_final.glbbinary141.1 KB
studio/static/tutorial/make_tutorial.pyscript4.9 KB
studio/static/viewer.jsscript41.4 KB
studio/studio.pyscript29.2 KB
studio/studiolib.pyscript77.8 KB
studio/test_studio.pyscript90.2 KB
studio/test_worker.pyscript31.5 KB
studio/worker.pyscript56.8 KB
studio/worker_blender.pyscript2.7 KB
tools/autorig.pyscript44.1 KB
tools/bind_rigid_parts.pyscript3.6 KB
tools/blender_mcp_start.pyscript1.5 KB
tools/check_usdz.pyscript1004 B
tools/cutout.swiftscript2.0 KB
tools/export_outputs.pyscript5.2 KB
tools/fidelity_check.pyscript39.0 KB
tools/fit_coupon.pyscript11.3 KB
tools/fixtures/skintokens_raw_child.glbbinary88.8 KB
tools/fixtures/skintokens_skeletons.jsonconfig6.5 KB
tools/flatten.pyscript14.9 KB
tools/glb_to_fbx.pyscript2.1 KB
tools/glb_to_usdz.pyscript6.2 KB
tools/motion_loop.pyscript5.9 KB
tools/motion_measure.pyscript15.2 KB
tools/motions/LICENSE-image-to-3dlab.txtmarkdown11.1 KB
tools/motions/cheer.npzbinary48.4 KB
tools/motions/cheer_b.npzbinary48.1 KB
tools/motions/dance.npzbinary78.2 KB
tools/motions/dance_b.npzbinary78.9 KB
tools/motions/death.npzbinary45.9 KB
tools/motions/death_b.npzbinary46.5 KB
tools/motions/fight_stance.npzbinary60.3 KB
tools/motions/fight_stance_b.npzbinary61.3 KB
tools/motions/flying_kick.npzbinary39.7 KB
tools/motions/flying_kick_b.npzbinary39.9 KB
tools/motions/hit_react.npzbinary31.9 KB
tools/motions/hit_react_b.npzbinary31.8 KB
tools/motions/idle.npzbinary51.8 KB
tools/motions/idle_b.npzbinary57.7 KB
tools/motions/jump.npzbinary39.8 KB
tools/motions/jump_b.npzbinary39.9 KB
tools/motions/kata.npzbinary77.4 KB
tools/motions/kata_b.npzbinary75.3 KB
tools/motions/kick.npzbinary32.4 KB
tools/motions/kick_b.npzbinary32.5 KB
tools/motions/presets.jsonconfig9.6 KB
tools/motions/punch.npzbinary32.0 KB
tools/motions/punch_b.npzbinary32.1 KB
tools/motions/punch_combo.npzbinary47.4 KB
tools/motions/punch_combo_b.npzbinary47.5 KB
tools/motions/roll.npzbinary46.7 KB
tools/motions/roll_b.npzbinary47.5 KB
tools/motions/roundhouse.npzbinary39.7 KB
tools/motions/roundhouse_b.npzbinary39.9 KB
tools/motions/run.npzbinary47.2 KB
tools/motions/run_b.npzbinary47.7 KB
tools/motions/sit.npzbinary47.2 KB
tools/motions/sit_b.npzbinary47.2 KB
tools/motions/sneak.npzbinary61.6 KB
tools/motions/sneak_b.npzbinary61.8 KB
tools/motions/strafe_left.npzbinary45.9 KB
tools/motions/strafe_left_b.npzbinary47.1 KB
tools/motions/sword_swing.npzbinary39.7 KB
tools/motions/sword_swing_b.npzbinary39.4 KB
tools/motions/walk.npzbinary62.8 KB
tools/motions/walk_b.npzbinary62.6 KB
tools/motions/walk_woman.npzbinary62.9 KB
tools/motions/wave.npzbinary46.3 KB
tools/motions/wave_b.npzbinary46.3 KB
tools/open_blender.pyscript5.0 KB
tools/photo_project.pyscript37.8 KB
tools/presets.pyscript16.3 KB
tools/print_check.pyscript47.2 KB
tools/quadruped.pyscript19.4 KB
tools/retarget.pyscript46.9 KB
tools/review_renders.pyscript13.8 KB
tools/review_sheet.pyscript11.0 KB
tools/skintokens-requirements.txtmarkdown2.4 KB
tools/skintokens.patchother9.2 KB
tools/template_profile.pyscript5.8 KB
tools/test_autorig.pyscript15.9 KB
tools/test_fidelity_check.pyscript20.7 KB
tools/test_fit_coupon.pyscript6.4 KB
tools/test_flatten.pyscript15.0 KB
tools/test_open_blender.pyscript1.3 KB
tools/test_photo_project.pyscript12.6 KB
tools/test_presets.pyscript17.6 KB
tools/test_print_check.pyscript33.1 KB
tools/test_review_renders.pyscript11.4 KB
tools/test_review_sheet.pyscript4.0 KB
tools/test_template_profile.pyscript3.6 KB
tools/test_uv_check.pyscript5.0 KB
tools/test_verify_docs.pyexecutablescript7.9 KB
tools/unimate.patchother3.5 KB
tools/unimate.pyscript17.5 KB
tools/uv_check.pyscript8.4 KB
tools/verify_blender.pyexecutablescript29.2 KB
tools/verify_docs.pyexecutablescript16.6 KB

studio/studiolib.py

View on GitHub
"""Kiln Studio: project scan, model stats, and the review store.

Standard library only. Shared by the server (server.py) and the CLI (studio.py).

A project is any folder. Studio finds every model under it (.glb .gltf .fbx .obj)
and groups them into assets:

- kiln's layout — `wooden-chair/wooden-chair_{original,clean,textured,optimized,final}.glb`
  beside `wooden-chair.blend` and `wooden-chair_log.md` — is one asset whose stages
  are its variants;
- any other model file is an asset of its own; the same stem in several formats
  (`chair.glb`, `chair.fbx`) is one asset with one variant per format.

Everything Studio writes lives in `<project>/.kiln-studio/`:

    catalog.json                    categories and tags, per asset
    assets/<key>/notes.json         notes, with their threads
    assets/<key>/history.json       versions seen (hash, size, tris) + changelog
    assets/<key>/shots/             a screenshot per note, and per "addressed" reply
    assets/<key>/live.json          the build kiln is running: its phases, step by step
    baseline/<key>/                 ONE previous copy of the model (n-1), git-ignored
    cache/thumbs/<key>/<hash>.webp  a small render of each version seen, git-ignored
    cache/server.log
    server.json                     the running server's port and pid, git-ignored

<key> is the asset id with "/" replaced by "~" (a literal "~" or "%" is escaped),
so the folder name stays readable.
Coordinates: three.js/glTF is Y-up with the model front on +Z; notes also carry
Blender coordinates (x, -z, y), front on -Y, Z up, which is what kiln models in.
"""

from __future__ import annotations

import filecmp
import fnmatch
import hashlib
import json
import math
import os
import re
import secrets
import shutil
import struct
import tempfile
import time
import zipfile
from dataclasses import dataclass, field
from datetime import datetime, timezone
from pathlib import Path
from urllib.parse import unquote

DATA_DIR = ".kiln-studio"
MODEL_EXTS = (".glb", ".gltf", ".fbx", ".obj", ".usdz", ".3mf", ".stl")
# kiln's pipeline stages, best first: the default variant is the most finished one.
KILN_STAGES = ("final", "optimized", "textured", "clean", "original", "preview", "print", "game", "ar")
# preview: a copy of original, for Quick Look. print, game, ar: the outputs, each in its folder.
# The scratch export kiln writes after each phase while it builds: first while it is the
# newest file of the asset (the build is under way), last once a real stage is newer.
LIVE = "live"
FORMAT_ORDER = (".glb", ".gltf", ".fbx", ".obj", ".usdz", ".3mf", ".stl")
STAGE_RE = re.compile(r"^(?P<name>.+)_(?P<stage>" + "|".join(KILN_STAGES + (LIVE,)) + r")$")
# The printable output's parts beside {name}_print.3mf: {name}_print_{part}.stl, side files of the model.
PRINT_PART_RE = re.compile(r"^(?P<name>.+)_print_[^_/]+$")
AR_FINISH_RE = re.compile(r"^(?P<name>.+)_ar_[^_/]+$")   # a finish's own USDZ, ar/<model>_ar_<finish>.usdz
# A model's outputs, one folder per use in its own folder: web/{name}_final.glb,
# game/{name}_game.fbx, ar/{name}_ar.usdz + .glb, print/{name}_print.3mf + _print_{part}.stl.
OUTPUT_DIRS = ("web", "game", "ar", "print")
# kiln's phases, in pipeline order; rig and animate only show when a build reports them.
PHASES = ("config", "brief", "source", "import", "cleanup", "texture", "rig", "animate", "optimize", "export")
OPTIONAL_PHASES = ("rig", "animate")
PHASE_ALIASES = {"texturing": "texture", "5b": "texture", "rigging": "rig", "5c": "rig",
                 "animation": "animate", "5d": "animate", "opt": "optimize", "sourcing": "source",
                 "create": "source", "creation": "source", "model": "source", "modeling": "source"}
# Unity's Library/ and Temp/ hold thousands of cached imports, never source models.
SKIP_DIRS = {"node_modules", "__pycache__", "venv", "site-packages", "Library", "Temp"}
STATUSES = ("open", "addressed", "resolved", "wontfix")
ACTIVE = ("open", "addressed")
NOTE_ID_RE = re.compile(r"^n_[a-z0-9]{6,16}$")
REPLY_ID_RE = re.compile(r"^r_[a-z0-9]{6,16}$")
SIDE_EXTS = (".png", ".jpg", ".jpeg", ".webp", ".md", ".txt", ".json", ".yaml", ".yml", ".blend", ".py")


def now() -> str:
    return datetime.now(timezone.utc).isoformat(timespec="seconds")


def new_id(prefix: str) -> str:
    # Time-sortable, short, and unique enough for one person's notes.
    t = format(int(time.time() * 1000), "x")[-8:]
    return f"{prefix}_{t}{secrets.token_hex(2)}"


def asset_key(asset_id: str) -> str:
    # Readable and unambiguous: "a/b" -> "a~b", while a literal "~" or "%" is escaped.
    return asset_id.replace("%", "%25").replace("~", "%7E").replace("/", "~")


# ── project ──────────────────────────────────────────────────────────────────


class Project:
    def __init__(self, root: Path | str):
        self.root = Path(root).resolve()
        self.data = self.root / DATA_DIR

    # paths
    def asset_dir(self, asset_id: str) -> Path:
        return self.data / "assets" / asset_key(asset_id)

    def baseline_dir(self, asset_id: str) -> Path:
        return self.data / "baseline" / asset_key(asset_id)

    def rel(self, p: Path) -> str:
        return Path(p).resolve().relative_to(self.root).as_posix()

    def inside(self, rel: str) -> Path:
        """Resolve a project-relative path, refusing anything outside the project."""
        # Checked before resolving: on Windows, resolving "\\host\share" alone opens
        # an SMB connection, which would hand the user's NTLM hash to that host.
        if "\\" in rel or re.match(r"^[A-Za-z]:", rel) or rel.startswith("/") or "\0" in rel:
            raise ValueError(f"not a project path: {rel!r}")
        # realpath, then a prefix test: the same refusal as before, in the form CodeQL reads as a guard
        p, root = os.path.realpath(os.path.join(self.root, rel)), str(self.root)
        if p != root and not p.startswith(root + os.sep):
            raise ValueError(f"outside the project: {rel!r}")
        return Path(p)

    def ensure(self) -> None:
        if (self.data / ".gitignore").exists():
            return
        self.data.mkdir(parents=True, exist_ok=True)
        # Notes, screenshots and version renders are worth committing with the
        # models; the baseline copy, the cache and the pid file are not.
        (self.data / ".gitignore").write_text("baseline/\ncache/\nserver.json\n*.lock\n*.tmp\n")

    def config(self) -> dict:
        p = self.data / "config.json"
        try:
            data = json.loads(p.read_text()) if p.exists() else {}
        except (OSError, json.JSONDecodeError):
            return {}
        return data if isinstance(data, dict) else {}

    def settings(self) -> dict:
        """The project's settings (CONFIG_KEYS) with their defaults filled in. What a model is
        for comes from the project when it says, else from the user's default for every
        project (~/.kiln-studio/defaults.json), else the web."""
        return {**CONFIG_DEFAULTS, "target": user_defaults()["target"], **clean_config(self.config())}

    def target_source(self) -> str:
        return "project" if "target" in clean_config(self.config()) else "default"

    # scanning
    def scan(self) -> list["Asset"]:
        return scan(self)

    def find(self, asset_id: str) -> "Asset":
        for a in self.scan():
            if a.id == asset_id:
                return a
        # Accept a bare name when it is unambiguous: `/kiln studio wooden-chair`.
        hits = [a for a in self.scan() if a.name == asset_id or a.id.endswith("/" + asset_id)]
        if len(hits) == 1:
            return hits[0]
        if hits:
            raise KeyError(f"{asset_id!r} is ambiguous: {', '.join(a.id for a in hits)}")
        raise KeyError(f"no asset {asset_id!r} under {self.root}")


@dataclass
class Variant:
    label: str          # kiln stage ("final") or format ("glb")
    path: Path
    rel: str
    size: int
    mtime: float
    hash: str = ""

    def to_json(self) -> dict:
        return {"label": self.label, "file": self.rel, "size": self.size,
                "mtime": self.mtime, "hash": self.hash, "ext": self.path.suffix.lower()}


@dataclass
class Asset:
    id: str
    name: str
    folder: str                          # project-relative folder holding the files
    kiln: bool                           # kiln's stage layout
    variants: list[Variant] = field(default_factory=list)
    files: list[str] = field(default_factory=list)   # side files: .blend, log, images

    @property
    def primary(self) -> Variant:
        return self.variants[0]

    def variant(self, label: str | None) -> Variant:
        if not label:
            return self.primary
        for v in self.variants:
            if v.label == label or v.rel == label:
                return v
        raise KeyError(f"{self.id} has no variant {label!r} "
                       f"(has {', '.join(v.label for v in self.variants)})")

    @property
    def default_category(self) -> str:
        # A kiln asset folder's parent (the output folder, or the batch folder);
        # for a loose file, its own folder.
        folder = str(Path(self.folder).parent) if self.kiln else self.folder
        return "" if folder in (".", "") else folder

    def log_file(self) -> str | None:
        return next((f for f in self.files if f.endswith("_log.md")), None)

    def blend_file(self) -> str | None:
        return next((f for f in self.files if f.endswith(".blend")), None)


# ── project settings: .kiln-studio/config.json ───────────────────────────────
# Shared with Claude: the skill reads live_view, auto_open and target as CONFIG's
# defaults (references/studio.md § 9), the server reads exclude and target.

TARGETS = ("web", "desktop", "print")
BLENDER_MCPS = ("ahujasid", "lab")
RESERVED_PORT = 9876   # the usual Blender MCP port: the user's own Blender, never the worker's
CONFIG_DEFAULTS = {"live_view": True, "auto_open": True, "exclude": [], "target": "web",
                   # The Claude worker (worker.py): off until the user turns it on; its own
                   # Blender's port, and which Blender MCP server drives it.
                   "claude_worker": False, "blender_port": 9877, "blender_mcp": "ahujasid",
                   # How Claude's tool calls are approved (ask: the safe list passes, the rest
                   # waits for the user; auto: Claude Code's auto mode decides, paid generation
                   # still asks), how many runs at once (each its own Blender, ports from
                   # blender_port up), the model ("" = Claude Code's default), and the cap per
                   # request when running on an API key.
                   "claude_approvals": "ask", "claude_parallel": 1, "claude_model": "", "claude_budget_usd": 2.0,
                   # Paid generation (Hyper3D Rodin, Hunyuan3D…): ask each time, or let it through.
                   "claude_paid": "ask",
                   # Studio's Blender opens behind the other windows, without taking focus.
                   "blender_behind": True}
CLAUDE_APPROVALS = ("ask", "auto", "all")   # claude_paid takes ask or auto only


def user_dir() -> Path:
    """The user's own Studio folder, for every project on this computer."""
    return Path(os.environ.get("KILN_STUDIO_HOME") or "~/.kiln-studio").expanduser()


def user_defaults() -> dict:
    d = read_json(user_dir() / "defaults.json", {}) or {}
    return {"target": d.get("target") if d.get("target") in TARGETS else "web"}


def save_user_defaults(**kw) -> dict:
    if "target" in kw and kw["target"] not in TARGETS:
        raise ValueError(f"target must be one of {', '.join(TARGETS)}")
    cur = {**user_defaults(), **kw}
    user_dir().mkdir(parents=True, exist_ok=True)
    write_json(user_dir() / "defaults.json", cur)
    return cur
MAX_PARALLEL = 4
MODEL_RE = re.compile(r"^[a-z0-9][a-z0-9.\-\[\]]{0,63}$")


def _parallel_ok(v) -> bool:
    return isinstance(v, int) and not isinstance(v, bool) and 1 <= v <= MAX_PARALLEL


def _budget_ok(v) -> bool:
    return isinstance(v, (int, float)) and not isinstance(v, bool) and 0.1 <= v <= 100


def _port_ok(v) -> bool:
    return isinstance(v, int) and not isinstance(v, bool) and 1024 <= v <= 65535 and v != RESERVED_PORT


def clean_config(data: dict) -> dict:
    """The known keys, of the right type; anything else is left out (but kept on disk)."""
    out: dict = {}
    for k in ("live_view", "auto_open", "claude_worker", "blender_behind"):
        if isinstance(data.get(k), bool):
            out[k] = data[k]
    if _port_ok(data.get("blender_port")):
        out["blender_port"] = data["blender_port"]
    if data.get("blender_mcp") in BLENDER_MCPS:
        out["blender_mcp"] = data["blender_mcp"]
    if data.get("claude_approvals") in CLAUDE_APPROVALS:
        out["claude_approvals"] = data["claude_approvals"]
    if data.get("claude_paid") in ("ask", "auto"):
        out["claude_paid"] = data["claude_paid"]
    if _parallel_ok(data.get("claude_parallel")):
        out["claude_parallel"] = data["claude_parallel"]
    if isinstance(data.get("claude_model"), str) and (data["claude_model"] == "" or MODEL_RE.match(data["claude_model"])):
        out["claude_model"] = data["claude_model"]
    if _budget_ok(data.get("claude_budget_usd")):
        out["claude_budget_usd"] = float(data["claude_budget_usd"])
    ex = data.get("exclude")
    if isinstance(ex, list):
        out["exclude"] = [str(x).strip() for x in ex if str(x).strip()][:200]
    if data.get("target") in TARGETS:
        out["target"] = data["target"]
    return out


def save_config(project: "Project", updates: dict) -> dict:
    """Change some settings. Unknown keys and bad values are refused; keys the file has
    that Studio does not know are kept as they are."""
    for k, v in updates.items():
        if k not in CONFIG_DEFAULTS:
            raise ValueError(f"unknown setting {k!r} (known: {', '.join(CONFIG_DEFAULTS)})")
        if k in ("live_view", "auto_open", "claude_worker", "blender_behind") and not isinstance(v, bool):
            raise ValueError(f"{k} must be true or false")
        if k == "blender_port" and not _port_ok(v):
            raise ValueError(f"blender_port must be a port from 1024 to 65535, not {RESERVED_PORT} "
                             "(the usual Blender MCP port, kept for your own Blender)")
        if k == "blender_mcp" and v not in BLENDER_MCPS:
            raise ValueError(f"blender_mcp must be one of {', '.join(BLENDER_MCPS)}")
        if k == "claude_approvals" and v not in CLAUDE_APPROVALS:
            raise ValueError("claude_approvals must be ask, auto or all")
        if k == "claude_paid" and v not in ("ask", "auto"):
            raise ValueError("claude_paid must be ask or auto")
        if k == "claude_parallel" and not _parallel_ok(v):
            raise ValueError(f"claude_parallel must be 1 to {MAX_PARALLEL}")
        if k == "claude_model" and not (isinstance(v, str) and (v == "" or MODEL_RE.match(v))):
            raise ValueError("claude_model is an alias (opus, sonnet…) or a model's full name, or empty for the default")
        if k == "claude_budget_usd" and not _budget_ok(v):
            raise ValueError("claude_budget_usd must be 0.1 to 100 (dollars per request)")
        if k == "exclude" and not (isinstance(v, list) and all(isinstance(x, str) for x in v)):
            raise ValueError("exclude must be a list of glob patterns")
        if k == "target" and v not in (*TARGETS, ""):
            raise ValueError(f"target must be one of {', '.join(TARGETS)}, or empty for your default")
    project.ensure()
    with Lock(project):
        data = project.config()
        data.update(updates)
        if data.get("target") == "":
            data.pop("target")   # back to the user's default
        if "exclude" in updates:
            data["exclude"] = clean_config(data)["exclude"]
        write_json(project.data / "config.json", data)
    return project.settings()


def _within(project: Project, p: Path) -> bool:
    try:
        r = p.resolve()
    except OSError:
        return False
    return r == project.root or project.root in r.parents


def _excluded(rel: str, patterns: list[str]) -> bool:
    return any(fnmatch.fnmatch(rel, p) or fnmatch.fnmatch(rel + "/", p) for p in patterns)


_hash_cache: dict[tuple[str, float, int], str] = {}


def file_hash(p: Path) -> str:
    st = p.stat()
    key = (str(p), st.st_mtime, st.st_size)
    h = _hash_cache.get(key)
    if h is None:
        d = hashlib.sha1()
        with p.open("rb") as f:
            for chunk in iter(lambda: f.read(1 << 20), b""):
                d.update(chunk)
        h = _hash_cache[key] = d.hexdigest()[:12]
    return h


def scan(project: Project) -> list[Asset]:
    exclude = project.settings()["exclude"]
    by_dir: dict[Path, list[os.DirEntry]] = {}
    for dirpath, dirnames, filenames in os.walk(project.root):
        d = Path(dirpath)
        rel_dir = "" if d == project.root else d.relative_to(project.root).as_posix()
        dirnames[:] = sorted(
            n for n in dirnames
            if not n.startswith(".") and n not in SKIP_DIRS
            and not _excluded(f"{rel_dir}/{n}".lstrip("/"), exclude))
        models = [f for f in filenames if f.lower().endswith(MODEL_EXTS)
                  and not f.startswith(".")
                  and not _excluded(f"{rel_dir}/{f}".lstrip("/"), exclude)]
        if models and d.name in OUTPUT_DIRS and d != project.root and all(f.startswith(d.parent.name + "_") for f in models):
            # An output folder of the model next to it: its files are that model's.
            by_dir.setdefault(d.parent, []).extend(f"{d.name}/{f}" for f in sorted(models))
            continue
        if models:
            by_dir.setdefault(d, []).extend(sorted(models))
    assets: list[Asset] = []
    for d, models in by_dir.items():
        assets.extend(_group_dir(project, d, models))
    assets.sort(key=lambda a: a.id)
    return assets


def _group_dir(project: Project, d: Path, models: list[str]) -> list[Asset]:
    rel_dir = "" if d == project.root else d.relative_to(project.root).as_posix()
    # A model symlinked from outside the project cannot be served (/files/ stays
    # inside it), so it is left out rather than listed broken.
    models = [f for f in models if _within(project, d / f)]
    siblings = sorted(f for f in os.listdir(d) if f.lower().endswith(SIDE_EXTS) and not f.startswith(".")
                      and _within(project, d / f))
    groups: dict[tuple[str, bool], list[tuple[str, str]]] = {}
    mtimes = {f: (d / f).stat().st_mtime for f in models}
    parts = []
    for f in models:
        stem, ext = os.path.splitext(f.rsplit("/", 1)[-1])   # an output folder's file: its own name
        if ext.lower() in (".stl", ".3mf") and PRINT_PART_RE.match(stem) and not STAGE_RE.match(stem):
            parts.append(f)
            continue
        if ext.lower() == ".usdz" and AR_FINISH_RE.match(stem) and not STAGE_RE.match(stem):
            parts.append(f)   # beside its model, not a model of its own
            continue
        m = STAGE_RE.match(stem)
        if m:
            groups.setdefault((m.group("name"), True), []).append((m.group("stage"), f))
        else:
            groups.setdefault((stem, False), []).append((ext.lower().lstrip("."), f))
    # A kiln asset and a plain file with the same name (wooden-chair.glb next to
    # wooden-chair_final.glb) are one asset: the plain file joins as a variant.
    for (name, kiln) in list(groups):
        if not kiln and (name, True) in groups:
            groups[(name, True)].extend(groups.pop((name, False)))
    out = []
    for (name, kiln), items in groups.items():
        newest_other = max((mtimes[f] for label, f in items if label != LIVE), default=0.0)

        def order(item: tuple[str, str]) -> tuple[int, int]:
            label, f = item
            ext = os.path.splitext(f)[1].lower()
            if label == LIVE:
                stage = -1 if mtimes[f] >= newest_other else len(KILN_STAGES)
            else:
                stage = KILN_STAGES.index(label) if label in KILN_STAGES else len(KILN_STAGES)
            return (stage, FORMAT_ORDER.index(ext) if ext in FORMAT_ORDER else 9)
        items.sort(key=order)
        variants = []
        seen_labels: set[str] = set()
        for label, f in items:
            p = d / f
            ext = os.path.splitext(f)[1].lower().lstrip(".")
            # final.glb and final.fbx: label the second by its format too.
            lab = label if label not in seen_labels else f"{label}.{ext}"
            seen_labels.add(lab)
            st = p.stat()
            variants.append(Variant(lab, p, p.relative_to(project.root).as_posix(), st.st_size, st.st_mtime))
        # _preview is kiln's copy of _original for Quick Look: the same model twice is no stage to pick.
        orig = next((v for v in variants if v.label == "original"), None)
        if orig:
            variants = [v for v in variants if not (v.label == "preview" and v.size == orig.size
                                                    and filecmp.cmp(v.path, orig.path, shallow=False))]
        # A folder named after the asset is kiln's per-asset output folder: the id is
        # the folder, and every side file in it belongs to the asset.
        own_folder = kiln and d.name == name and rel_dir
        if own_folder:
            asset_id = rel_dir
            files = sorted(siblings + [f for f in parts if f.rsplit("/", 1)[-1].startswith(name)])
        else:
            asset_id = f"{rel_dir}/{name}".lstrip("/")
            files = [f for f in siblings if f.startswith(name) and not f.lower().endswith(MODEL_EXTS)]
        out.append(Asset(asset_id, name, rel_dir or ".", kiln, variants,
                         [f"{rel_dir}/{f}".lstrip("/") for f in files]))
    return out


# ── glTF stats (no decoding: accessor counts and min/max are in the JSON) ────


def read_gltf_json(path: Path) -> dict:
    with path.open("rb") as f:
        if path.suffix.lower() == ".gltf":
            return json.load(f)
        head = f.read(12)
        if len(head) < 12 or head[:4] != b"glTF":
            raise ValueError("not a GLB")
        length, ctype = struct.unpack("<II", f.read(8))
        if ctype != 0x4E4F534A:  # "JSON"
            raise ValueError("GLB has no JSON chunk first")
        return json.loads(f.read(length))


def _mat_mul(a: list[float], b: list[float]) -> list[float]:
    # Column-major 4x4, as glTF stores them.
    return [sum(a[k * 4 + r] * b[c * 4 + k] for k in range(4)) for c in range(4) for r in range(4)]


def _node_matrix(n: dict) -> list[float]:
    if "matrix" in n:
        return list(n["matrix"])
    tx, ty, tz = n.get("translation", (0, 0, 0))
    x, y, z, w = n.get("rotation", (0, 0, 0, 1))
    sx, sy, sz = n.get("scale", (1, 1, 1))
    return [
        (1 - 2 * (y * y + z * z)) * sx, (2 * (x * y + z * w)) * sx, (2 * (x * z - y * w)) * sx, 0,
        (2 * (x * y - z * w)) * sy, (1 - 2 * (x * x + z * z)) * sy, (2 * (y * z + x * w)) * sy, 0,
        (2 * (x * z + y * w)) * sz, (2 * (y * z - x * w)) * sz, (1 - 2 * (x * x + y * y)) * sz, 0,
        tx, ty, tz, 1,
    ]


_NORM = {5120: 127.0, 5121: 255.0, 5122: 32767.0, 5123: 65535.0}


def gltf_stats(path: Path) -> dict:
    g = read_gltf_json(path)
    acc = g.get("accessors", [])
    meshes = g.get("meshes", [])
    nodes = g.get("nodes", [])
    tris = verts = instances = 0
    lo = [math.inf] * 3
    hi = [-math.inf] * 3

    def count(a: int | None) -> int:
        return acc[a].get("count", 0) if a is not None and a < len(acc) else 0

    def visit(i: int, parent: list[float], seen: set[int]) -> None:
        nonlocal tris, verts, instances
        if i in seen or i >= len(nodes):
            return
        seen.add(i)
        n = nodes[i]
        m = _mat_mul(parent, _node_matrix(n))
        if "mesh" in n and n["mesh"] < len(meshes):
            instances += 1
            for p in meshes[n["mesh"]].get("primitives", []):
                pos = p.get("attributes", {}).get("POSITION")
                nv = count(pos)
                ni = count(p.get("indices")) if "indices" in p else nv
                mode = p.get("mode", 4)
                tris += ni // 3 if mode == 4 else max(ni - 2, 0) if mode in (5, 6) else 0
                verts += nv
                a = acc[pos] if pos is not None and pos < len(acc) else {}
                if "min" in a and "max" in a:
                    k = _NORM.get(a.get("componentType")) if a.get("normalized") else None
                    mn = [v / k for v in a["min"]] if k else a["min"]
                    mx = [v / k for v in a["max"]] if k else a["max"]
                    for cx in (mn[0], mx[0]):
                        for cy in (mn[1], mx[1]):
                            for cz in (mn[2], mx[2]):
                                for r in range(3):
                                    v = m[r] * cx + m[4 + r] * cy + m[8 + r] * cz + m[12 + r]
                                    lo[r] = min(lo[r], v)
                                    hi[r] = max(hi[r], v)
        for c in n.get("children", []):
            visit(c, m, seen)

    ident = [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]
    scenes = g.get("scenes", [])
    if scenes:
        roots = scenes[g.get("scene", 0) if g.get("scene", 0) < len(scenes) else 0].get("nodes", [])
    else:
        children = {c for n in nodes for c in n.get("children", [])}
        roots = [i for i in range(len(nodes)) if i not in children]
    seen: set[int] = set()
    for r in roots:
        visit(r, ident, seen)
    anims = []
    for a in g.get("animations", []):
        dur = 0.0
        for s in a.get("samplers", []):
            inp = s.get("input")
            if inp is not None and inp < len(acc) and acc[inp].get("max"):
                dur = max(dur, acc[inp]["max"][0])
        anims.append({"name": a.get("name", ""), "duration": round(dur, 3),
                      "channels": len(a.get("channels", []))})
    out = {
        "tris": tris, "verts": verts, "meshes": len(meshes), "instances": instances,
        "nodes": len(nodes), "materials": [m.get("name", f"material_{i}") for i, m in enumerate(g.get("materials", []))],
        "textures": len(g.get("textures", [])), "images": len(g.get("images", [])),
        "animations": anims, "skins": len(g.get("skins", [])),
        "extensions": sorted(set(g.get("extensionsUsed", []))),
        # Finishes: the same shape in other materials (KHR_materials_variants), by name.
        "finishes": [v.get("name", "") for v in (g.get("extensions") or {}).get("KHR_materials_variants", {}).get("variants", [])],
        "generator": g.get("asset", {}).get("generator", ""),
    }
    if lo[0] != math.inf:
        dims = [hi[i] - lo[i] for i in range(3)]
        out["bbox"] = {"min": [round(v, 4) for v in lo], "max": [round(v, 4) for v in hi]}
        # Blender reads glTF (x, y, z) as (x, -z, y): width X, depth Y, height Z.
        out["dimensions_blender"] = [round(dims[0], 4), round(dims[2], 4), round(dims[1], 4)]
    return out


_stats_cache: dict[tuple[str, str], dict] = {}


def stl_stats(path: Path) -> dict:
    """Triangles and size of an STL (binary or ASCII). kiln's print files are in millimetres."""
    data = path.read_bytes()
    pts: list[tuple[float, float, float]] = []
    n = struct.unpack_from("<I", data, 80)[0] if len(data) >= 84 else 0
    if len(data) == 84 + 50 * n and n:
        for i in range(n):
            o = 84 + 50 * i + 12
            pts += [struct.unpack_from("<3f", data, o + 12 * k) for k in range(3)]
    else:
        txt = data.decode("ascii", "replace")
        n = txt.count("facet normal")
        pts = [tuple(map(float, m.groups())) for m in re.finditer(r"vertex\s+(\S+)\s+(\S+)\s+(\S+)", txt)]
    out: dict = {"tris": n, "verts": None, "meshes": 1, "units": "mm"}
    if pts:
        lo = [min(p[k] for p in pts) for k in range(3)]
        hi = [max(p[k] for p in pts) for k in range(3)]
        out["dimensions_blender"] = [round((hi[k] - lo[k]) / 1000, 4) for k in range(3)]
    return out


def threemf_stats(path: Path) -> dict:
    """Triangles, parts and size of a 3MF (a zip of XML models)."""
    tris, objects, xs, ys, zs, unit = 0, 0, [], [], [], "millimeter"
    with zipfile.ZipFile(path) as z:
        for name in z.namelist():
            if not name.lower().endswith(".model"):
                continue
            x = z.read(name)
            m = re.search(rb'<model[^>]*\sunit="(\w+)"', x)
            unit = m.group(1).decode() if m else unit
            tris += x.count(b"<triangle ")
            objects += len(re.findall(rb"<mesh>", x))
            for v in re.finditer(rb'<vertex\s+x="([^"]+)"\s+y="([^"]+)"\s+z="([^"]+)"', x):
                xs.append(float(v.group(1))); ys.append(float(v.group(2))); zs.append(float(v.group(3)))
    scale = {"micron": 1e-6, "millimeter": 1e-3, "centimeter": 1e-2, "inch": 0.0254, "foot": 0.3048, "meter": 1.0}.get(unit, 1e-3)
    out: dict = {"tris": tris, "verts": None, "meshes": objects, "units": unit}
    if xs:
        out["dimensions_blender"] = [round((max(a) - min(a)) * scale, 4) for a in (xs, ys, zs)]
    return out


def variant_stats(v: Variant) -> dict | None:
    ext = v.path.suffix.lower()
    if ext not in (".glb", ".gltf", ".stl", ".3mf"):
        return None
    key = (v.rel, v.hash or file_hash(v.path))
    if key not in _stats_cache:
        try:
            _stats_cache[key] = stl_stats(v.path) if ext == ".stl" else threemf_stats(v.path) if ext == ".3mf" else gltf_stats(v.path)
        except (OSError, ValueError, KeyError, IndexError, TypeError, json.JSONDecodeError) as e:
            _stats_cache[key] = {"error": str(e)}
    return _stats_cache[key]


# ── storage: locked JSON read-modify-write ───────────────────────────────────


class Lock:
    """A cross-process lock file (the server and the CLI both write)."""

    # Holders keep it for milliseconds; one older than STALE died holding it.
    STALE = 5.0

    def __init__(self, project: Project, timeout: float = 15.0):
        self.path = project.data / "store.lock"
        self.timeout = timeout

    def __enter__(self) -> "Lock":
        self.path.parent.mkdir(parents=True, exist_ok=True)
        deadline = time.monotonic() + self.timeout
        while True:
            try:
                fd = os.open(self.path, os.O_CREAT | os.O_EXCL | os.O_WRONLY)
                os.write(fd, str(os.getpid()).encode())
                os.close(fd)
                return self
            except FileExistsError:
                try:  # a holder that died leaves the file behind
                    if time.time() - self.path.stat().st_mtime > self.STALE:
                        self.path.unlink(missing_ok=True)
                        continue
                except FileNotFoundError:
                    continue
                if time.monotonic() > deadline:
                    raise TimeoutError(f"could not lock {self.path}; if no Studio command is running, delete it")
                time.sleep(0.02)

    def __exit__(self, *exc) -> None:
        self.path.unlink(missing_ok=True)


def read_json(p: Path, default):
    try:
        with p.open() as f:
            return json.load(f)
    except FileNotFoundError:
        return default
    except json.JSONDecodeError as e:
        raise ValueError(f"{p} is not valid JSON ({e}); fix or delete it") from e


def write_json(p: Path, data) -> None:
    p.parent.mkdir(parents=True, exist_ok=True)
    fd, tmp = tempfile.mkstemp(dir=p.parent, suffix=".tmp")
    with os.fdopen(fd, "w") as f:
        json.dump(data, f, indent=2, ensure_ascii=False)
        f.write("\n")
    os.chmod(tmp, 0o644)  # mkstemp makes it 0600; these files are shared and committed
    os.replace(tmp, p)


# ── catalog: categories and tags ─────────────────────────────────────────────


def load_catalog(project: Project) -> dict:
    return read_json(project.data / "catalog.json", {"assets": {}})


def set_meta(project: Project, asset_id: str, category: str | None = None,
             tags: list[str] | None = None) -> dict:
    project.ensure()
    with Lock(project):
        cat = load_catalog(project)
        entry = cat.setdefault("assets", {}).setdefault(asset_id, {})
        if category is not None:
            category = category.strip().strip("/")
            if category:
                entry["category"] = category
            else:
                entry.pop("category", None)
        if tags is not None:
            clean = sorted({re.sub(r"\s+", "-", t.strip().lower()) for t in tags if t.strip()})
            if clean:
                entry["tags"] = clean
            else:
                entry.pop("tags", None)
        if not entry:
            cat["assets"].pop(asset_id, None)
        write_json(project.data / "catalog.json", cat)
        return entry


# ── notes ────────────────────────────────────────────────────────────────────


def notes_path(project: Project, asset_id: str) -> Path:
    return project.asset_dir(asset_id) / "notes.json"


def load_notes(project: Project, asset_id: str) -> list[dict]:
    return read_json(notes_path(project, asset_id), {"notes": []}).get("notes", [])


def _save_notes(project: Project, asset_id: str, notes: list[dict]) -> None:
    write_json(notes_path(project, asset_id), {"asset": asset_id, "notes": notes})


def counts(notes: list[dict]) -> dict:
    return {s: sum(1 for n in notes if n.get("status") == s) for s in STATUSES}


def version_ref(v: Variant) -> dict:
    return {"variant": v.label, "file": v.rel, "hash": v.hash or file_hash(v.path)}


def image_ext(data: bytes) -> str:
    if data.startswith(b"\xff\xd8"):
        return ".jpg"
    if data.startswith(b"\x89PNG"):
        return ".png"
    if data.startswith(b"RIFF") and data[8:12] == b"WEBP":
        return ".webp"
    raise ValueError("a screenshot must be a JPEG, PNG or WebP")


def save_shot(project: Project, asset_id: str, stem: str, data: bytes) -> str:
    d = project.asset_dir(asset_id) / "shots"
    # stem is a note or reply id the server already matched; checked here again, on the path itself
    p = os.path.normpath(d / (stem + image_ext(data)))
    if not p.startswith(str(d) + os.sep) or os.path.dirname(p) != str(d):
        raise ValueError(f"not a screenshot name: {stem!r}")
    d.mkdir(parents=True, exist_ok=True)
    for old in d.glob(Path(p).stem + ".*"):
        old.unlink()
    Path(p).write_bytes(data)
    return project.rel(Path(p))


def _nums(v, n: int, lo: float = -1e9, hi: float = 1e9) -> list[float] | None:
    if not (isinstance(v, list) and len(v) == n and all(isinstance(x, (int, float)) for x in v)):
        return None
    return [min(hi, max(lo, float(x))) for x in v]


def clean_view(view) -> dict | None:
    """How a note's pictures were framed, so the "after" ones match: `crop`, the part of
    the view kept (fractions: x0, y0, x1, y1), and for a pin `detail`, the close-up's
    camera (glTF frame). Anything else the page sends is dropped."""
    if not isinstance(view, dict):
        return None
    out: dict = {}
    crop = _nums(view.get("crop"), 4, 0.0, 1.0)
    if crop and crop[2] > crop[0] and crop[3] > crop[1]:
        out["crop"] = crop
    d = view.get("detail")
    if isinstance(d, dict):
        pos, tgt, fov = _nums(d.get("position"), 3), _nums(d.get("target"), 3), d.get("fov")
        if pos and tgt and isinstance(fov, (int, float)) and 1 <= fov <= 120:
            out["detail"] = {"position": pos, "target": tgt, "fov": float(fov)}
    return out or None


def add_note(project: Project, asset: Asset, text: str, *, variant: str | None = None,
             anchor: dict | None = None, camera: dict | None = None, view: dict | None = None,
             shot: bytes | None = None, detail: bytes | None = None, by: str = "user") -> dict:
    """A new note on the variant as it is now. Also takes the n-1 baseline.

    `shot` is the view (cropped to the model); `detail`, for a pin, a close-up of it."""
    project.ensure()
    v = asset.variant(variant)
    nid = new_id("n")
    note = {
        "id": nid, "kind": "pin" if anchor else "general", "text": text.strip(),
        "status": "open", "by": by, "created": now(), "version": version_ref(v),
        "anchor": anchor, "camera": camera, "view": clean_view(view), "shot": None, "detail": None,
        "thread": [],
    }
    if shot:
        note["shot"] = save_shot(project, asset.id, nid, shot)
    if detail:
        note["detail"] = save_shot(project, asset.id, f"{nid}_detail", detail)
    with Lock(project):
        notes = load_notes(project, asset.id)
        notes.append(note)
        _save_notes(project, asset.id, notes)
    observe(project, asset)
    take_baseline(project, asset, v, reason=f"note {nid}", only_if_new=True)
    return note


def update_note(project: Project, asset_id: str, note_id: str, fn) -> dict:
    with Lock(project):
        notes = load_notes(project, asset_id)
        for n in notes:
            if n["id"] == note_id:
                fn(n)
                _save_notes(project, asset_id, notes)
                return n
    raise KeyError(f"no note {note_id} on {asset_id}")


def reply(project: Project, asset: Asset, note_id: str, text: str, *, by: str,
          status: str | None = None, shot: bytes | None = None) -> dict:
    if status is not None and status not in STATUSES:
        raise ValueError(f"status must be one of {STATUSES}")
    if by == "claude" and status == "resolved":
        # Only the owner closes a note: they are the one who has looked at it.
        raise ValueError("only the user resolves a note; reply with --status addressed")
    observe(project, asset)
    entry: dict = {"id": new_id("r"), "by": by, "at": now(), "text": text.strip()}
    if status:
        entry["status"] = status

    def apply(n: dict) -> None:
        # The version the reply was made on: for "addressed", the version to check.
        try:
            v = asset.variant(n.get("version", {}).get("variant"))
        except KeyError:
            v = asset.primary
        entry["version"] = version_ref(v)
        if shot:
            entry["shot"] = save_shot(project, asset.id, f"{n['id']}_{entry['id']}", shot)
        n.setdefault("thread", []).append(entry)
        if status:
            n["status"] = status
        n["updated"] = entry["at"]

    update_note(project, asset.id, note_id, apply)
    return entry


def set_reply_shot(project: Project, asset_id: str, note_id: str, reply_id: str, shot: bytes,
                   detail: bytes | None = None) -> str:
    """The "after" of an addressed reply: the note's view and, for a pin, its close-up."""
    rel = save_shot(project, asset_id, f"{note_id}_{reply_id}", shot)
    rel_d = save_shot(project, asset_id, f"{note_id}_{reply_id}_detail", detail) if detail else None

    def apply(n: dict) -> None:
        for r in n.get("thread", []):
            if r["id"] == reply_id:
                r["shot"] = rel
                if rel_d:
                    r["detail"] = rel_d
                return
        raise KeyError(f"no reply {reply_id}")

    update_note(project, asset_id, note_id, apply)
    return rel


def edit_note_text(project: Project, asset_id: str, note_id: str, text: str) -> dict:
    def apply(n: dict) -> None:
        n["text"] = text.strip()
        n["updated"] = now()
    return update_note(project, asset_id, note_id, apply)


def delete_note(project: Project, asset_id: str, note_id: str) -> None:
    with Lock(project):
        notes = load_notes(project, asset_id)
        keep = [n for n in notes if n["id"] != note_id]
        if len(keep) == len(notes):
            raise KeyError(f"no note {note_id} on {asset_id}")
        _save_notes(project, asset_id, keep)
    shots = project.asset_dir(asset_id) / "shots"
    if shots.is_dir():
        for f in shots.glob(f"{note_id}*"):
            f.unlink()


def pending_shots(notes: list[dict], asset: Asset) -> list[dict]:
    """Replies that marked a note addressed, on the version that is current, with no
    screenshot yet: the page renders them from the note's camera (the "after")."""
    out = []
    current = {v.label: v.hash for v in asset.variants}
    for n in notes:
        for r in n.get("thread", []):
            if r.get("status") == "addressed" and not r.get("shot"):
                ver = r.get("version", {})
                if current.get(ver.get("variant")) == ver.get("hash"):
                    out.append({"note": n["id"], "reply": r["id"], "variant": ver.get("variant")})
    return out


# ── history: versions seen, and the changelog ────────────────────────────────


def history_path(project: Project, asset_id: str) -> Path:
    return project.asset_dir(asset_id) / "history.json"


def load_history(project: Project, asset_id: str) -> list[dict]:
    return read_json(history_path(project, asset_id), {"events": []}).get("events", [])


def _append_events(project: Project, asset_id: str, events: list[dict]) -> None:
    with Lock(project):
        evs = load_history(project, asset_id)
        evs.extend(events)
        write_json(history_path(project, asset_id), {"asset": asset_id, "events": evs})


def observe(project: Project, asset: Asset) -> list[dict]:
    """Record every variant whose content differs from the last version seen.

    No model is copied: a version is its hash, size, triangle count, and the small
    render the page adds. Called by the server's watcher and by every CLI write, so
    history is kept whether or not the page is open.
    """
    def last_seen(events: list[dict]) -> dict[str, str]:
        return {e["variant"]: e["hash"] for e in events if e.get("type") == "version"}

    # Hash and stats outside the lock (slow on big files)...
    for v in asset.variants:
        v.hash = v.hash or file_hash(v.path)
        variant_stats(v)
    if all(last_seen(load_history(project, asset.id)).get(v.label) == v.hash for v in asset.variants):
        return []
    project.ensure()
    live = load_live(project, asset.id) if any(v.label.startswith(LIVE) for v in asset.variants) else None
    # ...and decide under it, so the server and the CLI never both record one version.
    with Lock(project):
        evs = load_history(project, asset.id)
        last = last_seen(evs)
        new = []
        for v in asset.variants:
            if last.get(v.label) != v.hash:
                st = variant_stats(v) or {}
                e = {"type": "version", "at": now(), "variant": v.label, "file": v.rel,
                     "hash": v.hash, "size": v.size,
                     "mtime": datetime.fromtimestamp(v.mtime, timezone.utc).isoformat(timespec="seconds"),
                     "tris": st.get("tris"), "first": v.label not in last}
                if live and v.label.startswith(LIVE):
                    # Which phase this snapshot closed: the build record, version by version.
                    e["phase"], e["step"] = live.get("phase"), (live.get("steps") or [{}])[-1].get("text", "")
                new.append(e)
        if new:
            evs.extend(new)
            write_json(history_path(project, asset.id), {"asset": asset.id, "events": evs})
    return new


def log(project: Project, asset: Asset, text: str, by: str = "claude") -> dict:
    observe(project, asset)
    e = {"type": "log", "at": now(), "by": by, "text": text.strip(), "hash": asset.primary.hash}
    project.ensure()
    _append_events(project, asset.id, [e])
    return e


# Renders of each version, made by the page. A cache: the durable record of what a
# model looked like is the screenshot on each note.
def thumb_path(project: Project, asset_id: str, h: str) -> Path:
    return project.data / "cache" / "thumbs" / asset_key(asset_id) / f"{h}.webp"


def thumb_rel(project: Project, asset_id: str, h: str) -> str:
    return project.rel(thumb_path(project, asset_id, h))


def has_thumb(project: Project, asset_id: str, h: str) -> bool:
    return thumb_path(project, asset_id, h).exists()


def save_thumb(project: Project, asset_id: str, h: str, data: bytes) -> str:
    project.ensure()
    p = thumb_path(project, asset_id, h)
    p.parent.mkdir(parents=True, exist_ok=True)
    p.write_bytes(data)
    return thumb_rel(project, asset_id, h)


# ── baseline: one previous copy (n-1) ────────────────────────────────────────


def baseline(project: Project, asset_id: str) -> dict | None:
    meta = read_json(project.baseline_dir(asset_id) / "meta.json", None)
    if meta and (project.baseline_dir(asset_id) / meta["name"]).exists():
        meta["file"] = project.rel(project.baseline_dir(asset_id) / meta["name"])
        return meta
    return None


def _gltf_deps(path: Path) -> list[str]:
    """Relative files a .gltf points at (buffers, images), to copy alongside it."""
    if path.suffix.lower() != ".gltf":
        return []
    try:
        g = read_gltf_json(path)
    except (OSError, ValueError):
        return []
    # URIs are URI-encoded: Blender writes "My%20Chair.bin" for "My Chair.bin".
    uris = [unquote(x.get("uri", "")) for x in g.get("buffers", []) + g.get("images", [])]
    return [u for u in uris if u and not u.startswith("data:") and "://" not in u
            and ".." not in u and not u.startswith("/")]


def take_baseline(project: Project, asset: Asset, v: Variant | None = None, *,
                  reason: str, only_if_new: bool = False) -> dict | None:
    """Copy the variant as it is now into the asset's single baseline slot.

    Studio keeps exactly one previous copy per asset — the version a review pass
    started from — so a pass can be compared before/after and reverted, without a
    growing pile of model copies. `only_if_new` keeps an existing baseline of the
    same content (several notes on one version are one pass).
    """
    v = v or asset.primary
    v.hash = v.hash or file_hash(v.path)
    cur = baseline(project, asset.id)
    if only_if_new and cur and cur.get("hash") == v.hash:
        return cur
    project.ensure()
    d = project.baseline_dir(asset.id)
    d.parent.mkdir(parents=True, exist_ok=True)
    tmp = Path(tempfile.mkdtemp(dir=d.parent, prefix=d.name + ".", suffix=".tmp"))
    shutil.copy2(v.path, tmp / v.path.name)
    for dep in _gltf_deps(v.path):
        src = v.path.parent / dep
        if src.is_file():
            (tmp / dep).parent.mkdir(parents=True, exist_ok=True)
            shutil.copy2(src, tmp / dep)
    meta = {"name": v.path.name, "variant": v.label, "source": v.rel, "hash": v.hash,
            "size": v.size, "at": now(), "reason": reason}
    write_json(tmp / "meta.json", meta)
    with Lock(project):
        shutil.rmtree(d, ignore_errors=True)
        os.replace(tmp, d)
    _append_events(project, asset.id, [{"type": "baseline", "at": meta["at"], "variant": v.label,
                                        "hash": v.hash, "reason": reason}])
    return baseline(project, asset.id)


def revert(project: Project, asset: Asset) -> dict:
    """Put the baseline back over its source file. The version it replaces becomes
    the new baseline, so a revert is itself one revert away from undone."""
    b = baseline(project, asset.id)
    if not b:
        raise ValueError(f"{asset.id} has no previous version to revert to")
    target = project.inside(b["source"])
    src_dir = project.baseline_dir(asset.id)
    hold = Path(tempfile.mkdtemp(dir=src_dir.parent, prefix=src_dir.name + ".", suffix=".revert"))
    shutil.copytree(src_dir, hold, dirs_exist_ok=True)
    cur = None
    if target.exists():
        v = next((x for x in asset.variants if x.path == target), None)
        if v:
            cur = take_baseline(project, asset, v, reason=f"replaced by revert to {b['hash']}")
    # copyfile, not copy2: the restored file gets a new mtime, so anything watching
    # for newer files (Studio itself, a game engine's importer) sees the change.
    shutil.copyfile(hold / b["name"], target)
    for dep in _gltf_deps(hold / b["name"]):
        if (hold / dep).is_file():
            (target.parent / dep).parent.mkdir(parents=True, exist_ok=True)
            shutil.copyfile(hold / dep, target.parent / dep)
    shutil.rmtree(hold, ignore_errors=True)
    _append_events(project, asset.id, [{"type": "revert", "at": now(), "variant": b["variant"],
                                        "hash": b["hash"], "replaced": cur and cur["hash"]}])
    return b


# ── live: the build kiln is running ──────────────────────────────────────────


def live_path(project: Project, asset_id: str) -> Path:
    return project.asset_dir(asset_id) / "live.json"


def load_live(project: Project, asset_id: str) -> dict | None:
    try:
        return read_json(live_path(project, asset_id), None)
    except ValueError:
        return None


def norm_phase(phase: str) -> str:
    # "cleanup", "CLEANUP", "[5] CLEANUP", "5b", "texturing" are all accepted.
    p = (phase or "").strip().lower()
    p = PHASE_ALIASES.get(p, p)
    if p not in PHASES:
        p = re.sub(r"^\[?\d+[a-z]?\]?\s*", "", p)
        p = PHASE_ALIASES.get(p, p)
    if p not in PHASES:
        raise ValueError(f"unknown phase {phase!r}: one of {', '.join(PHASES)}")
    return p


def live_files(project: Project, asset_id: str) -> list[Path]:
    """The scratch `<name>_live.*` exports of a kiln asset folder."""
    d = project.inside(asset_id)
    name = d.name
    return [p for ext in (".glb", ".gltf") if (p := d / f"{name}_{LIVE}{ext}").is_file()]


def set_live(project: Project, asset_id: str, phase: str | None = None, text: str = "",
             end: bool = False) -> dict:
    """Record a step of a build. The asset need not exist yet: `asset_id` is its kiln folder
    (`generated-assets/wooden-chair`), which is the id it gets once a model lands there.

    A step on a build that ended starts a new one. `end` closes the build; the scratch
    `_live` export is the caller's to remove (end_live does both).
    """
    project.ensure()
    with Lock(project):
        cur = load_live(project, asset_id)
        t = now()
        if not cur or (cur.get("state") != "building" and not end):
            cur = {"asset": asset_id, "state": "building", "started": t, "phase": None, "steps": []}
        if phase:
            cur["phase"] = norm_phase(phase)
        elif end:
            cur["phase"] = "export"   # the build ends with its export
        if phase or text:
            cur["steps"] = (cur.get("steps") or [])[-199:] + [{"at": t, "phase": cur.get("phase"), "text": text.strip()}]
        if end:
            cur["state"] = "done"
            cur["ended"] = t
        cur["updated"] = t
        write_json(live_path(project, asset_id), cur)
        return cur


def end_live(project: Project, asset_id: str, text: str = "", keep_file: bool = False) -> tuple[dict, list[str]]:
    """Close the build, and remove the scratch `_live` export unless asked to keep it:
    kiln wrote it for the view, and compact storage keeps only original, final, .blend, log."""
    state = set_live(project, asset_id, text=text, end=True)
    removed = []
    if not keep_file:
        for p in live_files(project, asset_id):
            removed.append(project.rel(p))
            p.unlink()
    return state, removed


def live_summary(live: dict | None) -> dict | None:
    if not live:
        return None
    return {k: live.get(k) for k in ("state", "phase", "started", "updated", "ended")}


# ── work: which models a kiln command is on ──────────────────────────────────
#
# One run per project, `.kiln-studio/work.json`: the models a command works through, in
# order, each queued → active → done. The page shows a dot per model (waiting, breathing,
# green); a done model's dot goes once the user has looked at it, and the run with it.

WORK_STATES = ("queued", "active", "done", "dropped")
# A run with no word from kiln for this long died with its session: stop showing it working.
WORK_STALE = 2 * 3600


def work_path(project: Project) -> Path:
    return project.data / "work.json"


def load_work(project: Project) -> dict | None:
    try:
        return read_json(work_path(project), None)
    except ValueError:
        return None


def _work_item(run: dict, asset_id: str) -> dict:
    for it in run["items"]:
        if it["asset"] == asset_id:
            return it
    raise KeyError(f"{asset_id!r} is not in the run ({', '.join(it['asset'] for it in run['items'])})")


def _activate(it: dict, t: str) -> None:
    it["state"] = "active"
    it["started"] = it.get("started") or t


def _finish(it: dict, t: str, text: str = "") -> None:
    it["state"] = "done"
    it["ended"] = t
    if text.strip():
        it["text"] = text.strip()


def _update_work(project: Project, fn) -> dict:
    project.ensure()
    with Lock(project):
        run = load_work(project)
        t = now()
        run = fn(run, t)
        run["updated"] = t
        if run["state"] == "running" and not any(it["state"] in ("queued", "active") for it in run["items"]):
            run["state"] = "done"
            run["ended"] = t
        write_json(work_path(project), run)
        return run


def start_work(project: Project, asset_ids: list[str], label: str = "") -> dict:
    """A new run over these models, in this order, the first one active. It replaces the
    last run, its unchecked dots included."""
    ids = list(dict.fromkeys(asset_ids))
    if not ids:
        raise ValueError("name at least one model")

    def fn(_old, t):
        items = [{"asset": a, "state": "queued"} for a in ids]
        _activate(items[0], t)
        return {"id": new_id("w"), "label": label.strip(), "state": "running", "started": t, "items": items}
    return _update_work(project, fn)


def _running(run: dict | None) -> dict:
    if not run or run.get("state") != "running":
        raise ValueError("no run under way: start one with `studio.py work start <asset>...`")
    return run


def work_next(project: Project, text: str = "") -> dict:
    """The active model is done; the next queued one becomes active."""
    def fn(run, t):
        run = _running(run)
        for it in run["items"]:
            if it["state"] == "active":
                _finish(it, t, text)
        nxt = next((it for it in run["items"] if it["state"] == "queued"), None)
        if nxt:
            _activate(nxt, t)
        return run
    return _update_work(project, fn)


def work_begin(project: Project, asset_id: str) -> dict:
    """Work on this model now, out of order; the one active before it is done. A model not
    in the run joins it; with no run under way, this starts one."""
    def fn(run, t):
        if not run or run.get("state") != "running":
            return {"id": new_id("w"), "label": "", "state": "running", "started": t,
                    "items": [{"asset": asset_id, "state": "active", "started": t}]}
        for it in run["items"]:
            if it["state"] == "active" and it["asset"] != asset_id:
                _finish(it, t)
        try:
            _activate(_work_item(run, asset_id), t)
        except KeyError:
            run["items"].append({"asset": asset_id, "state": "active", "started": t})
        return run
    return _update_work(project, fn)


def work_done(project: Project, asset_id: str, text: str = "") -> dict:
    def fn(run, t):
        _finish(_work_item(_running(run), asset_id), t, text)
        return run
    return _update_work(project, fn)


def end_work(project: Project, text: str = "") -> dict:
    """Close the run: the active model is done, the ones never started are dropped."""
    def fn(run, t):
        run = _running(run)
        for it in run["items"]:
            if it["state"] == "active":
                _finish(it, t)
            elif it["state"] == "queued":
                it["state"] = "dropped"
        if text.strip():
            run["text"] = text.strip()
        run["state"] = "done"
        run["ended"] = t
        return run
    return _update_work(project, fn)


def check_work(project: Project, asset_ids: list[str] | None = None) -> dict | None:
    """The user looked: these models' green dots go (all the done ones when None).
    A finished run whose done models are all checked is cleared."""
    with Lock(project):
        run = load_work(project)
        if not run:
            return None
        changed = False
        for it in run["items"]:
            if it["state"] == "done" and not it.get("checked") and (asset_ids is None or it["asset"] in asset_ids):
                it["checked"] = now()
                changed = True
        if run["state"] != "running" and all(it.get("checked") or it["state"] != "done" for it in run["items"]):
            work_path(project).unlink(missing_ok=True)
            return None
        if changed:
            write_json(work_path(project), run)
        return run


def _age(iso: str | None) -> float:
    try:
        return time.time() - datetime.fromisoformat(iso).timestamp()
    except (TypeError, ValueError):
        return float("inf")


def work_view(run: dict | None) -> dict | None:
    """What the page shows: each model's dot (queued, active, done), and the run's progress.
    Checked and dropped models have none; a stale run shows only what it finished."""
    if not run:
        return None
    stale = run.get("state") == "running" and _age(run.get("updated")) > WORK_STALE
    dots = {}
    for it in run["items"]:
        st = it["state"]
        if stale and st in ("queued", "active"):
            continue
        if st == "dropped" or (st == "done" and it.get("checked")):
            continue
        dots[it["asset"]] = {k: it.get(k) for k in ("state", "started", "ended", "text")}
    if not dots:
        return None
    done = sum(it["state"] == "done" for it in run["items"])
    total = sum(it["state"] != "dropped" for it in run["items"])
    active = next((it["asset"] for it in run["items"] if it["state"] == "active" and not stale), None)
    return {"id": run["id"], "label": run.get("label", ""), "running": run["state"] == "running" and not stale,
            "stale": stale, "done": done, "total": total, "active": active,
            "started": run.get("started"), "updated": run.get("updated"), "dots": dots}


# ── requests: a model asked for in Studio's Create form ──────────────────────
# Like a note, but for a model that does not exist yet: open until Claude has built it.

REQUEST_ID_RE = re.compile(r"^q_[a-z0-9]{6,16}$")
REQUEST_TYPES = ("prop", "character", "creature", "vehicle", "environment")
REQUEST_TARGETS = ("web", "desktop", "ar", "print")
REQUEST_STYLES = ("realistic", "stylized", "cartoon", "low-poly")
TARGET_WORDS = {"web": "for the web (glTF)", "desktop": "for Unity/Unreal (FBX)", "ar": "for AR (USDZ)",
                "print": "for 3D printing"}


def requests_path(project: Project) -> Path:
    return project.data / "requests.json"


def load_requests(project: Project) -> list[dict]:
    return read_json(requests_path(project), {"requests": []}).get("requests", [])


def request_command(r: dict) -> str:
    """What the user pastes in Claude Code: the brief first (the skill reads anything that
    is not a command as a brief), then what the form said, then the request's id."""
    parts = [r["brief"].strip().rstrip(".")]
    if r.get("type"):
        parts.append(f"type {r['type']}")
    if r.get("target"):
        parts.append(TARGET_WORDS[r["target"]])
    if r.get("style"):
        parts.append(r["style"])
    if r.get("reference"):
        parts.append(f"reference photo {r['reference']}")
    one_line = " ".join(", ".join(parts).split())
    return f"/kiln {one_line} (Studio request {r['id']})"


def add_request(project: Project, brief: str, *, type_: str | None = None, target: str | None = None,
                style: str | None = None, photo: bytes | None = None) -> dict:
    brief = " ".join(str(brief or "").split())
    if not brief:
        raise ValueError("a request needs a brief")
    if len(brief) > 4000:
        raise ValueError("the brief is too long (4,000 characters at most)")
    for name, v, allowed in (("type", type_, REQUEST_TYPES), ("target", target, REQUEST_TARGETS), ("style", style, REQUEST_STYLES)):
        if v and v not in allowed:
            raise ValueError(f"{name} must be one of {', '.join(allowed)}")
    project.ensure()
    rid = new_id("q")
    r = {"id": rid, "kind": "create", "brief": brief, "type": type_ or None, "target": target or None,
         "style": style or None, "reference": None, "status": "open", "by": "user", "created": now(),
         "thread": []}
    if photo:
        d = project.data / "requests"
        d.mkdir(parents=True, exist_ok=True)
        p = d / (rid + image_ext(photo))
        p.write_bytes(photo)
        r["reference"] = project.rel(p)
    r["command"] = request_command(r)
    with Lock(project):
        items = load_requests(project)
        items.append(r)
        write_json(requests_path(project), {"requests": items})
    return r


def close_request(project: Project, rid: str, *, status: str = "done", asset: str | None = None,
                  text: str = "") -> dict:
    if status not in ("open", "done", "wontfix"):
        raise ValueError("status must be open, done or wontfix")
    with Lock(project):
        items = load_requests(project)
        for r in items:
            if r["id"] == rid:
                r["status"] = status
                if asset:
                    r["asset"] = asset
                r.setdefault("thread", []).append({"by": "claude", "at": now(), "status": status, "text": text.strip()})
                write_json(requests_path(project), {"requests": items})
                return r
    raise KeyError(f"no request {rid}")


# ── import: model files dropped on the page ──────────────────────────────────

IMPORT_DIR = "imports"
COMPANION_EXTS = (".bin", ".mtl", ".png", ".jpg", ".jpeg", ".webp", ".ktx2")
SAFE_NAME_RE = re.compile(r"^[^/\\\x00-\x1f:*?\"<>|]{1,200}$")


def import_file(project: Project, name: str, data: bytes, folder: str | None = None) -> str:
    """Save a dropped file under imports/ (or imports/<folder>/ for a glTF or OBJ and the
    files it needs), never over an existing one. Returns its project path."""
    name = Path(str(name)).name
    if not SAFE_NAME_RE.match(name) or name.startswith("."):
        raise ValueError(f"not a file name Studio saves: {name!r}")
    ext = Path(name).suffix.lower()
    if ext not in MODEL_EXTS and not (folder and ext in COMPANION_EXTS):
        raise ValueError(f"{name}: Studio imports {', '.join(MODEL_EXTS)} (and, beside a glTF or OBJ, its {', '.join(COMPANION_EXTS)})")
    base = project.root / IMPORT_DIR
    if folder:
        folder = Path(str(folder)).name
        if not re.match(r"^[\w.-]{1,80}$", folder) or folder.startswith("."):
            raise ValueError(f"not a folder name Studio makes: {folder!r}")
        base = base / folder
    base.mkdir(parents=True, exist_ok=True)
    dst = base / name
    # Never replace a file: chair.glb, chair-2.glb, … (companions keep their name: the
    # glTF or OBJ refers to them by it, and their folder is new).
    if dst.exists() and not (folder and ext in COMPANION_EXTS):
        stem, n = dst.stem, 2
        while (base / f"{stem}-{n}{dst.suffix}").exists():
            n += 1
        dst = base / f"{stem}-{n}{dst.suffix}"
    tmp = dst.with_name(f".{dst.name}.tmp")
    tmp.write_bytes(data)
    os.replace(tmp, dst)
    return project.rel(dst)


# ── declinations: a new model from a copy of another ─────────────────────────

DERIVE_NAME_RE = re.compile(r"^[a-z0-9][a-z0-9_-]{0,63}$")
DERIVE_TARGETS = ("same", "web", "desktop", "ar", "print")


def derive(project: Project, a: Asset, name: str, text: str, *, target: str = "same",
           start: str = "current", copy_notes: bool = False) -> Asset:
    """A declination of a kiln model: a new model beside it, from a copy of its source.

    current: the .blend, _original.glb, the build scripts and the log, renamed; kept: the
    one previous version Studio keeps (a GLB, no .blend). The outputs are not copied (they
    would be wrong once the copy changes), nor the original's working folders. The link
    goes in the catalog (`derived`), the change in the copy's log; Claude does the rest.
    The original is never written to."""
    if not a.kiln:
        raise ValueError("only a kiln model can be declined (it needs its _original and .blend)")
    name, text = str(name).strip(), str(text).strip()
    if not DERIVE_NAME_RE.match(name):
        raise ValueError(f"not a model name: {name!r} (lower case, digits, - and _)")
    if not text:
        raise ValueError("say what changes")
    if target not in DERIVE_TARGETS:
        raise ValueError(f"made for: one of {', '.join(DERIVE_TARGETS)}")
    if start not in ("current", "kept"):
        raise ValueError("start from current or kept")
    src_dir = project.root / a.folder
    parent = str(src_dir.parent)
    dst = os.path.normpath(os.path.join(parent, name))
    if not dst.startswith(parent + os.sep) or os.path.dirname(dst) != parent:
        raise ValueError(f"not a model name: {name!r}")
    name, dst = os.path.basename(dst), Path(dst)
    if dst.exists() or any(x.name == name for x in scan(project)):
        raise ValueError(f"a model named {name} is already there")
    old = a.name
    tmp = Path(tempfile.mkdtemp(dir=src_dir.parent, prefix=f".{name}.", suffix=".tmp"))
    try:
        if start == "kept":
            b = baseline(project, a.id)
            if not b:
                raise ValueError("no kept version of this model")
            kept = project.root / b["file"]
            shutil.copy2(kept, tmp / f"{name}_original{kept.suffix.lower()}")
        else:
            for f in sorted(src_dir.iterdir()):
                if not f.is_file() or f.name.startswith("."):
                    continue
                if f.name == f"{old}.blend":
                    shutil.copy2(f, tmp / f"{name}.blend")
                elif f.name.startswith(f"{old}_original."):
                    shutil.copy2(f, tmp / f.name.replace(old, name, 1))
                elif f.suffix == ".py":
                    shutil.copy2(f, tmp / f.name)   # the build scripts: Claude adapts them
            if not any(tmp.glob(f"{name}_original.*")):
                # No _original (a model made before kiln kept one): its main file stands in.
                p = a.primary.path
                shutil.copy2(p, tmp / f"{name}_original{p.suffix.lower()}")
        log = src_dir / f"{old}_log.md"
        head = log.read_text() if log.is_file() else f"# {old}\n"
        made = {"same": "as the original", "web": "the web", "desktop": "Unity / Unreal", "ar": "AR",
                "print": "3D printing"}[target]
        (tmp / f"{name}_log.md").write_text(
            head.rstrip() + f"\n\n## Declined from {old} ({now()[:10]})\n\n{text}\n\n"
            f"Made for: {made}. Studio copied {'the kept version' if start == 'kept' else 'the source'} of {old}; "
            "the outputs are to make again.\n")
        os.replace(tmp, dst)
    except BaseException:
        shutil.rmtree(tmp, ignore_errors=True)
        raise
    # Scanned afresh: a server's project caches its scan.
    new = next((x for x in scan(project) if x.id == project.rel(dst)), None)
    if new is None:
        raise ValueError(f"{name}: the copy is not a model Studio can read")
    with Lock(project):
        cat = load_catalog(project)
        cat.setdefault("assets", {}).setdefault(new.id, {})["derived"] = {
            "from": a.id, "text": text, "target": target, "start": start, "at": now()}
        write_json(project.data / "catalog.json", cat)
    if copy_notes:
        v = new.primary
        v.hash = v.hash or file_hash(v.path)
        notes = [dict(n, thread=[], version={"variant": v.label, "file": v.rel, "hash": v.hash})
                 for n in load_notes(project, a.id) if n.get("status") == "open"]
        if notes:
            _save_notes(project, new.id, notes)
    return new


DERIVE_STOP = {"a", "an", "the", "of", "with", "for", "and", "in", "on", "to", "at", "version", "same", "one",
               "la", "le", "les", "un", "une", "des", "de", "du", "et", "en", "au", "aux", "avec", "pour", "sans", "sur", "meme"}


def derive_name(project: Project, a: Asset, text: str, taken: set[str] | None = None) -> str:
    """A name for a variation from its words (as the page suggests): `stool-high-seat`."""
    import unicodedata
    plain = unicodedata.normalize("NFD", text).encode("ascii", "ignore").decode().lower()
    words = [w for w in re.split(r"[^a-z0-9]+", plain) if len(w) > 1 and w not in DERIVE_STOP][:2]
    base = "-".join([a.name, *words])[:64].strip("-")
    names = {x.name for x in scan(project)} | (taken or set())
    name, n = base, 2
    while name in names or (project.root / a.folder).parent.joinpath(name).exists():
        name, n = f"{base}-{n}", n + 1
    return name


OUTPUT_FILES = {"game": "game/{n}_game.fbx (Unity, Unreal)", "ar": "ar/{n}_ar.usdz (iPhone, Vision Pro) and ar/{n}_ar.glb (Android)",
                "print": "print/{n}_print.3mf and one STL per part, print/{n}_print_<part>.stl, in millimetres, with kiln's print mode"}


def derive_task(a: Asset, new: str, text: str, *, target: str = "same", start: str = "current",
                outputs: list[str] | None = None, notes: bool = False) -> str:
    """What is asked of Claude for one variation (the page asks the same, in the user's language)."""
    made = {"same": f"the same use as {a.name}", "web": "the web", "desktop": "Unity and Unreal", "ar": "AR",
            "print": "3D printing, with kiln's print mode"}[target]
    src = (f"Studio copied the kept (previous) version of {a.name} as {new}_original.glb; there is no .blend: rebuild it from that file."
           if start == "kept" else
           f"Studio copied the source of {a.name} here: {new}.blend, {new}_original.glb, its build scripts and its log.")
    parts = [f"{new} is a variation of {a.name}, in its own folder. {src}", f"Change it: {text.strip()}",
             f"Made for: {made}. Work on this copy only, never on {a.name}. Save {new}.blend, export {new}_original.glb "
             f"and web/{new}_final.glb with kiln's settings, and add the change to {new}_log.md."]
    if notes:
        parts.append(f"The open notes of {a.name} were copied onto it: handle them too.")
    outs = [OUTPUT_FILES[o].format(n=new) for o in (outputs or []) if o in OUTPUT_FILES]
    if outs:
        parts.append("Then make its outputs, each in its folder: " + "; ".join(outs) + ".")
    return "\n\n".join(parts)


def finish_slug(name: str) -> str:
    """A finish's name in a file name: "Noir mat" -> "noir-mat" (ar/<model>_ar_noir-mat.usdz)."""
    import unicodedata
    plain = unicodedata.normalize("NFD", name).encode("ascii", "ignore").decode().lower()
    return re.sub(r"[^a-z0-9]+", "-", plain).strip("-") or "finish"


def finish_files(a: Asset) -> list[Variant]:
    """The model's glTF files that carry finishes: the web one (its final) and AR's GLB."""
    out = []
    for v in a.variants:
        kind, ext = v.label.split(".")[0], v.path.suffix.lower()
        if ext in (".glb", ".gltf") and (kind == "final" or kind == "ar"):
            out.append(v)
    return out


def finishes_of(a: Asset) -> list[str]:
    """The finishes the model's glTF files have (KHR_materials_variants), by name."""
    for v in finish_files(a):
        names = [x.get("name", "") for x in (read_gltf_json(v.path).get("extensions") or {}).get("KHR_materials_variants", {}).get("variants", [])]
        if names:
            return names
    return []


def finish_task(project: Project, a: Asset, finishes: list[tuple[str, str]], shown: str | None = None,
                ios: bool = False) -> str:
    """What is asked of Claude to add finishes (the page asks the same, in the user's language)."""
    have = finishes_of(a)
    base = have or ["Current"]
    files = [str(Path(project.rel(v.path)).relative_to(a.folder)) for v in finish_files(a)] or [f"web/{a.name}_final.glb"]
    parts = [f"Add finishes to {a.name}: the same shape in other materials, in the same glTF files, as material "
             "variants (KHR_materials_variants; kiln's export-targets.md § Finishes).",
             f"It has these finishes already: {', '.join(have)}. Keep them." if have else
             f'Keep its material as it is as the first finish, named "{base[0]}".',
             "The new finishes:\n" + "\n".join(f"- {n.strip()}: {m.strip()}" for n, m in finishes),
             (f"Shown on opening: {shown}. " if shown else "") + f"Export again {', '.join(files)} with the finishes"
             + ("" if shown else ", the material shown on opening left as it is") + "; leave the FBX, "
             f"the USDZ and the print files (they carry none). Add the finishes to {a.name}_log.md."]
    if ios:
        parts.append(f"For iPhone AR (Quick Look shows one finish per file): also export a USDZ per finish, new ones and "
                     f"those already there, beside ar/{a.name}_ar.usdz: ar/{a.name}_ar_<finish>.usdz, the finish in lower case, "
                     f"- for spaces, no accents (e.g. ar/{a.name}_ar_{finish_slug(finishes[0][0])}.usdz), each with that "
                     "finish's materials, with the AR export's settings.")
    return "\n\n".join(parts)


def derivations(catalog: dict, asset_id: str) -> list[str]:
    """The models declined from this one."""
    return sorted(k for k, e in catalog.get("assets", {}).items() if (e.get("derived") or {}).get("from") == asset_id)


# ── the example model: "See an example" on Studio's welcome screen ───────────

EXAMPLE_SRC = Path(__file__).resolve().parent / "example"
EXAMPLE_DIR = "kiln-example"


def add_example(project: Project) -> str:
    """Copy Studio's example model (kiln's gallery barrel, MIT) into the project, in
    kiln's layout, unless it is there already. Returns its asset id."""
    src = EXAMPLE_SRC / "barrel"
    dst = project.root / EXAMPLE_DIR / "barrel"
    if not (dst / "barrel_final.glb").is_file():
        dst.mkdir(parents=True, exist_ok=True)
        for f in src.iterdir():
            if f.is_file():
                shutil.copy2(f, dst / f.name)
    return f"{EXAMPLE_DIR}/barrel"


# ── summaries for the page and the CLI ───────────────────────────────────────


def asset_summary(project: Project, a: Asset, catalog: dict) -> dict:
    notes = load_notes(project, a.id)
    meta = catalog.get("assets", {}).get(a.id, {})
    for v in a.variants:
        v.hash = v.hash or file_hash(v.path)
    st = variant_stats(a.primary) or {}
    b = baseline(project, a.id)
    return {
        "id": a.id, "name": a.name, "folder": a.folder, "kiln": a.kiln,
        "category": meta.get("category", a.default_category),
        "category_custom": "category" in meta,
        "tags": meta.get("tags", []),
        "variants": [v.to_json() for v in a.variants],
        "thumb": thumb_rel(project, a.id, a.primary.hash) if has_thumb(project, a.id, a.primary.hash) else None,
        "counts": counts(notes),
        "tris": st.get("tris"),
        "updated": max(v.mtime for v in a.variants),
        "baseline": b and {"hash": b["hash"], "variant": b["variant"], "at": b["at"]},
        "pending_shots": len(pending_shots(notes, a)),
        "live": live_summary(load_live(project, a.id)) if a.kiln else None,
        "derived": meta.get("derived"),
        "finishes": finishes_of(a),
    }


def shape_signature(path: Path) -> str | None:
    """What the shape is, from a glTF's JSON alone: each primitive's vertex count and bounds,
    each node's transform — not its materials. Finishes (new materials, a second UV map)
    leave it as it is."""
    try:
        g = read_gltf_json(path)
    except (OSError, ValueError):
        return None
    acc = g.get("accessors") or []
    parts = []
    for m in g.get("meshes") or []:
        for p in m.get("primitives") or []:
            a = acc[p["attributes"]["POSITION"]] if p.get("attributes", {}).get("POSITION") is not None else {}
            # Bounds to the millimetre, not the vertex count: Draco may renumber vertices.
            parts.append([[round(x, 3) for x in a.get("min", [])], [round(x, 3) for x in a.get("max", [])]])
    nodes = [[n.get("mesh"), [round(x, 3) for x in n.get("translation", [])], [round(x, 3) for x in n.get("scale", [])],
              [round(x, 3) for x in n.get("rotation", [])]] for n in g.get("nodes") or []]
    return hashlib.sha1(json.dumps([parts, nodes]).encode()).hexdigest()[:16]


def shape_since(project: Project, a: Asset) -> float | None:
    """When the model's shape last changed: the source's date the first time its shape was
    seen as it is now. An output older than that is to redo; one made before a change that
    left the shape alone (finishes) is not."""
    src = next((v for v in a.variants if v.label == "original"), None)
    if not src:
        return None
    sig = shape_signature(src.path)
    if not sig:
        return src.mtime
    p = project.asset_dir(a.id) / "shape.json"
    cur = read_json(p, None) or {}
    if cur.get("signature") != sig:
        since = src.mtime
        if not cur:
            # First look: the kept version, when it has this shape, says it is at least as old.
            b = baseline(project, a.id)
            kept = project.root / b["file"] if b else None
            if kept and kept.suffix.lower() in (".glb", ".gltf") and shape_signature(kept) == sig:
                since = min(since, kept.stat().st_mtime)
        cur = {"signature": sig, "since": since}
        write_json(p, cur)
    return cur["since"]


def asset_detail(project: Project, a: Asset, catalog: dict) -> dict:
    out = asset_summary(project, a, catalog)
    out["variants"] = [dict(v.to_json(), stats=variant_stats(v)) for v in a.variants]
    out["files"] = a.files
    out["log"] = a.log_file()
    out["blend"] = a.blend_file()
    out["notes"] = load_notes(project, a.id)
    out["history"] = load_history(project, a.id)
    out["baseline"] = baseline(project, a.id)
    out["pending"] = pending_shots(out["notes"], a)
    versions = {e["hash"] for e in out["history"] if e.get("type") == "version"}
    out["thumbs"] = sorted(h for h in versions if has_thumb(project, a.id, h))
    out["live"] = load_live(project, a.id) if a.kiln else None
    out["derivations"] = derivations(catalog, a.id)
    out["shape_since"] = shape_since(project, a) if a.kiln else None
    return out
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall