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

topview_3d_cli/director_static.py

@@ -0,0 +1,134 @@
+"""Stored-document helpers for static tools; never accept a caller's replacement scene."""
+from __future__ import annotations
+
+import copy
+import math
+
+from topview_3d_cli.director_document import fcurve_node_id, new_scene_operation_id
+
+
+def node_in(document: dict, node_id: str) -> dict:
+    node = next((n for n in document['content']['nodes'] if n['id'] == node_id), None)
+    if node is None:
+        raise ValueError(f'DIRECTOR_NODE_NOT_FOUND:{node_id}')
+    return node
+
+
+def camera_view(body: dict, camera_id: str | None) -> dict:
+    if camera_id:
+        camera = node_in(body['document'], camera_id)
+        if camera.get('type') != 'camera':
+            raise ValueError('DIRECTOR_CAMERA_REQUIRED')
+        body['document']['content']['activeShotCameraNodeId'] = camera_id
+        body['cameraNodeId'] = camera_id
+    return body
+
+
+def _detach_subject(camera: dict, subject: dict):
+    binding = camera['camera'].pop('subject')
+    if not binding.get('follow'):
+        return
+    rotation = subject['transform']['rotation']
+    yaw = math.atan2(math.sin(math.radians(rotation['y'])),
+                     math.cos(math.radians(rotation['x'])) * math.cos(math.radians(rotation['y']))) \
+        if binding.get('followRotation') else 0
+    position = subject['transform']['position']
+    def world(offset):
+        return {'x': position['x'] + offset['x'] * math.cos(yaw) + offset['z'] * math.sin(yaw),
+                'y': position['y'] + offset['y'],
+                'z': position['z'] - offset['x'] * math.sin(yaw) + offset['z'] * math.cos(yaw)}
+    camera['transform']['position'] = world(binding['offset'])
+    camera['camera']['lookAt'] = world(binding['lookAtOffset'])
+
+
+def delete_node_operations(snapshot: dict, node_id: str) -> tuple[dict, dict]:
+    document = snapshot['document']
+    target = node_in(document, node_id)
+    if target.get('locked'):
+        raise ValueError(f'DIRECTOR_NODE_LOCKED:{node_id}')
+    nodes = document['content']['nodes']
+    cameras = [n for n in nodes if n['type'] == 'camera' and n['id'] != node_id]
+    if target['type'] == 'camera' and not cameras:
+        raise ValueError('DIRECTOR_LAST_CAMERA_REQUIRED')
+    if target.get('children'):
+        raise ValueError('DIRECTOR_DELETE_CHILDREN_FIRST')
+    sequence = snapshot.get('sceneSequence', 0)
+    versions = snapshot.get('entityVersions') or {}
+    operations = []
+    def add(kind, entity_id, payload):
+        operations.append({'kind': kind, 'entityId': entity_id, 'payload': payload,
+                           'operationId': new_scene_operation_id('static_delete'),
+                           'baseSequence': sequence, 'expectedEntityVersion': versions.get(entity_id)})
+    add('director.node.delete', node_id, {})
+    detached = []
+    for original in nodes:
+        if original['id'] == node_id:
+            continue
+        node = copy.deepcopy(original)
+        if node.get('camera', {}).get('subject', {}).get('nodeId') == node_id:
+            _detach_subject(node, target)
+            detached.append(node['id'])
+        if node.get('camera', {}).get('lookAtTarget', {}).get('nodeId') == node_id:
+            look_target = node['camera'].pop('lookAtTarget')
+            offset = look_target.get('offset') or {'x': 0, 'y': 1.2, 'z': 0}
+            node['camera']['lookAt'] = {
+                axis: target['transform']['position'][axis] + offset[axis]
+                for axis in ('x', 'y', 'z')}
+            if node['id'] not in detached:
+                detached.append(node['id'])
+        if node_id in node.get('children', []):
+            node['children'] = [n for n in node['children'] if n != node_id]
+        if node != original:
+            add('director.node.upsert', node['id'], {'node': node})
+    content = document['content']
+    removed_clips = []
+    animation = content['timeline']['animation']
+    for key in ('cameraMotionClips', 'motionClips', 'pathMotionClips'):
+        for clip in animation.get(key, []):
+            if clip.get('target', {}).get('nodeId') == node_id or clip.get('pathNodeId') == node_id:
+                add('director.clip.delete', clip['id'], {})
+                removed_clips.append(clip['id'])
+    curves_id = 'fcurves__' + node_id
+    curves = snapshot.get('fcurves') or {}
+    if curves_id in versions or curves_id in curves or any(fcurve_node_id(c) == node_id for c in curves.get('fcurves', [])):
+        add('director.fcurves.delete', curves_id, {})
+    # Scene-level patch preserves unrelated environment/timeline data.
+    scene = {}
+    animation_patch = {}
+    for key in ('fcurves', 'motionTransitions'):
+        original = animation.get(key, [])
+        kept_entries = [entry for entry in original if not (
+            isinstance(entry, dict) and (
+                entry.get('nodeId') == node_id
+                or entry.get('targetNodeId') == node_id
+                or (isinstance(entry.get('target'), dict) and entry['target'].get('nodeId') == node_id)
+                or any(entry.get(field) in removed_clips for field in ('fromClipId', 'toClipId'))))]
+        if kept_entries != original:
+            animation_patch[key] = kept_entries
+    if animation_patch:
+        # scene.set replaces content.timeline as a whole, so send the full timeline.
+        timeline = copy.deepcopy(content['timeline'])
+        timeline['animation'] = {
+            key: value for key, value in timeline['animation'].items()
+            if key not in ('cameraMotionClips', 'motionClips', 'pathMotionClips')}
+        timeline['animation'].update(animation_patch)
+        scene['timeline'] = timeline
+    if content.get('activeShotCameraNodeId') == node_id:
+        scene['activeShotCameraNodeId'] = cameras[0]['id']
+    editorial = copy.deepcopy(content.get('editorial'))
+    if isinstance(editorial, dict):
+        for sequence_item in editorial.get('sequences', []):
+            sequence_item['clips'] = [c for c in sequence_item.get('clips', []) if c.get('cameraNodeId') != node_id]
+        if editorial != content['editorial']:
+            scene['editorial'] = editorial
+    constraints = content.get('physicalConstraints', [])
+    kept = [c for c in constraints if not (isinstance(c, dict) and any(
+        c.get(key) == node_id for key in ('nodeId', 'targetNodeId', 'sourceNodeId', 'supportNodeId')))]
+    if kept != constraints:
+        scene['physicalConstraints'] = kept
+    if scene:
+        add('director.scene.set', 'director', {'scene': {'content': {'version': 1, **scene}}})
+    if len(operations) > 64:
+        raise ValueError('DIRECTOR_DELETE_TOO_MANY_DEPENDENCIES')
+    return ({'schemaVersion': 2, 'batchId': new_scene_operation_id('delete_node'), 'operations': operations},
+            {'deletedNodeId': node_id, 'deletedClipIds': removed_clips, 'detachedCameraIds': detached})

