orkid-data 0.1.0__py3-none-any.whl

orkid_bundle/.deploy_path

@@ -0,0 +1 @@
+__OBT_DEPLOY_SENTINEL__

orkid_bundle/.relocatable_files

@@ -0,0 +1,27 @@
+obt_venv/bin/activate
+obt_venv/bin/activate.csh
+obt_venv/bin/activate.fish
+obt_venv/bin/distro
+obt_venv/bin/markdown-it
+obt_venv/bin/pip
+obt_venv/bin/pip3
+obt_venv/bin/pip3.14
+obt_venv/bin/pygmentize
+obt_venv/pyvenv.cfg
+pyvenv/bin/activate
+pyvenv/bin/activate.csh
+pyvenv/bin/activate.fish
+pyvenv/bin/f2py
+pyvenv/bin/idle3.14
+pyvenv/bin/normalizer
+pyvenv/bin/numpy-config
+pyvenv/bin/pip3
+pyvenv/bin/pip3.14
+pyvenv/bin/pydoc3.14
+pyvenv/bin/python3.14t-config
+pyvenv/lib/pkgconfig/python-3.14t-embed.pc
+pyvenv/lib/pkgconfig/python-3.14t.pc
+pyvenv/lib/python3.14t/_sysconfig_vars_t_darwin_darwin.json
+pyvenv/lib/python3.14t/_sysconfigdata_t_darwin_darwin.py
+pyvenv/lib/python3.14t/build-details.json
+pyvenv/pyvenv.cfg

orkid_bundle/.symlinks.d/orkid_data.txt

@@ -0,0 +1 @@
+builds/moltenvk/Package/Latest/MoltenVK/dylib/macOS/libMoltenVk.dylib	../../../../../../../lib/libMoltenVk.dylib

orkid_bundle/builds/moltenvk/Package/Latest/MoltenVK/dylib/macOS/MoltenVK_icd.json

@@ -0,0 +1,8 @@
+{
+    "file_format_version" : "1.0.0",
+    "ICD": {
+        "library_path": "./libMoltenVK.dylib",
+        "api_version" : "1.4.0",
+        "is_portability_driver" : true
+    }
+}

orkid_bundle/obt-launch-env

