topview-3d-cli 0.1.0__py3-none-any.whl

topview_3d_cli/local_edit.py

@@ -0,0 +1,350 @@
+"""``node batch`` and ``pose batch``: staged edits compiled to one atomic operation batch.
+
+Every change is staged on a copy of the stored snapshot (static intents run in the Node renderer,
+library poses compile in Chromium). Any rejected change aborts the command before anything is
+written; the compiled batch then goes through the shared operation engine like ``document apply``.
+"""
+from __future__ import annotations
+
+import copy
+import json
+import math
+import sys
+from pathlib import Path
+from typing import Any, Callable
+
+from jsonschema import Draft7Validator
+
+from topview_3d_cli.director_camera_view import apply_camera_view
+from topview_3d_cli.director_document import new_scene_operation_id, normalize_node
+from topview_3d_cli.director_geometry import check_primitive_geometry, compact_geometry
+from topview_3d_cli.director_static import node_in
+from topview_3d_cli.local_assets import asset_catalog, check_render_assets, find_asset, local_asset_map
+from topview_3d_cli.local_catalog import find_any_asset
+from topview_3d_cli.local_errors import LocalProjectError
+from topview_3d_cli.local_project import apply_operations, base_result, open_project
+from topview_3d_cli.node_batch import (
+    BATCH_OPERATION_LIMIT, affected_nodes, batch_schema, compact_node_state, compile_operations, expand_changes,
+    node_state, obj, schema_error, stage_delete,
+)
+from topview_3d_cli.renderer import director_cli
+
+NODE_BATCH_SCHEMA = batch_schema(require_sequence=False)
+_UPDATE = NODE_BATCH_SCHEMA["properties"]["changes"]["items"]["oneOf"][3]["properties"]
+POSE_BATCH_SCHEMA = obj({
+    "expectedSceneSequence": {"type": "integer", "minimum": 0},
+    "items": {"type": "array", "minItems": 1, "maxItems": 16, "items": {
+        **obj({"nodeId": _UPDATE["nodeId"], "poseId": _UPDATE["nodeId"], "libraryId": _UPDATE["nodeId"],
+               **{key: _UPDATE[key] for key in ("position", "rotation", "scale")}}, ("nodeId",)),
+        "oneOf": [{"required": ["poseId"]}, {"required": ["libraryId"]}],
+    }},
+}, ("items",))
+POSE_FILE_LIMIT = 1024 * 1024
+
+
+def load_spec(path: str, invalid_code: str) -> dict[str, Any]:
+    """Read a JSON object from a file or ``-`` (stdin)."""
+    try:
+        text = sys.stdin.read() if path == "-" else Path(path).read_text(encoding="utf-8")
+    except FileNotFoundError as exc:
+        raise LocalProjectError("INPUT_NOT_FOUND", str(path)) from exc
+    try:
+        value = json.loads(text)
+    except json.JSONDecodeError as exc:
+        raise LocalProjectError(invalid_code, f"{path}: {exc.msg}") from exc
+    if not isinstance(value, dict):
+        raise LocalProjectError(invalid_code, f"{path} must contain a JSON object")
+    try:
+        json.dumps(value, allow_nan=False)
+    except ValueError as exc:
+        raise LocalProjectError(invalid_code, "NaN and Infinity are not allowed") from exc
+    return value
+
+
+def check_scene_sequence(spec: dict[str, Any], sequence: int) -> None:
+    expected = spec.get("expectedSceneSequence")
+    if expected is not None and expected != sequence:
+        raise LocalProjectError("SCENE_SEQUENCE_CONFLICT",
+                                f"expectedSceneSequence={expected} but the project is at {sequence}; re-read and re-plan",
+                                details={"expected": expected, "current": sequence})
+
+
+# Rejections that name something missing are input errors (exit 2), not scene conflicts.
+_MISSING_REFERENCE = {"NODE_NOT_FOUND:": "DIRECTOR_NODE_NOT_FOUND", "ASSET_NOT_FOUND:": "ASSET_NOT_FOUND"}
+
+
+def _reject(code: str, index: int, node_id: str, reason: str) -> LocalProjectError:
+    return LocalProjectError(code, f"changes[{index}] ({node_id}): {reason}; nothing was written",
+                             details={"index": index, "nodeId": node_id, "reason": reason})
+
+
+class _Stager:
+    """Runs static intents in the renderer in as few calls as possible, in change order."""
+
+    def __init__(self, snapshot: dict[str, Any], reject_code: str):
+        self.snapshot = snapshot
+        self.pending: list[dict[str, Any]] = []
+        self.reject_code = reject_code
+        self.node_ids: dict[int, str] = {}
+
+    def intent(self, index: int, node_id: str, intent: dict[str, Any]) -> None:
+        self.node_ids[index] = node_id
+        self.pending.append({"index": index, "intent": intent})
+
+    def flush(self) -> None:
+        if not self.pending:
+            return
+        try:
+            result = director_cli("apply-intents", {"document": self.snapshot["document"],
+                                                    "fcurves": self.snapshot.get("fcurves"),
+                                                    "intents": self.pending})
+        except LocalProjectError as exc:
+            reason = (exc.details or {}).get("reason", "") if isinstance(exc.details, dict) else ""
+            if exc.code == "RENDERER_FAILED" and reason.startswith("INTENT_REJECTED:"):
+                _, index, message = reason.split(":", 2)
+                raise _reject(self.reject_code, int(index), self.node_ids.get(int(index), ""), message) from exc
+            raise
+        finally:
+            self.pending = []
+        self.snapshot["document"] = result["document"]
+
+    def direct(self, work: Callable[[], Any]) -> Any:
+        self.flush()
+        return work()
+
+
+def _primitive_size(node: dict[str, Any]) -> dict[str, Any] | None:
+    """Parameters and the scaled local size (width/height/depth before rotation) of a primitive."""
+    primitive = node.get("primitive") or {}
+    parameters = primitive.get("parameters") or {}
+    kind = primitive.get("kind")
+    if kind == "BoxGeometry":
+        size = (parameters.get("width", 0), parameters.get("height", 0), parameters.get("depth", 0))
+    elif kind == "SphereGeometry":
+        size = (2 * parameters.get("radius", 0),) * 3
+    elif kind in ("CylinderGeometry", "ConeGeometry"):
+        radius = max(parameters.get("radiusTop", 0), parameters.get("radiusBottom", 0), parameters.get("radius", 0))
+        size = (2 * radius, parameters.get("height", 0), 2 * radius)
+    else:
+        return None
+    scale = node["transform"].get("scale") or {}
+    return {"kind": kind, "parameters": parameters,
+            "size": {axis: round(value * scale.get(axis, 1), 4) for axis, value in zip("xyz", size)}}
+
+
+def _node_row(node: dict[str, Any], versions: dict[str, Any]) -> dict[str, Any]:
+    row = compact_node_state(node_state(node, versions))
+    if node.get("type") == "primitive":
+        primitive = _primitive_size(node)
+        if primitive:
+            row["primitive"] = primitive
+    return row
+
+
+def _state(snapshot: dict[str, Any], node_ids: list[str]) -> dict[str, Any]:
+    versions = snapshot.get("entityVersions") or {}
+    ids = set(affected_nodes(snapshot, node_ids))
+    return {
+        "sceneSequence": snapshot.get("sceneSequence"),
+        "nodes": [_node_row(node, versions)
+                  for node in snapshot["document"]["content"]["nodes"] if node["id"] in ids],
+        "geometry": compact_geometry(check_primitive_geometry(snapshot["document"])),
+    }
+
+
+def _commit(directory: str, before: dict[str, Any], staged: dict[str, Any], deleted_curves: set[str], *,
+            stem: str, dry_run: bool) -> tuple[dict[str, Any], dict[str, Any], dict[str, Any], int]:
+    try:
+        operations, old, new = compile_operations(before, staged, deleted_curves)
+    except ValueError as exc:
+        raise LocalProjectError("BATCH_TOO_LARGE", str(exc)) from exc
+    if operations:
+        result = apply_operations(directory, operations, batch_id=new_scene_operation_id(stem), dry_run=dry_run)
+    else:
+        project = open_project(directory)
+        result = {**base_result(project), "dryRun": dry_run, "strictVersions": False, "operationCount": 0,
+                  "accepted": [], "warnings": [], "entityVersions": project.store.entity_versions()}
+    return result, old, new, len(operations)
+
+
+def _library_entry(catalog: list[dict[str, Any]], kind: str, library_id: str) -> dict[str, Any]:
+    return find_any_asset(catalog, library_id, "character" if kind == "characters" else "prop")
+
+
+def check_node_spec(spec: dict[str, Any], invalid_code: str = "NODE_BATCH_INVALID") -> None:
+    error = schema_error(NODE_BATCH_SCHEMA, spec)
+    if error:
+        raise LocalProjectError(invalid_code, f"{error}; nothing was written")
+
+
+def stage_node_changes(project: Any, spec: dict[str, Any]):
+    """Stage validated ``changes`` on a copy: ``(before, staged, deleted_curves, expanded)``."""
+    before = project.store.assemble()
+    check_scene_sequence(spec, before["sceneSequence"])
+    expanded = expand_changes(spec["changes"])
+    if len(expanded) > BATCH_OPERATION_LIMIT:
+        raise LocalProjectError("NODE_BATCH_INVALID", f"at most {BATCH_OPERATION_LIMIT} changes after repeat expansion")
+    staged = copy.deepcopy(before)
+    stager = _Stager(staged, "NODE_BATCH_REJECTED")
+    catalog: list[dict[str, Any]] | None = None
+    deleted_curves: set[str] = set()
+    present = {node["id"] for node in before["document"]["content"]["nodes"]}
+    for index, change in enumerate(expanded):
+        action, node_id = change["action"], change["nodeId"]
+        try:
+            if "view" in change and any(key in change for key in ("position", "rotation", "distance", "subjectNodeId")):
+                raise ValueError("CAMERA_VIEW_CONFLICT: use view with fov; omit position, rotation, distance and "
+                                 "subjectNodeId")
+            if "position" in change and "distance" in change:
+                raise ValueError("CAMERA_POSITION_DISTANCE_CONFLICT: use view or distance, not both")
+            if action.startswith("add_"):
+                if node_id in present:
+                    raise ValueError(f"NODE_ALREADY_EXISTS:{node_id}")
+                present.add(node_id)
+            elif node_id not in present:
+                raise ValueError(f"NODE_NOT_FOUND:{node_id}")
+            else:
+                existing = next((node for node in staged["document"]["content"]["nodes"] if node["id"] == node_id), None)
+                if existing and existing.get("locked"):
+                    raise ValueError(f"NODE_LOCKED:{node_id}")
+            if action == "delete":
+                deleted_curves.update(stager.direct(lambda: stage_delete(staged, node_id)))
+                present.discard(node_id)
+                continue
+            if action == "add_primitive":
+                primitive = change["primitive"]
+                if primitive["kind"] == "CylinderGeometry" and not any(
+                        primitive["parameters"][key] > 0 for key in ("radiusTop", "radiusBottom")):
+                    raise ValueError("CYLINDER_RADIUS_REQUIRED")
+                node = normalize_node({"id": node_id, "type": "primitive", "name": change.get("name", node_id),
+                                       "primitive": primitive})
+                stager.direct(lambda: staged["document"]["content"]["nodes"].append(node))
+            elif action == "add_library":
+                if catalog is None:
+                    catalog = asset_catalog(project.paths)
+                try:
+                    entry = _library_entry(catalog, change["kind"], change["libraryId"])
+                except LocalProjectError as exc:
+                    raise ValueError(f"ASSET_NOT_FOUND:{change['libraryId']}") from exc
+                stager.intent(index, node_id, {
+                    "type": "add-character" if change["kind"] == "characters" else "add-prop",
+                    "nodeId": node_id, "libraryId": entry["id"],
+                    "name": change.get("name") or entry.get("name") or node_id, "modelUrl": entry["key"]})
+            elif action == "add_camera":
+                subject_id = change.get("subjectNodeId") or (change.get("view") or {}).get("subjectNodeId")
+                stager.intent(index, node_id, {"type": "add-camera", "nodeId": node_id, "presetId": change["presetId"],
+                                               **({"subjectNodeId": subject_id} if subject_id else {})})
+            patch = {key: change[key] for key in ("name", "position", "rotation", "scale") if key in change}
+            if patch:
+                stager.intent(index, node_id, {"type": "patch-transform", "nodeId": node_id, **patch})
+            if "view" in change:
+                stager.direct(lambda: apply_camera_view(staged["document"], node_id, change["view"]))
+            for field, kind in (("fov", "set-fov"), ("distance", "set-distance")):
+                if field in change:
+                    stager.intent(index, node_id, {"type": kind, "cameraNodeId": node_id, field: change[field]})
+        except ValueError as exc:
+            reason = str(exc)
+            code = next((code for prefix, code in _MISSING_REFERENCE.items() if reason.startswith(prefix)),
+                        "NODE_BATCH_REJECTED")
+            raise _reject(code, index, node_id, reason) from exc
+    stager.flush()
+    return before, staged, deleted_curves, expanded
+
+
+def node_batch(directory: str, spec_path: str, *, dry_run: bool = False) -> dict[str, Any]:
+    spec = load_spec(spec_path, "NODE_BATCH_INVALID")
+    check_node_spec(spec)
+    before, staged, deleted_curves, expanded = stage_node_changes(open_project(directory), spec)
+    result, old, new, count = _commit(directory, before, staged, deleted_curves, stem="nodes", dry_run=dry_run)
+    created = [key for key in new if key not in old]
+    updated = [key for key in new if key in old and old[key] != new[key]]
+    after = {**staged, "sceneSequence": result["sceneSequence"], "entityVersions": result["entityVersions"]}
+    return {**result, "createdIds": created, "updatedIds": updated, "deletedIds": [key for key in old if key not in new],
+            "changeCount": len(spec["changes"]), "expandedChangeCount": len(expanded), "operationCount": count,
+            "state": _state(after, created + updated)}
+
+
+def _pose_payload(entry: dict[str, Any]) -> dict[str, Any]:
+    path = Path(entry["path"])
+    if path.stat().st_size > POSE_FILE_LIMIT:
+        raise LocalProjectError("POSE_ASSET_INVALID", f"{entry['id']}: pose file larger than 1 MiB")
+    try:
+        pose = json.loads(path.read_text(encoding="utf-8"))
+    except (UnicodeDecodeError, json.JSONDecodeError) as exc:
+        raise LocalProjectError("POSE_ASSET_INVALID", f"{entry['id']}: not JSON") from exc
+
+    def vector(value, length):
+        return isinstance(value, list) and len(value) == length and all(
+            type(item) in (int, float) and math.isfinite(item) for item in value)
+    bones = pose.get("bones") if isinstance(pose, dict) else None
+    if (not isinstance(bones, dict) or not 1 <= len(bones) <= 256
+            or not vector(pose.get("hips"), 3)
+            or not all(isinstance(name, str) and vector(value, 4) and sum(x * x for x in value) > 0.01
+                       for name, value in bones.items())):
+        raise LocalProjectError("POSE_ASSET_INVALID", f"{entry['id']}: needs hips [x,y,z] and 1-256 bone quaternions")
+    return pose
+
+
+def pose_batch(directory: str, spec: dict[str, Any], *, dry_run: bool = False) -> dict[str, Any]:
+    error = next(Draft7Validator(POSE_BATCH_SCHEMA).iter_errors(spec), None)
+    if error:
+        path = list(error.path)
+        index = path[1] if len(path) > 1 and path[0] == "items" and isinstance(path[1], int) else None
+        raise LocalProjectError("POSE_BATCH_INVALID", f"{'.'.join(map(str, path))}: {error.message[:450]}; "
+                                "nothing was written", details={"index": index} if index is not None else None)
+    ids = [item["nodeId"] for item in spec["items"]]
+    repeated = next((index for index, node_id in enumerate(ids) if node_id in ids[:index]), None)
+    if repeated is not None:
+        raise LocalProjectError("POSE_BATCH_INVALID", f"items.{repeated}: {ids[repeated]} appears twice; each "
+                                "character may appear once per batch",
+                                details={"index": repeated, "nodeId": ids[repeated]})
+    project = open_project(directory)
+    before = project.store.assemble()
+    check_scene_sequence(spec, before["sceneSequence"])
+    staged = copy.deepcopy(before)
+    document = staged["document"]
+    clips = document["content"].get("timeline", {}).get("animation", {}).get("motionClips", [])
+    catalog = asset_catalog(project.paths)
+    items = []
+    for index, item in enumerate(spec["items"]):
+        where = {"index": index, "nodeId": item["nodeId"]}
+        try:
+            node = node_in(document, item["nodeId"])
+        except ValueError as exc:
+            raise LocalProjectError("DIRECTOR_NODE_NOT_FOUND", f"items.{index}: no node {item['nodeId']}",
+                                    details=where) from exc
+        if node.get("type") != "character":
+            raise LocalProjectError("POSE_TARGET_INVALID", f"items.{index}: {item['nodeId']} is not a character",
+                                    details=where)
+        if node.get("locked"):
+            raise _reject("POSE_BATCH_REJECTED", index, item["nodeId"], "NODE_LOCKED")
+        if any((clip.get("target") or {}).get("nodeId") == item["nodeId"] for clip in clips):
+            raise _reject("POSE_BATCH_REJECTED", index, item["nodeId"],
+                          "POSE_BLOCKED_BY_MOTION: delete the character's motion clips first")
+        try:
+            entry = find_asset(catalog, "pose", item.get("poseId") or item["libraryId"])
+        except LocalProjectError as exc:
+            raise LocalProjectError(exc.code, f"items.{index}: {exc}",
+                                    details={**where, "poseId": item.get("poseId") or item["libraryId"]}) from exc
+        items.append({"nodeId": item["nodeId"], "libraryId": entry["id"], "pose": _pose_payload(entry)})
+    mapping = local_asset_map(catalog)
+    check_render_assets({"content": {"nodes": [node_in(document, node_id) for node_id in ids]}}, mapping)
+    compiled = director_cli("apply-library-poses", {"document": document, "items": items,
+                                                    "publicAssetBase": "", "localAssets": mapping})
+    results = compiled.get("results") or []
+    if len(results) != len(items):
+        raise LocalProjectError("RENDER_RESULT_INVALID", "apply-library-poses returned the wrong number of results")
+    poses = []
+    for item, compiled_pose in zip(items, results):
+        node_in(document, item["nodeId"])["character"]["animation"] = compiled_pose["animation"]
+        poses.append({"nodeId": item["nodeId"], "poseId": item["libraryId"], "pose": compiled_pose.get("pose")})
+    stager = _Stager(staged, "POSE_BATCH_REJECTED")
+    for index, item in enumerate(spec["items"]):
+        patch = {key: item[key] for key in ("position", "rotation", "scale") if key in item}
+        if patch:
+            stager.intent(index, item["nodeId"], {"type": "patch-transform", "nodeId": item["nodeId"], **patch})
+    stager.flush()
+    result, old, new, count = _commit(directory, before, staged, set(), stem="poses", dry_run=dry_run)
+    after = {**staged, "sceneSequence": result["sceneSequence"], "entityVersions": result["entityVersions"]}
+    return {**result, "poses": poses, "updatedIds": [key for key in new if old.get(key) != new[key]],
+            "operationCount": count, "state": _state(after, ids)}

