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

topview_3d_cli/local_read.py

@@ -0,0 +1,139 @@
+"""Read-only views: document outline and entities, render runs and their PNGs, camera presets."""
+from __future__ import annotations
+
+import hashlib
+import json
+from pathlib import Path
+from typing import Any
+
+from topview_3d_cli.director_document import get_director_entity, summarize_director_snapshot
+from topview_3d_cli.local_errors import LocalProjectError
+from topview_3d_cli.local_project import base_result, document_get, open_project
+from topview_3d_cli.renderer import director_cli
+
+ENTITY_TYPES = ("node", "clip", "fcurves")
+PNG_SIGNATURE = b"\x89PNG\r\n\x1a\n"
+
+
+def document_summary(directory: str) -> dict[str, Any]:
+    project = open_project(directory)
+    summary = summarize_director_snapshot(project.store.assemble())
+    summary["message"] = ("Outline only: curves and full nodes omitted. "
+                          "Use `document get <dir> --entity <id>` for one node, clip or fcurves shard.")
+    return {**base_result(project), "summary": summary}
+
+
+def document_entity(directory: str, entity_id: str, *, entity_type: str | None = None,
+                    include_curves: bool = False) -> dict[str, Any]:
+    """One node, clip or ``fcurves__<nodeId>`` shard; the type is inferred when omitted."""
+    project = open_project(directory)
+    snapshot = project.store.assemble()
+    if entity_type:
+        types = [entity_type]
+    elif entity_id.startswith("fcurves__"):
+        types = ["fcurves"]
+    else:
+        types = ["node", "clip", "fcurves"]
+    for candidate in types:
+        try:
+            found = get_director_entity(snapshot, candidate, entity_id, include_curves=include_curves)
+        except ValueError:
+            continue
+        key = found.get("entityId", entity_id)
+        return {**base_result(project), **found, "entityId": key,
+                "entityVersion": snapshot["entityVersions"].get(key)}
+    raise LocalProjectError("DOCUMENT_ENTITY_NOT_FOUND", f"no {' or '.join(types)} {entity_id!r} in the document")
+
+
+def document_view(directory: str, *, summary: bool, entity: str | None, entity_type: str | None,
+                  include_curves: bool) -> dict[str, Any]:
+    if summary and entity:
+        raise LocalProjectError("USAGE_INVALID", "use either --summary or --entity")
+    if entity_type and not entity:
+        raise LocalProjectError("USAGE_INVALID", "--type needs --entity")
+    if summary:
+        return document_summary(directory)
+    if entity:
+        return document_entity(directory, entity, entity_type=entity_type, include_curves=include_curves)
+    return document_get(directory)
+
+
+def _read_run(run_dir: Path) -> dict[str, Any] | None:
+    try:
+        manifest = json.loads((run_dir / "render.json").read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return None
+    return manifest if isinstance(manifest, dict) else None
+
+
+def _runs(renders: Path) -> list[tuple[Path, dict[str, Any]]]:
+    rows = []
+    for run_dir in renders.iterdir() if renders.is_dir() else []:
+        manifest = _read_run(run_dir) if run_dir.is_dir() else None
+        if manifest:
+            rows.append((run_dir, manifest))
+    rows.sort(key=lambda row: (str(row[1].get("createdAt") or ""), row[0].name))
+    return rows
+
+
+def renders_list(directory: str) -> dict[str, Any]:
+    project = open_project(directory)
+    sequence = project.store.scene_sequence
+    runs = [{
+        "runId": run_dir.name,
+        "createdAt": manifest.get("createdAt"),
+        "cameraNodeId": manifest.get("cameraNodeId"),
+        "sceneSequence": manifest.get("sceneSequence"),
+        "stale": manifest.get("sceneSequence") != sequence,
+        "frames": [frame.get("frame") for frame in manifest.get("frames") or []],
+        "width": manifest.get("width"),
+        "height": manifest.get("height"),
+        "blank": manifest.get("blank"),
+        "blockedRequests": len(manifest.get("blockedRequests") or []),
+    } for run_dir, manifest in _runs(project.paths.renders)]
+    return {**base_result(project), "count": len(runs), "runs": runs}
+
+
+def renders_show(directory: str, run_id: str | None = None, *, frame: int | None = None) -> dict[str, Any]:
+    """Path and checksum of one PNG inside the project (the contact sheet unless --frame)."""
+    project = open_project(directory)
+    runs = _runs(project.paths.renders)
+    if run_id is None:
+        if not runs:
+            raise LocalProjectError("RENDER_NOT_FOUND", "the project has no renders yet; run `topview-3d-cli render`")
+        run_dir, manifest = runs[-1]
+    else:
+        run_dir, manifest = next(((path, data) for path, data in runs if path.name == run_id), (None, None))
+        if run_dir is None:
+            raise LocalProjectError("RENDER_NOT_FOUND", f"no render run {run_id!r}")
+    if frame is None:
+        entry = manifest.get("contactSheet") or {}
+    else:
+        entry = next((item for item in manifest.get("frames") or [] if item.get("frame") == frame), None)
+        if entry is None:
+            raise LocalProjectError("RENDER_NOT_FOUND", f"run {run_dir.name} has no frame {frame}")
+    path = (run_dir / str(entry.get("file") or "")).resolve()
+    if not entry.get("file") or path.parent != run_dir.resolve() or not path.is_file():
+        raise LocalProjectError("RENDER_NOT_FOUND", f"{run_dir.name}: image file missing")
+    data = path.read_bytes()
+    digest = hashlib.sha256(data).hexdigest()
+    if not data.startswith(PNG_SIGNATURE) or (entry.get("sha256") and entry["sha256"] != digest):
+        raise LocalProjectError("RENDER_IMAGE_INVALID", f"{path} is not the PNG recorded in render.json")
+    return {
+        **base_result(project),
+        "runId": run_dir.name,
+        "kind": "contactSheet" if frame is None else "frame",
+        "frame": frame,
+        "path": str(path),
+        "mimeType": "image/png",
+        "sizeBytes": len(data),
+        "sha256": digest,
+        "cameraNodeId": manifest.get("cameraNodeId"),
+        "sceneSequence": manifest.get("sceneSequence"),
+        "stale": manifest.get("sceneSequence") != project.store.scene_sequence,
+    }
+
+
+def camera_presets() -> dict[str, Any]:
+    listed = director_cli("list-camera-presets")
+    return {"ok": True, "presets": listed.get("presets", [])}

topview_3d_cli/local_render.py

@@ -0,0 +1,97 @@
+"""Render runs under ``.topview3d/renders/<runId>`` with the Node renderer and local model files."""
+from __future__ import annotations
+
+import hashlib
+import json
+import shutil
+import uuid
+from pathlib import Path
+from typing import Any
+
+from topview_3d_cli.local_assets import asset_catalog, check_render_assets, local_asset_map
+from topview_3d_cli.local_errors import LocalProjectError
+from topview_3d_cli.local_project import CLI_VERSION, Project, open_project
+from topview_3d_cli.renderer import director_cli
+from topview_3d_cli.runtime import builder_version
+
+# Console noise from the headless page, not scene problems: the builder's two bundles each import
+# Mediabunny, and SwiftShader reports ReadPixels stalls.
+BENIGN_RENDER_WARNINGS = ("Mediabunny was loaded twice", "GPU stall due to ReadPixels")
+RENDER_PAYLOAD_KEYS = {"frames", "width", "height", "cameraNodeId", "publicAssetBase"}
+
+
+def document_sha256(document: dict[str, Any]) -> str:
+    canonical = json.dumps(document, ensure_ascii=False, sort_keys=True, separators=(",", ":"))
+    return hashlib.sha256(canonical.encode("utf-8")).hexdigest()
+
+
+def require_camera(document: dict[str, Any], camera_id: str | None) -> str:
+    """The camera to use: ``camera_id`` (which must exist and be a camera) or the document's default."""
+    nodes = document["content"]["nodes"]
+    if camera_id:
+        node = next((item for item in nodes if item["id"] == camera_id), None)
+        if node is None:
+            raise LocalProjectError("CAMERA_NOT_FOUND", f"no node {camera_id!r}; cameras: "
+                                    f"{[item['id'] for item in nodes if item.get('type') == 'camera']}",
+                                    details={"cameraNodeId": camera_id})
+        if node.get("type") != "camera":
+            raise LocalProjectError("CAMERA_REQUIRED", f"{camera_id} is a {node.get('type')}, not a camera",
+                                    details={"cameraNodeId": camera_id})
+        return camera_id
+    active = document["content"].get("activeShotCameraNodeId")
+    if any(item["id"] == active and item.get("type") == "camera" for item in nodes):
+        return active
+    fallback = next((item["id"] for item in nodes if item.get("type") == "camera"), None)
+    if fallback is None:
+        raise LocalProjectError("CAMERA_REQUIRED", "the scene has no camera; add one with `node batch` add_camera")
+    return fallback
+
+
+def render_snapshot(project: Project, assembled: dict[str, Any], options: dict[str, Any]) -> dict[str, Any]:
+    """One render run of ``assembled``; the run directory is removed again when rendering fails."""
+    body: dict[str, Any] = {"frames": [0], **options}
+    mapping = local_asset_map(asset_catalog(project.paths))
+    warnings = check_render_assets(assembled["document"], mapping, str(body.get("publicAssetBase") or ""))
+    run_id = uuid.uuid4().hex
+    output_dir = project.paths.renders / run_id
+    body.update({
+        "document": assembled["document"],
+        "fcurves": assembled["fcurves"],
+        "sceneSequence": assembled["sceneSequence"],
+        "outputDir": str(output_dir),
+        "publicAssetBase": body.get("publicAssetBase") or "",
+        "localAssets": mapping,
+        "metadata": {
+            "revision": project.metadata.get("revision", 0),
+            "documentSha256": document_sha256(assembled["document"]),
+            "builderVersion": builder_version(),
+            "cliVersion": CLI_VERSION,
+        },
+    })
+    try:
+        result = director_cli("render-frames", body)
+    except LocalProjectError:
+        shutil.rmtree(output_dir, ignore_errors=True)
+        raise
+    if isinstance(result.get("warnings"), list):
+        result["warnings"] = [item for item in result["warnings"]
+                              if not any(marker in str(item) for marker in BENIGN_RENDER_WARNINGS)]
+    return {"ok": True, "runId": run_id, **body["metadata"], "sceneSequence": assembled["sceneSequence"],
+            "warnings": warnings, "result": result}
+
+
+def render(directory: str, payload_path: str | None = None) -> dict[str, Any]:
+    project = open_project(directory)
+    options: dict[str, Any] = {}
+    if payload_path:
+        try:
+            supplied = json.loads(Path(payload_path).read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError) as exc:
+            raise LocalProjectError("RENDER_PAYLOAD_INVALID", str(exc)) from exc
+        if not isinstance(supplied, dict) or set(supplied) - RENDER_PAYLOAD_KEYS:
+            raise LocalProjectError("RENDER_PAYLOAD_INVALID",
+                                    f"payload must be an object with keys from {sorted(RENDER_PAYLOAD_KEYS)}")
+        options.update(supplied)
+    assembled = project.store.assemble()
+    options["cameraNodeId"] = require_camera(assembled["document"], options.get("cameraNodeId"))
+    return render_snapshot(project, assembled, options)

topview_3d_cli/node_batch.py

@@ -0,0 +1,299 @@
+"""Typed, ordered node changes (``node batch``) and their compilation to one operation batch.
+
+Staging runs on a copy of the stored snapshot, so a rejected change writes nothing.
+"""
+from __future__ import annotations
+
+import copy
+from typing import Any
+
+from jsonschema import Draft7Validator
+
+from topview_3d_cli.director_document import apply_scene_set, fcurve_node_id, new_scene_operation_id
+from topview_3d_cli.director_static import delete_node_operations
+
+CLIP_ARRAYS = ("cameraMotionClips", "motionClips", "pathMotionClips")
+BATCH_OPERATION_LIMIT = 64
+
+
+def obj(properties, required=()):
+    return {"type": "object", "properties": properties, "required": list(required),
+            "additionalProperties": False}
+
+
+def batch_schema(*, require_sequence: bool = True) -> dict[str, Any]:
+    identifier = {"type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$"}
+    number = {"type": "number"}
+    positive = {"type": "number", "exclusiveMinimum": 0}
+    vector = {**obj({axis: number for axis in "xyz"}), "minProperties": 1}
+    scale = {**obj({axis: positive for axis in "xyz"}), "minProperties": 1}
+    transform = {"position": vector, "rotation": vector, "scale": scale}
+    point = obj({axis: number for axis in "xyz"}, "xyz")
+    view = {"oneOf": [
+        obj({"mode": {"const": "world"}, "position": point, "target": point},
+            ("mode", "position", "target")),
+        obj({"mode": {"const": "subject"}, "subjectNodeId": identifier,
+             "offset": point, "targetOffset": point},
+            ("mode", "subjectNodeId", "offset", "targetOffset")),
+    ]}
+    name = {"type": "string", "minLength": 1, "maxLength": 128, "pattern": "\\S"}
+    camera = {
+        "fov": {"type": "number", "minimum": 12, "maximum": 120},
+        "distance": {"type": "number", "minimum": 0.1, "maximum": 200},
+        "view": view,
+    }
+    geometry = []
+    for kind, dimensions in (
+        ("BoxGeometry", ("width", "height", "depth")),
+        ("SphereGeometry", ("radius",)),
+        ("CylinderGeometry", ("radiusTop", "radiusBottom", "height")),
+        ("ConeGeometry", ("radius", "height")),
+    ):
+        parameters = {key: positive for key in dimensions}
+        if kind == "CylinderGeometry":
+            parameters.update({key: {"type": "number", "minimum": 0}
+                               for key in ("radiusTop", "radiusBottom")})
+        if kind in {"CylinderGeometry", "ConeGeometry"}:
+            parameters["radialSegments"] = {"type": "integer", "minimum": 3, "maximum": 128}
+        geometry.append(obj({"kind": {"const": kind}, "parameters": obj(parameters, dimensions)},
+                            ("kind", "parameters")))
+
+    def action(kind, fields, required=(), description=""):
+        schema = obj({"action": {"const": kind}, "nodeId": identifier, **fields},
+                     ("action", "nodeId", *required))
+        if description:
+            schema["description"] = description
+        return schema
+    return obj({
+        "expectedSceneSequence": {"type": "integer", "minimum": 0},
+        "changes": {"type": "array", "minItems": 1, "maxItems": 64, "items": {"oneOf": [
+            action("add_primitive", {"name": name, "primitive": {"oneOf": geometry}, **transform},
+                   ("primitive",), "Create a new primitive. Requires primitive geometry."),
+            action("add_library", {"kind": {"enum": ["characters", "props"]},
+                   "libraryId": identifier, "name": name, **transform}, ("kind", "libraryId"),
+                   "Create a new character or prop from the asset library. Requires kind and libraryId."),
+            action("add_camera", {"presetId": name, "subjectNodeId": identifier,
+                   "name": name, **transform, **camera}, ("presetId",),
+                   "Create a new camera. Requires presetId. Do not use update to create cameras."),
+            {**action("update", {"name": name, **transform, **camera},
+                      description="Change an existing node: name, partial transform, fov, distance. "
+                      "Does not create nodes and does not accept presetId."),
+             "minProperties": 3},
+            action("delete", {}, description="Delete an existing node by nodeId."),
+            action("repeat_primitive", {
+                "name": name, "primitive": {"oneOf": geometry}, **transform,
+                "count": {"type": "integer", "minimum": 2, "maximum": 32},
+                "step": point,
+            }, ("primitive", "count", "step"),
+                   "Create regularly spaced primitive copies nodeId_1 through nodeId_count."),
+        ]}},
+    }, ("expectedSceneSequence", "changes") if require_sequence else ("changes",))
+
+
+BATCH_SCHEMA = batch_schema()
+
+
+def schema_error(schema: dict[str, Any], arguments: Any) -> str | None:
+    """First schema violation as ``path: message``, preferring the change's own action schema."""
+    error = next(Draft7Validator(schema).iter_errors(arguments), None)
+    if error is None:
+        return None
+    for index, change in enumerate(arguments.get("changes", []) if isinstance(arguments, dict) else []):
+        if not isinstance(change, dict):
+            continue
+        selected = next((item for item in schema["properties"]["changes"]["items"]["oneOf"]
+                         if item["properties"]["action"]["const"] == change.get("action")), None)
+        detail = next(Draft7Validator(selected).iter_errors(change), None) if selected else None
+        if detail and list(detail.path)[:1] == ["primitive"] and isinstance(change.get("primitive"), dict):
+            return f"changes.{index}.{_primitive_error(selected['properties']['primitive'], change['primitive'])}"
+        if detail:
+            return f"changes.{index}.{'.'.join(map(str, detail.path))}: {detail.message[:450]}"
+    return f"{'.'.join(map(str, error.path))}: {error.message[:450]}"
+
+
+def _primitive_error(schema: dict[str, Any], primitive: dict[str, Any]) -> str:
+    """Validate against the branch for ``primitive.kind`` so the message names the kind and field."""
+    branches = {branch["properties"]["kind"]["const"]: branch for branch in schema["oneOf"]}
+    kind = primitive.get("kind")
+    if kind not in branches:
+        return f"primitive.kind: {kind!r} is not one of {sorted(branches)}"
+    detail = next(Draft7Validator(branches[kind]).iter_errors(primitive), None)
+    if detail is None:
+        return f"primitive: invalid {kind}"
+    return f"primitive.{'.'.join(map(str, detail.path))}: {detail.message[:400]} ({kind} takes " \
+           f"{sorted(branches[kind]['properties']['parameters']['properties'])})"
+
+
+def expand_changes(changes: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    """``repeat_primitive`` becomes ``add_primitive`` for nodeId_1..nodeId_count."""
+    expanded = []
+    for change in changes:
+        if change["action"] != "repeat_primitive":
+            expanded.append(change)
+            continue
+        for copy_index in range(change["count"]):
+            expanded.append({
+                **{key: value for key, value in change.items() if key not in {"count", "step"}},
+                "action": "add_primitive",
+                "nodeId": f"{change['nodeId']}_{copy_index + 1}",
+                "position": {
+                    axis: change.get("position", {}).get(axis, 0) + copy_index * change["step"][axis]
+                    for axis in "xyz"
+                },
+            })
+    return expanded
+
+
+def stage_delete(snapshot: dict[str, Any], node_id: str) -> set[str]:
+    """Apply the cascading delete of ``node_id`` to a staged snapshot; return deleted fcurve ids."""
+    batch, _ = delete_node_operations(snapshot, node_id)
+    for operation in batch["operations"]:
+        kind, entity_id, payload = (operation[key] for key in ("kind", "entityId", "payload"))
+        content = snapshot["document"]["content"]
+        if kind == "director.node.delete":
+            content["nodes"] = [node for node in content["nodes"] if node["id"] != entity_id]
+        elif kind == "director.node.upsert":
+            content["nodes"] = [payload["node"] if node["id"] == entity_id else node for node in content["nodes"]]
+        elif kind == "director.clip.delete":
+            for key in CLIP_ARRAYS:
+                animation = content["timeline"]["animation"]
+                animation[key] = [clip for clip in animation.get(key, []) if clip["id"] != entity_id]
+        elif kind == "director.fcurves.delete":
+            curves = snapshot.get("fcurves") or {}
+            snapshot["fcurves"] = curves
+            curves.pop(entity_id, None)
+            if curves.get("encoding") == "compact-v1":
+                curves["fcurves"] = [c for c in curves.get("fcurves", []) if fcurve_node_id(c) != node_id]
+        elif kind == "director.scene.set":
+            snapshot["document"] = apply_scene_set(snapshot["document"], payload["scene"])
+    return {op["entityId"] for op in batch["operations"] if op["kind"] == "director.fcurves.delete"}
+
+
+def scene_fields(document: dict[str, Any]) -> dict[str, Any]:
+    content = copy.deepcopy(document["content"])
+    content.pop("nodes", None)
+    for key in CLIP_ARRAYS:
+        content.get("timeline", {}).get("animation", {}).pop(key, None)
+    return content
+
+
+def compile_operations(before: dict[str, Any], after: dict[str, Any], deleted_curves: set[str]):
+    """Diff two snapshots into director operations; returns (operations, old nodes, new nodes)."""
+    operations = []
+
+    def add(kind, entity_id, payload):
+        operations.append({"operationId": new_scene_operation_id("batch_node"),
+                           "baseSequence": before["sceneSequence"], "entityId": entity_id,
+                           "expectedEntityVersion": (before.get("entityVersions") or {}).get(entity_id),
+                           "kind": kind, "payload": payload})
+    old = {node["id"]: node for node in before["document"]["content"]["nodes"]}
+    new = {node["id"]: node for node in after["document"]["content"]["nodes"]}
+    for node_id, node in new.items():
+        if old.get(node_id) != node:
+            add("director.node.upsert", node_id, {"node": node})
+    for node_id in old.keys() - new.keys():
+        add("director.node.delete", node_id, {})
+    for key in CLIP_ARRAYS:
+        old_clips = before["document"]["content"]["timeline"]["animation"].get(key, [])
+        kept = {clip["id"] for clip in after["document"]["content"]["timeline"]["animation"].get(key, [])}
+        for clip in old_clips:
+            if clip["id"] not in kept:
+                add("director.clip.delete", clip["id"], {})
+    for entity_id in sorted(deleted_curves):
+        add("director.fcurves.delete", entity_id, {})
+    old_scene, new_scene = scene_fields(before["document"]), scene_fields(after["document"])
+    delta = {key: value for key, value in new_scene.items() if old_scene.get(key) != value}
+    if delta:
+        add("director.scene.set", "director", {"scene": {"content": {"version": 1, **delta}}})
+    if len(operations) > BATCH_OPERATION_LIMIT:
+        raise ValueError("DIRECTOR_BATCH_OPERATION_LIMIT: split at dependency boundaries (including delete cleanup)")
+    return operations, old, new
+
+
+def affected_nodes(snapshot: dict[str, Any], node_ids) -> list[str]:
+    """Include children and bound cameras whose world state follows edited nodes."""
+    nodes = snapshot["document"]["content"]["nodes"]
+    affected = set(node_ids)
+    while True:
+        previous = len(affected)
+        for node in nodes:
+            camera = node.get("camera") or {}
+            if (node.get("parentId") in affected
+                    or (camera.get("subject") or {}).get("nodeId") in affected
+                    or (camera.get("lookAtTarget") or {}).get("nodeId") in affected):
+                affected.add(node["id"])
+            if node["id"] in affected:
+                affected.update(node.get("children") or [])
+                if node.get("parentId"):
+                    affected.add(node["parentId"])
+        if len(affected) == previous:
+            return [node["id"] for node in nodes if node["id"] in affected]
+
+
+def compact_numbers(value, ndigits=3):
+    if isinstance(value, bool) or value is None:
+        return value
+    if isinstance(value, float):
+        return round(value, ndigits)
+    if isinstance(value, list):
+        return [compact_numbers(item, ndigits) for item in value]
+    if isinstance(value, dict):
+        return {key: compact_numbers(item, ndigits) for key, item in value.items()}
+    return value
+
+
+def _near(value, expected) -> bool:
+    return isinstance(value, (int, float)) and abs(float(value) - expected) < 1e-6
+
+
+def compact_node_state(row: dict[str, Any]) -> dict[str, Any]:
+    row = compact_numbers(row)
+    transform = row.get("transform")
+    if isinstance(transform, dict):
+        scale, rotation = transform.get("scale"), transform.get("rotation")
+        if isinstance(scale, dict) and all(_near(scale.get(axis, 1), 1) for axis in "xyz"):
+            transform.pop("scale", None)
+        if isinstance(rotation, dict) and all(_near(rotation.get(axis, 0), 0) for axis in "xyz"):
+            transform.pop("rotation", None)
+    if row.get("visible") is True:
+        row.pop("visible", None)
+    if row.get("locked") is False:
+        row.pop("locked", None)
+    measurement = row.get("measurement")
+    if isinstance(measurement, dict):
+        position = transform.get("position") if isinstance(transform, dict) else None
+        if measurement.get("origin") == position:
+            measurement.pop("origin", None)
+        axis = measurement.get("localForwardAxis")
+        if isinstance(axis, dict) and _near(axis.get("x", 0), 0) and _near(axis.get("y", 0), 0) \
+                and _near(axis.get("z", 0), 1):
+            measurement.pop("localForwardAxis", None)
+        surfaces = [{key: surface[key] for key in ("height", "worldWidth", "worldDepth") if key in surface}
+                    for surface in measurement.get("supportSurfaces") or [] if isinstance(surface, dict)]
+        if surfaces:
+            measurement["supportSurfaces"] = surfaces
+        else:
+            measurement.pop("supportSurfaces", None)
+        for key in list(measurement):
+            if key not in {"status", "size", "bounds", "supportSurfaces", "landmarks", "origin", "localForwardAxis"}:
+                measurement.pop(key, None)
+    return row
+
+
+def node_state(node: dict[str, Any], versions: dict[str, Any]) -> dict[str, Any]:
+    row = {"nodeId": node["id"], "type": node["type"], "name": node.get("name"),
+           "entityVersion": versions.get(node["id"]), "transform": copy.deepcopy(node["transform"])}
+    if "parentId" in node:
+        row["parentId"] = node["parentId"]
+    if (node.get("metadata") or {}).get("assetId"):
+        row["assetId"] = node["metadata"]["assetId"]
+    for key in ("visible", "locked"):
+        if key in node:
+            row[key] = node[key]
+    if node.get("camera"):
+        row["camera"] = {key: copy.deepcopy(node["camera"][key])
+                         for key in ("fov", "lookAt", "subject", "lookAtTarget") if key in node["camera"]}
+    animation = (node.get("character") or {}).get("animation") or {}
+    if animation.get("posePresetId"):
+        row["posePresetId"] = animation["posePresetId"]
+    return row

topview_3d_cli/renderer.py

@@ -0,0 +1,75 @@
+"""Calls into the Node renderer (``director-cli``): one process per command, JSON in and out."""
+from __future__ import annotations
+
+import json
+import os
+import re
+import shutil
+import subprocess
+import tempfile
+from pathlib import Path
+from typing import Any
+
+from topview_3d_cli.local_errors import LocalProjectError
+from topview_3d_cli.runtime import node_env, runtime
+
+BROWSER_COMMANDS = frozenset({"render-frames", "inspect-nodes", "apply-library-pose", "apply-library-poses"})
+
+
+def node_path() -> str:
+    node = shutil.which("node")
+    if not node:
+        raise LocalProjectError("NODE_UNAVAILABLE", "node is not on PATH; install Node.js 20.6 or newer")
+    return node
+
+
+def director_cli(command: str, body: dict[str, Any] | None = None) -> dict[str, Any]:
+    """Run one director-cli command with a JSON payload file; return its last JSON line.
+
+    Failures raise ``RENDERER_FAILED`` (``RENDER_FAILED`` for ``render-frames``) with the thrown
+    error message as the message and the full stderr (stack included) in ``details.stderr``, or
+    ``BROWSER_NOT_INSTALLED`` when Chromium is missing.
+    """
+    current = runtime()
+    node = node_path()
+    args = [node, "cli.mjs", command]
+    payload_file = None
+    if body is not None:
+        descriptor, payload_file = tempfile.mkstemp(prefix="topview3d-", suffix=".json")
+        with os.fdopen(descriptor, "w", encoding="utf-8") as stream:
+            json.dump(body, stream, ensure_ascii=False)
+        args.append(payload_file)
+    try:
+        process = subprocess.run(args, cwd=current.director_cli, env=node_env(current), check=False,
+                                 capture_output=True, text=True, encoding="utf-8")
+    finally:
+        if payload_file:
+            Path(payload_file).unlink(missing_ok=True)
+    if process.returncode:
+        message = (process.stderr or process.stdout).strip()[-2000:]
+        if "PLAYWRIGHT_NOT_INSTALLED" in message or "Executable doesn't exist" in message:
+            raise LocalProjectError("BROWSER_NOT_INSTALLED", "run `topview-3d-cli browser ensure` first")
+        failure = "RENDER_FAILED" if command == "render-frames" else "RENDERER_FAILED"
+        reason = renderer_reason(message)
+        raise LocalProjectError(failure, reason or f"director-cli {command} exited with {process.returncode}",
+                                details={"command": command, "reason": reason, "stderr": message[-4000:]})
+    lines = [line for line in process.stdout.splitlines() if line.strip()]
+    if not lines:
+        raise LocalProjectError("RENDER_RESULT_MISSING")
+    try:
+        return json.loads(lines[-1])
+    except json.JSONDecodeError as exc:
+        raise LocalProjectError("RENDER_RESULT_INVALID", str(exc)) from exc
+
+
+def renderer_reason(message: str) -> str:
+    """The thrown error message: an ``...Error:`` line, else the first line that is not a Node warning."""
+    for line in message.splitlines():
+        match = re.match(r"\s*(?:Uncaught )?[A-Za-z]*Error: (.+)", line)
+        if match:
+            return match.group(1).strip()
+    for line in message.splitlines():
+        text = line.strip()
+        if text and not text.startswith(("(node:", "(Use `node --trace")):
+            return text.removeprefix("Error: ")
+    return ""