@@ -0,0 +1,135 @@
+#!/usr/bin/env bash
+###############################################################################
+# obt-launch-env — Relocatable OBT environment launcher
+# Generated by ork.deploy.macos.relocatable.py (Phase 6)
+#
+# This script is self-locating: it computes all paths relative to its own
+# location, so the deployment can be moved anywhere.
+###############################################################################
+
+# Compute DEPLOY_ROOT from this script's location.
+# -P / pwd -P resolves symlinks to their physical target so that a symlink
+# pointing at .staging (e.g. from a nested utilities folder) doesn't make
+# DEPLOY_ROOT differ string-wise from .deploy_path on alternating launches.
+# Without this, the relocation fixup ping-pongs ~170 files every time the
+# user alternates between launching a symlink-routed app and a direct-path
+# app — harmless per-launch but wasteful and confusing.
+SCRIPT_DIR="$(cd -P "$(dirname "${BASH_SOURCE[0]}")" && pwd -P)"
+DEPLOY_ROOT="$SCRIPT_DIR"
+
+# Sever all connections to any host OBT/Python environment.
+# Without this, PYTHONPATH from the host leaks in and causes
+# the deploy's Python to import obt from the host's site-packages,
+# which then discovers source-tree projects instead of deploy projects.
+unset PYTHONPATH
+unset PYTHONHOME
+unset VIRTUAL_ENV
+unset OBT_STAGE
+unset OBT_ROOT
+unset OBT_PROJECT_DIRS
+unset OBT_PROJECTS_LIST
+unset OBT_SEARCH_PATH
+unset OBT_BUILDS
+unset OBT_SUBSPACE_DIR
+unset OBT_SUBSPACE_LIB_DIR
+unset OBT_SUBSPACE_BIN_DIR
+unset OBT_SUBSPACE_BUILD_DIR
+unset OBT_TARGET
+unset ORKID_WORKSPACE_DIR
+unset ORKID_ASSET_MANIFEST_DIRS
+unset ORKID_IS_MAIN_PROJECT
+unset LD_LIBRARY_PATH
+unset DYLD_LIBRARY_PATH
+unset DYLD_FALLBACK_LIBRARY_PATH
+unset PKG_CONFIG
+unset PKG_CONFIG_PATH
+unset LUA_PATH
+export PYTHONNOUSERSITE=1
+
+# Bootstrap the OBT framework venv.
+# The obt_venv's pyvenv.cfg already tells Python 3.14 where its stdlib is.
+export VIRTUAL_ENV="$DEPLOY_ROOT/obt_venv"
+
+# Build PATH: deploy dirs first, then system essentials.
+# No homebrew — the deployment is fully self-contained.
+export PATH="$DEPLOY_ROOT/obt_venv/bin:$DEPLOY_ROOT/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin"
+
+# ---- Bash-level relocation fixup (runs BEFORE Python) ----
+# Python cannot start if pyvenv.cfg contains stale paths, so the rewrite
+# must happen in bash before we exec the interpreter.
+#
+# Bundle time writes every text file containing a build path with the
+# sentinel __OBT_DEPLOY_SENTINEL__ in place of the real path, and emits
+# .relocatable_files listing every such file. Launch time reads that
+# manifest and substitutes sentinel -> DEPLOY_ROOT in each entry — no
+# filesystem walk, O(N) where N = relocatable file count.
+_MARKER_FILE="$DEPLOY_ROOT/.deploy_path"
+_MANIFEST="$DEPLOY_ROOT/.relocatable_files"
+_NEED_FIXUP=0
+if [ -f "$_MARKER_FILE" ]; then
+  _OLD_ROOT="$(cat "$_MARKER_FILE")"
+  if [ "$_OLD_ROOT" != "$DEPLOY_ROOT" ]; then
+    _NEED_FIXUP=1
+  fi
+else
+  echo "$DEPLOY_ROOT" > "$_MARKER_FILE"
+fi
+
+if [ "$_NEED_FIXUP" -eq 1 ]; then
+  echo "[deploy-fixup] Relocation detected: $_OLD_ROOT -> $DEPLOY_ROOT"
+  if [ ! -f "$_MANIFEST" ]; then
+    echo "[deploy-fixup] FATAL: manifest $_MANIFEST missing — cannot relocate" >&2
+    exit 1
+  fi
+  _n=0
+  while IFS= read -r _rel; do
+    [ -z "$_rel" ] && continue
+    _f="$DEPLOY_ROOT/$_rel"
+    [ -f "$_f" ] || continue
+    [ -L "$_f" ] && continue
+    sed -i '' "s|$_OLD_ROOT|$DEPLOY_ROOT|g" "$_f" && _n=$((_n+1))
+  done < "$_MANIFEST"
+  echo "$DEPLOY_ROOT" > "$_MARKER_FILE"
+  echo "[deploy-fixup] Done ($_n files updated)."
+fi
+
+# Ensure assetcache symlink points to user's global cache
+_GLOBAL_CACHE="$HOME/.obt-global/assetcache"
+mkdir -p "$_GLOBAL_CACHE"
+if [ ! -e "$DEPLOY_ROOT/assetcache" ]; then
+  ln -s "$_GLOBAL_CACHE" "$DEPLOY_ROOT/assetcache"
+fi
+
+# Ensure envmaps bake-cache symlink points to user's global cache.
+# Baked IBL/envmaps are regenerable runtime output — keep them out of the
+# bundle so they never bloat it (same pattern as assetcache).
+_GLOBAL_ENVMAPS="$HOME/.obt-global/envmaps"
+mkdir -p "$_GLOBAL_ENVMAPS"
+if [ ! -e "$DEPLOY_ROOT/envmaps" ]; then
+  ln -s "$_GLOBAL_ENVMAPS" "$DEPLOY_ROOT/envmaps"
+fi
+
+# Source user/machine-specific configuration (audio devices, CDN keys, etc.)
+if [ -f "$DEPLOY_ROOT/obt_config/env.common.sh" ]; then
+  source "$DEPLOY_ROOT/obt_config/env.common.sh"
+fi
+
+# Discover projects: any directory under projects/ that contains obt.project/
+OBT_PROJECT_ARGS=()
+for proj_dir in "$DEPLOY_ROOT/projects"/*/; do
+  if [ -d "${proj_dir}obt.project" ]; then
+    # Strip trailing slash for clean path
+    OBT_PROJECT_ARGS+=(--project "${proj_dir%/}")
+  fi
+done
+
+# Detect CPU core count
+NUM_CORES=$(sysctl -n hw.ncpu 2>/dev/null || nproc 2>/dev/null || echo 4)
+
+# Launch OBT environment — invoke python explicitly to bypass hardcoded shebangs
+exec "$DEPLOY_ROOT/obt_venv/bin/python3" \
+  "$DEPLOY_ROOT/obt_venv/bin/obt.env.launch.py" \
+  --stagedir "$DEPLOY_ROOT" \
+  --numcores "$NUM_CORES" \
+  "${OBT_PROJECT_ARGS[@]}" \
+  "$@"

orkid_bundle/obt_config/env.common.sh

@@ -0,0 +1,8 @@
+# env.common.sh — generated by deploy from project manifests
+# This file is sourced by obt-launch-env before launching OBT.
+
+export ORKID_AUDIO_FRAMESIZE="128"
+export ORKID_AUDIO_INPUT_DEVICE="MacBook Pro Microphone"
+export ORKID_AUDIO_OUTPUT_DEVICE="MacBook Pro Speakers"
+export ORKID_GRAPHICS_API="VULKAN"
+export MVK_CONFIG_LOG_LEVEL="0"

orkid_bundle/projects/manifest.json

@@ -0,0 +1,17 @@
+{
+  "projects": [
+    {
+      "name": "orkid",
+      "canonical_name": "orkid",
+      "source": "/Users/michael/projects/orkid",
+      "dirs": [
+        "obt.project",
+        "ork.core/pyext/tests",
+        "ork.lev2/examples/python",
+        "ork.lev2/pyext/tests",
+        "ork.ecs/examples/python",
+        "ork.data"
+      ]
+    }
+  ]
+}

orkid_bundle/projects/orkid/obt.project/.gitignore

@@ -0,0 +1,2 @@
+*.pyc
+

orkid_bundle/projects/orkid/obt.project/bin/_blender_impl_export_character.py

@@ -0,0 +1,10 @@
+# to be executed from ork.blender.export.character.py
+
+from obt.path import Path
+from ork import blender
+import os
+
+inp_file = Path(os.environ["BLENDER_FILE_PATH"])
+out_file = Path(os.environ["EXPORT_PATH"])
+
+blender.export_character_mesh(inp_file, out_file)

orkid_bundle/projects/orkid/obt.project/bin/_debug_helpers.py

@@ -0,0 +1,52 @@
+import os, re
+
+####################################################################
+
+def find_executable(exec_name):
+  """Find the executable in PATH or use the provided path."""
+  exec_name = os.path.expandvars(exec_name)
+  if exec_name.startswith(("./", "../")) or os.path.isabs(exec_name):
+    full_path = os.path.abspath(exec_name)
+    if os.path.exists(full_path) and os.access(full_path, os.X_OK):
+      return full_path
+    return None
+  for path in os.environ["PATH"].split(os.pathsep):
+    full_path = os.path.join(path, exec_name)
+    if os.path.exists(full_path) and os.access(full_path, os.X_OK):
+      return full_path
+  if os.path.exists(exec_name) and os.access(exec_name, os.X_OK):
+    return exec_name
+  return None
+
+####################################################################
+
+def is_python_script(executable_path):
+  """Determine if the given file is a Python script."""
+  try:
+    with open(executable_path, 'r') as f:
+      first_line = f.readline().strip()
+      return first_line.startswith("#!") and "python" in first_line
+  except Exception as e:
+    return False
+
+####################################################################
+
+def get_exec_and_args(parse_args):
+  executable_path = find_executable(parse_args.executable_name)
+
+  if not executable_path:
+    print(f"Executable '{parse_args.executable_name}' not found in $PATH.")
+    exit(1)
+
+  exec_args = parse_args.exec_args
+
+  if is_python_script(executable_path):
+    python_path = find_executable("ork.python")
+    if not python_path:
+      print("python3 not found.")
+      exit(1)
+    exec_args.insert(0, executable_path)
+    executable_path = os.path.realpath(python_path)
+
+  exec_name = re.sub(r"[^a-zA-Z0-9]", "_", parse_args.executable_name)
+  return executable_path, exec_args, exec_name

orkid_bundle/projects/orkid/obt.project/bin/_ork.hypermesh.validate.py

@@ -0,0 +1,280 @@
+#!/usr/bin/env ork.python
+################################################################################
+# Copyright 1996-2026, Michael T. Mayers. MIT License.
+################################################################################
+# _ork.hypermesh.validate.py — OFFSCREEN hypermesh asset validator (the subprocess ork.hypermesh.viewer.py
+# --watch spawns on a file change). It loads the asset, renders it offscreen through the SAME scene path
+# the viewer uses (headless StandardSceneGraphComponent), captures the rendered frame, runs a cheap
+# content check, and EXITS with a code the parent reads to decide whether the asset is safe to live-reload:
+#
+#   exit 0  PASS    — rendered, content present   -> parent reloads
+#   exit 2  BLANK   — rendered but empty/flat      -> parent skips (asset is structurally fine but draws nothing)
+#   exit 3  ERROR   — exception while loading/rendering
+#   exit 4  TIMEOUT — GPU capture never completed
+# It also prints "HMVALIDATE_RESULT=PASS|BLANK|ERROR|TIMEOUT" to stdout BEFORE teardown, so the decision
+# survives even if GPU teardown SIGABRTs (exit-134 history) — the parent prefers that token.
+#
+#   ork.python obt.project/bin/_ork.hypermesh.validate.py RippleGrid ; echo "rc=$?"
+#
+# -o ROUTES BY EXTENSION (works headless with ANY hypermesh asset, search- or -i path-mode):
+#   -o foo.obj  -> materialize the asset + dump the MESH to foo.obj (the headless equivalent of the
+#                  viewer's [O] key; no GUI needed). Skips the pixel/content check.
+#   -o foo.png  -> dump the captured RENDER frame to foo.png (the original render diagnostic).
+#   ./_ork.hypermesh.validate.py racer -o /tmp/racer.obj
+################################################################################
+import os; os.environ["PYTHONUNBUFFERED"] = "1"
+import sys, time
+from orkengine.core import vec3, CrcStringProxy   # core MUST import before lev2
+from orkengine import lev2
+from ork.app.application import ComponentizedApplication
+from ork.app.std_scenegraph import StandardSceneGraphComponent
+from ork.hypergraph.dflow.hypermesh import make_drawable
+from ork.hypergraph.assets.hypermesh._resolve import (
+    resolve_asset, load_asset_from_path, EXIT_OK, EXIT_BLANK, EXIT_LOAD_ERROR, EXIT_TIMEOUT, EXIT_VETFAIL,
+    RESULT_TOKEN)
+
+tokens = CrcStringProxy()
+
+DIM            = 512    # offscreen render dimension
+WARMUP_FRAMES  = 4      # minimal frames before the first capture poll
+POLL_EVERY     = 8      # frames between capture+inspect polls
+SETTLE_S       = 0.75   # once a frame is non-black, keep rendering this long before finalizing (lets the
+                        # async IBL envmap finish loading + any blocking shader recompiles settle) — time
+                        # ALONE is unreliable, so we gate on actual pixel content, then settle from there
+APPEAR_TIMEOUT_S = 15.0 # max wall-time waiting for ANY content to appear -> else BLANK
+CAP_TIMEOUT_S  = 6.0    # max wait for a single GPU readback -> TIMEOUT
+NB_MIN         = 0.005  # >=0.5% of sampled px must differ from the (corner-estimated) background.
+                        # NOT 2%: sparse-but-REAL geometry reads low (delete_demo's open bowl = a dim
+                        # interior, 1.4% of samples) and was false-negatived as BLANK; a true blank is
+                        # 0% and a flat fill is still rejected by SPREAD_MIN, so 0.5% loses no safety.
+SPREAD_MIN     = 0.03   # AND luminance spread >= this (rejects a flat single-color fill)
+
+
+class ValidatorApp(ComponentizedApplication):
+  def __init__(self, asset_name, asset_path=None, png_path=None, obj_path=None):
+    super().__init__()
+    self._asset_name = asset_name
+    self._asset_path = asset_path   # -i: load from this explicit .py path (overrides search)
+    self._label      = asset_path or asset_name
+    self._png_path   = png_path     # -o *.png: dump the captured frame to this PNG (diagnostic)
+    self._obj_path   = obj_path     # -o *.obj: dump the materialized mesh to this OBJ (any asset)
+    self._obj_written = False
+    self._result     = EXIT_LOAD_ERROR   # pessimistic until proven otherwise
+    self._token      = "ERROR"
+    self._frame       = 0
+    self._future      = None
+    self._capbuf      = None
+    self._cap_start   = 0.0
+    self._done        = False
+    self._want_exit   = False  # set by _finish; the actual signalExit() is issued from onGpuPostFrame, so
+                               # an error during _onGpuInit doesn't signalExit before the loop is running
+                               # (which crashes teardown) — it exits cleanly on the first frame instead
+    self._start_time  = 0.0    # when rendering began (first post-frame)
+    self._next_poll   = 0      # next frame index to start a capture poll
+    self._saw_content = False  # have we seen a non-black frame yet?
+    self._content_at  = 0.0    # wall-time of the first non-black frame
+    def _env_vec3(name, dflt):                        # HMVAL_EYE / HMVAL_TGT = "x,y,z" to orbit the inspect cam
+      s = os.environ.get(name)
+      if not s: return dflt
+      p = [float(c) for c in s.replace(" ", "").split(",")]
+      return vec3(p[0], p[1], p[2])
+    self.SGC = self.addComponent("std_scenegraph", StandardSceneGraphComponent,
+                                 eye=_env_vec3("HMVAL_EYE", vec3(6, 5, 9)),
+                                 tgt=_env_vec3("HMVAL_TGT", vec3(0, 0, 0)), up=vec3(0, 1, 0),
+                                 grid_variant=None)
+    # lockstep mode (mirrors the working ork.lev2/pyext/tests/movie/complex.py): forces offscreen AND
+    # composites each frame into fbi->_main_rtg — the buffer the movie recorder / our capture reads.
+    self.createEzApp(enable_lockstep_ups=True, enable_lockstep_fps=True,
+                     enable_freerun_ups=True, enable_freerun_fps=True,
+                     freerun=False, target_ups=60, target_fps=60,
+                     width=DIM, height=DIM,
+                     use_subsystems=['opq', 'core', 'gpu', 'lev2'])
+
+  def _finish(self, code, token):
+    if self._done:
+      return
+    self._result    = code
+    self._token     = token
+    self._done      = True
+    self._want_exit = True                    # signalExit() issued from onGpuPostFrame (loop running)
+    print(RESULT_TOKEN + token, flush=True)   # emit the decision BEFORE any teardown (survives SIGABRT)
+    if self._obj_written:                      # the kept OBJ = the last poll's write (= the captured frame)
+      print("hmvalidate: dumped OBJ -> %s (verts=%d faces=%d)"
+            % (self._obj_path, self._live.mesh.num_verts, self._live.mesh.num_faces), flush=True)
+
+  def _onGpuInit(self, ctx):
+    self._ctx = ctx
+    self.ezapp.topWidget.enableUiDraw()   # OFFSCREEN: a windowed app enables UI draw by default; we must
+                                          # do it explicitly so the SGC viewport composites into _main_rtg.
+    try:
+      asset_cls   = (load_asset_from_path(self._asset_path) if self._asset_path
+                     else resolve_asset(self._asset_name))     # -i path OR search-mode stem
+      self._asset_cls = asset_cls                              # meshvet: VET expectations + baseline location
+      import inspect
+      try:    self._asset_file = self._asset_path or inspect.getsourcefile(asset_cls)
+      except Exception: self._asset_file = self._asset_path
+      self._asset = asset_cls()
+      self._live  = self._asset.materialize_live(ctx)            # may raise on a bad graph -> ERROR
+      cdd, _gmtl  = make_drawable(self._live, ctx, animated=False, material_cls=None,
+                                  instances=getattr(self._asset, "instances", None))  # asset opts into instancing
+      self.node   = self.SGC.layer_fwd.createDrawableNodeFromData("hmvalidate", cdd)
+      # keep the skybox LOADED (it's the IBL light source — the geometry must be lit to be visible) but
+      # DON'T render it, so the background stays black for the content check.
+      self.SGC.pbr_common.enable_skybox = False
+      print("hmvalidate: %s materialized verts=%d faces=%d"
+            % (self._label, self._live.mesh.num_verts, self._live.mesh.num_faces), flush=True)
+    except Exception as e:
+      import traceback; traceback.print_exc()
+      print("hmvalidate: load/materialize error: %s" % e, flush=True)
+      self._finish(EXIT_LOAD_ERROR, "ERROR")
+
+  def _onUpdate(self, updinfo):
+    if not self._done:
+      self.SGC.scenegraph.updateScene(self.SGC.cameralut)
+
+  # onGpuPostFrame is wired to the CONTEXT post-frame callback (ezapp.cpp:1172) — the exact point the movie
+  # recorder captures fbi->_main_rtg from (ezapp.cpp:1393). Capturing main_RTG here (after super() lets the
+  # SGC composite) gets the finished frame; capturing earlier (e.g. _onGpuUpdate) reads an unrendered buffer.
+  def onGpuPostFrame(self, ctx):
+    super().onGpuPostFrame(ctx)        # broadcast to components (SGC renders the scene into its viewport RTG)
+    if self._want_exit:                # deferred clean exit (issued here, never from _onGpuInit)
+      self._want_exit = False
+      self.ezapp.signalExit()
+      return
+    if self._done:
+      return
+    self._frame += 1
+    now = time.time()
+    if self._start_time == 0.0:
+      self._start_time = now
+    try:
+      # --- no capture in flight: start a poll every POLL_EVERY frames ---
+      if self._future is None:
+        if self._frame >= WARMUP_FRAMES and self._frame >= self._next_poll:
+          # the SGC viewport renders the scene into its OWN surface RTG (not the window's _main_rtg).
+          rtg = getattr(self.SGC.SGVPW, "rtgroup", None)
+          if rtg is None or rtg.numBuffers < 1:
+            if now - self._start_time > APPEAR_TIMEOUT_S:
+              print("hmvalidate: viewport RTG never ready", flush=True)
+              self._finish(EXIT_BLANK, "BLANK")
+            return
+          self._capbuf = lev2.CaptureBuffer()
+          self._future = ctx.FBI.captureAsFormat(rtg.buffer(0), self._capbuf, "RGBA8")
+          # -o dumps on the SAME frame as the capture (last poll's write = the kept one = the settled frame),
+          # so the OBJ mesh corresponds exactly to the rendered frame / PNG (matters for animated assets).
+          if self._png_path:
+            from orkengine.core import Path as _CorePath
+            ctx.FBI.captureToFile(rtg.buffer(0), _CorePath(self._png_path))
+          if self._obj_path:
+            lev2.hypermesh.dump_obj(self._live.mesh, ctx, self._obj_path)
+            self._obj_written = True
+          self._cap_start = now
+        return
+      # --- capture in flight: wait for the readback ---
+      if not self._future.is_ready:
+        if now - self._cap_start > CAP_TIMEOUT_S:
+          print("hmvalidate: capture timeout", flush=True)
+          self._finish(EXIT_TIMEOUT, "TIMEOUT")
+        return
+      # --- readback ready: inspect this poll ---
+      has = _content_check(self._capbuf)
+      self._future = None
+      self._capbuf = None
+      self._next_poll = self._frame + POLL_EVERY
+      if has:
+        if not self._saw_content:
+          self._saw_content = True
+          self._content_at  = now
+          print("hmvalidate: first content at frame %d (t=%.2fs) — settling %.2fs"
+                % (self._frame, now - self._start_time, SETTLE_S), flush=True)
+        elif now - self._content_at >= SETTLE_S:         # content present + settled -> safe
+          self._finish(EXIT_OK, "PASS")
+      else:
+        self._saw_content = False                        # require content to be STABLE across the settle
+        if now - self._start_time > APPEAR_TIMEOUT_S:    # never got (stable) content -> blank
+          self._finish(EXIT_BLANK, "BLANK")
+    except Exception as e:
+      import traceback; traceback.print_exc()
+      print("hmvalidate: capture/render error: %s" % e, flush=True)
+      self._finish(EXIT_LOAD_ERROR, "ERROR")
+
+
+def _content_check(capbuf):
+  """True if the captured RGBA8 frame shows actual geometry: >=NB_MIN of sampled pixels differ from the
+  corner-estimated background AND luminance spread >= SPREAD_MIN (rejects a flat single-color fill)."""
+  w, h = capbuf.width, capbuf.height
+  data = bytes(capbuf)                       # buffer protocol -> RGBA8, len == w*h*4
+  if w <= 0 or h <= 0 or len(data) < w * h * 4:
+    print("hmvalidate: capture buffer empty (w=%d h=%d len=%d)" % (w, h, len(data)), flush=True)
+    return False
+  def px(x, y):
+    o = (y * w + x) * 4
+    return data[o], data[o + 1], data[o + 2]
+  cor = [px(0, 0), px(w - 1, 0), px(0, h - 1), px(w - 1, h - 1)]   # background = the 4 corners
+  bg  = (sum(c[0] for c in cor) // 4, sum(c[1] for c in cor) // 4, sum(c[2] for c in cor) // 4)
+  sx, sy = max(1, w // 32), max(1, h // 32)
+  n = nb = 0
+  lmin, lmax = 1e9, -1e9
+  y = 0
+  while y < h:
+    x = 0
+    while x < w:
+      r, g, b = px(x, y)
+      n += 1
+      if max(abs(r - bg[0]), abs(g - bg[1]), abs(b - bg[2])) > 12:
+        nb += 1
+      lum  = 0.299 * r + 0.587 * g + 0.114 * b
+      lmin = min(lmin, lum); lmax = max(lmax, lum)
+      x += sx
+    y += sy
+  nb_frac = nb / max(1, n)
+  spread  = (lmax - lmin) / 255.0
+  return (nb_frac >= NB_MIN) and (spread >= SPREAD_MIN)
+
+
+def main():
+  import argparse
+  ap = argparse.ArgumentParser(description="offscreen hypermesh asset validator")
+  ap.add_argument("asset", nargs="?", help="asset filename stem (search mode)")
+  ap.add_argument("-i", "--input", default=None, help="explicit path to an asset .py (overrides search)")
+  ap.add_argument("-o", "--out", default=None,
+                  help="dump output, routed by extension: <name>.obj -> the materialized MESH as OBJ "
+                       "(works with ANY hypermesh asset); <name>.png -> the captured frame (render diagnostic)")
+  ap.add_argument("--bless", action="store_true",
+                  help="freeze the CURRENT (visually approved) mesh as the golden baseline next to the asset "
+                       "(<asset_dir>/.vet/<stem>.vetbase.npz); subsequent vet runs FAIL on drift until re-blessed")
+  ap.add_argument("--no-vet", action="store_true", help="skip the meshvet geometric tier (escape hatch)")
+  a = ap.parse_args()
+  if not a.input and not a.asset:
+    print("usage: _ork.hypermesh.validate.py <ASSET_NAME> | -i <path.py>  [-o <out.obj|out.png>] [--bless]", flush=True)
+    return EXIT_LOAD_ERROR
+  out = a.out
+  obj_path = out if (out and out.lower().endswith(".obj")) else None      # -o *.obj  -> mesh OBJ dump
+  png_path = out if (out and not obj_path) else None                      # -o *.png  -> frame capture
+  app = ValidatorApp(a.asset, asset_path=a.input, png_path=png_path, obj_path=obj_path)
+  app.ezapp.mainThreadLoop()    # runs until _finish() -> signalExit()
+  app.ezapp.shutdown()
+  rc = app._result
+  # -o *.obj: run the dumped mesh through the MESHVET geometric tier (structural + crossing self-
+  # intersection + buried/flip parity + collapse/sliver + fan-fold + VET expectations + golden baseline).
+  # A FAIL must BLOCK the watch live-reload: the parent prefers the LAST result token in stdout, so we
+  # OVERRIDE the earlier render-tier PASS with VETFAIL (crash-after-render still fails open, as designed).
+  if obj_path and rc == EXIT_OK and app._obj_written and not a.no_vet:
+    from ork.hypergraph.dflow.hypermesh import meshvet
+    stem = (os.path.splitext(os.path.basename(app._asset_file))[0]
+            if getattr(app, "_asset_file", None) else (a.asset or "asset"))
+    expectations = dict(getattr(getattr(app, "_asset_cls", None), "VET", None) or {})
+    verdict, report = meshvet.run(obj_path,
+                                  asset_py=getattr(app, "_asset_file", None), stem=stem,
+                                  expectations=expectations, bless=a.bless)
+    print(report, flush=True)
+    if verdict == meshvet.FAIL:
+      print("\033[1;31mHMVALIDATE_GEOMETRY=FAIL\033[0m — the mesh is not well-formed (see above).", flush=True)
+      print(RESULT_TOKEN + "VETFAIL", flush=True)        # LAST token wins in the parent -> blocks live-reload
+      return EXIT_VETFAIL
+    print("HMVALIDATE_GEOMETRY=%s" % verdict, flush=True)
+  return rc
+
+
+if __name__ == "__main__":
+  sys.exit(main())