topview_3d_cli/local_errors.py

@@ -0,0 +1,104 @@
+"""Stable error codes and exit codes of the local ``topview-3d-cli`` CLI.
+
+Keep this table in sync with ``docs/topview-3d-cli.md``; ``test_local_cli`` enforces it.
+"""
+from __future__ import annotations
+
+from typing import Any
+
+EXIT_OK = 0
+EXIT_FAILED = 1
+EXIT_INVALID_INPUT = 2
+
+# code -> (exit code, meaning)
+ERROR_CODES: dict[str, tuple[int, str]] = {
+    # Command line and input files
+    "USAGE_INVALID": (2, "Unknown command, missing argument or bad option."),
+    "PROJECT_NOT_INITIALIZED": (2, "The directory has no .topview3d project; run `project init`."),
+    "PROJECT_EXISTS": (2, "`project init` target already contains a project; pass --force to replace it."),
+    "OPERATIONS_NOT_FOUND": (2, "The operations file does not exist."),
+    "OPERATIONS_JSON_INVALID": (2, "The operations file is not JSON or not an operation batch."),
+    "RENDER_PAYLOAD_INVALID": (2, "The render payload is not a JSON object of frames/width/height/cameraNodeId/publicAssetBase."),
+    "ASSET_IMPORT_INVALID": (2, "`asset import` got a bad kind, id, file type, cover or pose JSON."),
+    "ASSET_NOT_FOUND": (2, "No asset with that id and kind in the local manifests (in a batch, details.index)."),
+    "POSE_TARGET_INVALID": (2, "`pose apply` / `pose batch` target is not a character."),
+    "INPUT_NOT_FOUND": (2, "A spec, plan, views or checkpoint file does not exist."),
+    "NODE_BATCH_INVALID": (2, "`node batch` spec is not JSON or fails the change schema."),
+    "POSE_BATCH_INVALID": (2, "`pose batch` spec fails its schema or repeats a character."),
+    "BATCH_TOO_LARGE": (2, "The edit compiles to more than 64 operations; split it."),
+    "PLAN_INVALID": (2, "`evaluate` plan is not JSON or not exactly one of changes/operations."),
+    "VIEWS_INVALID": (2, "`inspect views` spec fails its schema, or the primary camera is not among the views."),
+    "CAMERA_REQUIRED": (2, "A --camera / cameraNodeId is not a camera node, or the scene has no camera."),
+    "CAMERA_NOT_FOUND": (2, "A --camera / cameraNodeId names no node in the scene."),
+    "DANGLING_REFERENCE": (2, "The batch would leave a clip, fcurves or node reference pointing at a missing node."),
+    "ENTITY_NOT_FOUND": (2, "Delete targets an entity that never existed."),
+    "DIRECTOR_NODE_NOT_FOUND": (2, "A referenced node does not exist (the message names it; batches add details.index)."),
+    "DOCUMENT_ENTITY_NOT_FOUND": (2, "`document get --entity` found no node, clip or fcurves shard with that id."),
+    "RENDER_NOT_FOUND": (2, "No such render run or frame image in .topview3d/renders."),
+    "BOM_CHECKPOINT_INVALID": (2, "`bom checkpoint` patch fails its schema or repeats/conflicts ids."),
+    "BOM_TOO_LARGE": (2, "The merged BOM would exceed 64 KiB."),
+    # Operation shape (nothing is applied)
+    "INVALID_DIRECTOR_BATCH": (2, "Batch must contain 1..64 operations."),
+    "INVALID_DIRECTOR_OPERATION": (2, "Operation is not an object or has a bad baseSequence/expectedEntityVersion."),
+    "INVALID_OPERATION_ID": (2, "operationId must match [A-Za-z0-9_-]{1,128}."),
+    "UNSUPPORTED_DIRECTOR_KIND": (2, "kind is not one of the seven director.* kinds."),
+    "INVALID_DIRECTOR_PAYLOAD": (2, "payload is not an object or has missing/extra fields."),
+    "INVALID_ENTITY_ID": (2, "entityId is missing, malformed, or not fcurves__<nodeId> for fcurves kinds."),
+    "INVALID_DIRECTOR_SCENE": (2, "scene.set payload is invalid (entityId, nodes/clips in content, type/version)."),
+    "INVALID_DIRECTOR_NODE": (2, "Node fails normalization/schema or node.id != entityId."),
+    "INVALID_DIRECTOR_TRANSFORM": (2, "Node transform is not position/rotation/scale of finite x/y/z."),
+    "INVALID_DIRECTOR_CLIP": (2, "Clip kind, id, frame range or camera motion.curves is invalid."),
+    "INVALID_DIRECTOR_FCURVES": (2, "fcurves payload is not version 1 compact-v1 or fails its schema."),
+    "INVALID_DIRECTOR_DOCUMENT": (2, "The batch would produce a document that fails the director schema."),
+    # State conflicts (nothing is applied)
+    "ENTITY_VERSION_CONFLICT": (1, "expectedEntityVersion does not match the entity's current version."),
+    "ENTITY_DELETED": (1, "Target entity was deleted (strict mode also forbids recreating it)."),
+    "ENTITY_TYPE_CONFLICT": (1, "entityId already belongs to another entity type."),
+    "SEQUENCE_GAP": (1, "baseSequence is negative or ahead of the project's sceneSequence."),
+    "OPERATION_KEY_REUSED": (1, "operationId was already accepted with a different body."),
+    "SCENE_SEQUENCE_CONFLICT": (1, "expectedSceneSequence does not match the project; re-read and re-plan."),
+    "DIRECTOR_NODE_LOCKED": (1, "`node delete` target is locked."),
+    "NODE_BATCH_REJECTED": (1, "One `node batch` change cannot apply to the current scene (details: index, nodeId, reason)."),
+    "POSE_BATCH_REJECTED": (1, "A pose target is locked or still has motion clips (details: index, nodeId, reason)."),
+    "BOM_REVISION_CONFLICT": (1, "expectedBomRevision does not match the stored BOM."),
+    "BOM_REVIEW_EVIDENCE_MISSING": (1, "modelReview needs current `inspect views` evidence with matching image sha256."),
+    "DIRECTOR_LAST_CAMERA_REQUIRED": (1, "The last camera cannot be deleted."),
+    "DIRECTOR_DELETE_CHILDREN_FIRST": (1, "Delete the node's children first."),
+    "DIRECTOR_DELETE_TOO_MANY_DEPENDENCIES": (1, "Cascading delete would exceed one 64-operation batch."),
+    # Project state and runtime
+    "PROJECT_JSON_INVALID": (1, "A project state file is corrupt."),
+    "PROJECT_FORMAT_UNSUPPORTED": (1, "The project was written by a newer CLI (schemaVersion too high)."),
+    "DOCUMENT_INVALID": (1, "`document validate` found schema errors or references to missing nodes."),
+    "BUILDER_PACKAGE_UNREADABLE": (1, "editor/packages/builder/package.json is missing or has no version."),
+    "ASSET_MANIFEST_INVALID": (1, "An asset manifest is corrupt or lists a path outside its root."),
+    "POSE_ASSET_INVALID": (1, "A pose file is larger than 1 MiB or lacks hips and 1-256 bone quaternions."),
+    "BOM_JSON_INVALID": (1, ".topview3d/bom.json is corrupt; fix or delete it."),
+    "RENDER_IMAGE_INVALID": (1, "A render image is not a PNG or no longer matches the sha256 in render.json."),
+    "ASSET_FILE_MISSING": (1, "A manifest entry points to a file that does not exist."),
+    "ASSET_NOT_AVAILABLE": (1, "A character or prop model in the document has no local asset (see details)."),
+    "RUNTIME_MISSING": (1, "The renderer runtime is missing (incomplete install, or an unbuilt checkout)."),
+    "NODE_UNAVAILABLE": (1, "`node` is not on PATH."),
+    "NPM_UNAVAILABLE": (1, "`browser ensure` needs `npm` (it ships with Node.js)."),
+    "PLAYWRIGHT_INSTALL_FAILED": (1, "`browser ensure` could not install the pinned Playwright into the user cache."),
+    "BROWSER_INSTALL_FAILED": (1, "`browser ensure` could not install or launch Chromium."),
+    "BROWSER_NOT_INSTALLED": (1, "Playwright or Chromium is missing; run `topview-3d-cli browser ensure`."),
+    "RENDER_FAILED": (1, "The Node renderer exited with an error."),
+    "RENDERER_FAILED": (1, "A non-render Node renderer command (for example pose compilation) failed."),
+    "RENDER_RESULT_MISSING": (1, "The Node renderer printed no result."),
+    "RENDER_RESULT_INVALID": (1, "The Node renderer printed a non-JSON result."),
+    "DOCTOR_FAILED": (1, "Plain `doctor` found a missing or outdated dependency (`doctor --json` always exits 0)."),
+    "INTERNAL_ERROR": (1, "Unexpected failure; the message carries the exception."),
+}
+
+
+def exit_code_for(code: str) -> int:
+    return ERROR_CODES.get(code, (EXIT_FAILED, ""))[0]
+
+
+class LocalProjectError(RuntimeError):
+    """A stable, user-facing local project error (codes: ``ERROR_CODES``)."""
+
+    def __init__(self, code: str, message: str | None = None, *, details: Any = None):
+        self.code = code
+        self.details = details
+        super().__init__(message or code)