topview_3d_cli/local_assets.py

@@ -0,0 +1,248 @@
+"""Offline asset layer: built-in and project asset manifests.
+
+A manifest (``manifest.json``, format ``scene3d-asset-manifest`` v1) lists assets. File-backed
+assets (character, prop, pose) map the asset ``key`` used in director documents
+(``metadata.modelUrl``) to a file next to the manifest; primitives are code-generated and carry
+their geometry. The renderer only serves files listed here, so nothing is fetched remotely.
+"""
+from __future__ import annotations
+
+import copy
+import hashlib
+import json
+import os
+import re
+import shutil
+import tempfile
+from pathlib import Path
+from typing import Any
+
+from topview_3d_cli.local_errors import LocalProjectError
+from topview_3d_cli.local_project import ProjectPaths
+from topview_3d_cli.runtime import runtime
+
+MANIFEST_FORMAT = "scene3d-asset-manifest"
+MANIFEST_VERSION = 1
+MANIFEST_NAME = "manifest.json"
+ASSET_KINDS = ("character", "prop", "pose", "primitive")
+FILE_KINDS = {"character": (".glb", ".gltf"), "prop": (".glb", ".gltf"), "pose": (".json",)}
+COVER_TYPES = (".webp", ".png", ".jpg", ".jpeg")
+PRIMITIVE_KINDS = ("BoxGeometry", "SphereGeometry", "CylinderGeometry", "ConeGeometry", "PlaneGeometry")
+ASSET_ID = re.compile(r"^[A-Za-z0-9_-]{1,128}$")
+
+
+def builtin_asset_root() -> Path:
+    override = os.environ.get("TOPVIEW3D_BUILTIN_ASSETS")
+    return Path(override).expanduser().resolve() if override else runtime().builtin_assets
+
+
+def _invalid(root: Path, message: str) -> LocalProjectError:
+    return LocalProjectError("ASSET_MANIFEST_INVALID", f"{root / MANIFEST_NAME}: {message}")
+
+
+def empty_manifest() -> dict[str, Any]:
+    return {"format": MANIFEST_FORMAT, "version": MANIFEST_VERSION, "assets": []}
+
+
+def asset_key(raw: Any) -> str:
+    return str(raw or "").lstrip("/").split("?")[0]
+
+
+def _inside(root: Path, relative: str) -> Path | None:
+    if not isinstance(relative, str) or not relative or Path(relative).is_absolute():
+        return None
+    if any(part in ("..", ".") for part in re.split(r"[\\/]+", relative)):
+        return None
+    resolved = (root / relative).resolve()
+    return resolved if resolved.is_relative_to(root.resolve()) else None
+
+
+def read_manifest(root: Path) -> dict[str, Any]:
+    path = root / MANIFEST_NAME
+    if not path.is_file():
+        return empty_manifest()
+    try:
+        manifest = json.loads(path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as exc:
+        raise _invalid(root, exc.msg) from exc
+    if not isinstance(manifest, dict) or manifest.get("format") != MANIFEST_FORMAT:
+        raise _invalid(root, f"format must be {MANIFEST_FORMAT!r}")
+    if manifest.get("version") != MANIFEST_VERSION:
+        raise _invalid(root, f"unsupported version {manifest.get('version')!r}")
+    if not isinstance(manifest.get("assets"), list):
+        raise _invalid(root, "assets must be a list")
+    return manifest
+
+
+def load_assets(root: Path, origin: str) -> list[dict[str, Any]]:
+    """Validated manifest entries with an absolute ``path`` for file-backed assets."""
+    entries = []
+    seen: set[str] = set()
+    for index, raw in enumerate(read_manifest(root)["assets"]):
+        where = f"assets[{index}]"
+        if not isinstance(raw, dict):
+            raise _invalid(root, f"{where} must be an object")
+        entry = copy.deepcopy(raw)
+        asset_id, kind = entry.get("id"), entry.get("kind")
+        if not isinstance(asset_id, str) or not ASSET_ID.match(asset_id) or asset_id in seen:
+            raise _invalid(root, f"{where}.id missing, malformed or duplicated")
+        seen.add(asset_id)
+        if kind not in ASSET_KINDS:
+            raise _invalid(root, f"{where}.kind must be one of {', '.join(ASSET_KINDS)}")
+        if kind == "primitive":
+            primitive = entry.get("primitive")
+            if (not isinstance(primitive, dict) or primitive.get("kind") not in PRIMITIVE_KINDS
+                    or not isinstance(primitive.get("parameters"), dict)):
+                raise _invalid(root, f"{where}.primitive must name a supported geometry with parameters")
+        else:
+            path = _inside(root, entry.get("file"))
+            if path is None:
+                raise _invalid(root, f"{where}.file must be a relative path inside the asset root")
+            if not path.is_file():
+                raise LocalProjectError("ASSET_FILE_MISSING", f"{asset_id}: {path}")
+            if isinstance(entry.get("bytes"), int) and path.stat().st_size != entry["bytes"]:
+                raise _invalid(root, f"{where}: {path.name} size does not match bytes")
+            entry["path"] = str(path)
+            if kind in ("character", "prop") and not asset_key(entry.get("key")):
+                raise _invalid(root, f"{where}.key is required for {kind} assets")
+        if entry.get("cover") is not None:
+            cover = _inside(root, entry["cover"])
+            if cover is None or not cover.is_file():
+                raise _invalid(root, f"{where}.cover must be an existing file inside the asset root")
+        entry["origin"] = origin
+        entries.append(entry)
+    return entries
+
+
+def asset_catalog(paths: ProjectPaths | None = None) -> list[dict[str, Any]]:
+    """Built-in assets, overridden by the project's own assets (same id or key)."""
+    catalog = {entry["id"]: entry for entry in load_assets(builtin_asset_root(), "builtin")}
+    if paths is not None:
+        for entry in load_assets(paths.assets, "project"):
+            catalog.pop(entry["id"], None)
+            catalog[entry["id"]] = entry
+    return list(catalog.values())
+
+
+def local_asset_map(catalog: list[dict[str, Any]]) -> dict[str, str]:
+    """Asset key -> absolute file for the renderer (characters and props)."""
+    mapping: dict[str, str] = {}
+    for entry in catalog:
+        if entry["kind"] in ("character", "prop"):
+            mapping[asset_key(entry["key"])] = entry["path"]
+    return mapping
+
+
+def find_asset(catalog: list[dict[str, Any]], kind: str, asset_id: str) -> dict[str, Any]:
+    """Look an asset up by id; library poses also match without their ``a3d_pose_`` prefix."""
+    candidates = {asset_id, f"a3d_pose_{asset_id}"} if kind == "pose" else {asset_id}
+    for entry in catalog:
+        if entry["kind"] == kind and entry["id"] in candidates:
+            return entry
+    raise LocalProjectError("ASSET_NOT_FOUND", f"no {kind} asset {asset_id!r} in the local manifests")
+
+
+def public_asset_entry(entry: dict[str, Any]) -> dict[str, Any]:
+    return {key: value for key, value in entry.items() if key != "path"}
+
+
+def document_asset_refs(document: dict[str, Any]) -> dict[str, list[dict[str, str]]]:
+    """Asset references of a director document: required models and optional motions."""
+    content = document.get("content") or {}
+    required = []
+    for node in content.get("nodes") or []:
+        if node.get("type") not in ("character", "prop"):
+            continue
+        metadata = node.get("metadata") or {}
+        if node["type"] == "character" and metadata.get("assetSource") == "user" and metadata.get("assetId"):
+            required.append({"nodeId": node["id"], "key": f"user:{metadata['assetId']}"})
+            continue
+        key = asset_key(metadata.get("modelUrl"))
+        if key:
+            required.append({"nodeId": node["id"], "key": key})
+    motion_ids = {clip.get("motion", {}).get("assetId")
+                  for clip in ((content.get("timeline") or {}).get("animation") or {}).get("motionClips") or []}
+    motions = [{"assetId": entry.get("id"), "key": asset_key(entry.get("path"))}
+               for entry in ((content.get("asset") or {}).get("motionPath") or [])
+               if entry.get("id") in motion_ids]
+    return {"required": required, "motions": motions}
+
+
+def check_render_assets(document: dict[str, Any], mapping: dict[str, str],
+                        public_asset_base: str = "") -> list[str]:
+    """Raise ASSET_NOT_AVAILABLE for missing models; return warnings for missing motions."""
+    refs = document_asset_refs(document)
+    def available(key: str) -> bool:
+        return (key in mapping or re.match(r"^https?://", key, re.I) is not None
+                or (bool(public_asset_base) and key.startswith("3d-builder/public/")))
+    missing = [ref for ref in refs["required"] if not available(ref["key"])]
+    if missing:
+        raise LocalProjectError(
+            "ASSET_NOT_AVAILABLE",
+            "models not available offline: " + ", ".join(f"{m['nodeId']} ({m['key']})" for m in missing),
+            details={"missing": missing})
+    return [f"MOTION_NOT_AVAILABLE:{motion['assetId']}" for motion in refs["motions"]
+            if not available(motion["key"])]
+
+
+def _sha256(path: Path) -> str:
+    digest = hashlib.sha256()
+    with path.open("rb") as stream:
+        for chunk in iter(lambda: stream.read(1 << 20), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def import_asset(root: Path, source: str | os.PathLike[str], *, kind: str, asset_id: str,
+                 key: str | None = None, cover: str | os.PathLike[str] | None = None,
+                 name: str | None = None, category: str | None = None,
+                 tags: list[str] | None = None, rig: str | None = None,
+                 license_name: str | None = None, source_url: str | None = None) -> dict[str, Any]:
+    """Copy one file into ``root`` and add or replace its manifest entry."""
+    if kind not in FILE_KINDS:
+        raise LocalProjectError("ASSET_IMPORT_INVALID", f"kind must be one of {', '.join(FILE_KINDS)}")
+    if not ASSET_ID.match(asset_id or ""):
+        raise LocalProjectError("ASSET_IMPORT_INVALID", "id must match [A-Za-z0-9_-]{1,128}")
+    file = Path(source).expanduser()
+    if not file.is_file():
+        raise LocalProjectError("ASSET_IMPORT_INVALID", f"{file} is not a file")
+    if file.suffix.lower() not in FILE_KINDS[kind]:
+        raise LocalProjectError("ASSET_IMPORT_INVALID", f"{kind} files must be {', '.join(FILE_KINDS[kind])}")
+    if kind == "pose":
+        try:
+            pose = json.loads(file.read_text(encoding="utf-8"))
+        except (UnicodeDecodeError, json.JSONDecodeError) as exc:
+            raise LocalProjectError("ASSET_IMPORT_INVALID", f"pose is not JSON: {exc}") from exc
+        if not isinstance(pose, dict) or not isinstance(pose.get("bones"), dict):
+            raise LocalProjectError("ASSET_IMPORT_INVALID", "pose JSON must contain a bones object")
+    manifest = read_manifest(root)
+    relative = f"{kind}s/{asset_id}{file.suffix.lower()}"
+    entry: dict[str, Any] = {"id": asset_id, "kind": kind, "name": name or asset_id, "file": relative,
+                             "bytes": file.stat().st_size, "sha256": _sha256(file)}
+    if kind in ("character", "prop"):
+        entry["key"] = asset_key(key) or f"local/{relative}"
+    elif key:
+        entry["key"] = asset_key(key)
+    cover_file = Path(cover).expanduser() if cover else None
+    if cover_file is not None:
+        if not cover_file.is_file() or cover_file.suffix.lower() not in COVER_TYPES:
+            raise LocalProjectError("ASSET_IMPORT_INVALID", f"cover must be one of {', '.join(COVER_TYPES)}")
+        entry["cover"] = f"covers/{asset_id}{cover_file.suffix.lower()}"
+    for field, value in (("category", category), ("tags", tags), ("rig", rig),
+                         ("license", license_name), ("source", source_url)):
+        if value:
+            entry[field] = value
+    target = root / relative
+    target.parent.mkdir(parents=True, exist_ok=True)
+    shutil.copyfile(file, target)
+    if cover_file is not None:
+        (root / "covers").mkdir(parents=True, exist_ok=True)
+        shutil.copyfile(cover_file, root / entry["cover"])
+    manifest["assets"] = [item for item in manifest["assets"] if item.get("id") != asset_id] + [entry]
+    descriptor, temporary = tempfile.mkstemp(prefix=".manifest.", suffix=".tmp", dir=root)
+    with os.fdopen(descriptor, "w", encoding="utf-8") as stream:
+        json.dump(manifest, stream, ensure_ascii=False, indent=2)
+        stream.write("\n")
+    os.chmod(temporary, 0o644)
+    os.replace(temporary, root / MANIFEST_NAME)
+    return entry

topview_3d_cli/local_bom.py

@@ -0,0 +1,108 @@
+"""``.topview3d/bom.json``: the plan / constraint record kept next to the director document."""
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from topview_3d_cli.bom import (
+    derive_verification, encode_bom, merge_checkpoint, normalize_bom, observed_from_snapshot,
+    record_runtime_verification,
+)
+from topview_3d_cli.local_errors import LocalProjectError
+from topview_3d_cli.local_project import Project, utc_timestamp, atomic_write_json, base_result, open_project
+
+_CHECKPOINT_CODES = {
+    "SCENE_SEQUENCE_CONFLICT": "SCENE_SEQUENCE_CONFLICT",
+    "BOM_REVISION_CONFLICT": "BOM_REVISION_CONFLICT",
+    "BOM_TOO_LARGE": "BOM_TOO_LARGE",
+    "BOM_REVIEW_REQUIRES_CURRENT_RUNTIME_EVIDENCE": "BOM_REVIEW_EVIDENCE_MISSING",
+    "BOM_REVIEW_IMAGE_MISMATCH": "BOM_REVIEW_EVIDENCE_MISSING",
+}
+
+
+def read_bom(project: Project) -> dict[str, Any]:
+    """Stored record in the current shape; a missing file is an empty BOM."""
+    try:
+        raw = json.loads(project.paths.bom.read_text(encoding="utf-8"))
+    except FileNotFoundError:
+        raw = None
+    except (UnicodeDecodeError, json.JSONDecodeError) as exc:
+        raise LocalProjectError("BOM_JSON_INVALID", f"{project.paths.bom}: not JSON; fix or delete it") from exc
+    if raw is not None and not isinstance(raw, dict):
+        raise LocalProjectError("BOM_JSON_INVALID", f"{project.paths.bom} must contain an object")
+    return normalize_bom(raw, project.paths.root.name)
+
+
+# Node references a checkpoint may carry, per entry list.
+_NODE_REFERENCES = {"relationships": ("subjectId", "targetId"), "cameras": ("nodeId",)}
+
+
+def _check_references(project: Project, patch: dict[str, Any]) -> None:
+    nodes = {node["id"] for node in project.store.assemble()["document"]["content"]["nodes"]}
+    for field, keys in _NODE_REFERENCES.items():
+        for index, entry in enumerate(patch.get(field) or []):
+            for key in keys:
+                values = entry.get(key) if isinstance(entry, dict) else None
+                for value in values if isinstance(values, list) else [values]:
+                    if isinstance(value, str) and value not in nodes:
+                        raise LocalProjectError(
+                            "DIRECTOR_NODE_NOT_FOUND",
+                            f"{field}.{index}.{key}: no node {value!r}; nothing was written",
+                            details={"field": field, "index": index, "id": entry.get("id"), "property": key,
+                                     "ref": value})
+
+
+def _public(bom: dict[str, Any]) -> dict[str, Any]:
+    """The record as shown: ``guidesRead`` belongs to the hosted guide service and stays unused here."""
+    return {key: value for key, value in bom.items() if key != "guidesRead"}
+
+
+def write_bom(project: Project, bom: dict[str, Any]) -> None:
+    bom = {**bom, "updatedAt": utc_timestamp()}
+    try:
+        encode_bom(bom)
+    except ValueError as exc:
+        raise LocalProjectError("BOM_TOO_LARGE", str(exc)) from exc
+    atomic_write_json(project.paths.bom, bom)
+
+
+def _with_observed(project: Project, bom: dict[str, Any]) -> dict[str, Any]:
+    observed = observed_from_snapshot(project.store.assemble())
+    return _public({**bom, "observed": observed, "verification": derive_verification(bom, observed)})
+
+
+def bom_get(directory: str) -> dict[str, Any]:
+    project = open_project(directory)
+    return {**base_result(project), "path": str(project.paths.bom), "exists": project.paths.bom.is_file(),
+            "bom": _with_observed(project, read_bom(project))}
+
+
+def bom_checkpoint(directory: str, patch: dict[str, Any]) -> dict[str, Any]:
+    project = open_project(directory)
+    current = read_bom(project)
+    try:
+        merged = merge_checkpoint(current, patch, project.store.scene_sequence)
+    except ValueError as exc:
+        prefix = str(exc).split(":", 1)[0]
+        code = _CHECKPOINT_CODES.get(prefix, "BOM_CHECKPOINT_INVALID")
+        message, details = str(exc), None
+        if code == "BOM_REVIEW_EVIDENCE_MISSING":
+            evidence = current.get("verification") or {}
+            details = {"evidenceSceneSequence": evidence.get("sceneSequence"),
+                       "currentSceneSequence": project.store.scene_sequence,
+                       "evidenceStale": bool(evidence.get("stale", True))}
+            message = (f"{message}: the last complete `inspect views` evidence is from sceneSequence "
+                       f"{details['evidenceSceneSequence']}, the project is at {details['currentSceneSequence']}; "
+                       "rerun `inspect views` (any write, including adding or deleting a diagnostic camera, "
+                       "invalidates it)")
+        raise LocalProjectError(code, message, details=details) from exc
+    _check_references(project, patch)
+    merged.pop("observed", None)
+    write_bom(project, merged)
+    merged = read_bom(project)
+    return {**base_result(project), "path": str(project.paths.bom), "bomRevision": merged["bomRevision"],
+            "bom": _with_observed(project, merged)}
+
+
+def record_views(project: Project, result: dict[str, Any]) -> None:
+    write_bom(project, record_runtime_verification(read_bom(project), result))

topview_3d_cli/local_catalog.py

@@ -0,0 +1,156 @@
+"""Offline asset search, asset details and the pose catalog over the local manifests."""
+from __future__ import annotations
+
+import json
+from collections import Counter
+from pathlib import Path
+from typing import Any
+
+from topview_3d_cli.local_assets import ASSET_KINDS, asset_catalog, public_asset_entry
+from topview_3d_cli.local_errors import LocalProjectError
+from topview_3d_cli.local_project import open_project
+
+SEARCH_LIMIT_DEFAULT = 20
+SEARCH_LIMIT_MAX = 200
+TAG_FACET_LIMIT = 40
+POSE_PREFIX = "a3d_pose_"
+
+
+def _catalog(directory: str | None) -> list[dict[str, Any]]:
+    return asset_catalog(open_project(directory).paths if directory else None)
+
+
+def _root_of(entry: dict[str, Any]) -> Path | None:
+    if not entry.get("path") or not entry.get("file"):
+        return None
+    return Path(entry["path"]).parents[len(Path(entry["file"]).parts) - 1]
+
+
+def _cover_path(entry: dict[str, Any]) -> str | None:
+    root = _root_of(entry)
+    return str(root / entry["cover"]) if root and entry.get("cover") else None
+
+
+def _fold(value: Any) -> str:
+    return str(value or "").casefold()
+
+
+def _score(entry: dict[str, Any], tokens: list[str]) -> int | None:
+    """None when a token is missing; otherwise name hits count 3, tag hits 2, other fields 1."""
+    name, tags = _fold(entry.get("name")), [_fold(tag) for tag in entry.get("tags") or []]
+    other = " ".join(_fold(entry.get(key)) for key in ("id", "category", "description", "rig"))
+    score = 0
+    for token in tokens:
+        if token in name:
+            score += 3
+        elif any(token == tag for tag in tags):
+            score += 2
+        elif any(token in tag for tag in tags) or token in other:
+            score += 1
+        else:
+            return None
+    return score
+
+
+def compact_entry(entry: dict[str, Any]) -> dict[str, Any]:
+    row = {key: entry[key] for key in ("id", "kind", "name", "category", "tags", "description", "rig", "key",
+                                       "license", "origin") if entry.get(key) not in (None, "", [])}
+    if entry["kind"] == "pose":
+        row["shortId"] = entry["id"].removeprefix(POSE_PREFIX)
+    if entry["kind"] == "primitive":
+        row["primitive"] = entry["primitive"]
+    cover = _cover_path(entry)
+    if cover:
+        row["coverPath"] = cover
+    return row
+
+
+def _facets(entries: list[dict[str, Any]]) -> dict[str, Any]:
+    tags = Counter(tag for entry in entries for tag in entry.get("tags") or [])
+    return {
+        "kind": dict(Counter(entry["kind"] for entry in entries)),
+        "category": dict(Counter(entry.get("category") or "" for entry in entries if entry.get("category"))),
+        "rig": dict(Counter(entry["rig"] for entry in entries if entry.get("rig"))),
+        "tags": dict(tags.most_common(TAG_FACET_LIMIT)),
+    }
+
+
+def asset_search(directory: str | None, query: str | None = None, *, kind: str | None = None,
+                 category: str | None = None, tags: list[str] | None = None, rig: str | None = None,
+                 limit: int = SEARCH_LIMIT_DEFAULT, offset: int = 0) -> dict[str, Any]:
+    """Keyword search (every word must match) with exact filters; facets cover all matches."""
+    if not 1 <= limit <= SEARCH_LIMIT_MAX or offset < 0:
+        raise LocalProjectError("USAGE_INVALID", f"--limit must be 1..{SEARCH_LIMIT_MAX} and --offset >= 0")
+    tokens = _fold(query).split()
+    wanted_tags = {_fold(tag) for tag in tags or []}
+    matches = []
+    for entry in _catalog(directory):
+        if kind and entry["kind"] != kind:
+            continue
+        if category and _fold(entry.get("category")) != _fold(category):
+            continue
+        if rig and entry.get("rig") != rig:
+            continue
+        if not wanted_tags <= {_fold(tag) for tag in entry.get("tags") or []}:
+            continue
+        score = _score(entry, tokens)
+        if score is not None:
+            matches.append((score, entry))
+    matches.sort(key=lambda item: (-item[0], ASSET_KINDS.index(item[1]["kind"]), _fold(item[1].get("name"))))
+    page = matches[offset:offset + limit]
+    end = offset + len(page)
+    return {
+        "ok": True,
+        "query": {"text": query or "", "kind": kind, "category": category, "tags": sorted(wanted_tags),
+                  "rig": rig, "limit": limit, "offset": offset},
+        "total": len(matches),
+        "complete": end >= len(matches),
+        "nextOffset": None if end >= len(matches) else end,
+        "facets": _facets([entry for _, entry in matches]),
+        "items": [{**compact_entry(entry), "score": score} for score, entry in page],
+    }
+
+
+def find_any_asset(catalog: list[dict[str, Any]], asset_id: str, kind: str | None = None) -> dict[str, Any]:
+    """Look up by exact id (pose ids also without ``a3d_pose_``), optionally restricted to one kind."""
+    candidates = [entry for entry in catalog if kind is None or entry["kind"] == kind]
+    for wanted in (asset_id, POSE_PREFIX + asset_id):
+        found = next((entry for entry in candidates if entry["id"] == wanted), None)
+        if found:
+            return found
+    raise LocalProjectError("ASSET_NOT_FOUND", f"no {kind or 'asset'} {asset_id!r} in the local manifests")
+
+
+def asset_show(directory: str | None, asset_id: str, *, kind: str | None = None) -> dict[str, Any]:
+    entry = find_any_asset(_catalog(directory), asset_id, kind)
+    detail: dict[str, Any] = {**public_asset_entry(entry), **compact_entry(entry)}
+    if entry.get("path"):
+        detail["path"] = entry["path"]
+    result: dict[str, Any] = {"ok": True, "asset": detail}
+    if entry["kind"] == "pose":
+        pose = json.loads(Path(entry["path"]).read_text(encoding="utf-8"))
+        bones = pose.get("bones") if isinstance(pose.get("bones"), dict) else {}
+        result["pose"] = {"boneCount": len(bones), "hips": pose.get("hips")}
+        result["usage"] = {"command": f"topview-3d-cli pose apply <dir> <characterNodeId> {detail['shortId']}",
+                           "batchItem": {"nodeId": "<characterNodeId>", "poseId": detail["shortId"]}}
+    elif entry["kind"] in ("character", "prop"):
+        result["usage"] = {"change": {"action": "add_library", "kind": f"{entry['kind']}s",
+                                      "libraryId": entry["id"], "nodeId": "<new node id>"}}
+    else:
+        result["usage"] = {"change": {"action": "add_primitive", "nodeId": "<new node id>",
+                                      "primitive": entry["primitive"]}}
+    return result
+
+
+def pose_catalog(directory: str | None, *, category: str | None = None, tag: str | None = None) -> dict[str, Any]:
+    """Every pose (built-in and project), compact and deterministic."""
+    poses = [entry for entry in _catalog(directory) if entry["kind"] == "pose"]
+    categories = dict(Counter(entry.get("category") or "" for entry in poses))
+    if category:
+        poses = [entry for entry in poses if _fold(entry.get("category")) == _fold(category)]
+    if tag:
+        poses = [entry for entry in poses if _fold(tag) in {_fold(item) for item in entry.get("tags") or []}]
+    poses.sort(key=lambda entry: (_fold(entry.get("category")), _fold(entry.get("name")), entry["id"]))
+    items = [{key: value for key, value in compact_entry(entry).items() if key not in ("kind", "license", "key")}
+             for entry in poses]
+    return {"ok": True, "total": len(items), "categories": categories, "items": items}