Initial mirror of localai-org/motion-bricks.cpp@6fdb75e

.gitignore

@@ -0,0 +1,10 @@
+/build/
+/dist/
+/generated/
+/models/
+/fixtures/
+/.cache/
+/.direnv/
+/result
+compile_commands.json
+__pycache__/

.gitmodules

@@ -0,0 +1,3 @@
+[submodule "ggml"]
+	path = ggml
+	url = https://github.com/ggml-org/ggml.git

CMakeLists.txt

@@ -0,0 +1,141 @@
+cmake_minimum_required(VERSION 3.25)
+project(motionbricks VERSION 0.1.0 LANGUAGES C CXX)
+
+set(CMAKE_C_STANDARD 11)
+set(CMAKE_C_STANDARD_REQUIRED ON)
+set(CMAKE_C_EXTENSIONS OFF)
+set(CMAKE_CXX_STANDARD 23)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+set(CMAKE_CXX_EXTENSIONS OFF)
+
+include(GNUInstallDirs)
+
+option(MOTIONBRICKS_BUILD_TESTS "Build motion-bricks.cpp tests" ON)
+option(MOTIONBRICKS_ENABLE_GGML "Use the pinned GGML submodule when present" ON)
+option(MOTIONBRICKS_ENABLE_VULKAN "Enable the GGML Vulkan backend" ON)
+option(MOTIONBRICKS_ENABLE_FUZZERS "Build libFuzzer targets" OFF)
+option(MOTIONBRICKS_SANITIZE "Enable AddressSanitizer and UndefinedBehaviorSanitizer" OFF)
+option(MOTIONBRICKS_DOWNLOAD_MODELS "Download and verify the published runtime model/style bundle" ON)
+set(MOTIONBRICKS_GGML_SOURCE_DIR "${CMAKE_CURRENT_SOURCE_DIR}/ggml" CACHE PATH
+    "Pinned GGML submodule source directory")
+set(MOTIONBRICKS_MODEL_REPOSITORY "LocalAI-io/MotionBricks-G1-GGML" CACHE STRING
+    "Hugging Face repository containing the runtime bundle")
+set(MOTIONBRICKS_MODEL_REVISION "cc2a47603dbc203a4f18f35dd06ed3611833f506" CACHE STRING
+    "Pinned Hugging Face revision containing the runtime bundle")
+set(MOTIONBRICKS_REFERENCE_BUNDLE "${CMAKE_CURRENT_SOURCE_DIR}/generated/g1-f32" CACHE PATH
+    "Downloaded or locally converted MotionBricks runtime bundle")
+set(MOTIONBRICKS_REFERENCE_STYLES "${CMAKE_CURRENT_SOURCE_DIR}/generated/styles" CACHE PATH
+    "Downloaded or locally converted MotionBricks style bundle")
+
+if(MOTIONBRICKS_ENABLE_GGML AND MOTIONBRICKS_DOWNLOAD_MODELS)
+    find_package(Python3 COMPONENTS Interpreter REQUIRED)
+    execute_process(
+        COMMAND "${Python3_EXECUTABLE}" "${CMAKE_CURRENT_SOURCE_DIR}/scripts/download_gguf_weights.py"
+            --output "${CMAKE_CURRENT_SOURCE_DIR}/generated"
+            --repo "${MOTIONBRICKS_MODEL_REPOSITORY}"
+            --revision "${MOTIONBRICKS_MODEL_REVISION}"
+        RESULT_VARIABLE MOTIONBRICKS_MODEL_DOWNLOAD_RESULT
+        COMMAND_ECHO STDOUT)
+    if(NOT MOTIONBRICKS_MODEL_DOWNLOAD_RESULT EQUAL 0)
+        message(FATAL_ERROR
+            "MotionBricks model download/verification failed. Set "
+            "MOTIONBRICKS_DOWNLOAD_MODELS=OFF for a source-only build.")
+    endif()
+endif()
+
+set(MOTIONBRICKS_SOURCES
+    src/capi.cpp
+    src/decoder.cpp
+    src/error.cpp
+    src/model.cpp
+    src/neural_runtime.cpp
+    src/pose.cpp)
+list(APPEND MOTIONBRICKS_SOURCES src/root.cpp)
+list(APPEND MOTIONBRICKS_SOURCES src/motion_rep.cpp)
+list(APPEND MOTIONBRICKS_SOURCES src/planner.cpp)
+list(APPEND MOTIONBRICKS_SOURCES src/style.cpp)
+list(APPEND MOTIONBRICKS_SOURCES src/agent.cpp)
+
+add_library(motionbricks_shared SHARED ${MOTIONBRICKS_SOURCES})
+add_library(motionbricks::motionbricks ALIAS motionbricks_shared)
+set_target_properties(motionbricks_shared PROPERTIES
+    OUTPUT_NAME motionbricks
+    EXPORT_NAME motionbricks
+    CXX_VISIBILITY_PRESET hidden
+    VISIBILITY_INLINES_HIDDEN YES
+    VERSION ${PROJECT_VERSION}
+    SOVERSION 0)
+target_compile_definitions(motionbricks_shared PRIVATE MOTIONBRICKS_BUILD MOTIONBRICKS_SHARED)
+
+add_library(motionbricks_static STATIC ${MOTIONBRICKS_SOURCES})
+add_library(motionbricks::motionbricks_static ALIAS motionbricks_static)
+set_target_properties(motionbricks_static PROPERTIES
+    OUTPUT_NAME motionbricks
+    EXPORT_NAME motionbricks_static)
+target_compile_definitions(motionbricks_static PRIVATE MOTIONBRICKS_BUILD)
+
+foreach(target motionbricks_shared motionbricks_static)
+    target_include_directories(${target}
+        PUBLIC
+            "$<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include>"
+            "$<INSTALL_INTERFACE:${CMAKE_INSTALL_INCLUDEDIR}>"
+        PRIVATE "${CMAKE_CURRENT_SOURCE_DIR}/src")
+    if(MSVC)
+        target_compile_options(${target} PRIVATE /W4 /permissive-)
+    else()
+        target_compile_options(${target} PRIVATE
+            -Wall -Wextra -Wpedantic -Wconversion -Wshadow)
+    endif()
+endforeach()
+
+if(MOTIONBRICKS_ENABLE_GGML)
+    if(EXISTS "${MOTIONBRICKS_GGML_SOURCE_DIR}/CMakeLists.txt")
+        set(GGML_BUILD_TESTS OFF CACHE BOOL "" FORCE)
+        set(GGML_BUILD_EXAMPLES OFF CACHE BOOL "" FORCE)
+        set(GGML_NATIVE OFF CACHE BOOL "" FORCE)
+        set(GGML_VULKAN ${MOTIONBRICKS_ENABLE_VULKAN} CACHE BOOL "" FORCE)
+        set(GGML_BACKEND_DL OFF CACHE BOOL "" FORCE)
+        add_subdirectory("${MOTIONBRICKS_GGML_SOURCE_DIR}"
+                         "${CMAKE_BINARY_DIR}/ggml" EXCLUDE_FROM_ALL)
+        # GGML is currently an internal build-tree dependency. Its installed
+        # runtime/package contract will be added with the first neural graph.
+        target_link_libraries(motionbricks_shared PRIVATE "$<BUILD_INTERFACE:ggml>")
+        target_link_libraries(motionbricks_static PRIVATE "$<BUILD_INTERFACE:ggml>")
+        target_compile_definitions(motionbricks_shared PRIVATE MOTIONBRICKS_HAVE_GGML=1)
+        target_compile_definitions(motionbricks_static PRIVATE MOTIONBRICKS_HAVE_GGML=1)
+        if(MOTIONBRICKS_ENABLE_VULKAN AND TARGET ggml-vulkan)
+            target_link_libraries(motionbricks_shared PRIVATE "$<BUILD_INTERFACE:ggml-vulkan>")
+            target_link_libraries(motionbricks_static PRIVATE "$<BUILD_INTERFACE:ggml-vulkan>")
+            target_compile_definitions(motionbricks_shared PRIVATE MOTIONBRICKS_HAVE_VULKAN=1)
+            target_compile_definitions(motionbricks_static PRIVATE MOTIONBRICKS_HAVE_VULKAN=1)
+        endif()
+    else()
+        message(STATUS "GGML submodule not present; building the ABI scaffold only")
+    endif()
+endif()
+
+if(MOTIONBRICKS_SANITIZE)
+    if(MSVC)
+        message(FATAL_ERROR "MOTIONBRICKS_SANITIZE currently requires Clang or GCC")
+    endif()
+    foreach(target motionbricks_shared motionbricks_static)
+        target_compile_options(${target} PRIVATE -fsanitize=address,undefined -fno-omit-frame-pointer)
+        target_link_options(${target} PRIVATE -fsanitize=address,undefined)
+    endforeach()
+endif()
+
+add_executable(motionbricks-cli src/cli.cpp)
+target_link_libraries(motionbricks-cli PRIVATE motionbricks::motionbricks)
+set_target_properties(motionbricks-cli PROPERTIES
+    RUNTIME_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}/bin")
+
+include(CTest)
+if(BUILD_TESTING AND MOTIONBRICKS_BUILD_TESTS)
+    add_subdirectory(tests)
+endif()
+
+install(TARGETS motionbricks_shared motionbricks_static motionbricks-cli
+    RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR}
+    LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR}
+    ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR})
+install(DIRECTORY include/ DESTINATION ${CMAKE_INSTALL_INCLUDEDIR})

CMakePresets.json

@@ -0,0 +1,50 @@
+{
+  "version": 6,
+  "configurePresets": [
+    {
+      "name": "debug",
+      "generator": "Ninja",
+      "binaryDir": "${sourceDir}/build/debug",
+      "cacheVariables": {
+        "CMAKE_BUILD_TYPE": "Debug",
+        "CMAKE_EXPORT_COMPILE_COMMANDS": "ON"
+      }
+    },
+    {
+      "name": "release",
+      "generator": "Ninja",
+      "binaryDir": "${sourceDir}/build/release",
+      "cacheVariables": {
+        "CMAKE_BUILD_TYPE": "Release"
+      }
+    },
+    {
+      "name": "asan-ubsan",
+      "inherits": "debug",
+      "binaryDir": "${sourceDir}/build/asan-ubsan",
+      "cacheVariables": {
+        "CMAKE_C_COMPILER": "clang",
+        "CMAKE_CXX_COMPILER": "clang++",
+        "MOTIONBRICKS_ENABLE_VULKAN": "OFF",
+        "MOTIONBRICKS_SANITIZE": "ON"
+      }
+    }
+  ],
+  "buildPresets": [
+    {"name": "debug", "configurePreset": "debug"},
+    {"name": "release", "configurePreset": "release"},
+    {"name": "asan-ubsan", "configurePreset": "asan-ubsan"}
+  ],
+  "testPresets": [
+    {
+      "name": "debug",
+      "configurePreset": "debug",
+      "output": {"outputOnFailure": true}
+    },
+    {
+      "name": "asan-ubsan",
+      "configurePreset": "asan-ubsan",
+      "output": {"outputOnFailure": true}
+    }
+  ]
+}

FORK_PROVENANCE.md

@@ -0,0 +1,11 @@
+# Fork provenance
+
+- **Upstream:** `localai-org/motion-bricks.cpp (github)`
+- **Upstream commit / SHA:** `6fdb75e15ddb7f97dd1a4abb8017a57b936bc7a3`
+- **License:** Apache-2.0
+- **Kind:** Code mirror
+- **Workspace consumer:** MotionBricks-G1-GGML (converter/inference)
+- **Forked to:** `chibifire/motion-bricks.cpp`
+- **Forked on:** 2026-09-05
+- **Author:** Ernest Lee <ernest.lee@chibifire.com>
+- **Reason:** shipping-surface completeness under our own HF org so a base/source we depend on cannot disappear or relicense out from under us

LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

README.md

@@ -0,0 +1,161 @@
+# motion-bricks.cpp
+
+A C++23/GGML port of NVIDIA MotionBricks for CPU and Vulkan inference, with a
+stable C ABI suitable for PureGo.
+
+The released batch-one G1 inference path is implemented end to end: strict
+GGUF loading, root/duration planning, pose-token prediction, VQ decoding,
+418/414/413 feature conversion, style alignment, and skeletal animation
+output. CPU and Vulkan use the same public API and preserve the same duration
+and pose-token decisions in the reference suite.
+
+## Build
+
+The normal build uses CMake and does not depend on Nix:
+
+```sh
+cmake --preset debug
+cmake --build --preset debug
+ctest --preset debug
+```
+
+Configuration downloads and SHA-256-verifies the published 0.73 GB G1 F32
+GGUF and style bundles into `generated/` when they are not already present.
+The same operation can be run explicitly:
+
+```sh
+python scripts/download_gguf_weights.py
+```
+
+For an offline or source-only build, preserve an existing local bundle or use
+`cmake --preset debug -DMOTIONBRICKS_DOWNLOAD_MODELS=OFF`. The repository and
+revision are configurable with `MOTIONBRICKS_MODEL_REPOSITORY` and
+`MOTIONBRICKS_MODEL_REVISION`.
+
+On NixOS, enter the reproducible development shell first:
+
+```sh
+nix develop
+cmake --preset debug
+cmake --build --preset debug
+ctest --preset debug
+```
+
+When the pinned `ggml/` submodule is present, it is included automatically.
+The non-neural ABI and validation subset can also be built without GGML:
+
+```sh
+cmake -S . -B build/debug -G Ninja -DMOTIONBRICKS_ENABLE_GGML=OFF
+```
+
+The Go binding and demo use PureGo to load `libmotionbricks` at runtime; they
+do not use cgo or `import "C"`. Once the native shared library has been built,
+the Go components therefore need no C compiler and can be built with cgo
+explicitly disabled:
+
+```sh
+cd demo
+CGO_ENABLED=0 go build -o ../build/debug/bin/motionbricks-demo .
+```
+
+`CGO_ENABLED=0` is optional but recommended for making this property explicit
+in builds and CI. It affects only the Go build—the native C++ library is still
+built separately with CMake.
+
+The sanitizer lane is:
+
+```sh
+cmake --preset asan-ubsan
+cmake --build --preset asan-ubsan
+ctest --preset asan-ubsan
+```
+
+## Current ABI
+
+The installed C API uses only fixed-width scalars, pointers, and opaque heap
+handles. Callers never reproduce a C or C++ structure layout. All constructors
+have matching free functions, and no C++ exception crosses the ABI boundary.
+
+The current CLI can report ABI information:
+
+```sh
+./build/debug/bin/motionbricks-cli abi
+```
+
+After producing the trusted safetensors intermediates described in
+`reference/README.md`, build and inspect an F32 runtime bundle with:
+
+```sh
+python scripts/convert_to_gguf.py \
+  --safe-directory generated/safe \
+  --output generated/g1-f32
+./build/debug/bin/motionbricks-cli inspect generated/g1-f32
+```
+
+The released G1 inference path contains exactly **183,148,382 learned F32
+parameters**. The bundle loader validates the upstream revision, source
+checkpoint identities, component roles, tensor counts, parameter counts,
+anchor shapes, and the 34-joint parent topology before accepting a model.
+
+Convert the 15 original demo styles with:
+
+```sh
+python scripts/convert_styles.py \
+  --safe-directory generated/safe \
+  --output generated/styles
+```
+
+At runtime the high-level flow is: load one immutable model, load one or more
+`.mbstyle` assets, create an agent, reset it from an initial style (or supply
+at least four frames of G1 context), set movement/facing/style on a command,
+then call `mb_agent_plan`. The returned motion owns row-major F32 root
+translations `[frames,3]` and local XYZW rotations `[frames,34,4]`. Call
+`mb_agent_advance` as playback progresses so replanning uses the generated
+motion as its next context.
+
+The current implementation covers original preprocessed G1 styles. Direct
+Kimodo GLB-to-`.mbstyle` conversion remains subsequent integration work.
+
+## Weights
+
+Ready-to-run native weights and all 15 upstream style primitives are published
+as [MotionBricks-G1-GGML](https://huggingface.co/LocalAI-io/MotionBricks-G1-GGML)
+under the Hugging Face `LocalAI-io` organisation. NVIDIA currently distributes
+MotionBricks checkpoints through Git LFS in
+[`NVlabs/GR00T-WholeBodyControl`](https://github.com/NVlabs/GR00T-WholeBodyControl/tree/a0732b642c0333077e127a2f56ab0014c196bca4/motionbricks),
+not a separate Hugging Face model repository, so the model card links to that
+pinned upstream revision. The downloader verifies the version-controlled
+distribution manifest before accepting any file.
+
+The default build is pinned to Hugging Face commit
+`cc2a47603dbc203a4f18f35dd06ed3611833f506` rather than the mutable `main`
+branch.
+
+## Interactive demo
+
+The initial Go/Three.js demo renders the model's 34-joint skeleton alongside
+the four actual placed target-keyframe ghosts. It lets you steer with W/A/S/D,
+turn facing with the arrow keys, orbit/zoom the camera, and switch among the
+converted upstream styles. It uses the reusable PureGo binding and the same
+stateful native agent as other applications. See the
+[demo guide](docs/DEMO.md) for build, run, architecture, and headless-Chromium
+test instructions.
+
+## Design
+
+- [Human-led design](docs/motions-bricks.md)
+- [Implementation sketch and plan](docs/IMPLEMENTATION.md)
+- [Versioned formats](docs/FORMATS.md)
+- [Go/Three.js demo](docs/DEMO.md)
+- [Pinned upstream reference](reference/README.md)
+
+## License
+
+motion-bricks.cpp source code is licensed under the
+[Apache License 2.0](LICENSE). NVIDIA's original model weights and converted
+GGUF/style distributions remain under the NVIDIA Open Model License reproduced
+with the published model. It permits derivative models and redistribution with
+conditions including retention of the agreement and attribution, Trustworthy
+AI terms, and trade compliance. Bundled third-party components retain their own
+licenses; the vendored Three.js files are covered by
+`demo/web/vendor/THREE-LICENSE.txt`.

bindings/go/abi_test.go

@@ -0,0 +1,104 @@
+//go:build linux || darwin || freebsd
+
+package motionbricks
+
+import (
+	"math"
+	"os"
+	"testing"
+	"unsafe"
+
+	"github.com/ebitengine/purego"
+)
+
+const (
+	statusOK      = uint32(0)
+	deviceAuto    = uint32(0)
+	deviceVulkan  = uint32(2)
+	abiVersion    = uint32(1)
+	errorCapacity = uint64(256)
+)
+
+// TestOpaqueABIRoundTrip intentionally mirrors no C struct. Every object is an
+// opaque uintptr and every record field is accessed through a function.
+func TestOpaqueABIRoundTrip(t *testing.T) {
+	library := os.Getenv("MOTIONBRICKS_LIB")
+	if library == "" {
+		t.Skip("set MOTIONBRICKS_LIB to the motion-bricks.cpp shared library")
+	}
+
+	handle, err := purego.Dlopen(library, purego.RTLD_NOW|purego.RTLD_LOCAL)
+	if err != nil {
+		t.Fatalf("dlopen %s: %v", library, err)
+	}
+	defer purego.Dlclose(handle)
+
+	var version func() uint32
+	var optionsCreate func(unsafe.Pointer, unsafe.Pointer, uint64) uint32
+	var optionsFree func(uintptr)
+	var optionsSetDevice func(uintptr, uint32, unsafe.Pointer, uint64) uint32
+	var optionsGetDevice func(uintptr, unsafe.Pointer, unsafe.Pointer, uint64) uint32
+	var commandCreate func(unsafe.Pointer, unsafe.Pointer, uint64) uint32
+	var commandFree func(uintptr)
+	var commandSetMovement func(uintptr, float32, float32, float32, unsafe.Pointer, uint64) uint32
+	var commandGetMovement func(uintptr, unsafe.Pointer, unsafe.Pointer, unsafe.Pointer, unsafe.Pointer, uint64) uint32
+
+	purego.RegisterLibFunc(&version, handle, "mb_abi_version")
+	purego.RegisterLibFunc(&optionsCreate, handle, "mb_runtime_options_create")
+	purego.RegisterLibFunc(&optionsFree, handle, "mb_runtime_options_free")
+	purego.RegisterLibFunc(&optionsSetDevice, handle, "mb_runtime_options_set_device")
+	purego.RegisterLibFunc(&optionsGetDevice, handle, "mb_runtime_options_get_device")
+	purego.RegisterLibFunc(&commandCreate, handle, "mb_command_create")
+	purego.RegisterLibFunc(&commandFree, handle, "mb_command_free")
+	purego.RegisterLibFunc(&commandSetMovement, handle, "mb_command_set_movement_direction")
+	purego.RegisterLibFunc(&commandGetMovement, handle, "mb_command_get_movement_direction")
+
+	if got := version(); got != abiVersion {
+		t.Fatalf("ABI version = %d, want %d", got, abiVersion)
+	}
+
+	errorBuffer := make([]byte, errorCapacity)
+	errorPointer := unsafe.Pointer(&errorBuffer[0])
+	var options uintptr
+	if status := optionsCreate(unsafe.Pointer(&options), errorPointer, errorCapacity); status != statusOK {
+		t.Fatalf("options create status %d: %q", status, errorBuffer)
+	}
+	if options == 0 {
+		t.Fatal("options create returned a null handle")
+	}
+	defer optionsFree(options)
+
+	var device uint32 = math.MaxUint32
+	if status := optionsGetDevice(options, unsafe.Pointer(&device), errorPointer, errorCapacity); status != statusOK {
+		t.Fatalf("get default device status %d", status)
+	}
+	if device != deviceAuto {
+		t.Fatalf("default device = %d, want auto", device)
+	}
+	if status := optionsSetDevice(options, deviceVulkan, errorPointer, errorCapacity); status != statusOK {
+		t.Fatalf("set Vulkan status %d", status)
+	}
+	if status := optionsGetDevice(options, unsafe.Pointer(&device), errorPointer, errorCapacity); status != statusOK || device != deviceVulkan {
+		t.Fatalf("Vulkan round trip status=%d device=%d", status, device)
+	}
+
+	var command uintptr
+	if status := commandCreate(unsafe.Pointer(&command), errorPointer, errorCapacity); status != statusOK {
+		t.Fatalf("command create status %d", status)
+	}
+	if command == 0 {
+		t.Fatal("command create returned a null handle")
+	}
+	defer commandFree(command)
+
+	if status := commandSetMovement(command, 1.0, 0.0, -0.25, errorPointer, errorCapacity); status != statusOK {
+		t.Fatalf("set movement status %d", status)
+	}
+	var x, y, z float32
+	if status := commandGetMovement(command, unsafe.Pointer(&x), unsafe.Pointer(&y), unsafe.Pointer(&z), errorPointer, errorCapacity); status != statusOK {
+		t.Fatalf("get movement status %d", status)
+	}
+	if x != 1.0 || y != 0.0 || z != -0.25 {
+		t.Fatalf("movement = (%g, %g, %g)", x, y, z)
+	}
+}

bindings/go/go.mod

@@ -0,0 +1,5 @@
+module github.com/localai/motion-bricks.cpp/bindings/go
+
+go 1.23
+
+require github.com/ebitengine/purego v0.10.0

bindings/go/go.sum

@@ -0,0 +1,2 @@
+github.com/ebitengine/purego v0.10.0 h1:QIw4xfpWT6GWTzaW5XEKy3HXoqrJGx1ijYHzTF0/ISU=
+github.com/ebitengine/purego v0.10.0/go.mod h1:iIjxzd6CiRiOG0UyXP+V1+jWqUXVjPKLAI0mRfJZTmQ=

bindings/go/motionbricks.go

@@ -0,0 +1,410 @@
+//go:build linux || darwin || freebsd
+
+// Package motionbricks provides a PureGo wrapper around the stable opaque C ABI.
+package motionbricks
+
+import (
+	"errors"
+	"fmt"
+	"math"
+	"unsafe"
+
+	"github.com/ebitengine/purego"
+)
+
+type Device uint32
+
+const (
+	DeviceAuto   Device = 0
+	DeviceCPU    Device = 1
+	DeviceVulkan Device = 2
+)
+
+const errorBufferSize = 1024
+
+type Library struct {
+	handle                uintptr
+	abiVersion            func() uint32
+	statusString          func(uint32) uintptr
+	optionsCreate         func(unsafe.Pointer, unsafe.Pointer, uint64) uint32
+	optionsFree           func(uintptr)
+	optionsSetDevice      func(uintptr, uint32, unsafe.Pointer, uint64) uint32
+	modelLoad             func(unsafe.Pointer, uintptr, unsafe.Pointer, unsafe.Pointer, uint64) uint32
+	modelFree             func(uintptr)
+	modelJointCount       func(uintptr, unsafe.Pointer, unsafe.Pointer, uint64) uint32
+	modelJointName        func(uintptr, uint32, unsafe.Pointer, unsafe.Pointer, uint64) uint32
+	modelJointParent      func(uintptr, uint32, unsafe.Pointer, unsafe.Pointer, uint64) uint32
+	modelNeutralPosition  func(uintptr, uint32, unsafe.Pointer, unsafe.Pointer, unsafe.Pointer, unsafe.Pointer, uint64) uint32
+	styleLoad             func(uintptr, unsafe.Pointer, unsafe.Pointer, unsafe.Pointer, uint64) uint32
+	styleFree             func(uintptr)
+	styleName             func(uintptr, unsafe.Pointer, unsafe.Pointer, uint64) uint32
+	styleSpeed            func(uintptr, unsafe.Pointer, unsafe.Pointer, uint64) uint32
+	agentCreate           func(uintptr, unsafe.Pointer, unsafe.Pointer, uint64) uint32
+	agentFree             func(uintptr)
+	agentReset            func(uintptr, uintptr, unsafe.Pointer, uint64) uint32
+	agentSetContext       func(uintptr, unsafe.Pointer, unsafe.Pointer, uint64, uint64, unsafe.Pointer, uint64) uint32
+	agentPlan             func(uintptr, uintptr, unsafe.Pointer, unsafe.Pointer, uint64) uint32
+	agentAdvance          func(uintptr, uint32, unsafe.Pointer, uint64) uint32
+	commandCreate         func(unsafe.Pointer, unsafe.Pointer, uint64) uint32
+	commandFree           func(uintptr)
+	commandSetStyle       func(uintptr, uintptr, unsafe.Pointer, uint64) uint32
+	commandSetMovement    func(uintptr, float32, float32, float32, unsafe.Pointer, uint64) uint32
+	commandSetFacing      func(uintptr, float32, float32, float32, unsafe.Pointer, uint64) uint32
+	commandSetSpeed       func(uintptr, float32, unsafe.Pointer, uint64) uint32
+	commandSetWorldTarget func(uintptr, float32, float32, float32, float32, uint32, unsafe.Pointer, uint64) uint32
+	commandSetSeed        func(uintptr, uint64, unsafe.Pointer, uint64) uint32
+	motionFree            func(uintptr)
+	motionFrames          func(uintptr, unsafe.Pointer, unsafe.Pointer, uint64) uint32
+	motionJoints          func(uintptr, unsafe.Pointer, unsafe.Pointer, uint64) uint32
+	motionRoots           func(uintptr, unsafe.Pointer, unsafe.Pointer, unsafe.Pointer, uint64) uint32
+	motionRotations       func(uintptr, unsafe.Pointer, unsafe.Pointer, unsafe.Pointer, uint64) uint32
+	motionTargetFrames    func(uintptr, unsafe.Pointer, unsafe.Pointer, uint64) uint32
+	motionTargetRoots     func(uintptr, unsafe.Pointer, unsafe.Pointer, unsafe.Pointer, uint64) uint32
+	motionTargetRotations func(uintptr, unsafe.Pointer, unsafe.Pointer, unsafe.Pointer, uint64) uint32
+}
+
+func Open(path string) (*Library, error) {
+	handle, err := purego.Dlopen(path, purego.RTLD_NOW|purego.RTLD_LOCAL)
+	if err != nil {
+		return nil, err
+	}
+	library := &Library{handle: handle}
+	register := func(target any, name string) { purego.RegisterLibFunc(target, handle, name) }
+	register(&library.abiVersion, "mb_abi_version")
+	register(&library.statusString, "mb_status_string")
+	register(&library.optionsCreate, "mb_runtime_options_create")
+	register(&library.optionsFree, "mb_runtime_options_free")
+	register(&library.optionsSetDevice, "mb_runtime_options_set_device")
+	register(&library.modelLoad, "mb_model_load")
+	register(&library.modelFree, "mb_model_free")
+	register(&library.modelJointCount, "mb_model_get_joint_count")
+	register(&library.modelJointName, "mb_model_get_joint_name")
+	register(&library.modelJointParent, "mb_model_get_joint_parent")
+	register(&library.modelNeutralPosition, "mb_model_get_neutral_joint_position")
+	register(&library.styleLoad, "mb_style_load")
+	register(&library.styleFree, "mb_style_free")
+	register(&library.styleName, "mb_style_get_name")
+	register(&library.styleSpeed, "mb_style_get_speed")
+	register(&library.agentCreate, "mb_agent_create")
+	register(&library.agentFree, "mb_agent_free")
+	register(&library.agentReset, "mb_agent_reset")
+	register(&library.agentSetContext, "mb_agent_set_context")
+	register(&library.agentPlan, "mb_agent_plan")
+	register(&library.agentAdvance, "mb_agent_advance")
+	register(&library.commandCreate, "mb_command_create")
+	register(&library.commandFree, "mb_command_free")
+	register(&library.commandSetStyle, "mb_command_set_style")
+	register(&library.commandSetMovement, "mb_command_set_movement_direction")
+	register(&library.commandSetFacing, "mb_command_set_facing_direction")
+	register(&library.commandSetSpeed, "mb_command_set_target_speed")
+	register(&library.commandSetWorldTarget, "mb_command_set_world_target")
+	register(&library.commandSetSeed, "mb_command_set_seed")
+	register(&library.motionFree, "mb_motion_free")
+	register(&library.motionFrames, "mb_motion_get_frame_count")
+	register(&library.motionJoints, "mb_motion_get_joint_count")
+	register(&library.motionRoots, "mb_motion_get_root_translations")
+	register(&library.motionRotations, "mb_motion_get_local_rotations_xyzw")
+	register(&library.motionTargetFrames, "mb_motion_get_target_frame_count")
+	register(&library.motionTargetRoots, "mb_motion_get_target_root_translations")
+	register(&library.motionTargetRotations, "mb_motion_get_target_local_rotations_xyzw")
+	if version := library.abiVersion(); version != 1 {
+		library.Close()
+		return nil, fmt.Errorf("motionbricks ABI version %d is unsupported", version)
+	}
+	return library, nil
+}
+
+func (l *Library) Close() error {
+	if l == nil || l.handle == 0 {
+		return nil
+	}
+	err := purego.Dlclose(l.handle)
+	l.handle = 0
+	return err
+}
+
+func cString(value string) ([]byte, error) {
+	for _, char := range value {
+		if char == 0 {
+			return nil, errors.New("string contains NUL")
+		}
+	}
+	return append([]byte(value), 0), nil
+}
+
+func goString(pointer uintptr) string {
+	if pointer == 0 {
+		return ""
+	}
+	const maximum = 1 << 20
+	bytes := make([]byte, 0, 64)
+	for index := uintptr(0); index < maximum; index++ {
+		value := *(*byte)(unsafe.Pointer(pointer + index))
+		if value == 0 {
+			return string(bytes)
+		}
+		bytes = append(bytes, value)
+	}
+	return ""
+}
+
+func errorPointer(buffer []byte) unsafe.Pointer { return unsafe.Pointer(&buffer[0]) }
+
+func (l *Library) check(operation string, status uint32, buffer []byte) error {
+	if status == 0 {
+		return nil
+	}
+	message := ""
+	for index, value := range buffer {
+		if value == 0 {
+			message = string(buffer[:index])
+			break
+		}
+	}
+	if message == "" {
+		message = goString(l.statusString(status))
+	}
+	return fmt.Errorf("%s: %s", operation, message)
+}
+
+type Model struct {
+	library *Library
+	handle  uintptr
+}
+type Style struct {
+	library *Library
+	handle  uintptr
+	Name    string
+	Speed   float32
+}
+type Agent struct {
+	model  *Model
+	handle uintptr
+}
+type Command struct {
+	library *Library
+	handle  uintptr
+}
+
+type Joint struct {
+	Name     string     `json:"name"`
+	Parent   int32      `json:"parent"`
+	Position [3]float32 `json:"position"`
+}
+type Motion struct {
+	Frames    uint64     `json:"frames"`
+	Joints    uint64     `json:"joints"`
+	Roots     []float32  `json:"roots"`
+	Rotations []float32  `json:"rotations"`
+	Targets   *Keyframes `json:"-"`
+}
+type Keyframes struct {
+	Frames    uint64    `json:"frames"`
+	Joints    uint64    `json:"joints"`
+	Roots     []float32 `json:"roots"`
+	Rotations []float32 `json:"rotations"`
+}
+
+func (l *Library) LoadModel(path string, device Device) (*Model, error) {
+	pathBytes, err := cString(path)
+	if err != nil {
+		return nil, err
+	}
+	buffer := make([]byte, errorBufferSize)
+	var options uintptr
+	if err = l.check("create runtime options", l.optionsCreate(unsafe.Pointer(&options), errorPointer(buffer), uint64(len(buffer))), buffer); err != nil {
+		return nil, err
+	}
+	defer l.optionsFree(options)
+	if err = l.check("select device", l.optionsSetDevice(options, uint32(device), errorPointer(buffer), uint64(len(buffer))), buffer); err != nil {
+		return nil, err
+	}
+	var handle uintptr
+	status := l.modelLoad(unsafe.Pointer(&pathBytes[0]), options, unsafe.Pointer(&handle), errorPointer(buffer), uint64(len(buffer)))
+	if err = l.check("load model", status, buffer); err != nil {
+		return nil, err
+	}
+	return &Model{library: l, handle: handle}, nil
+}
+
+func (m *Model) Close() {
+	if m != nil && m.handle != 0 {
+		m.library.modelFree(m.handle)
+		m.handle = 0
+	}
+}
+
+func (m *Model) Skeleton() ([]Joint, error) {
+	buffer := make([]byte, errorBufferSize)
+	var count uint32
+	if err := m.library.check("get joint count", m.library.modelJointCount(m.handle, unsafe.Pointer(&count), errorPointer(buffer), uint64(len(buffer))), buffer); err != nil {
+		return nil, err
+	}
+	joints := make([]Joint, count)
+	for index := uint32(0); index < count; index++ {
+		var name uintptr
+		if err := m.library.check("get joint name", m.library.modelJointName(m.handle, index, unsafe.Pointer(&name), errorPointer(buffer), uint64(len(buffer))), buffer); err != nil {
+			return nil, err
+		}
+		joints[index].Name = goString(name)
+		if err := m.library.check("get joint parent", m.library.modelJointParent(m.handle, index, unsafe.Pointer(&joints[index].Parent), errorPointer(buffer), uint64(len(buffer))), buffer); err != nil {
+			return nil, err
+		}
+		position := &joints[index].Position
+		if err := m.library.check("get neutral position", m.library.modelNeutralPosition(m.handle, index, unsafe.Pointer(&position[0]), unsafe.Pointer(&position[1]), unsafe.Pointer(&position[2]), errorPointer(buffer), uint64(len(buffer))), buffer); err != nil {
+			return nil, err
+		}
+	}
+	return joints, nil
+}
+
+func (m *Model) LoadStyle(path string) (*Style, error) {
+	pathBytes, err := cString(path)
+	if err != nil {
+		return nil, err
+	}
+	buffer := make([]byte, errorBufferSize)
+	var handle uintptr
+	if err = m.library.check("load style", m.library.styleLoad(m.handle, unsafe.Pointer(&pathBytes[0]), unsafe.Pointer(&handle), errorPointer(buffer), uint64(len(buffer))), buffer); err != nil {
+		return nil, err
+	}
+	style := &Style{library: m.library, handle: handle}
+	var name uintptr
+	if err = m.library.check("get style name", m.library.styleName(handle, unsafe.Pointer(&name), errorPointer(buffer), uint64(len(buffer))), buffer); err != nil {
+		style.Close()
+		return nil, err
+	}
+	style.Name = goString(name)
+	if err = m.library.check("get style speed", m.library.styleSpeed(handle, unsafe.Pointer(&style.Speed), errorPointer(buffer), uint64(len(buffer))), buffer); err != nil {
+		style.Close()
+		return nil, err
+	}
+	return style, nil
+}
+
+func (s *Style) Close() {
+	if s != nil && s.handle != 0 {
+		s.library.styleFree(s.handle)
+		s.handle = 0
+	}
+}
+
+func (m *Model) NewAgent() (*Agent, error) {
+	buffer := make([]byte, errorBufferSize)
+	var handle uintptr
+	if err := m.library.check("create agent", m.library.agentCreate(m.handle, unsafe.Pointer(&handle), errorPointer(buffer), uint64(len(buffer))), buffer); err != nil {
+		return nil, err
+	}
+	return &Agent{model: m, handle: handle}, nil
+}
+func (a *Agent) Close() {
+	if a != nil && a.handle != 0 {
+		a.model.library.agentFree(a.handle)
+		a.handle = 0
+	}
+}
+func (a *Agent) Reset(style *Style) error {
+	buffer := make([]byte, errorBufferSize)
+	return a.model.library.check("reset agent", a.model.library.agentReset(a.handle, style.handle, errorPointer(buffer), uint64(len(buffer))), buffer)
+}
+func (a *Agent) Advance(frames uint32) error {
+	buffer := make([]byte, errorBufferSize)
+	return a.model.library.check("advance agent", a.model.library.agentAdvance(a.handle, frames, errorPointer(buffer), uint64(len(buffer))), buffer)
+}
+func (a *Agent) SetContext(roots, rotations []float32, frames uint64) error {
+	if frames < 4 || len(roots) != int(frames*3) || len(rotations) != int(frames*34*4) {
+		return errors.New("invalid G1 context shape")
+	}
+	buffer := make([]byte, errorBufferSize)
+	return a.model.library.check("set agent context", a.model.library.agentSetContext(a.handle, unsafe.Pointer(&roots[0]), unsafe.Pointer(&rotations[0]), frames, 34, errorPointer(buffer), uint64(len(buffer))), buffer)
+}
+
+func (l *Library) NewCommand() (*Command, error) {
+	buffer := make([]byte, errorBufferSize)
+	var handle uintptr
+	if err := l.check("create command", l.commandCreate(unsafe.Pointer(&handle), errorPointer(buffer), uint64(len(buffer))), buffer); err != nil {
+		return nil, err
+	}
+	return &Command{library: l, handle: handle}, nil
+}
+func (c *Command) Close() {
+	if c != nil && c.handle != 0 {
+		c.library.commandFree(c.handle)
+		c.handle = 0
+	}
+}
+func (c *Command) SetStyle(style *Style) error {
+	buffer := make([]byte, errorBufferSize)
+	return c.library.check("set command style", c.library.commandSetStyle(c.handle, style.handle, errorPointer(buffer), uint64(len(buffer))), buffer)
+}
+func (c *Command) SetMovement(x, y, z float32) error {
+	buffer := make([]byte, errorBufferSize)
+	return c.library.check("set movement", c.library.commandSetMovement(c.handle, x, y, z, errorPointer(buffer), uint64(len(buffer))), buffer)
+}
+func (c *Command) SetFacing(x, y, z float32) error {
+	buffer := make([]byte, errorBufferSize)
+	return c.library.check("set facing", c.library.commandSetFacing(c.handle, x, y, z, errorPointer(buffer), uint64(len(buffer))), buffer)
+}
+func (c *Command) SetSpeed(speed float32) error {
+	if math.IsNaN(float64(speed)) {
+		return errors.New("speed is NaN")
+	}
+	buffer := make([]byte, errorBufferSize)
+	return c.library.check("set speed", c.library.commandSetSpeed(c.handle, speed, errorPointer(buffer), uint64(len(buffer))), buffer)
+}
+func (c *Command) SetSeed(seed uint64) error {
+	buffer := make([]byte, errorBufferSize)
+	return c.library.check("set seed", c.library.commandSetSeed(c.handle, seed, errorPointer(buffer), uint64(len(buffer))), buffer)
+}
+func (c *Command) SetWorldTarget(x, y, z, heading float32, enabled bool) error {
+	var flag uint32
+	if enabled {
+		flag = 1
+	}
+	buffer := make([]byte, errorBufferSize)
+	return c.library.check("set world target", c.library.commandSetWorldTarget(c.handle, x, y, z, heading, flag, errorPointer(buffer), uint64(len(buffer))), buffer)
+}
+
+func (a *Agent) Plan(command *Command) (*Motion, error) {
+	buffer := make([]byte, errorBufferSize)
+	var handle uintptr
+	if err := a.model.library.check("plan motion", a.model.library.agentPlan(a.handle, command.handle, unsafe.Pointer(&handle), errorPointer(buffer), uint64(len(buffer))), buffer); err != nil {
+		return nil, err
+	}
+	defer a.model.library.motionFree(handle)
+	motion := &Motion{}
+	var rootsPointer, rotationsPointer, targetRootsPointer, targetRotationsPointer uintptr
+	var rootsCount, rotationsCount, targetRootsCount, targetRotationsCount uint64
+	if err := a.model.library.check("get frame count", a.model.library.motionFrames(handle, unsafe.Pointer(&motion.Frames), errorPointer(buffer), uint64(len(buffer))), buffer); err != nil {
+		return nil, err
+	}
+	if err := a.model.library.check("get joint count", a.model.library.motionJoints(handle, unsafe.Pointer(&motion.Joints), errorPointer(buffer), uint64(len(buffer))), buffer); err != nil {
+		return nil, err
+	}
+	if err := a.model.library.check("get roots", a.model.library.motionRoots(handle, unsafe.Pointer(&rootsPointer), unsafe.Pointer(&rootsCount), errorPointer(buffer), uint64(len(buffer))), buffer); err != nil {
+		return nil, err
+	}
+	if err := a.model.library.check("get rotations", a.model.library.motionRotations(handle, unsafe.Pointer(&rotationsPointer), unsafe.Pointer(&rotationsCount), errorPointer(buffer), uint64(len(buffer))), buffer); err != nil {
+		return nil, err
+	}
+	targets := &Keyframes{Joints: motion.Joints}
+	if err := a.model.library.check("get target frame count", a.model.library.motionTargetFrames(handle, unsafe.Pointer(&targets.Frames), errorPointer(buffer), uint64(len(buffer))), buffer); err != nil {
+		return nil, err
+	}
+	if err := a.model.library.check("get target roots", a.model.library.motionTargetRoots(handle, unsafe.Pointer(&targetRootsPointer), unsafe.Pointer(&targetRootsCount), errorPointer(buffer), uint64(len(buffer))), buffer); err != nil {
+		return nil, err
+	}
+	if err := a.model.library.check("get target rotations", a.model.library.motionTargetRotations(handle, unsafe.Pointer(&targetRotationsPointer), unsafe.Pointer(&targetRotationsCount), errorPointer(buffer), uint64(len(buffer))), buffer); err != nil {
+		return nil, err
+	}
+	if rootsCount != motion.Frames*3 || rotationsCount != motion.Frames*motion.Joints*4 ||
+		targetRootsCount != targets.Frames*3 || targetRotationsCount != targets.Frames*targets.Joints*4 {
+		return nil, errors.New("native motion data has inconsistent dimensions")
+	}
+	motion.Roots = append([]float32(nil), unsafe.Slice((*float32)(unsafe.Pointer(rootsPointer)), rootsCount)...)
+	motion.Rotations = append([]float32(nil), unsafe.Slice((*float32)(unsafe.Pointer(rotationsPointer)), rotationsCount)...)
+	targets.Roots = append([]float32(nil), unsafe.Slice((*float32)(unsafe.Pointer(targetRootsPointer)), targetRootsCount)...)
+	targets.Rotations = append([]float32(nil), unsafe.Slice((*float32)(unsafe.Pointer(targetRotationsPointer)), targetRotationsCount)...)
+	motion.Targets = targets
+	return motion, nil
+}

demo/go.mod

@@ -0,0 +1,21 @@
+module github.com/localai/motion-bricks.cpp/demo
+
+go 1.26
+
+require (
+	github.com/chromedp/cdproto v0.0.0-20260714215040-dc233986426f
+	github.com/chromedp/chromedp v0.16.0
+	github.com/localai/motion-bricks.cpp/bindings/go v0.0.0
+)
+
+require (
+	github.com/chromedp/sysutil v1.1.0 // indirect
+	github.com/ebitengine/purego v0.10.0 // indirect
+	github.com/go-json-experiment/json v0.0.0-20260623181947-01eb4420fa68 // indirect
+	github.com/gobwas/httphead v0.1.0 // indirect
+	github.com/gobwas/pool v0.2.1 // indirect
+	github.com/gobwas/ws v1.4.0 // indirect
+	golang.org/x/sys v0.47.0 // indirect
+)
+
+replace github.com/localai/motion-bricks.cpp/bindings/go => ../bindings/go

demo/go.sum

@@ -0,0 +1,23 @@
+github.com/chromedp/cdproto v0.0.0-20260714215040-dc233986426f h1:0Z1zcSLEmnj2c2CmJYBqewtS6pxhB39bNWUSEUAWjgk=
+github.com/chromedp/cdproto v0.0.0-20260714215040-dc233986426f/go.mod h1:RwFsSODCtFExll+GhHM6R92SARHR3Z3oipaxLHj46C0=
+github.com/chromedp/chromedp v0.16.0 h1:rOO4deOm4CbZgBCa8mD9g2rDyIoNs0BkgvNrlbp5ouk=
+github.com/chromedp/chromedp v0.16.0/go.mod h1:rbuGKFT1vMcFcFqKfPIO1GpX/N+2s8onm2qMxZLbU5U=
+github.com/chromedp/sysutil v1.1.0 h1:PUFNv5EcprjqXZD9nJb9b/c9ibAbxiYo4exNWZyipwM=
+github.com/chromedp/sysutil v1.1.0/go.mod h1:WiThHUdltqCNKGc4gaU50XgYjwjYIhKWoHGPTUfWTJ8=
+github.com/ebitengine/purego v0.10.0 h1:QIw4xfpWT6GWTzaW5XEKy3HXoqrJGx1ijYHzTF0/ISU=
+github.com/ebitengine/purego v0.10.0/go.mod h1:iIjxzd6CiRiOG0UyXP+V1+jWqUXVjPKLAI0mRfJZTmQ=
+github.com/go-json-experiment/json v0.0.0-20260623181947-01eb4420fa68 h1:KZaTBSyshWX3MP5jukJcNSuXDQTO+rNpt0J564dX/eg=
+github.com/go-json-experiment/json v0.0.0-20260623181947-01eb4420fa68/go.mod h1:tphK2c80bpPhMOI4v6bIc2xWywPfbqi1Z06+RcrMkDg=
+github.com/gobwas/httphead v0.1.0 h1:exrUm0f4YX0L7EBwZHuCF4GDp8aJfVeBrlLQrs6NqWU=
+github.com/gobwas/httphead v0.1.0/go.mod h1:O/RXo79gxV8G+RqlR/otEwx4Q36zl9rqC5u12GKvMCM=
+github.com/gobwas/pool v0.2.1 h1:xfeeEhW7pwmX8nuLVlqbzVc7udMDrwetjEv+TZIz1og=
+github.com/gobwas/pool v0.2.1/go.mod h1:q8bcK0KcYlCgd9e7WYLm9LpyS+YeLd8JVDW6WezmKEw=
+github.com/gobwas/ws v1.4.0 h1:CTaoG1tojrh4ucGPcoJFiAQUAsEWekEWvLy7GsVNqGs=
+github.com/gobwas/ws v1.4.0/go.mod h1:G3gNqMNtPppf5XUz7O4shetPpcZ1VJ7zt18dlUeakrc=
+github.com/ledongthuc/pdf v0.0.0-20220302134840-0c2507a12d80 h1:6Yzfa6GP0rIo/kULo2bwGEkFvCePZ3qHDDTC3/J9Swo=
+github.com/ledongthuc/pdf v0.0.0-20220302134840-0c2507a12d80/go.mod h1:imJHygn/1yfhB7XSJJKlFZKl/J+dCPAknuiaGOshXAs=
+github.com/orisano/pixelmatch v0.0.0-20220722002657-fb0b55479cde h1:x0TT0RDC7UhAVbbWWBzr41ElhJx5tXPWkIHA2HWPRuw=
+github.com/orisano/pixelmatch v0.0.0-20220722002657-fb0b55479cde/go.mod h1:nZgzbfBr3hhjoZnS66nKrHmduYNpc34ny7RK4z5/HM0=
+golang.org/x/sys v0.6.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/sys v0.47.0 h1:o7XGOvZQCADBQQ4Y7VNq2dRWQR7JmOUW8Kxx4ZsNgWs=
+golang.org/x/sys v0.47.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=

demo/main.go

@@ -0,0 +1,371 @@
+package main
+
+import (
+	"crypto/rand"
+	"embed"
+	"encoding/hex"
+	"encoding/json"
+	"errors"
+	"flag"
+	"fmt"
+	"io"
+	"io/fs"
+	"log"
+	"math"
+	"net/http"
+	"os"
+	"os/signal"
+	"path/filepath"
+	"sort"
+	"strings"
+	"sync"
+	"syscall"
+	"time"
+
+	mb "github.com/localai/motion-bricks.cpp/bindings/go"
+)
+
+//go:embed web/* web/vendor/*
+var webFiles embed.FS
+
+type styleInfo struct {
+	Name  string  `json:"name"`
+	Speed float32 `json:"speed"`
+}
+
+type session struct {
+	mu      sync.Mutex
+	agent   *mb.Agent
+	planned bool
+}
+
+type demoServer struct {
+	library  *mb.Library
+	model    *mb.Model
+	styles   map[string]*mb.Style
+	ordered  []styleInfo
+	joints   []mb.Joint
+	planMu   sync.Mutex
+	mu       sync.Mutex
+	sessions map[string]*session
+	static   http.Handler
+}
+
+type sessionRequest struct {
+	Style string `json:"style"`
+}
+type planRequest struct {
+	Session string     `json:"session"`
+	Style   string     `json:"style"`
+	Move    [2]float32 `json:"move"`
+	Facing  [2]float32 `json:"facing"`
+	Speed   *float32   `json:"speed,omitempty"`
+	Seed    uint64     `json:"seed"`
+	Advance uint32     `json:"advance"`
+}
+type planResponse struct {
+	Session string        `json:"session"`
+	Style   string        `json:"style"`
+	Motion  *mb.Motion    `json:"motion"`
+	Targets *mb.Keyframes `json:"targets"`
+}
+
+func parseDevice(value string) (mb.Device, error) {
+	switch strings.ToLower(value) {
+	case "auto":
+		return mb.DeviceAuto, nil
+	case "cpu":
+		return mb.DeviceCPU, nil
+	case "vulkan":
+		return mb.DeviceVulkan, nil
+	default:
+		return 0, fmt.Errorf("unknown device %q", value)
+	}
+}
+
+func loadDemoServer(libraryPath, modelPath, styleDirectory string, device mb.Device) (*demoServer, error) {
+	library, err := mb.Open(libraryPath)
+	if err != nil {
+		return nil, fmt.Errorf("open native library: %w", err)
+	}
+	model, err := library.LoadModel(modelPath, device)
+	if err != nil {
+		library.Close()
+		return nil, err
+	}
+	paths, err := filepath.Glob(filepath.Join(styleDirectory, "*.mbstyle"))
+	if err != nil || len(paths) == 0 {
+		model.Close()
+		library.Close()
+		return nil, fmt.Errorf("no .mbstyle files in %s", styleDirectory)
+	}
+	sort.Strings(paths)
+	server := &demoServer{library: library, model: model, styles: make(map[string]*mb.Style), sessions: make(map[string]*session)}
+	for _, path := range paths {
+		style, loadErr := model.LoadStyle(path)
+		if loadErr != nil {
+			server.Close()
+			return nil, fmt.Errorf("load %s: %w", path, loadErr)
+		}
+		if _, exists := server.styles[style.Name]; exists {
+			style.Close()
+			server.Close()
+			return nil, fmt.Errorf("duplicate style %q", style.Name)
+		}
+		server.styles[style.Name] = style
+		server.ordered = append(server.ordered, styleInfo{Name: style.Name, Speed: style.Speed})
+	}
+	sort.Slice(server.ordered, func(i, j int) bool { return server.ordered[i].Name < server.ordered[j].Name })
+	server.joints, err = model.Skeleton()
+	if err != nil {
+		server.Close()
+		return nil, err
+	}
+	root, err := fs.Sub(webFiles, "web")
+	if err != nil {
+		server.Close()
+		return nil, err
+	}
+	server.static = http.FileServer(http.FS(root))
+	return server, nil
+}
+
+func (s *demoServer) Close() {
+	if s == nil {
+		return
+	}
+	s.mu.Lock()
+	for _, item := range s.sessions {
+		item.agent.Close()
+	}
+	s.sessions = nil
+	s.mu.Unlock()
+	for _, style := range s.styles {
+		style.Close()
+	}
+	if s.model != nil {
+		s.model.Close()
+	}
+	if s.library != nil {
+		_ = s.library.Close()
+	}
+}
+
+func randomID() (string, error) {
+	var value [16]byte
+	if _, err := rand.Read(value[:]); err != nil {
+		return "", err
+	}
+	return hex.EncodeToString(value[:]), nil
+}
+
+func jsonResponse(writer http.ResponseWriter, status int, value any) {
+	writer.Header().Set("Content-Type", "application/json")
+	writer.Header().Set("Cache-Control", "no-store")
+	writer.WriteHeader(status)
+	_ = json.NewEncoder(writer).Encode(value)
+}
+func apiError(writer http.ResponseWriter, status int, err error) {
+	jsonResponse(writer, status, map[string]string{"error": err.Error()})
+}
+func decodeJSON(request *http.Request, output any) error {
+	decoder := json.NewDecoder(io.LimitReader(request.Body, 1<<20))
+	decoder.DisallowUnknownFields()
+	if err := decoder.Decode(output); err != nil {
+		return fmt.Errorf("invalid JSON: %w", err)
+	}
+	return nil
+}
+func finite(values ...float32) bool {
+	for _, value := range values {
+		if math.IsNaN(float64(value)) || math.IsInf(float64(value), 0) {
+			return false
+		}
+	}
+	return true
+}
+
+func (s *demoServer) style(name string) (*mb.Style, error) {
+	style := s.styles[name]
+	if style == nil {
+		return nil, fmt.Errorf("unknown style %q", name)
+	}
+	return style, nil
+}
+
+func (s *demoServer) commandPlan(item *session, style *mb.Style, request planRequest) (*mb.Motion, error) {
+	if !finite(request.Move[0], request.Move[1], request.Facing[0], request.Facing[1]) {
+		return nil, errors.New("control vector is not finite")
+	}
+	if math.Hypot(float64(request.Facing[0]), float64(request.Facing[1])) < 1e-6 {
+		return nil, errors.New("facing vector is zero")
+	}
+	item.mu.Lock()
+	defer item.mu.Unlock()
+	if item.planned && request.Advance > 0 {
+		if err := item.agent.Advance(request.Advance); err != nil {
+			return nil, err
+		}
+	}
+	command, err := s.library.NewCommand()
+	if err != nil {
+		return nil, err
+	}
+	defer command.Close()
+	if err = command.SetStyle(style); err != nil {
+		return nil, err
+	}
+	if err = command.SetMovement(request.Move[0], 0, request.Move[1]); err != nil {
+		return nil, err
+	}
+	if err = command.SetFacing(request.Facing[0], 0, request.Facing[1]); err != nil {
+		return nil, err
+	}
+	if request.Speed != nil {
+		if !finite(*request.Speed) || *request.Speed < 0 {
+			return nil, errors.New("speed is invalid")
+		}
+		if err = command.SetSpeed(*request.Speed); err != nil {
+			return nil, err
+		}
+	}
+	if err = command.SetSeed(request.Seed); err != nil {
+		return nil, err
+	}
+	s.planMu.Lock()
+	motion, err := item.agent.Plan(command)
+	s.planMu.Unlock()
+	if err == nil {
+		item.planned = true
+	}
+	return motion, err
+}
+
+func (s *demoServer) routes() http.Handler {
+	mux := http.NewServeMux()
+	mux.HandleFunc("GET /api/health", func(w http.ResponseWriter, _ *http.Request) {
+		jsonResponse(w, http.StatusOK, map[string]any{"ok": true})
+	})
+	mux.HandleFunc("GET /api/meta", func(w http.ResponseWriter, _ *http.Request) {
+		jsonResponse(w, http.StatusOK, map[string]any{"fps": 30, "joints": s.joints, "styles": s.ordered})
+	})
+	mux.HandleFunc("POST /api/session", s.createSession)
+	mux.HandleFunc("POST /api/plan", s.plan)
+	mux.Handle("/", s.static)
+	return securityHeaders(mux)
+}
+
+func securityHeaders(next http.Handler) http.Handler {
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Cache-Control", "no-store")
+		w.Header().Set("X-Content-Type-Options", "nosniff")
+		w.Header().Set("Referrer-Policy", "no-referrer")
+		w.Header().Set("Content-Security-Policy", "default-src 'self'; script-src 'self'; style-src 'self'; img-src 'self' data:; connect-src 'self'")
+		next.ServeHTTP(w, r)
+	})
+}
+
+func (s *demoServer) createSession(w http.ResponseWriter, r *http.Request) {
+	var request sessionRequest
+	if err := decodeJSON(r, &request); err != nil {
+		apiError(w, http.StatusBadRequest, err)
+		return
+	}
+	if request.Style == "" {
+		if _, ok := s.styles["idle"]; ok {
+			request.Style = "idle"
+		} else {
+			request.Style = s.ordered[0].Name
+		}
+	}
+	style, err := s.style(request.Style)
+	if err != nil {
+		apiError(w, http.StatusBadRequest, err)
+		return
+	}
+	agent, err := s.model.NewAgent()
+	if err != nil {
+		apiError(w, http.StatusInternalServerError, err)
+		return
+	}
+	if err = agent.Reset(style); err != nil {
+		agent.Close()
+		apiError(w, http.StatusInternalServerError, err)
+		return
+	}
+	id, err := randomID()
+	if err != nil {
+		agent.Close()
+		apiError(w, http.StatusInternalServerError, err)
+		return
+	}
+	item := &session{agent: agent}
+	s.mu.Lock()
+	s.sessions[id] = item
+	s.mu.Unlock()
+	motion, err := s.commandPlan(item, style, planRequest{Move: [2]float32{0, 0}, Facing: [2]float32{0, 1}, Seed: 1})
+	if err != nil {
+		s.mu.Lock()
+		delete(s.sessions, id)
+		s.mu.Unlock()
+		agent.Close()
+		apiError(w, http.StatusInternalServerError, err)
+		return
+	}
+	jsonResponse(w, http.StatusOK, planResponse{Session: id, Style: style.Name, Motion: motion, Targets: motion.Targets})
+}
+
+func (s *demoServer) plan(w http.ResponseWriter, r *http.Request) {
+	var request planRequest
+	if err := decodeJSON(r, &request); err != nil {
+		apiError(w, http.StatusBadRequest, err)
+		return
+	}
+	s.mu.Lock()
+	item := s.sessions[request.Session]
+	s.mu.Unlock()
+	if item == nil {
+		apiError(w, http.StatusNotFound, errors.New("unknown session"))
+		return
+	}
+	style, err := s.style(request.Style)
+	if err != nil {
+		apiError(w, http.StatusBadRequest, err)
+		return
+	}
+	motion, err := s.commandPlan(item, style, request)
+	if err != nil {
+		apiError(w, http.StatusInternalServerError, err)
+		return
+	}
+	jsonResponse(w, http.StatusOK, planResponse{Session: request.Session, Style: style.Name, Motion: motion, Targets: motion.Targets})
+}
+
+func main() {
+	listen := flag.String("listen", "127.0.0.1:8080", "HTTP listen address")
+	libraryPath := flag.String("library", os.Getenv("MOTIONBRICKS_LIB"), "path to libmotionbricks")
+	modelPath := flag.String("model", os.Getenv("MOTIONBRICKS_MODEL"), "model bundle directory")
+	stylesPath := flag.String("styles", os.Getenv("MOTIONBRICKS_STYLES"), "style directory")
+	deviceName := flag.String("device", "cpu", "auto, cpu, or vulkan")
+	flag.Parse()
+	if *libraryPath == "" || *modelPath == "" || *stylesPath == "" {
+		log.Fatal("-library, -model, and -styles are required")
+	}
+	device, err := parseDevice(*deviceName)
+	if err != nil {
+		log.Fatal(err)
+	}
+	demo, err := loadDemoServer(*libraryPath, *modelPath, *stylesPath, device)
+	if err != nil {
+		log.Fatal(err)
+	}
+	defer demo.Close()
+	server := &http.Server{Addr: *listen, Handler: demo.routes(), ReadHeaderTimeout: 5 * time.Second}
+	stopped := make(chan os.Signal, 1)
+	signal.Notify(stopped, os.Interrupt, syscall.SIGTERM)
+	go func() { <-stopped; _ = server.Close() }()
+	log.Printf("MotionBricks demo: http://%s", *listen)
+	if err = server.ListenAndServe(); err != nil && !errors.Is(err, http.ErrServerClosed) {
+		log.Fatal(err)
+	}
+}

demo/main_test.go

@@ -0,0 +1,236 @@
+package main
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+
+	cdplog "github.com/chromedp/cdproto/log"
+	"github.com/chromedp/cdproto/runtime"
+	"github.com/chromedp/chromedp"
+	mb "github.com/localai/motion-bricks.cpp/bindings/go"
+)
+
+func TestParseDevice(t *testing.T) {
+	for name, expected := range map[string]mb.Device{"auto": mb.DeviceAuto, "cpu": mb.DeviceCPU, "vulkan": mb.DeviceVulkan, "CPU": mb.DeviceCPU} {
+		actual, err := parseDevice(name)
+		if err != nil || actual != expected {
+			t.Fatalf("parseDevice(%q)=(%d,%v), want %d", name, actual, err, expected)
+		}
+	}
+	if _, err := parseDevice("cuda"); err == nil {
+		t.Fatal("unknown device was accepted")
+	}
+}
+
+func TestNativeHTTPFlow(t *testing.T) {
+	libraryPath, modelPath, stylesPath := os.Getenv("MOTIONBRICKS_LIB"), os.Getenv("MOTIONBRICKS_MODEL"), os.Getenv("MOTIONBRICKS_STYLES")
+	if libraryPath == "" || modelPath == "" || stylesPath == "" {
+		t.Skip("native demo paths are not configured")
+	}
+	demo, err := loadDemoServer(libraryPath, modelPath, stylesPath, mb.DeviceCPU)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer demo.Close()
+	server := httptest.NewServer(demo.routes())
+	defer server.Close()
+	response, err := http.Get(server.URL + "/api/meta")
+	if err != nil {
+		t.Fatal(err)
+	}
+	var metadata struct {
+		FPS    int         `json:"fps"`
+		Joints []mb.Joint  `json:"joints"`
+		Styles []styleInfo `json:"styles"`
+	}
+	if err = json.NewDecoder(response.Body).Decode(&metadata); err != nil {
+		t.Fatal(err)
+	}
+	response.Body.Close()
+	if response.StatusCode != http.StatusOK || metadata.FPS != 30 || len(metadata.Joints) != 34 || len(metadata.Styles) < 10 {
+		t.Fatalf("invalid metadata: status=%d fps=%d joints=%d styles=%d", response.StatusCode, metadata.FPS, len(metadata.Joints), len(metadata.Styles))
+	}
+	post := func(path string, value any, output any) {
+		t.Helper()
+		body, _ := json.Marshal(value)
+		reply, postErr := http.Post(server.URL+path, "application/json", bytes.NewReader(body))
+		if postErr != nil {
+			t.Fatal(postErr)
+		}
+		defer reply.Body.Close()
+		if reply.StatusCode != http.StatusOK {
+			var failure any
+			_ = json.NewDecoder(reply.Body).Decode(&failure)
+			t.Fatalf("%s: status=%d body=%v", path, reply.StatusCode, failure)
+		}
+		if err := json.NewDecoder(reply.Body).Decode(output); err != nil {
+			t.Fatal(err)
+		}
+	}
+	var initial planResponse
+	post("/api/session", sessionRequest{Style: "walk"}, &initial)
+	if initial.Session == "" || initial.Motion == nil || initial.Motion.Joints != 34 || initial.Motion.Frames < 24 ||
+		initial.Targets == nil || initial.Targets.Frames != 4 || initial.Targets.Joints != 34 ||
+		len(initial.Targets.Roots) != 12 || len(initial.Targets.Rotations) != 4*34*4 {
+		t.Fatalf("invalid initial response: %+v", initial)
+	}
+	turnedStyle := ""
+	for _, style := range metadata.Styles {
+		if style.Name == "walk_zombie" {
+			turnedStyle = style.Name
+			break
+		}
+		if style.Name != "walk" && turnedStyle == "" {
+			turnedStyle = style.Name
+		}
+	}
+	if turnedStyle == "" {
+		t.Fatal("no alternate upstream style is available")
+	}
+	var turned planResponse
+	post("/api/plan", planRequest{Session: initial.Session, Style: turnedStyle, Move: [2]float32{1, 0}, Facing: [2]float32{1, 0}, Advance: 3, Seed: 77}, &turned)
+	if turned.Style != turnedStyle || turned.Motion == nil || turned.Motion.Joints != 34 || len(turned.Motion.Rotations) != int(turned.Motion.Frames*34*4) ||
+		turned.Targets == nil || turned.Targets.Frames != 4 || len(turned.Targets.Rotations) != 4*34*4 {
+		t.Fatalf("invalid turned response: style=%q motion=%+v", turned.Style, turned.Motion)
+	}
+}
+
+func TestHeadlessChrome(t *testing.T) {
+	libraryPath, modelPath, stylesPath := os.Getenv("MOTIONBRICKS_LIB"), os.Getenv("MOTIONBRICKS_MODEL"), os.Getenv("MOTIONBRICKS_STYLES")
+	if libraryPath == "" || modelPath == "" || stylesPath == "" {
+		t.Skip("native demo paths are not configured")
+	}
+	chrome := os.Getenv("MOTIONBRICKS_CHROME")
+	if chrome == "" {
+		var err error
+		chrome, err = exec.LookPath("chromium")
+		if err != nil {
+			t.Skip("chromium is not installed")
+		}
+	}
+	demo, err := loadDemoServer(libraryPath, modelPath, stylesPath, mb.DeviceCPU)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer demo.Close()
+	server := httptest.NewServer(demo.routes())
+	defer server.Close()
+
+	options := append([]chromedp.ExecAllocatorOption{}, chromedp.DefaultExecAllocatorOptions[:]...)
+	options = append(options,
+		chromedp.ExecPath(chrome),
+		chromedp.Flag("no-sandbox", true),
+		chromedp.Flag("disable-dev-shm-usage", true),
+		chromedp.Flag("use-angle", "swiftshader"),
+		chromedp.Flag("enable-unsafe-swiftshader", true),
+		chromedp.WindowSize(1280, 800),
+	)
+	allocator, cancelAllocator := chromedp.NewExecAllocator(context.Background(), options...)
+	defer cancelAllocator()
+	browser, cancelBrowser := chromedp.NewContext(allocator)
+	defer cancelBrowser()
+	chromedp.ListenTarget(browser, func(event any) {
+		switch event := event.(type) {
+		case *cdplog.EventEntryAdded:
+			t.Logf("browser log: %s", event.Entry.Text)
+		case *runtime.EventConsoleAPICalled:
+			t.Logf("browser console: %v", event.Args)
+		case *runtime.EventExceptionThrown:
+			t.Logf("browser exception: %s", event.ExceptionDetails.Text)
+		}
+	})
+	ctx, cancel := context.WithTimeout(browser, 30*time.Second)
+	defer cancel()
+
+	waitFor := func(expression, description string) chromedp.Action {
+		return chromedp.ActionFunc(func(ctx context.Context) error {
+			deadline := time.Now().Add(25 * time.Second)
+			for time.Now().Before(deadline) {
+				var ready bool
+				if evaluateErr := chromedp.Evaluate(expression, &ready).Do(ctx); evaluateErr != nil {
+					return evaluateErr
+				}
+				if ready {
+					return nil
+				}
+				time.Sleep(100 * time.Millisecond)
+			}
+			var diagnostic any
+			_ = chromedp.Evaluate(`({status: document.documentElement.dataset.testStatus, sequence: document.documentElement.dataset.planSequence, moveX: document.documentElement.dataset.plannedMoveX, moveZ: document.documentElement.dataset.plannedMoveZ, scripts: [...document.scripts].map(s => ({src:s.src,type:s.type})), resources: performance.getEntriesByType("resource").map(r => r.name)})`, &diagnostic).Do(ctx)
+			return fmt.Errorf("%w for %s: %#v", errors.New("timeout waiting for browser"), description, diagnostic)
+		})
+	}
+	var initialScreenshot, movingScreenshot, screenshot []byte
+	var message string
+	err = chromedp.Run(ctx,
+		chromedp.ActionFunc(func(ctx context.Context) error {
+			if enableErr := cdplog.Enable().Do(ctx); enableErr != nil {
+				return enableErr
+			}
+			return runtime.Enable().Do(ctx)
+		}),
+		chromedp.Navigate(server.URL+"/"),
+		waitFor(`document.documentElement.dataset.testStatus === "ready"`, "initial plan"),
+		chromedp.FullScreenshot(&initialScreenshot, 90),
+		chromedp.Click(`.pad button[data-key="w"]`, chromedp.ByQuery),
+		waitFor(`Number(document.documentElement.dataset.planSequence) >= 2 && document.documentElement.dataset.plannedMoveZ === "1"`, "forward pad-button plan"),
+		chromedp.FullScreenshot(&movingScreenshot, 90),
+		chromedp.Click(`.pad button[data-key="w"]`, chromedp.ByQuery),
+		waitFor(`Number(document.documentElement.dataset.planSequence) >= 3 && document.documentElement.dataset.plannedMoveX === "0" && document.documentElement.dataset.plannedMoveZ === "0"`, "pad-button stop plan"),
+		chromedp.Evaluate(`dispatchEvent(new KeyboardEvent("keydown", {key:"d", bubbles:true}))`, nil),
+		waitFor(`Number(document.documentElement.dataset.planSequence) >= 4 && document.documentElement.dataset.plannedMoveX === "1"`, "keyboard-right plan"),
+		chromedp.Evaluate(`dispatchEvent(new KeyboardEvent("keyup", {key:"d", bubbles:true}))`, nil),
+		waitFor(`Number(document.documentElement.dataset.planSequence) >= 5 && document.documentElement.dataset.plannedMoveX === "0" && document.documentElement.dataset.plannedMoveZ === "0"`, "keyboard stop plan"),
+		chromedp.Navigate(server.URL+"/?test=1"),
+		waitFor(`document.documentElement.dataset.testStatus === "passed" || document.documentElement.dataset.testStatus === "failed"`, "style-and-turn self-test"),
+		chromedp.Text("#test-result", &message, chromedp.ByQuery),
+		chromedp.FullScreenshot(&screenshot, 90),
+	)
+	if err != nil {
+		t.Fatal(err)
+	}
+	var status string
+	if err = chromedp.Run(ctx, chromedp.Evaluate(`document.documentElement.dataset.testStatus`, &status)); err != nil {
+		t.Fatal(err)
+	}
+	if status != "passed" {
+		t.Fatalf("browser self-test status=%q: %s", status, message)
+	}
+	if len(initialScreenshot) < 10_000 || len(movingScreenshot) < 10_000 || len(screenshot) < 10_000 {
+		t.Fatalf("rendered screenshots are unexpectedly small: initial=%d moving=%d final=%d", len(initialScreenshot), len(movingScreenshot), len(screenshot))
+	}
+	artifact := os.Getenv("MOTIONBRICKS_SCREENSHOT")
+	if artifact == "" {
+		artifact = filepath.Join(t.TempDir(), "motionbricks-demo.png")
+	}
+	extension := filepath.Ext(artifact)
+	if extension == "" {
+		extension = ".png"
+	}
+	base := strings.TrimSuffix(artifact, filepath.Ext(artifact))
+	artifacts := []struct {
+		path string
+		data []byte
+	}{
+		{path: base + "-initial" + extension, data: initialScreenshot},
+		{path: base + "-moving" + extension, data: movingScreenshot},
+		{path: artifact, data: screenshot},
+	}
+	for _, item := range artifacts {
+		if err = os.WriteFile(item.path, item.data, 0o600); err != nil {
+			t.Fatal(err)
+		}
+	}
+	t.Logf("%s; screenshots: %s, %s, %s (final %s)", message, artifacts[0].path, artifacts[1].path, artifacts[2].path, fmt.Sprintf("%d bytes", len(screenshot)))
+}

demo/web/app.js

@@ -0,0 +1,499 @@
+import * as THREE from './vendor/three.module.min.js';
+
+const viewport = document.querySelector('#viewport');
+const styleSelect = document.querySelector('#style-select');
+const statusElement = document.querySelector('#status');
+const planInfo = document.querySelector('#plan-info');
+const targetInfo = document.querySelector('#target-info');
+const testResult = document.querySelector('#test-result');
+const showAllTargets = document.querySelector('#show-all-targets');
+const targetFrame = document.querySelector('#target-frame');
+const targetFrameLabel = document.querySelector('#target-frame-label');
+const resetCamera = document.querySelector('#reset-camera');
+const query = new URLSearchParams(location.search);
+
+const state = {
+  meta: null, session: '', motion: null, targets: null, playhead: 0,
+  lastTime: performance.now(), move: [0, 0], facing: [0, 1], keys: new Set(),
+  padKey: '', pending: false, replanQueued: false, seed: 10, style: '', rig: null, targetRigs: [],
+  generatedPath: null, targetPath: null,
+};
+
+const scene = new THREE.Scene();
+scene.fog = new THREE.FogExp2(0x090b10, 0.045);
+const camera = new THREE.PerspectiveCamera(42, 1, 0.02, 100);
+const renderer = new THREE.WebGLRenderer({antialias: true, alpha: true});
+renderer.setPixelRatio(Math.min(devicePixelRatio, 2));
+renderer.outputColorSpace = THREE.SRGBColorSpace;
+renderer.shadowMap.enabled = true;
+renderer.shadowMap.type = THREE.PCFSoftShadowMap;
+viewport.append(renderer.domElement);
+
+scene.add(new THREE.HemisphereLight(0xcde4ff, 0x253226, 2.5));
+const keyLight = new THREE.DirectionalLight(0xffffff, 3.2);
+keyLight.position.set(3, 7, 4);
+keyLight.castShadow = true;
+scene.add(keyLight);
+const rimLight = new THREE.DirectionalLight(0x67e8c3, 1.2);
+rimLight.position.set(-4, 3, -3);
+scene.add(rimLight);
+const floor = new THREE.Mesh(
+  new THREE.PlaneGeometry(40, 40),
+  new THREE.MeshStandardMaterial({color: 0x0d121a, roughness: 0.96, metalness: 0.02}),
+);
+floor.rotation.x = -Math.PI / 2;
+floor.position.y = -0.012;
+floor.receiveShadow = true;
+scene.add(floor);
+const grid = new THREE.GridHelper(24, 48, 0x3a4b5d, 0x202b38);
+grid.position.y = 0;
+scene.add(grid);
+
+const cylinderGeometry = new THREE.CylinderGeometry(1, 1, 1, 8, 1, false);
+const sphereGeometry = new THREE.SphereGeometry(1, 14, 10);
+const diamondGeometry = new THREE.OctahedronGeometry(1, 0);
+const up = new THREE.Vector3(0, 1, 0);
+const startPoint = new THREE.Vector3();
+const endPoint = new THREE.Vector3();
+const direction = new THREE.Vector3();
+const midpoint = new THREE.Vector3();
+
+function labelSprite(text, color, opacity) {
+  const canvas = document.createElement('canvas');
+  canvas.width = 128;
+  canvas.height = 64;
+  const context = canvas.getContext('2d');
+  context.font = '700 30px system-ui';
+  context.textAlign = 'center';
+  context.textBaseline = 'middle';
+  context.fillStyle = color;
+  context.fillText(text, 64, 32);
+  const texture = new THREE.CanvasTexture(canvas);
+  texture.colorSpace = THREE.SRGBColorSpace;
+  const sprite = new THREE.Sprite(new THREE.SpriteMaterial({map: texture, transparent: true, opacity, depthTest: false}));
+  sprite.scale.set(0.32, 0.16, 1);
+  sprite.renderOrder = 20;
+  return sprite;
+}
+
+class SkeletonRig {
+  constructor(joints, options) {
+    this.bones = [];
+    this.jointMeshes = [];
+    this.segments = [];
+    this.group = new THREE.Group();
+    this.radius = options.radius;
+    this.jointRadius = options.jointRadius;
+    this.rootRadius = options.rootRadius;
+    this.labelHeight = options.labelHeight ?? 0.34;
+    this.boneMaterial = new THREE.MeshStandardMaterial({
+      color: options.color, emissive: options.emissive, emissiveIntensity: options.emissiveIntensity,
+      roughness: 0.42, transparent: options.opacity < 1, opacity: options.opacity,
+      depthWrite: options.opacity >= 0.95,
+    });
+    this.jointMaterial = new THREE.MeshStandardMaterial({
+      color: options.jointColor, emissive: options.emissive, emissiveIntensity: options.emissiveIntensity,
+      roughness: 0.35, transparent: options.opacity < 1, opacity: options.opacity,
+      depthWrite: options.opacity >= 0.95,
+    });
+    this.rootMaterial = new THREE.MeshStandardMaterial({
+      color: options.rootColor, emissive: options.rootEmissive, emissiveIntensity: 1.4,
+      transparent: options.opacity < 1, opacity: options.opacity, depthWrite: options.opacity >= 0.95,
+    });
+    for (let index = 0; index < joints.length; index++) {
+      const joint = joints[index];
+      const bone = new THREE.Bone();
+      bone.name = joint.name;
+      if (joint.parent < 0) {
+        bone.position.set(0, 0, 0);
+      } else {
+        const parent = joints[joint.parent].position;
+        bone.position.set(joint.position[0] - parent[0], joint.position[1] - parent[1], joint.position[2] - parent[2]);
+        this.bones[joint.parent].add(bone);
+      }
+      this.bones.push(bone);
+      const geometry = options.diamonds ? diamondGeometry : sphereGeometry;
+      const marker = new THREE.Mesh(geometry, index === 0 ? this.rootMaterial : this.jointMaterial);
+      marker.castShadow = !options.diamonds;
+      marker.renderOrder = options.renderOrder;
+      this.jointMeshes.push(marker);
+      this.group.add(marker);
+      if (joint.parent >= 0) {
+        const segment = new THREE.Mesh(cylinderGeometry, this.boneMaterial);
+        segment.castShadow = !options.diamonds;
+        segment.renderOrder = options.renderOrder;
+        this.segments.push({mesh: segment, child: index, parent: joint.parent});
+        this.group.add(segment);
+      }
+    }
+    scene.add(this.bones[0]);
+    scene.add(this.group);
+    this.label = options.label ? labelSprite(options.label, options.labelColor, options.opacity) : null;
+    if (this.label) scene.add(this.label);
+  }
+
+  pose(roots, rotations, frame, frameCount) {
+    const index = Math.min(frameCount - 1, Math.max(0, frame));
+    this.bones[0].position.fromArray(roots, index * 3);
+    for (let joint = 0; joint < this.bones.length; joint++) {
+      this.bones[joint].quaternion.fromArray(rotations, (index * this.bones.length + joint) * 4);
+    }
+    this.updateGeometry();
+  }
+
+  updateGeometry() {
+    this.bones[0].updateMatrixWorld(true);
+    for (let index = 0; index < this.bones.length; index++) {
+      this.bones[index].getWorldPosition(endPoint);
+      const marker = this.jointMeshes[index];
+      marker.position.copy(endPoint);
+      const radius = index === 0 ? this.rootRadius : this.jointRadius;
+      marker.scale.setScalar(radius);
+    }
+    for (const segment of this.segments) {
+      this.bones[segment.parent].getWorldPosition(startPoint);
+      this.bones[segment.child].getWorldPosition(endPoint);
+      direction.subVectors(endPoint, startPoint);
+      const length = direction.length();
+      midpoint.addVectors(startPoint, endPoint).multiplyScalar(0.5);
+      segment.mesh.position.copy(midpoint);
+      segment.mesh.quaternion.setFromUnitVectors(up, direction.normalize());
+      segment.mesh.scale.set(this.radius, length, this.radius);
+    }
+    if (this.label) {
+      this.bones[0].getWorldPosition(endPoint);
+      this.label.position.set(endPoint.x, endPoint.y + this.labelHeight, endPoint.z);
+    }
+  }
+
+  setVisible(visible) {
+    this.group.visible = visible;
+    this.bones[0].visible = visible;
+    if (this.label) this.label.visible = visible;
+  }
+
+  setOpacity(opacity) {
+    for (const material of [this.boneMaterial, this.jointMaterial, this.rootMaterial]) {
+      material.opacity = opacity;
+      material.transparent = opacity < 1;
+      material.depthWrite = opacity >= 0.95;
+    }
+    if (this.label) this.label.material.opacity = opacity;
+  }
+}
+
+function makeLine(color, dashed = false) {
+  const material = dashed
+    ? new THREE.LineDashedMaterial({color, dashSize: 0.09, gapSize: 0.055, transparent: true, opacity: 0.9})
+    : new THREE.LineBasicMaterial({color, transparent: true, opacity: 0.72});
+  const line = new THREE.Line(new THREE.BufferGeometry(), material);
+  line.renderOrder = 1;
+  scene.add(line);
+  return line;
+}
+
+function setGroundPath(line, roots, frames) {
+  const points = [];
+  for (let frame = 0; frame < frames; frame++) {
+    points.push(new THREE.Vector3(roots[frame * 3], 0.018, roots[frame * 3 + 2]));
+  }
+  line.geometry.dispose();
+  line.geometry = new THREE.BufferGeometry().setFromPoints(points);
+  if (line.material.isLineDashedMaterial) line.computeLineDistances();
+}
+
+function makeSkeletons(joints) {
+  state.rig = new SkeletonRig(joints, {
+    color: 0x55efc4, jointColor: 0xd9fff3, rootColor: 0xffd166,
+    emissive: 0x0c5b49, rootEmissive: 0x6a3b00, emissiveIntensity: 0.8,
+    radius: 0.022, jointRadius: 0.034, rootRadius: 0.062,
+    opacity: 1, diamonds: false, renderOrder: 5,
+  });
+  for (let frame = 0; frame < 4; frame++) {
+    state.targetRigs.push(new SkeletonRig(joints, {
+      color: 0xff763b, jointColor: 0xffb06b, rootColor: 0xff4f8b,
+      emissive: 0x7b1f00, rootEmissive: 0x790025, emissiveIntensity: 1,
+      radius: 0.018, jointRadius: 0.032, rootRadius: 0.056, opacity: 0.9, diamonds: true,
+      renderOrder: 8 + frame, label: `T${frame}`, labelColor: frame === 3 ? '#ffb477' : '#c97354',
+      labelHeight: 0.34 + (3 - frame) * 0.11,
+    }));
+  }
+  state.generatedPath = makeLine(0x43e8bf);
+  state.targetPath = makeLine(0xff6b3d, true);
+}
+
+function updateTargetVisibility() {
+  const frames = state.targets?.frames ?? 0;
+  const maximum = Math.max(0, frames - 1);
+  targetFrame.max = String(maximum);
+  const selected = THREE.MathUtils.clamp(Number(targetFrame.value), 0, maximum);
+  targetFrame.value = String(selected);
+  targetFrameLabel.textContent = `T${selected}`;
+  const overlay = showAllTargets.checked;
+  const overlayOpacities = [0.16, 0.25, 0.42, 0.9];
+  for (let frame = 0; frame < state.targetRigs.length; frame++) {
+    const exists = frame < frames;
+    state.targetRigs[frame].setOpacity(overlay ? overlayOpacities[frame] : 0.9);
+    state.targetRigs[frame].setVisible(exists && (overlay || frame === selected));
+  }
+  state.targetPath.visible = frames > 0;
+  targetInfo.textContent = frames > 0
+    ? (overlay ? `${frames} consecutive constraints overlaid` : `T${selected} of ${frames} consecutive constraints`)
+    : '—';
+}
+
+const cameraView = {yaw: 0.68, pitch: 0.24, distance: 4.8, dragging: false, x: 0, y: 0};
+const focus = new THREE.Vector3();
+const desiredCamera = new THREE.Vector3();
+const visibleBounds = new THREE.Box3();
+function resetCameraView() {
+  cameraView.yaw = 0.68;
+  cameraView.pitch = 0.24;
+  cameraView.distance = 4.8;
+}
+resetCamera.addEventListener('click', resetCameraView);
+renderer.domElement.addEventListener('pointerdown', event => {
+  cameraView.dragging = true; cameraView.x = event.clientX; cameraView.y = event.clientY;
+  renderer.domElement.setPointerCapture(event.pointerId);
+});
+renderer.domElement.addEventListener('pointermove', event => {
+  if (!cameraView.dragging) return;
+  cameraView.yaw -= (event.clientX - cameraView.x) * 0.006;
+  cameraView.pitch = THREE.MathUtils.clamp(cameraView.pitch + (event.clientY - cameraView.y) * 0.004, -0.05, 1.05);
+  cameraView.x = event.clientX; cameraView.y = event.clientY;
+});
+renderer.domElement.addEventListener('pointerup', event => {
+  cameraView.dragging = false; renderer.domElement.releasePointerCapture(event.pointerId);
+});
+renderer.domElement.addEventListener('pointercancel', () => { cameraView.dragging = false; });
+renderer.domElement.addEventListener('wheel', event => {
+  cameraView.distance = THREE.MathUtils.clamp(cameraView.distance * Math.exp(event.deltaY * 0.001), 2.1, 8);
+  event.preventDefault();
+}, {passive: false});
+renderer.domElement.addEventListener('dblclick', resetCameraView);
+
+function resize() {
+  const width = Math.max(1, viewport.clientWidth), height = Math.max(1, viewport.clientHeight);
+  renderer.setSize(width, height, false);
+  camera.aspect = width / height;
+  camera.updateProjectionMatrix();
+}
+addEventListener('resize', resize);
+resize();
+
+async function api(path, body) {
+  const response = await fetch(path, {
+    method: body ? 'POST' : 'GET', headers: {'Content-Type': 'application/json'},
+    body: body ? JSON.stringify(body) : undefined,
+  });
+  const value = await response.json();
+  if (!response.ok) throw new Error(value.error || `${response.status} ${response.statusText}`);
+  return value;
+}
+
+function installStyles(styles) {
+  for (const style of styles) {
+    const option = document.createElement('option');
+    option.value = style.name;
+    option.textContent = `${style.name.replaceAll('_', ' ')} · ${style.speed.toFixed(1)} m/s`;
+    styleSelect.append(option);
+  }
+  state.style = styles.some(item => item.name === 'walk') ? 'walk' : styles[0].name;
+  styleSelect.value = state.style;
+  styleSelect.addEventListener('change', () => { state.style = styleSelect.value; void requestPlan(); });
+}
+
+function useMotion(response, plannedMove = state.move) {
+  state.session = response.session;
+  state.style = response.style;
+  styleSelect.value = response.style;
+  state.motion = response.motion;
+  state.targets = response.targets;
+  state.playhead = 0;
+  state.lastTime = performance.now();
+  planInfo.textContent = `${response.motion.frames} frames · ${response.style.replaceAll('_', ' ')}`;
+  statusElement.textContent = 'Playing';
+  document.documentElement.dataset.planSequence = String(Number(document.documentElement.dataset.planSequence || 0) + 1);
+  document.documentElement.dataset.plannedMoveX = String(plannedMove[0]);
+  document.documentElement.dataset.plannedMoveZ = String(plannedMove[1]);
+  setGroundPath(state.generatedPath, response.motion.roots, response.motion.frames);
+  setGroundPath(state.targetPath, response.targets.roots, response.targets.frames);
+  for (let frame = 0; frame < response.targets.frames; frame++) {
+    state.targetRigs[frame].pose(response.targets.roots, response.targets.rotations, frame, response.targets.frames);
+  }
+  updateTargetVisibility();
+}
+
+async function requestPlan(advance = Math.floor(state.playhead)) {
+  if (!state.session) return null;
+  if (state.pending) {
+    state.replanQueued = true;
+    return null;
+  }
+  state.pending = true;
+  statusElement.textContent = 'Planning…';
+  const plannedMove = [...state.move];
+  try {
+    const response = await api('/api/plan', {
+      session: state.session, style: state.style, move: state.move, facing: state.facing,
+      seed: state.seed++, advance,
+    });
+    useMotion(response, plannedMove);
+    return response;
+  } finally {
+    state.pending = false;
+    if (state.replanQueued) {
+      state.replanQueued = false;
+      queueMicrotask(() => void requestPlan(Math.floor(state.playhead)));
+    }
+  }
+}
+
+function updateControl() {
+  let x = 0, z = 0;
+  const active = key => state.keys.has(key) || state.padKey === key;
+  if (active('w')) z += 1;
+  if (active('s')) z -= 1;
+  if (active('a')) x -= 1;
+  if (active('d')) x += 1;
+  const length = Math.hypot(x, z);
+  if (length > 0) { x /= length; z /= length; state.facing = [x, z]; }
+  state.move = [x, z];
+  document.querySelectorAll('.pad button').forEach(button => {
+    const pressed = active(button.dataset.key);
+    button.classList.toggle('active', pressed);
+    button.setAttribute('aria-pressed', String(pressed));
+  });
+}
+
+let controlTimer = 0;
+function schedulePlan(delay = 0) { clearTimeout(controlTimer); controlTimer = setTimeout(() => void requestPlan(), delay); }
+addEventListener('keydown', event => {
+  const key = event.key.toLowerCase();
+  if (['w', 'a', 's', 'd'].includes(key) && !state.keys.has(key)) {
+    state.keys.add(key); updateControl(); schedulePlan(); event.preventDefault();
+  }
+  if (event.code === 'Space' || event.key === 'Escape') {
+    state.keys.clear(); state.padKey = ''; updateControl(); schedulePlan(); event.preventDefault();
+  }
+  if (event.key === 'ArrowLeft' || event.key === 'ArrowRight') {
+    const angle = Math.atan2(state.facing[0], state.facing[1]) + (event.key === 'ArrowLeft' ? 0.25 : -0.25);
+    state.facing = [Math.sin(angle), Math.cos(angle)]; schedulePlan(35); event.preventDefault();
+  }
+});
+addEventListener('keyup', event => {
+  const key = event.key.toLowerCase();
+  if (state.keys.delete(key)) { updateControl(); schedulePlan(); }
+});
+for (const button of document.querySelectorAll('.pad button')) {
+  button.setAttribute('aria-pressed', 'false');
+  button.addEventListener('click', event => {
+    state.padKey = state.padKey === button.dataset.key ? '' : button.dataset.key;
+    updateControl();
+    schedulePlan();
+    event.preventDefault();
+  });
+}
+showAllTargets.addEventListener('change', updateTargetVisibility);
+targetFrame.addEventListener('input', updateTargetVisibility);
+
+function updateCamera() {
+  visibleBounds.makeEmpty();
+  for (const marker of state.rig.jointMeshes) visibleBounds.expandByPoint(marker.position);
+  visibleBounds.getCenter(focus);
+  const horizontal = Math.cos(cameraView.pitch) * cameraView.distance;
+  desiredCamera.set(
+    focus.x + Math.sin(cameraView.yaw) * horizontal,
+    focus.y + Math.sin(cameraView.pitch) * cameraView.distance,
+    focus.z + Math.cos(cameraView.yaw) * horizontal,
+  );
+  if (camera.userData.positioned) camera.position.lerp(desiredCamera, 0.12);
+  else { camera.position.copy(desiredCamera); camera.userData.positioned = true; }
+  camera.lookAt(focus);
+}
+
+function renderMotion(frame) {
+  if (!state.motion) return;
+  const index = Math.min(state.motion.frames - 1, Math.max(0, frame));
+  state.rig.pose(state.motion.roots, state.motion.rotations, index, state.motion.frames);
+  updateCamera();
+}
+
+function animate(now) {
+  requestAnimationFrame(animate);
+  const delta = Math.min(0.1, (now - state.lastTime) / 1000);
+  state.lastTime = now;
+  if (state.motion) {
+    state.playhead += delta * state.meta.fps;
+    if (state.playhead >= state.motion.frames - 5 && !state.pending) void requestPlan(Math.floor(state.playhead));
+    renderMotion(Math.floor(state.playhead));
+  }
+  renderer.render(scene, camera);
+}
+
+async function selfTest() {
+  const alternate = state.meta.styles.find(item => item.name === 'walk_zombie') || state.meta.styles.find(item => item.name !== 'walk');
+  if (!alternate) throw new Error('no alternate upstream style available');
+  state.style = alternate.name;
+  styleSelect.value = alternate.name;
+  state.move = [1, 0];
+  state.facing = [1, 0];
+  const response = await requestPlan(3);
+  if (!response || response.style !== alternate.name) throw new Error('style change was not applied');
+  if (response.motion.joints !== 34 || response.motion.frames < 24 || response.motion.rotations.length !== response.motion.frames * 34 * 4) {
+    throw new Error('invalid skeletal animation response');
+  }
+  if (response.targets.frames !== 4 || response.targets.joints !== 34 || response.targets.roots.length !== 12 || response.targets.rotations.length !== 4 * 34 * 4) {
+    throw new Error('invalid placed target-keyframe response');
+  }
+  renderMotion(2);
+  renderer.render(scene, camera);
+  let visibleTargets = state.targetRigs.filter(rig => rig.group.visible).length;
+  if (!renderer.domElement.width || state.rig.bones.length !== 34 || visibleTargets !== 1 || !state.targetRigs[3].group.visible) {
+    throw new Error('animated and target skeletons were not rendered');
+  }
+  const expectedFocus = new THREE.Vector3();
+  const animatedBounds = new THREE.Box3();
+  for (const marker of state.rig.jointMeshes) animatedBounds.expandByPoint(marker.position);
+  animatedBounds.getCenter(expectedFocus);
+  if (focus.distanceTo(expectedFocus) > 1e-6) throw new Error('camera is not anchored to the animated skeleton');
+  targetFrame.value = '1';
+  updateTargetVisibility();
+  if (!state.targetRigs[1].group.visible || state.targetRigs.filter(rig => rig.group.visible).length !== 1) {
+    throw new Error('target-frame inspector did not select T1');
+  }
+  showAllTargets.checked = true;
+  updateTargetVisibility();
+  visibleTargets = state.targetRigs.filter(rig => rig.group.visible).length;
+  if (visibleTargets !== 4) throw new Error('four-pose target overlay did not render');
+  showAllTargets.checked = false;
+  targetFrame.value = '3';
+  updateTargetVisibility();
+  document.documentElement.dataset.animatedJoints = String(state.rig.bones.length);
+  document.documentElement.dataset.targetFrames = String(response.targets.frames);
+  document.documentElement.dataset.visibleTargets = '1';
+  document.documentElement.dataset.cameraSubject = 'animated';
+  document.documentElement.dataset.testStatus = 'passed';
+  testResult.textContent = `Headless check passed: animated-camera anchor + target inspector/overlay, ${alternate.name}, right turn`;
+}
+
+async function start() {
+  try {
+    state.meta = await api('/api/meta');
+    installStyles(state.meta.styles);
+    makeSkeletons(state.meta.joints);
+    const initial = await api('/api/session', {style: state.style});
+    useMotion(initial);
+    renderMotion(0);
+    requestAnimationFrame(animate);
+    if (query.get('test') === '1') await selfTest();
+    else document.documentElement.dataset.testStatus = 'ready';
+  } catch (error) {
+    console.error(error);
+    statusElement.textContent = 'Error';
+    testResult.textContent = error.message;
+    document.documentElement.dataset.testStatus = 'failed';
+  }
+}
+
+await start();

demo/web/index.html

@@ -0,0 +1,50 @@
+<!doctype html>
+<html lang="en" data-test-status="starting">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width,initial-scale=1">
+  <link rel="icon" href="data:,">
+  <title>MotionBricks G1</title>
+  <link rel="stylesheet" href="style.css">
+</head>
+<body>
+  <main>
+    <section id="viewport" aria-label="Animated G1 skeleton"></section>
+    <aside>
+      <p class="eyebrow">MOTIONBRICKS / G1</p>
+      <h1>Whole-body motion</h1>
+      <p class="lede">Move with WASD. The character faces its travel direction; arrow keys turn independently.</p>
+      <div class="legend" aria-label="Skeleton legend">
+        <span><i class="animated-swatch"></i>Animated model</span>
+        <span><i class="target-swatch"></i>Target keyframes</span>
+      </div>
+      <label for="style-select">Upstream pose style</label>
+      <select id="style-select" aria-label="Motion style"></select>
+      <div class="target-frame-control">
+        <label for="target-frame">Inspect placed target <output id="target-frame-label" for="target-frame">T3</output></label>
+        <input id="target-frame" type="range" min="0" max="3" step="1" value="3" aria-label="Target frame">
+      </div>
+      <div class="view-options">
+        <label><input id="show-all-targets" type="checkbox"> Overlay all four consecutive poses</label>
+        <button id="reset-camera" type="button">Reset camera</button>
+      </div>
+      <p class="target-help">T0–T3 are consecutive 30 FPS constraints, so their exact positions are intentionally close.</p>
+      <p class="camera-help">Drag to orbit · wheel to zoom · tap a pad direction to move, tap it again to stop</p>
+      <div class="pad" aria-label="Directional controls">
+        <button data-key="w" data-x="0" data-z="1" aria-label="Walk forward">W</button>
+        <button data-key="a" data-x="-1" data-z="0" aria-label="Walk left">A</button>
+        <button data-key="s" data-x="0" data-z="-1" aria-label="Walk backward">S</button>
+        <button data-key="d" data-x="1" data-z="0" aria-label="Walk right">D</button>
+      </div>
+      <dl>
+        <div><dt>Status</dt><dd id="status">Loading model…</dd></div>
+        <div><dt>Plan</dt><dd id="plan-info">—</dd></div>
+        <div><dt>Targets</dt><dd id="target-info">—</dd></div>
+        <div><dt>Backend</dt><dd>native GGML</dd></div>
+      </dl>
+      <p id="test-result" role="status"></p>
+    </aside>
+  </main>
+  <script type="module" src="app.js"></script>
+</body>
+</html>

demo/web/style.css

@@ -0,0 +1,39 @@
+:root { color-scheme: dark; font-family: Inter, ui-sans-serif, system-ui, sans-serif; background:#090b10; color:#edf1f7; }
+* { box-sizing:border-box; }
+html, body, main { width:100%; height:100%; margin:0; overflow:hidden; }
+main { display:grid; grid-template-columns:minmax(0,1fr) 320px; }
+#viewport { min-width:0; background:radial-gradient(circle at 50% 36%,#20293a 0,#10141d 38%,#080a0f 76%); }
+#viewport canvas { display:block; width:100%; height:100%; }
+aside { padding:36px 28px; border-left:1px solid #2a3240; background:rgba(11,14,20,.96); box-shadow:-18px 0 60px #0008; }
+.eyebrow { margin:0 0 10px; color:#6be6ba; letter-spacing:.18em; font-size:11px; font-weight:750; }
+h1 { margin:0 0 12px; font-size:30px; letter-spacing:-.04em; }
+.lede { color:#9eabbc; line-height:1.45; margin:0 0 18px; }
+.legend { display:flex; gap:16px; margin:0 0 24px; color:#aeb9c8; font-size:12px; }
+.legend span { display:flex; align-items:center; gap:7px; }
+.legend i { display:block; width:20px; height:5px; border-radius:4px; box-shadow:0 0 10px currentColor; }
+.animated-swatch { color:#55efc4; background:#55efc4; }
+.target-swatch { color:#ff763b; background:#ff763b; transform:rotate(-8deg); }
+label { display:block; color:#c8d1dd; font-size:12px; font-weight:700; margin-bottom:8px; }
+select { width:100%; color:#f2f6fb; background:#171c26; border:1px solid #343d4d; border-radius:8px; padding:11px; font:inherit; }
+.target-frame-control { margin-top:16px; }
+.target-frame-control label { display:flex; justify-content:space-between; margin-bottom:6px; }
+.target-frame-control output { color:#ff9a68; font-variant-numeric:tabular-nums; }
+#target-frame { display:block; width:100%; margin:0; accent-color:#ff763b; }
+.view-options { display:flex; align-items:center; justify-content:space-between; gap:10px; margin-top:14px; }
+.view-options label { display:flex; align-items:center; gap:7px; margin:0; font-weight:600; color:#b7c2d0; }
+.view-options input { accent-color:#ff763b; }
+#reset-camera { color:#dbe4ef; background:#171c26; border:1px solid #343d4d; border-radius:7px; padding:7px 9px; font:inherit; font-size:11px; white-space:nowrap; }
+#reset-camera:hover { border-color:#59677b; background:#202735; }
+.target-help, .camera-help { margin:9px 0 0; color:#647286; font-size:11px; line-height:1.35; }
+.pad { margin:28px auto; width:176px; display:grid; grid-template:52px 52px / 52px 52px 52px; gap:8px; }
+.pad button { border:1px solid #3b4658; border-radius:10px; background:#181e29; color:#dae3ed; font-weight:800; font-size:16px; box-shadow:0 4px 12px #0005; }
+.pad button:first-child { grid-column:2; }
+.pad button:nth-child(2) { grid-row:2; grid-column:1; }
+.pad button:nth-child(3) { grid-row:2; grid-column:2; }
+.pad button:nth-child(4) { grid-row:2; grid-column:3; }
+.pad button.active { background:#2e735f; border-color:#77f0c4; transform:translateY(1px); }
+dl { border-top:1px solid #2b3341; margin-top:30px; padding-top:10px; }
+dl div { display:flex; justify-content:space-between; gap:10px; padding:8px 0; }
+dt { color:#778599; } dd { margin:0; text-align:right; color:#dce4ee; }
+#test-result { min-height:1.3em; color:#6be6ba; font-size:12px; }
+@media (max-width:760px) { main { grid-template-columns:1fr; grid-template-rows:minmax(0,1fr) auto; } aside { padding:16px 20px; border-left:0; border-top:1px solid #2a3240; } .lede, dl, .target-help, .camera-help { display:none; } .legend { margin-bottom:12px; } .view-options { max-width:420px; } .pad { position:absolute; right:18px; bottom:12px; margin:0; transform:scale(.8); transform-origin:bottom right; } }

demo/web/vendor/THREE-LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License
+
+Copyright © 2010-2025 three.js authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

docs/DEMO.md

@@ -0,0 +1,120 @@
+# Go and Three.js demo
+
+The initial demo is a local Go application that calls `libmotionbricks`
+through the PureGo binding and serves an embedded Three.js viewer. It renders
+the released 34-joint G1 hierarchy directly from MotionBricks root
+translations and local XYZW joint rotations; it does not require MuJoCo or a
+skinned mesh. Solid cyan cylinders and round joints identify the generated
+character. An orange diamond-jointed ghost skeleton identifies a selected
+placed style-pose constraint supplied to the planner; all four constraints can
+be overlaid for inspection.
+
+## Build and run
+
+First build the native project and create the model/style assets described in
+the main README. Then build the Go application:
+
+```sh
+cmake --build --preset debug
+cd demo
+CGO_ENABLED=0 go build -o ../build/debug/bin/motionbricks-demo .
+cd ..
+```
+
+The demo and reusable Go binding call the native shared library through
+PureGo. They contain no cgo bridge and do not require a C compiler during the
+Go build, so cgo can be disabled. This does not remove the separate C++/CMake
+build that produces `libmotionbricks`.
+
+Run it from the repository root:
+
+```sh
+./build/debug/bin/motionbricks-demo \
+  -listen 127.0.0.1:8080 \
+  -library ./build/debug/libmotionbricks.so \
+  -model ./generated/g1-f32 \
+  -styles ./generated/styles \
+  -device cpu
+```
+
+Open `http://127.0.0.1:8080/`. Hold physical W/A/S/D keys to move, or tap an
+on-screen direction to latch it; tap the active pad direction again to stop.
+Space or Escape also stops movement. Left/right arrow keys rotate the facing
+direction without changing the current travel vector. The selector switches
+among all `.mbstyle` files found in the style directory, including the 15
+converted upstream styles. Drag over the viewport to orbit, use the wheel to
+zoom, and use **Reset camera** to restore the automatically framed view. The
+camera follows only the animated skeleton, so target placement never pulls the
+view away from the character. The T0–T3 slider selects one fully visible target
+pose. **Overlay all four consecutive poses** reveals the complete constraint
+window. These are adjacent 30 FPS constraint frames rather than four distant
+waypoints, so their exact world positions are intentionally close together.
+
+`-device` accepts `cpu`, `vulkan`, or `auto`. The server deliberately binds to
+localhost by default. Model inference is serialized while sessions keep
+independent agent/context state.
+
+## Runtime shape
+
+The browser creates a session, receives a 30 FPS animation chunk, and asks for
+a replacement chunk when controls change or playback approaches the end.
+Each request contains movement, facing, style, seed, and the number of frames
+already consumed. The Go server advances that session's native agent and
+returns owned animation data and target constraints as JSON:
+
+- root translations: `[frames, 3]`;
+- local joint rotations: `[frames, 34, 4]`, XYZW;
+- placed target roots: `[4, 3]`;
+- placed target local rotations: `[4, 34, 4]`, XYZW;
+- G1 joint names, parent indices, and neutral positions from the loaded model.
+
+The native target data is captured after style-frame sampling, spring-based
+world placement, and heading correction. The ghosts therefore visualize the
+actual planner inputs. The viewer does not force them in front: forward travel
+normally places them ahead, while stops and turns can make them overlap the
+character or move sideways.
+
+The browser builds `THREE.Bone` objects from the returned hierarchy and draws
+solid cylinders/spheres for the generated skeleton and translucent
+cylinders/diamonds for target poses. It also draws generated and target root
+paths on the floor. Animation chunks are immutable in JavaScript; a later
+version can replace JSON with a binary streaming protocol without changing
+the native API.
+
+Three.js r180 is vendored under `demo/web/vendor` so the demo has no runtime
+CDN dependency.
+
+## Tests
+
+With the generated assets present, CTest registers `motionbricks-go-demo` when
+Go and Chromium are available. The test starts an in-process HTTP server,
+loads the real native model, plans an initial `walk` chunk, then uses headless
+Chromium to select `walk_zombie`, turn right, plan another chunk, render the
+34-joint generated hierarchy plus the target inspector, and capture initial,
+forward-motion, and style-and-turn screenshots. It uses real Chrome click and
+keyboard events and asserts forward-pad movement, pad stop, keyboard movement,
+keyboard stop, animated-skeleton camera anchoring, individual target selection,
+and the four-pose overlay before the visual self-test.
+
+The Go tests can also be run directly:
+
+```sh
+cd demo
+MOTIONBRICKS_LIB=../build/debug/libmotionbricks.so \
+MOTIONBRICKS_MODEL=../generated/g1-f32 \
+MOTIONBRICKS_STYLES=../generated/styles \
+MOTIONBRICKS_CHROME="$(command -v chromium)" \
+CGO_ENABLED=0 go test -v ./...
+```
+
+Without the native asset environment variables, the parser test still runs
+and the native/browser integration cases are skipped.
+
+## Initial limitations
+
+- G1 is the only skeleton supported by the released model.
+- The viewer intentionally shows a bone skeleton, not a skinned avatar.
+- HTTP JSON carries whole planned chunks; binary streaming and client-side
+  overlap blending are future work.
+- Sessions are in-memory and intended for a trusted local demo, not an
+  internet-facing multi-user service.

docs/FORMATS.md

@@ -0,0 +1,50 @@
+# Versioned format registry
+
+A reader must reject an unknown major version rather than guessing.
+
+| Format | Version | Status |
+|---|---:|---|
+| Installed C ABI | 1 | Model, style, command, agent, and motion contract implemented |
+| GGUF model-bundle manifest | 1 | F32 inference components implemented |
+| MotionBricks style asset | 1 | Upstream G1 exemplar schema implemented |
+| Reference fixture manifest | 1 | Root, pose, and decoder fixtures implemented |
+| WebSocket animation protocol | 1 | Reserved; schema not implemented |
+
+Minor, backwards-compatible additions are represented by optional keys or by
+new API functions. Existing function signatures and field meanings do not
+change within one C ABI version.
+
+## GGUF model bundle v1
+
+A bundle is a directory containing `manifest.json` and four GGUF v3 files:
+
+| Component | Runtime contents | Tensors | Learned parameters |
+|---|---|---:|---:|
+| `pose.gguf` | Pose-token planner | 209 | 136,588,272 |
+| `root.gguf` | Root-trajectory and duration planner | 150 | 34,122,833 |
+| `vq-decoder.gguf` | Pose codebook and convolutional decoder | 51 | 12,437,277 |
+| `support.gguf` | G1 skeleton, parents, mean, and standard deviation | 4 | 0 |
+
+The learned inference total is 183,148,382 F32 parameters. The support file
+contains 972 non-learned scalar values. Training-only VQ encoder tensors,
+codebook EMA state, and initialization flags are deliberately omitted.
+
+Every component carries `general.architecture=motionbricks`, format version,
+component role, `g1skel34` skeleton identity, pinned upstream revision, source
+safetensors hash, and exact scalar count. PyTorch tensor dimensions are stored
+in reversed GGML order. Names at or above GGML's 64-byte limit are compacted
+deterministically and collision-checked by the converter.
+
+## MotionBricks style asset v1
+
+A `.mbstyle` is a GGUF v3 file with `component=style`, the `g1skel34`
+skeleton identity, a source SHA-256, name, configured speed, and frame count.
+It contains checked F32 tensors for global joint positions
+`[frames,34,3]`, flattened global rotation matrices `[frames,34,9]`, root
+positions `[frames,3]`, and headings `[frames]`, plus an I32 allowed-duration
+mask `[11]` corresponding to 6--16 tokens. The runtime validates all metadata,
+shapes, finite values, frame limits, and the binary mask before accepting it.
+
+The source identity is not restricted to NVIDIA's clip archive, so the same
+schema can hold a future checked Kimodo/G1 conversion. Skeleton and coordinate
+compatibility must still be established by the converter.

docs/IMPLEMENTATION.md

@@ -0,0 +1,806 @@
+# motion-bricks.cpp implementation sketch and plan
+
+This document proposes an implementation derived from `motions-bricks.md` and
+the checked-out NVIDIA MotionBricks source. It does not replace the human-led
+design document.
+
+## Goal and first supported slice
+
+`motion-bricks.cpp` will be a C++23/GGML inference port of the released G1
+MotionBricks planner. It will accept a recent G1 motion context plus a
+movement/facing command and a short reference-style clip, then generate the
+next continuous section of 30 FPS skeletal animation. The initial product
+slice is:
+
+- batch size one;
+- the released 34-joint G1 model only;
+- the same 4-frame context and 4-frame target-pose convention as upstream;
+- 24--64 generated frames (6--16 tokens, 4 frames per token);
+- F32 CPU inference with reference parity;
+- root translations and 34 local joint quaternions as the public animation
+  result;
+- a Go/PureGo server and a plain HTML/CSS/Three.js interactive viewer.
+
+Vulkan follows CPU parity. F16 and quantization are optimizations after both
+backends pass the F32 reference suite.
+
+Kimodo is an authoring input, not a runtime dependency of the MotionBricks
+neural network. A Kimodo G1 animation supplies characteristic poses for a
+named style. The controller positions and rotates those poses in the world,
+and MotionBricks generates the transition from the character's actual current
+motion. The original upstream demo clips use the same style-asset boundary.
+
+## Current implementation status
+
+The native inference slice described above is operational. The strict bundle
+loader, all three released neural graphs, normalization and motion
+representation conversion, original G1 style assets, spring-based target
+construction, stateful agent, and public skeletal outputs are implemented.
+The reusable PureGo binding, local Go session server, and embedded Three.js G1
+skeleton viewer are also implemented. The viewer supports directional
+steering, independent facing changes, and all converted upstream styles.
+
+The deterministic component fixtures pass against upstream PyTorch on CPU;
+CPU and Vulkan preserve duration and pose-token choices and agree end to end
+within small F32 tolerances. The demo has native HTTP integration coverage and
+a headless-Chromium test that performs real inference, changes style and
+direction, renders all 34 bones, and captures a screenshot.
+
+Still outstanding from the wider plan are direct Kimodo GLB style import,
+recorded upstream controller/session fixtures, context-output blending,
+Gumbel sampling, graph/buffer caching and performance work, binary browser
+streaming, fuzzing, and optimized weight formats. The human-led
+`motions-bricks.md` remains unchanged.
+
+## System shape
+
+```text
+                      offline / authoring
+
+ upstream .ckpt + config + stats        Kimodo G1 GLB / original demo clips
+          |                                           |
+ trusted reference container                         |
+          |                                           |
+    safetensors + manifest                 checked style conversion
+          |                                           |
+          +---------------> GGUF model bundle <-------+
+
+                         runtime
+
+ keyboard/game input
+          |
+ Go session controller -- movement, facing, speed, selected style
+          |
+ PureGo -> stable C ABI -> stateful C++ agent
+                              |
+          recent 4 frames -> target construction and normalization
+                              |
+                    root transformer
+                              |
+          predicted root path and predicted duration
+                              |
+                    pose transformer
+                              |
+                    VQ pose decoder
+                              |
+                 representation inverse / FK
+                              |
+             root translations + local joint rotations
+                              |
+                HTTP JSON chunks -> Three.js
+```
+
+There are three deliberately separate layers:
+
+1. **Neural inference** reproduces the root transformer, pose-token
+   transformer, and VQ decoder.
+2. **Planner/controller** reproduces context management, the critically
+   damped spring target, style-pose sampling/alignment, replanning, and output
+   blending.
+3. **Application** maps keyboard input to commands, owns user sessions, and
+   renders results. It does not implement model math.
+
+This separation lets network parity be established without the interactive
+demo and lets controller behavior be tested with recorded neural outputs.
+
+## Proposed repository layout
+
+```text
+CMakeLists.txt
+CMakePresets.json
+flake.nix
+include/motionbricks/
+  motionbricks.h                 stable C ABI; opaque handles only
+  motionbricks.hpp               optional RAII C++ wrapper
+src/
+  backend.{hpp,cpp}              GGML CPU/Vulkan selection and buffers
+  error.{hpp,cpp}                status mapping and exception firewall
+  gguf.{hpp,cpp}                 checked metadata/tensor loading
+  model.{hpp,cpp}                immutable model bundle
+  transformer.{hpp,cpp}          MHA, FFN, norms, masks, embeddings
+  root_model.{hpp,cpp}           duration and root-trajectory graph
+  pose_model.{hpp,cpp}           masked pose-token prediction graph
+  vq_decoder.{hpp,cpp}           multi-head code lookup and conv decoder
+  sampling.{hpp,cpp}             argmax/Gumbel and local deterministic PRNG
+  skeleton_g1.{hpp,cpp}          G1 hierarchy, rest pose, FK and mappings
+  motion_rep.{hpp,cpp}           414/413/418 feature conversion and stats
+  clip.{hpp,cpp}                 checked skeletal clip/style assets
+  controller.{hpp,cpp}           spring target and exemplar alignment
+  agent.{hpp,cpp}                stateful replanning and frame buffer
+  capi.cpp                       PureGo-facing ownership API
+  cli.cpp                        inspect, plan, convert-style, benchmark
+scripts/
+  convert_to_gguf.py             safetensors/config -> GGUF
+  inspect_bundle.py              independent metadata/tensor inspection
+reference/
+  Dockerfile                     pinned trusted PyTorch environment
+  extract_safe.py                legacy Lightning checkpoint -> safetensors
+  capture_fixture.py             layer/stage/end-to-end reference capture
+  capture_demo_session.py        recorded upstream controller interaction
+tests/
+  unit/                          deterministic C++ math and validation
+  parity/                        F32 CPU and Vulkan fixture runners
+  integration/                   C ABI, agent, GLB/style and demo protocol
+fuzz/
+  capi_fuzz.cpp                  public non-GGUF inputs and call sequences
+  clip_fuzz.cpp                  GLB/style parsing and validation
+demo/
+  main.go                        PureGo server and per-client sessions
+  web/index.html
+  web/app.js
+  web/style.css
+  web/vendor/                    pinned Three.js distribution or import map
+```
+
+GGML should be a pinned submodule as in the two reference projects. CMake
+builds shared and static library variants, a CLI, tests, and optional fuzzers.
+No source path, model path, GPU index, or backend path is compiled in.
+
+## Runtime data contracts
+
+### Canonical public animation
+
+The public animation boundary should be independent of MuJoCo:
+
+- `root_translation`: row-major F32 `[frames, 3]`, Y-up motion space;
+- `local_rotation_xyzw`: row-major F32 `[frames, 34, 4]`;
+- debug target roots: row-major F32 `[4, 3]`;
+- debug target local rotations: row-major F32 `[4, 34, 4]`;
+- frame rate: 30 FPS for the released model;
+- joint names, parents, and rest offsets: queried from model metadata;
+- optional contacts: row-major F32 `[frames, 4]`.
+
+MuJoCo qpos is an adapter/debug output, not the primary animation format. The
+29-DOF G1 qpos form is useful for exact upstream demo parity but loses the
+generic skeletal-animation boundary needed by Three.js and Kimodo.
+
+### Neural input
+
+Internally the planner builds the same unnormalized sparse constraints as
+upstream:
+
+- 4 recent context frames and up to 4 target frames;
+- global root features `[constraint_frames, 5]`;
+- local root features `[constraint_frames, 4]`;
+- local-pose constraint features;
+- masks saying which sparse constraints are present;
+- a requested duration or an allowed-duration mask;
+- optional text embeddings kept absent for the released demo path.
+
+The released inference path recenters root X/Z, normalizes features, predicts
+the root trajectory and duration, predicts 8-head pose codes, decodes four
+frames per token, converts local-root features back to global motion, and
+restores the original world offset.
+
+### Style assets
+
+A style is application/controller data rather than a learned model selector.
+It contains:
+
+- a name and optional command binding;
+- one or more G1 reference clips;
+- an allowed-duration mask;
+- average travel speed or an explicit override;
+- optional sampling range and heading correction;
+- provenance, skeleton identity, FPS, and source hash.
+
+Original demo styles are extracted from `G1-clip.ckpt` in the trusted reference
+container. User styles are imported from G1 skeletal GLB, including GLB output
+from `kimodo.cpp`. Both are converted to the same checked style format. The
+controller samples four adjacent pose frames, applies the requested world
+heading and spring-produced root target, and supplies them as ending
+constraints. A style can therefore be changed or added without changing
+MotionBricks weights.
+
+Before claiming direct Kimodo compatibility, a fixture must verify the G1
+joint order, rest pose, local-rotation convention, coordinate system, and FPS.
+The adapter will reject rather than guess when metadata is incompatible.
+
+## PureGo-compatible C API sketch
+
+All configurable records and returned objects are opaque heap handles. Public
+integer types have explicit widths; booleans and enum-like values are
+`uint32_t`; no C enum or by-value struct is part of the ABI. Every constructor
+has a matching free function. Functions return a status and use a caller-owned
+error buffer.
+
+```c
+typedef uint32_t mb_status;
+typedef uint32_t mb_device;
+
+typedef struct mb_runtime_options mb_runtime_options;
+typedef struct mb_model           mb_model;
+typedef struct mb_style           mb_style;
+typedef struct mb_command         mb_command;
+typedef struct mb_agent           mb_agent;
+typedef struct mb_motion          mb_motion;
+
+uint32_t mb_abi_version(void);
+
+mb_status mb_runtime_options_create(mb_runtime_options **out,
+                                    char *err, uint64_t err_cap);
+void mb_runtime_options_free(mb_runtime_options *value);
+mb_status mb_runtime_options_set_device(mb_runtime_options *, mb_device,
+                                        char *, uint64_t);
+mb_status mb_runtime_options_set_threads(mb_runtime_options *, uint32_t,
+                                         char *, uint64_t);
+mb_status mb_runtime_options_set_backend_directory(mb_runtime_options *,
+                                                   const char *, char *, uint64_t);
+mb_status mb_runtime_options_get_device(const mb_runtime_options *, mb_device *,
+                                        char *, uint64_t);
+
+mb_status mb_model_load(const char *bundle_directory,
+                        const mb_runtime_options *, mb_model **out,
+                        char *err, uint64_t err_cap);
+void mb_model_free(mb_model *);
+mb_status mb_model_get_joint_count(const mb_model *, uint32_t *out,
+                                   char *, uint64_t);
+mb_status mb_model_get_joint_name(const mb_model *, uint32_t joint,
+                                  const char **borrowed, char *, uint64_t);
+mb_status mb_model_get_joint_parent(const mb_model *, uint32_t joint,
+                                    int32_t *out, char *, uint64_t);
+mb_status mb_model_get_neutral_joint_position(const mb_model *, uint32_t joint,
+                                              float *x, float *y, float *z,
+                                              char *, uint64_t);
+
+mb_status mb_style_load(const mb_model *, const char *style_path,
+                        mb_style **out, char *err, uint64_t err_cap);
+void mb_style_free(mb_style *);
+mb_status mb_style_get_name(const mb_style *, const char **borrowed,
+                            char *, uint64_t);
+mb_status mb_style_set_speed(mb_style *, float metres_per_second,
+                             char *, uint64_t);
+
+mb_status mb_command_create(mb_command **out, char *err, uint64_t err_cap);
+void mb_command_free(mb_command *);
+mb_status mb_command_set_style(mb_command *, const mb_style *, char *, uint64_t);
+mb_status mb_command_set_movement_direction(mb_command *, float x, float y, float z,
+                                            char *, uint64_t);
+mb_status mb_command_set_facing_direction(mb_command *, float x, float y, float z,
+                                          char *, uint64_t);
+mb_status mb_command_set_target_speed(mb_command *, float, char *, uint64_t);
+mb_status mb_command_set_world_target(mb_command *, float x, float y, float z,
+                                      float heading_radians, uint32_t enabled,
+                                      char *, uint64_t);
+mb_status mb_command_set_seed(mb_command *, uint64_t, char *, uint64_t);
+
+mb_status mb_agent_create(const mb_model *, mb_agent **out,
+                          char *err, uint64_t err_cap);
+void mb_agent_free(mb_agent *);
+mb_status mb_agent_reset(mb_agent *, const mb_style *initial_style,
+                         char *err, uint64_t err_cap);
+mb_status mb_agent_set_context(mb_agent *, const float *root_xyz,
+                               const float *local_xyzw, uint64_t frames,
+                               uint64_t joints, char *err, uint64_t err_cap);
+mb_status mb_agent_plan(mb_agent *, const mb_command *, mb_motion **out,
+                        char *err, uint64_t err_cap);
+mb_status mb_agent_advance(mb_agent *, uint32_t frames, char *, uint64_t);
+
+void mb_motion_free(mb_motion *);
+mb_status mb_motion_get_frame_count(const mb_motion *, uint64_t *out,
+                                    char *, uint64_t);
+mb_status mb_motion_get_joint_count(const mb_motion *, uint64_t *out,
+                                    char *, uint64_t);
+mb_status mb_motion_get_root_translations(const mb_motion *,
+                                          const float **borrowed, uint64_t *values,
+                                          char *, uint64_t);
+mb_status mb_motion_get_local_rotations_xyzw(const mb_motion *,
+                                             const float **borrowed, uint64_t *values,
+                                             char *, uint64_t);
+mb_status mb_motion_get_target_frame_count(const mb_motion *, uint64_t *out,
+                                           char *, uint64_t);
+mb_status mb_motion_get_target_root_translations(const mb_motion *,
+                                                 const float **borrowed, uint64_t *values,
+                                                 char *, uint64_t);
+mb_status mb_motion_get_target_local_rotations_xyzw(const mb_motion *,
+                                                    const float **borrowed, uint64_t *values,
+                                                    char *, uint64_t);
+```
+
+The final header will add getters for every option setter and explicit lifetime
+documentation. Borrowed strings and arrays remain valid until their owning
+handle is freed or mutated. `mb_model` is immutable and may be shared;
+`mb_agent`, `mb_command`, and `mb_motion` are not concurrently mutable. No C++
+exception crosses `capi.cpp`.
+
+The CLI uses this same C API for end-to-end operations so the ABI is exercised
+outside unit tests. Internal parity tools may access raw tensors through a
+non-installed test header; raw GGML objects and 413/414-dimensional model
+features are not exposed as stable public API.
+
+## Model conversion and bundle
+
+Use a directory manifest with separate memory-mappable component files:
+
+```text
+motionbricks-g1-f32/
+  manifest.json
+  root-f32.gguf
+  pose-f32.gguf
+  vq-decoder-f32.gguf
+  styles/
+    upstream-defaults.mbstyle
+```
+
+The manifest records format version, model identity, source revision, source
+and intermediate hashes, skeleton key, FPS, component dtype, GGML revision,
+and mutually compatible component identities. Loading rejects mixed bundles.
+
+GGUF metadata records all architecture values rather than relying on C++
+defaults, including the released 512-wide root transformer, 1024-wide pose
+transformer, 16 attention heads, layer counts, token range, eight pose-code
+heads, four frames per token, normalization statistics, feature-index tables,
+skeleton data, and sampling defaults. Every tensor lookup is named, typed,
+shape checked, and bounds checked.
+
+The ordinary converter accepts safetensors plus JSON only. NVIDIA's Lightning
+checkpoints and the serialized demo-clip checkpoint are Python pickle formats;
+only the pinned, network-disabled reference container loads those files. It
+then writes safetensors/JSON with hashes for the normal converter. The VQ
+encoder is omitted from runtime bundles because inference only needs the code
+embeddings and decoder; a reference/debug bundle may retain it for tokenizer
+parity.
+
+## Neural implementation order
+
+### Shared operators
+
+Implement the smallest operation set used by the released checkpoints:
+
+- checked embedding lookup, linear layers, ReLU, LayerNorm, residual add;
+- PyTorch-compatible multi-head self-attention and key-padding masks;
+- fixed/learned position embeddings;
+- 1D convolution, transpose convolution, and dilated residual blocks;
+- reshape, permute, concatenate, gather/scatter, softmax and argmax.
+
+An operation audit against the actual `state_dict` and forward hooks precedes
+graph work. PyTorch defaults such as post-norm transformer order, bias,
+activation, epsilon, and attention scaling must be captured explicitly, not
+reconstructed from memory.
+
+### Root model
+
+The root graph embeds sparse start/end pose and root constraints, duration,
+and position; runs shared and output transformer stacks; predicts duration;
+and expands transformer features through the conditioned convolutional decoder
+to the global root trajectory. Duration filtering uses the caller/style's
+allowed-token mask exactly as upstream.
+
+### Pose model
+
+The pose graph combines masked multi-head VQ code embeddings, predicted root
+features, sparse pose constraints, duration embedding, and position embedding;
+runs the 16-layer transformer; and produces per-head code logits. One sampling
+iteration is the released demo default. Argmax is supported for deterministic
+diagnostics; production Gumbel sampling uses an agent-local PRNG and seed.
+Reference fixtures store the random uniforms/Gumbel values explicitly instead
+of assuming PyTorch and C++ generators produce identical streams.
+
+### VQ decoder and representation inverse
+
+Selected codes are expanded through the eight code heads and conditioned
+decoder. Sparse start/end constraints and the predicted root path are applied
+as upstream. The resulting normalized local representation is converted to
+global features, denormalized, and transformed into skeletal animation. These
+ordinary math stages are implemented in C++ and tested independently of GGML.
+
+### Stateful controller
+
+An agent owns its current generated buffer and frame cursor. At a replan it:
+
+1. gathers the previous four actual frames;
+2. derives current root velocity and heading velocity;
+3. applies the upstream critically damped spring to the requested movement,
+   facing, speed, or explicit world target;
+4. samples and aligns four frames from the selected style clip;
+5. constructs sparse model constraints and runs inference;
+6. restores the world transform, converts the output to local rotations, and
+   applies the upstream context blend;
+7. exposes the valid predicted prefix and retains it as the next context.
+
+The controller uses seconds internally and derives frame counts from model FPS.
+It must not silently enable canonicalization, target skipping, alternate root
+selection, extra pose iterations, or any other non-default upstream option.
+
+## Web demo
+
+The Go server dynamically loads the shared library with PureGo. It owns one
+`mb_agent` per WebSocket session and shares one immutable `mb_model`. Initially
+planning requests are serialized through a worker so Vulkan ownership and peak
+memory are predictable; parallel sessions can be added after profiling.
+
+The browser sends compact command state only: pressed controls, movement and
+camera-facing vectors, selected style, and monotonically increasing sequence
+number. The server returns a binary animation chunk containing a small
+versioned header, frame count, root translations, and local quaternions.
+Three.js keeps a short playback buffer and samples at render time. The server,
+not the browser, owns authoritative agent state and drops stale commands.
+
+HTTP endpoints provide model/style metadata and health information. A
+WebSocket carries interactive commands and generated chunks. The frontend
+includes:
+
+- WASD movement relative to the camera;
+- independently controllable facing direction;
+- style/action buttons populated from the style manifest;
+- a skeleton/mesh viewer, pause/reset, latency and buffered-frame display;
+- an optional debug view for target position, facing vector, contacts, and
+  replan boundaries.
+
+The initial viewer can render a simple G1 skeleton. A skinned character and
+retargeting are later integrations, potentially using `skin-tokens.cpp`.
+
+## Reference and parity strategy
+
+Every fixture has a JSON manifest containing the upstream commit, checkpoint
+and safetensors hashes, config hash, PyTorch version, dtype/device, tensor
+shapes, seed/random inputs, selected style, command stream, and tolerances.
+Binary tensors are little-endian and versioned. Tests refuse mismatched
+fixtures.
+
+Capture and compare in this order:
+
+| Boundary | Reference values |
+|---|---|
+| checkpoint extraction | every tensor name, dtype, shape, hash |
+| skeletal math | qpos/local rotations, FK positions, global rotations |
+| motion representation | raw, global 414, local 413, dual conversion, normalization |
+| style/controller | sampled frames, average speed, spring roots/headings, aligned targets |
+| shared neural ops | linear, LayerNorm, attention, masks, conv/residual blocks |
+| root network | every projection, transformer layer, duration logits, decoder layer, root path |
+| pose network | every embedding/projection, transformer layer, logits, sampled codes |
+| VQ decoder | code embeddings and every decoder layer |
+| inference composition | recenter, constraints, root, pose, decode, restore world transform |
+| agent session | recorded command changes, replans, valid lengths, final skeletal frames |
+
+The first exemplar set should be small but discriminating:
+
+- idle continuation with a fixed duration;
+- walk forward, then a 90-degree turn during playback;
+- switch from walk to one strongly recognizable upstream style;
+- explicit world target behind the character;
+- a fixed Kimodo G1 reference clip used as a style;
+- minimum and maximum allowed duration;
+- both argmax and stored-Gumbel-token inference.
+
+F32 CPU tolerances are set per stage from observed error, with maximum absolute
+and relative L2 limits. End-to-end animation also checks root error, joint
+position error after FK, quaternion angular error, token equality where
+applicable, duration equality, and contact equality. Vulkan has its own
+documented tolerances but must preserve duration and discrete code decisions
+on the exemplar suite unless an explicitly reviewed near-tie is present.
+
+### Automated upstream sessions and observational tracing
+
+The reference harness should drive the released upstream demo without a human
+keyboard and record both numerical traces and a MuJoCo preview. Numerical
+traces are the parity authority. Video is a synchronized diagnostic artifact,
+not a pixel-exact test oracle.
+
+Instrumentation must remain observational. In particular, adding target-pose
+visualization must not alter inference inputs, controller state, random-number
+consumption, playback timing, MuJoCo state, or final numerical output. Use the
+following intervention order, stopping as soon as the required value is
+available:
+
+1. call an existing public method and copy its returned value in the capture
+   script;
+2. wrap an existing method or register a PyTorch forward hook from the capture
+   script;
+3. add an optional no-op trace callback at a stable method boundary;
+4. make a small upstream source edit only when a value is otherwise confined
+   to a local variable;
+5. never refactor or reorder model/controller calculations merely to expose a
+   trace.
+
+Before adding internal taps, run the unmodified pinned upstream revision at
+least twice with the same scripted controls and seeds. Record the final motion
+features, MuJoCo qpos, valid lengths, modes, and replan frame indices using
+only values already returned by the demo classes. This establishes both the
+baseline and any numerical nondeterminism inherent to the reference CUDA
+environment. Discrete outputs must repeat exactly. Float tolerances for the
+instrumentation check must be no wider than the variation observed between
+the two unmodified runs.
+
+After each instrumentation change, repeat the same session with tracing off
+and on. Both runs must match the unmodified baseline: exact for masks, modes,
+seeds, duration choices and pose codes; bitwise for deterministic CPU values;
+and within the measured baseline envelope for CUDA floats. Reject or redesign
+any tap that changes those results. The recorder must not call random
+functions, mutate a tensor or dictionary owned by upstream, change dtype or
+device, enable gradients, or retain a view that upstream later modifies. It
+copies with `detach().clone()` and performs CPU transfer only after the value
+has been consumed by the upstream calculation.
+
+The initial taps are:
+
+| Boundary | Upstream location | Trace values |
+|---|---|---|
+| playback context | `full_navigation_agent.get_context_*` | four qpos frames and motion features |
+| controller | `WASD_controller.generate_control_signals` | scripted keys, mode, movement/facing vectors, allowed durations |
+| spring | `_generate_spring_model_position_and_heading` | start and target root positions/headings |
+| placed target poses | `_generate_target_joint_transforms` | four global joint positions/rotations and root positions |
+| sparse model input | `_generate_inbetween_frames` | global/local root values, poses, masks and requested/allowed durations |
+| root network | root-backbone forward hook | duration logits, selected duration and predicted root path |
+| pose network | pose-backbone forward hook | pose logits, selected codes and conditioning mask |
+| VQ decoder | decoder forward hook | quantized input, conditions, masks and normalized decoded motion |
+| composed inference | `motion_inference.predict` | valid length and global/local motion representations |
+| playback output | `generate_new_frames`/`get_next_frame` | raw qpos, blended qpos, cursor and replan event |
+
+Prefer explicit trace calls for controller-local values and forward hooks for
+neural modules. The existing `info` argument to `motion_inference.predict` may
+carry copied debug values, but normal inference must continue to work with it
+absent. Large layer-by-layer captures are enabled for one planning event at a
+time rather than every playback frame.
+
+The scripted session driver supplies `control_info["key_pressed"]`, so it does
+not require an OS keyboard listener. It uses a fixed camera proxy because the
+WASD controller derives movement from viewer-camera orientation. NumPy,
+PyTorch and per-plan MotionBricks seeds are explicit. An initial scenario is:
+
+- 60 frames idle;
+- 60 frames walking forward;
+- 45 frames walking through a right turn;
+- 60 frames released to idle;
+- 60 frames walking with a distinctive style such as `walk_zombie`;
+- 60 frames released and allowed to settle.
+
+Each scenario directory contains a manifest, JSONL control/replan events,
+Safetensors files for planning boundaries and playback, and optional media:
+
+```text
+session-idle-walk-turn/
+  manifest.json
+  controls.jsonl
+  events.jsonl
+  plan-000.safetensors
+  plan-001.safetensors
+  playback.safetensors
+  preview.mp4
+  snapshots/
+```
+
+The manifest records the upstream commit, checkpoint/config hashes, scenario
+version, all relevant demo flags, dtype/device, Python/PyTorch/CUDA/MuJoCo
+versions, seeds, FPS and coordinate conventions. Do not use pickle for fixture
+data. Each planning file identifies tensors by semantic name, shape and dtype.
+
+Generate video in a second, offline pass from the stored qpos and target-pose
+traces. Use `mujoco.Renderer`, assign the captured qpos, call `mj_forward`, and
+render with a deterministic camera at 30 FPS. On Linux use EGL when available
+and OSMesa as a software fallback. Save selected lossless PNG frames alongside
+the MP4. This separation ensures rendering load cannot affect controller
+cadence or inference.
+
+Visible target keyframes are also an offline rendering concern. Draw the four
+captured target skeletons as orange/magenta ghost geometry in an `MjvScene` or
+as a post-render overlay. Do not add bodies or constraints to the physics XML,
+write target poses into `mjData`, or reuse mutable tensors from inference. The
+animated G1 remains opaque and visually distinct. Overlay the absolute frame,
+plan number, mode/style, movement/facing vectors, selected duration and replan
+markers. If an interactive upstream target view is later useful, it is a
+separate optional patch and must pass the same trace-off/trace-on
+non-interference gate.
+
+The port replays each captured planning event at the same public boundaries.
+It compares integer decisions exactly, floats with boundary-specific
+tolerances, quaternions by sign-invariant angular distance, and joint positions
+after FK. Session checks cover replan timing, valid buffer lengths, root and
+joint velocity continuity, and style transitions. The idle scenario must also
+confirm that upstream performs only the expected transition into idle, then
+ceases idle-to-idle replanning and eventually holds a numerically constant
+frame.
+
+Implement this work in gates:
+
+1. create the external scripted driver and capture unmodified final outputs;
+2. prove same-seed repeatability and write the baseline manifest;
+3. add controller/model-input taps one boundary at a time, running the
+   non-interference comparison after each change;
+4. add neural forward hooks and capture one complete planning event;
+5. capture the full idle/walk/turn/style session and import it into the C++
+   parity runner;
+6. render MuJoCo video and target ghosts offline from the accepted traces;
+7. add the scenario to CPU CI and keep video generation as an optional local
+   or artifact-producing job.
+
+**Exit:** a fresh pinned upstream environment reproduces the accepted session;
+trace-off and trace-on outputs match the pre-instrumentation baseline; the C++
+runtime passes every captured boundary; and the synchronized MuJoCo preview
+shows playback and target keyframes without participating in inference.
+
+## Safety, fuzzing, and validation
+
+GGUF parsing remains GGML's responsibility, but motion-bricks validates bundle
+metadata and every expected tensor. Fuzz targets cover:
+
+- the installed C ABI with generated valid/invalid call sequences;
+- opaque-handle nulls, ownership order, repeated free attempts in the harness,
+  lengths, finite values, dimensions, and invalid enums;
+- GLB/style assets, skeleton metadata, malformed animation tracks, NaN/Inf,
+  huge frame counts, and incompatible joint orders;
+- command normalization, degenerate direction vectors, duration masks, spring
+  math, representation conversions, quaternion/matrix conversions, and FK;
+- the versioned WebSocket binary decoder independently in Go.
+
+Run C++ fuzzers with ASan and UBSan. Unit and integration tests run under the
+same sanitizers. File parsers impose explicit byte, frame, joint, accessor, and
+allocation limits before allocating. No user-provided path is interpreted by
+the browser; the server uses configured style/model roots.
+
+## Build and configuration
+
+The normal build is distro-agnostic CMake. Nix supplies a reproducible
+developer shell containing Clang, CMake, Ninja, Go, Python fixture tools,
+Vulkan headers/loader/tools, shaderc, and sanitizers. Docker contains upstream
+Python/CUDA extraction and fixture capture. Neither is required by installed
+runtime consumers.
+
+Suggested configuration inputs:
+
+- CMake cache: GGML source directory, tests/fuzzers, Vulkan enablement;
+- environment/CLI: model bundle, style directory, backend directory, device,
+  CPU thread count, server address, fixture directory;
+- Vulkan device selection: documented loader variables or a CLI-selected
+  GGML Vulkan device after confirming backend support. The Nix shell supplies
+  loader paths but never assumes an NVIDIA device index.
+
+CI lanes are formatting/static checks, CPU unit tests, ASan/UBSan tests, CPU
+parity with optional fixture artifacts, and a hardware-tagged Vulkan parity
+lane. Large weights and fixtures are downloaded by hash and never committed.
+
+## Implementation milestones
+
+### 0. Lock the reference
+
+- Record the upstream MotionBricks commit and GGML revision.
+- Fetch Git LFS checkpoints/assets and record their hashes/licences.
+- Build a pinned Python reference environment and reproduce the interactive
+  demo unchanged.
+- Capture one deterministic end-to-end upstream exemplar.
+
+**Exit:** the reference script reproduces a stored animation and manifest on a
+fresh environment.
+
+### 1. Scaffold and define contracts
+
+- Add CMake, presets, Nix flake, pinned GGML, library/CLI/test targets.
+- Land the opaque C header, C++ wrapper, status/error rules, and stub handles.
+- Define fixture, GGUF bundle, style, and WebSocket format versions.
+- Add ABI lifecycle tests from C and PureGo.
+
+**Exit:** CPU-only stubs build, install, and are called successfully through
+PureGo without any mirrored struct.
+
+### 2. Safe extraction and exemplar capture
+
+- Extract root, pose, VQ, stats, skeleton, and original style tensors to
+  safetensors/JSON in the trusted container.
+- Capture the unmodified scripted upstream session before adding internal
+  instrumentation, then apply the observational tracing and non-interference
+  gates defined above.
+- Add forward hooks/capture for every required layer and preprocessing stage.
+- Capture the exemplar matrix above, including random sampling inputs.
+- Render synchronized MuJoCo and target-keyframe previews offline from the
+  accepted numerical traces.
+- Build the safetensors-to-GGUF converter and bundle inspector.
+
+**Exit:** source and converted tensor inventories match exactly, all bundle
+identities are validated, and trace-enabled upstream output matches the
+unmodified baseline.
+
+### 3. Deterministic motion/controller math
+
+- Implement G1 metadata, quaternion/matrix conversions, FK, feature extraction,
+  414/413 representation conversion, stats, and skeletal output conversion.
+- Implement style import, clip alignment, spring trajectory, duration masks,
+  context selection, and blending without neural inference.
+- Add unit, fixture parity, and sanitizer tests for each stage.
+
+**Exit:** C++ matches all non-neural upstream fixture boundaries.
+
+### 4. VQ decoder on CPU
+
+- Audit and implement required GGML convolution/residual operations.
+- Load codebooks and decoder tensors from GGUF.
+- Match each decoder layer and decoded local-motion features in F32.
+
+**Exit:** CPU VQ decoder fixture passes end to end.
+
+### 5. Root model on CPU
+
+- Implement shared transformer operators and root embeddings/masks.
+- Match each transformer layer, duration selection, conditioned decoder, and
+  predicted global/local root trajectories.
+
+**Exit:** CPU root fixtures pass for fixed, predicted, minimum, and maximum
+durations.
+
+### 6. Pose model and composed inference on CPU
+
+- Implement pose embeddings, transformer, logits, argmax/Gumbel sampling.
+- Compose root -> pose -> VQ -> representation inverse.
+- Implement the stateful agent and verify recorded replanning sessions.
+
+**Exit:** F32 CPU passes every layer and end-to-end skeletal exemplar.
+
+### 7. C API, Kimodo styles, and web demo
+
+- Complete opaque getters/setters, ownership, error paths, and installed C API.
+- Verify Kimodo G1 GLB import and add a style conversion workflow.
+- Implement Go/PureGo server, binary WebSocket protocol, and Three.js viewer.
+- Reproduce upstream styles and interactive turn/style-switch scenarios.
+
+**Exit:** a fresh build runs the interactive demo using both an original and a
+Kimodo-authored style, with no Python process at runtime.
+
+### 8. Vulkan parity and performance
+
+- Enable GGML Vulkan and select the intended GPU through runtime configuration.
+- Match every component and end-to-end fixture using Vulkan-specific
+  tolerances.
+- Profile allocation, upload, graph construction, inference, and WebSocket
+  latency; cache graphs/buffers where safe.
+- Establish a replan cadence the machine sustains while playback remains
+  buffered.
+
+**Exit:** Vulkan preserves exemplar behavior and meets the documented
+interactive latency/buffer target on the test machine.
+
+### 9. Hardening and optimized weights
+
+- Run long ASan/UBSan fuzz campaigns and multi-session soak tests.
+- Add F16 conversion/parity, then evaluate quantization component by component.
+- Package install targets, model downloader, licences, deployment docs, and
+  reproducible release manifests.
+
+**Exit:** release artifacts are reproducible, validated, and contain no hidden
+machine-specific paths or upstream Python dependency.
+
+## Decisions to revisit after the first fixtures
+
+- Whether the public style format should be a small GGUF, GLB plus JSON, or a
+  custom binary. GLB plus JSON is easiest for user-authored Kimodo assets;
+  GGUF is likely best for exact preprocessed upstream tensors.
+- Whether `mb_agent_plan` should retain output internally or return an owning
+  immutable copy. The owning result above is simpler and safer for PureGo;
+  profiling may justify an explicit caller-buffer API later.
+- Whether to expose a generic sparse-keyframe API in ABI version 1. It is more
+  capable than the interactive controller but substantially enlarges the
+  validation surface. The first slice can support movement/facing/style/world
+  target while keeping the generic constraint builder internal.
+- Whether to link a small shared GLB module from `kimodo.cpp`/`skin-tokens.cpp`
+  or keep style conversion in the CLI. Reuse should happen only through a
+  clean library boundary, not by copying diverging parser code.
+- Exact interactive latency, memory, and browser buffer targets. Measure the
+  F32 CPU baseline and F32 Vulkan implementation before promising numbers.
+
+## Explicitly deferred
+
+- training or fine-tuning MotionBricks;
+- arbitrary skeleton inference or automatic retargeting;
+- text input to MotionBricks itself;
+- robot torque/control-policy output;
+- WebAssembly inference in the browser;
+- F16/quantized defaults before F32 parity;
+- multi-batch inference and concurrent mutation of one agent.

docs/motions-bricks.md

@@ -0,0 +1,42 @@
+# Human led design document
+
+Don't modify this unless instructed.
+
+# Questions to loop back to
+
+- camera controls, zoom pan etc
+- Set a new target for parity, exactly what components should we select for that?
+- where is the C API documentation
+- Are low-level functions exposed so things like styles can be handle externally? could someone just use it for inference?
+- camera relative WASD keys
+
+# End goal
+
+We want to use motion-bricks.cpp with kimodo.cpp animation key-frames and we want to be able to use these in a web demo.
+
+So we have a web demo that takes some key-frames for particular movements and styles of movements, like in the upstream demo, including the original key-frames. Like in the upstream demo we are going to have a bunch of movements we can do with the WASD keys and jump or some other user definable motion.
+
+Eventually, we want to have have a configurable list of movements, that include a keyframe, an action (e.g. move forward at 1m/s, move up (jump)), so we could define a walking action with a keyframe from someone walking and an action of moving forwards, and we could define a forward roll action by specifying one or more keyframes from rolling forwards and also a moving forward action (but perhaps faster forward motion).
+
+The motion-bricks.cpp library should expose a C API for FFI which is compatible with libraries like purego. So purego can't predict struct layouts, so struct based interfaces should have a constructor for allocating structs and getters and setters.
+
+The demo server should be written in Go and use purego (or similar). The frontend should use plain HTML/CSS and three.js.
+
+# Bonus Goal
+
+Use motion-bricks.cpp with a physically simulated robot in MuJoco or a web browser simulator.
+
+# Process
+
+- First we want to produce exemplar outputs from upstream
+- We want to create parity tests for each component, including every layer of the neural network.
+- We want to ensure that components feeding and consuming input and output from the neural network also match upstream in terms of functionality
+- We need to ensure we are not using settings in our implementation by default which are not set as default in upstream
+- We should use GGML with Vulkan and CPU backends, first CPU and then Vulkan parity should be achieved
+- We can use ../kimodo.cpp and ../skin-tokens.cpp/ as a reference, you should scan these projects before designing and check them when trying to solve an issue for an existing solution
+- We are on NixOS and can use a Nix flake to get depenencies for GGML/C++ and Vulkan, the machine we are on has a functioning NVIDIA Vulkan GPU and an AMD one. We want to use the NVIDIA gfx card.
+- For the upstream depencies, if we can use Nix that is great, but otherwise we can use Docker
+- Don't rely on the current machine's paths, use distro agnostic paths and env vars. parameterise anything that we need to specify in the CMake file or a .env
+- We need to fuzz the C++ components except for GGUF input (we trust that GGML has that covered). We should do that with the ASan and UBSAN enabled.
+- We should use GGML as git submodule and if we need to patch it for any reason we can apply patches during the project configuration phase
+- Use headless chrome (from nix) to perform QA after changes. Use a few different actions and take screenshots before during and after

flake.lock

@@ -0,0 +1,27 @@
+{
+  "nodes": {
+    "nixpkgs": {
+      "locked": {
+        "lastModified": 1776169885,
+        "narHash": "sha256-l/iNYDZ4bGOAFQY2q8y5OAfBBtrDAaPuRQqWaFHVRXM=",
+        "owner": "NixOS",
+        "repo": "nixpkgs",
+        "rev": "4bd9165a9165d7b5e33ae57f3eecbcb28fb231c9",
+        "type": "github"
+      },
+      "original": {
+        "owner": "NixOS",
+        "repo": "nixpkgs",
+        "rev": "4bd9165a9165d7b5e33ae57f3eecbcb28fb231c9",
+        "type": "github"
+      }
+    },
+    "root": {
+      "inputs": {
+        "nixpkgs": "nixpkgs"
+      }
+    }
+  },
+  "root": "root",
+  "version": 7
+}

flake.nix

@@ -0,0 +1,39 @@
+{
+  description = "motion-bricks.cpp — GGML CPU/Vulkan motion planning";
+
+  inputs.nixpkgs.url = "github:NixOS/nixpkgs/4bd9165a9165d7b5e33ae57f3eecbcb28fb231c9";
+
+  outputs = { self, nixpkgs }:
+    let
+      systems = [ "x86_64-linux" "aarch64-linux" ];
+      eachSystem = nixpkgs.lib.genAttrs systems;
+    in {
+      devShells = eachSystem (system:
+        let pkgs = import nixpkgs { inherit system; };
+        in {
+          default = pkgs.mkShell {
+            packages = with pkgs; [
+              cmake
+              ninja
+              clang
+              pkg-config
+              git
+              git-lfs
+              go
+              python3
+              python3Packages.huggingface-hub
+              python3Packages.numpy
+              python3Packages.safetensors
+              shaderc
+              spirv-tools
+              vulkan-headers
+              vulkan-loader
+              vulkan-tools
+            ];
+            shellHook = ''
+              export LD_LIBRARY_PATH="${pkgs.vulkan-loader}/lib:/run/opengl-driver/lib''${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH}"
+            '';
+          };
+        });
+    };
+}

include/motionbricks/motionbricks.h

@@ -0,0 +1,178 @@
+#ifndef MOTIONBRICKS_MOTIONBRICKS_H
+#define MOTIONBRICKS_MOTIONBRICKS_H
+
+#include <stdint.h>
+
+#define MB_ABI_VERSION UINT32_C(1)
+
+#if defined(_WIN32) && defined(MOTIONBRICKS_SHARED)
+#  if defined(MOTIONBRICKS_BUILD)
+#    define MB_API __declspec(dllexport)
+#  else
+#    define MB_API __declspec(dllimport)
+#  endif
+#elif defined(__GNUC__) && defined(MOTIONBRICKS_SHARED)
+#  define MB_API __attribute__((visibility("default")))
+#else
+#  define MB_API
+#endif
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+typedef uint32_t mb_status;
+#define MB_OK                   UINT32_C(0)
+#define MB_INVALID_ARGUMENT     UINT32_C(1)
+#define MB_OUT_OF_MEMORY        UINT32_C(2)
+#define MB_IO_ERROR             UINT32_C(3)
+#define MB_INVALID_FORMAT       UINT32_C(4)
+#define MB_INCOMPATIBLE_MODEL   UINT32_C(5)
+#define MB_BACKEND_UNAVAILABLE  UINT32_C(6)
+#define MB_COMPUTE_FAILED       UINT32_C(7)
+#define MB_NOT_IMPLEMENTED      UINT32_C(8)
+#define MB_INTERNAL_ERROR       UINT32_C(9)
+
+typedef uint32_t mb_device;
+#define MB_DEVICE_AUTO    UINT32_C(0)
+#define MB_DEVICE_CPU     UINT32_C(1)
+#define MB_DEVICE_VULKAN  UINT32_C(2)
+
+typedef struct mb_runtime_options mb_runtime_options;
+typedef struct mb_model mb_model;
+typedef struct mb_style mb_style;
+typedef struct mb_command mb_command;
+typedef struct mb_agent mb_agent;
+typedef struct mb_motion mb_motion;
+
+MB_API uint32_t mb_abi_version(void);
+MB_API const char * mb_status_string(mb_status status);
+
+/* Runtime options are opaque so FFI callers never reproduce a struct layout. */
+MB_API mb_status mb_runtime_options_create(mb_runtime_options ** output,
+                                           char * error, uint64_t error_capacity);
+MB_API void mb_runtime_options_free(mb_runtime_options * value);
+MB_API mb_status mb_runtime_options_set_device(mb_runtime_options * value, mb_device device,
+                                               char * error, uint64_t error_capacity);
+MB_API mb_status mb_runtime_options_get_device(const mb_runtime_options * value, mb_device * output,
+                                               char * error, uint64_t error_capacity);
+MB_API mb_status mb_runtime_options_set_threads(mb_runtime_options * value, uint32_t threads,
+                                                char * error, uint64_t error_capacity);
+MB_API mb_status mb_runtime_options_get_threads(const mb_runtime_options * value, uint32_t * output,
+                                                char * error, uint64_t error_capacity);
+/* Passing NULL clears the override. The returned string is borrowed. */
+MB_API mb_status mb_runtime_options_set_backend_directory(mb_runtime_options * value,
+                                                          const char * directory,
+                                                          char * error, uint64_t error_capacity);
+MB_API mb_status mb_runtime_options_get_backend_directory(const mb_runtime_options * value,
+                                                          const char ** output,
+                                                          char * error, uint64_t error_capacity);
+
+/* A command is independent of compiler layout and may be reused between plans. */
+MB_API mb_status mb_command_create(mb_command ** output,
+                                   char * error, uint64_t error_capacity);
+MB_API void mb_command_free(mb_command * value);
+MB_API mb_status mb_command_set_style(mb_command * value, const mb_style * style,
+                                      char * error, uint64_t error_capacity);
+MB_API mb_status mb_command_get_style(const mb_command * value, const mb_style ** output,
+                                      char * error, uint64_t error_capacity);
+MB_API mb_status mb_command_set_movement_direction(mb_command * value, float x, float y, float z,
+                                                   char * error, uint64_t error_capacity);
+MB_API mb_status mb_command_get_movement_direction(const mb_command * value,
+                                                   float * x, float * y, float * z,
+                                                   char * error, uint64_t error_capacity);
+MB_API mb_status mb_command_set_facing_direction(mb_command * value, float x, float y, float z,
+                                                 char * error, uint64_t error_capacity);
+MB_API mb_status mb_command_get_facing_direction(const mb_command * value,
+                                                 float * x, float * y, float * z,
+                                                 char * error, uint64_t error_capacity);
+/* A negative speed selects the style's configured speed. */
+MB_API mb_status mb_command_set_target_speed(mb_command * value, float metres_per_second,
+                                             char * error, uint64_t error_capacity);
+MB_API mb_status mb_command_get_target_speed(const mb_command * value, float * output,
+                                             char * error, uint64_t error_capacity);
+MB_API mb_status mb_command_set_world_target(mb_command * value,
+                                             float x, float y, float z,
+                                             float heading_radians, uint32_t enabled,
+                                             char * error, uint64_t error_capacity);
+MB_API mb_status mb_command_get_world_target(const mb_command * value,
+                                             float * x, float * y, float * z,
+                                             float * heading_radians, uint32_t * enabled,
+                                             char * error, uint64_t error_capacity);
+MB_API mb_status mb_command_set_seed(mb_command * value, uint64_t seed,
+                                    char * error, uint64_t error_capacity);
+MB_API mb_status mb_command_get_seed(const mb_command * value, uint64_t * output,
+                                    char * error, uint64_t error_capacity);
+
+/* Neural model, style, and stateful animation planner. */
+MB_API mb_status mb_model_load(const char * bundle_directory,
+                               const mb_runtime_options * options, mb_model ** output,
+                               char * error, uint64_t error_capacity);
+MB_API void mb_model_free(mb_model * value);
+MB_API mb_status mb_model_get_parameter_count(const mb_model * value, uint64_t * output,
+                                              char * error, uint64_t error_capacity);
+MB_API mb_status mb_model_get_joint_count(const mb_model * value, uint32_t * output,
+                                          char * error, uint64_t error_capacity);
+MB_API mb_status mb_model_get_joint_name(const mb_model * value, uint32_t joint,
+                                         const char ** output,
+                                         char * error, uint64_t error_capacity);
+MB_API mb_status mb_model_get_joint_parent(const mb_model * value, uint32_t joint,
+                                           int32_t * output,
+                                           char * error, uint64_t error_capacity);
+MB_API mb_status mb_model_get_neutral_joint_position(const mb_model * value, uint32_t joint,
+                                                     float * x, float * y, float * z,
+                                                     char * error, uint64_t error_capacity);
+
+MB_API mb_status mb_style_load(const mb_model * model, const char * style_path,
+                               mb_style ** output, char * error, uint64_t error_capacity);
+MB_API void mb_style_free(mb_style * value);
+MB_API mb_status mb_style_get_name(const mb_style * value, const char ** output,
+                                   char * error, uint64_t error_capacity);
+MB_API mb_status mb_style_set_speed(mb_style * value, float metres_per_second,
+                                    char * error, uint64_t error_capacity);
+MB_API mb_status mb_style_get_speed(const mb_style * value, float * output,
+                                    char * error, uint64_t error_capacity);
+
+MB_API mb_status mb_agent_create(const mb_model * model, mb_agent ** output,
+                                 char * error, uint64_t error_capacity);
+MB_API void mb_agent_free(mb_agent * value);
+MB_API mb_status mb_agent_reset(mb_agent * value, const mb_style * initial_style,
+                                char * error, uint64_t error_capacity);
+MB_API mb_status mb_agent_set_context(mb_agent * value,
+                                      const float * root_xyz,
+                                      const float * local_rotation_xyzw,
+                                      uint64_t frames, uint64_t joints,
+                                      char * error, uint64_t error_capacity);
+MB_API mb_status mb_agent_plan(mb_agent * value, const mb_command * command,
+                               mb_motion ** output,
+                               char * error, uint64_t error_capacity);
+MB_API mb_status mb_agent_advance(mb_agent * value, uint32_t frames,
+                                  char * error, uint64_t error_capacity);
+
+MB_API void mb_motion_free(mb_motion * value);
+MB_API mb_status mb_motion_get_frame_count(const mb_motion * value, uint64_t * output,
+                                           char * error, uint64_t error_capacity);
+MB_API mb_status mb_motion_get_joint_count(const mb_motion * value, uint64_t * output,
+                                           char * error, uint64_t error_capacity);
+/* Borrowed row-major F32 buffers valid until mb_motion_free. */
+MB_API mb_status mb_motion_get_root_translations(const mb_motion * value,
+                                                 const float ** output, uint64_t * values,
+                                                 char * error, uint64_t error_capacity);
+MB_API mb_status mb_motion_get_local_rotations_xyzw(const mb_motion * value,
+                                                    const float ** output, uint64_t * values,
+                                                    char * error, uint64_t error_capacity);
+/* The four placed style-pose constraints actually supplied to the planner. */
+MB_API mb_status mb_motion_get_target_frame_count(const mb_motion * value, uint64_t * output,
+                                                  char * error, uint64_t error_capacity);
+MB_API mb_status mb_motion_get_target_root_translations(const mb_motion * value,
+                                                        const float ** output, uint64_t * values,
+                                                        char * error, uint64_t error_capacity);
+MB_API mb_status mb_motion_get_target_local_rotations_xyzw(const mb_motion * value,
+                                                           const float ** output, uint64_t * values,
+                                                           char * error, uint64_t error_capacity);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif

include/motionbricks/motionbricks.hpp

@@ -0,0 +1,55 @@
+#pragma once
+
+#include <motionbricks/motionbricks.h>
+
+#include <array>
+#include <cstdint>
+#include <stdexcept>
+#include <string>
+
+namespace motionbricks {
+
+class api_error final : public std::runtime_error {
+public:
+    api_error(mb_status status, const char * message)
+        : std::runtime_error(message != nullptr ? message : mb_status_string(status)), status_(status) {}
+
+    [[nodiscard]] mb_status status() const noexcept { return status_; }
+
+private:
+    mb_status status_;
+};
+
+class runtime_options final {
+public:
+    runtime_options() {
+        std::array<char, 512> error{};
+        const auto status = mb_runtime_options_create(&value_, error.data(), error.size());
+        if (status != MB_OK) throw api_error(status, error.data());
+    }
+
+    ~runtime_options() { mb_runtime_options_free(value_); }
+    runtime_options(const runtime_options &) = delete;
+    runtime_options & operator=(const runtime_options &) = delete;
+
+    runtime_options(runtime_options && other) noexcept : value_(other.value_) {
+        other.value_ = nullptr;
+    }
+
+    runtime_options & operator=(runtime_options && other) noexcept {
+        if (this != &other) {
+            mb_runtime_options_free(value_);
+            value_ = other.value_;
+            other.value_ = nullptr;
+        }
+        return *this;
+    }
+
+    [[nodiscard]] mb_runtime_options * get() noexcept { return value_; }
+    [[nodiscard]] const mb_runtime_options * get() const noexcept { return value_; }
+
+private:
+    mb_runtime_options * value_ = nullptr;
+};
+
+} // namespace motionbricks

patches/ggml/README.md

@@ -0,0 +1,9 @@
+# GGML compatibility patches
+
+The initial GGML revision is
+`8c63e70982c95ceb862e3a1073a2c1beef75d60a` (`v0.20.2`). No compatibility
+patch is currently required.
+
+If a patch becomes necessary, add numbered patch files here and update CMake
+to copy GGML into the build directory and apply them in lexical order. Never
+modify the pinned submodule worktree during configuration.

reference/Dockerfile

@@ -0,0 +1,13 @@
+FROM python:3.10.14-slim-bookworm@sha256:2407c61b1a18067393fecd8a22cf6fceede893b6aaca817bf9fbfe65e33614a3
+
+RUN python -m pip install --no-cache-dir --upgrade pip==24.3.1 \
+    && python -m pip install --no-cache-dir \
+      --index-url https://download.pytorch.org/whl/cpu \
+      torch==2.4.0 \
+    && python -m pip install --no-cache-dir \
+      numpy==1.26.4 \
+      PyYAML==6.0.2 \
+      safetensors==0.4.5
+
+WORKDIR /work
+ENTRYPOINT ["python", "/work/reference/extract_safe.py"]

reference/README.md

@@ -0,0 +1,117 @@
+# Upstream reference
+
+The native implementation is validated against a pinned, unmodified NVIDIA
+MotionBricks checkout.
+
+| Component | Repository | Revision |
+|---|---|---|
+| MotionBricks | `https://github.com/NVlabs/GR00T-WholeBodyControl.git` | `a0732b642c0333077e127a2f56ab0014c196bca4` |
+| GGML | `https://github.com/ggml-org/ggml.git` | `8c63e70982c95ceb862e3a1073a2c1beef75d60a` (`v0.20.2`) |
+
+The `ggml/` submodule is pinned to the same revision used by the local
+`kimodo.cpp` and `skin-tokens.cpp` reference ports. Compatibility patches, if
+required, belong under `patches/ggml/` and will be applied to a build-directory
+copy during CMake configuration; the submodule worktree will remain untouched.
+
+## Checkpoint identities
+
+The required MotionBricks checkpoints and G1 meshes have been fetched through
+Git LFS. These identities are the initial trusted reference inputs:
+
+| Artifact | Bytes | SHA-256 |
+|---|---:|---|
+| `G1-clip.ckpt` | 7,761,041 | `84afc7c229473351a24b0a7d79fc47be9dbb81bd12774285f2f60a3c0e9028df` |
+| VQ-VAE `model-step=2000000.ckpt` | 285,607,244 | `f12a09d46ad390a8e2eecbe7219b2472fcab6b59df0a13f6a40c35cb6da4d99a` |
+| pose `model-step=2000000.ckpt` | 1,639,126,476 | `0223c352b308ba638a499cc5c92104da36cb1d04cea2f8ce61d54a2489f853f1` |
+| root `model-step=2000000.ckpt` | 409,551,754 | `d7299a9b1f5aca35730c36dfe7ea28075708ac8266bf384fe8e2ef9c9aee69c7` |
+
+Saved configuration identities:
+
+| Configuration | SHA-256 |
+|---|---|
+| VQ-VAE `config.yaml` | `027a2d7ba5f49cadeadbcc9a6b0c6784d657d5a842e41ff820c5233f1cd6c1f3` |
+| pose `config.yaml` | `273af770d328b458510ee6049fac8e38fa486c8792cc27b3515dddc094a7cd1f` |
+| root `config.yaml` | `b174f03a333f7f7857c3e2b8a32da517caddd198f228efeea2e203d046ce212a` |
+
+The 29-DOF G1 XML identities used by the initial interactive reference are:
+
+- `g1_29dof.xml`: `58660a6f1d0d33ffd8ee967ab3860def53e3327d956cb009dd1385ddaf430f56`
+- `scene_29dof.xml`: `e254f11acce2ec6f6efa5bf9b15e288bbd0ca29aeeabb1e1d0fea92f65436bbf`
+
+Legacy Lightning `.ckpt` and demo-clip files are deserialized only inside the
+reference container. Normal conversion accepts safetensors and JSON, never
+pickle-bearing checkpoints.
+
+Build and run the trusted extractor from the project root:
+
+```sh
+docker build -t motionbricks-reference:torch2.4 reference
+docker run --rm --user "$(id -u):$(id -g)" \
+  -v "$PWD:/work" \
+  -v /path/to/GR00T-WholeBodyControl:/upstream:ro \
+  motionbricks-reference:torch2.4 \
+  --upstream-root /upstream \
+  --output /work/generated/safe
+```
+
+The extractor verifies every pinned input hash and the small allowlist of
+pickle globals before loading. It writes independent safetensors for the three
+model checkpoints, original demo clips, and shared skeleton/statistics, plus a
+manifest containing every tensor name, shape, dtype, value count, and hash.
+
+## Native inference bundle
+
+The normal converter reads only those verified safetensors and JSON files:
+
+```sh
+nix develop --command python scripts/convert_to_gguf.py \
+  --safe-directory generated/safe \
+  --output generated/g1-f32
+```
+
+It emits three inference-weight components plus one small skeleton/statistics
+component. The VQ-VAE encoder and optimizer/training state are excluded. The
+resulting learned parameter inventory is:
+
+- pose planner: 136,588,272
+- root planner: 34,122,833
+- VQ pose decoder and codebook: 12,437,277
+- total: 183,148,382
+
+Validate the result through the same public model-loading path applications
+use:
+
+```sh
+./build/debug/bin/motionbricks-cli inspect generated/g1-f32
+```
+
+## Reference fixtures and styles
+
+Generate deterministic PyTorch layer fixtures inside the same pinned
+container, then package them as small GGUF test inputs:
+
+```sh
+docker run --rm --user "$(id -u):$(id -g)" \
+  --entrypoint python \
+  -v "$PWD:/work" \
+  -v /path/to/GR00T-WholeBodyControl:/upstream:ro \
+  motionbricks-reference:torch2.4 \
+  /work/reference/generate_fixtures.py \
+  --upstream-root /upstream \
+  --safe-directory /work/generated/safe \
+  --output /work/generated/fixtures
+
+python scripts/convert_fixtures_to_gguf.py \
+  --fixtures generated/fixtures \
+  --output generated/fixtures-gguf
+
+python scripts/convert_styles.py \
+  --safe-directory generated/safe \
+  --output generated/styles
+```
+
+The native suite checks every released neural component against these actual
+upstream PyTorch forwards. On the current reference machine, complete
+style-to-animation output also matches between CPU and strict-F32 Vulkan with
+the same 44-frame duration; observed maximum absolute differences were
+`2.19e-5` for root translations and `1.02e-4` for local quaternion components.

reference/extract_safe.py

@@ -0,0 +1,290 @@
+#!/usr/bin/env python3
+"""One-time extraction of pinned MotionBricks pickle checkpoints.
+
+Run this only inside the disposable reference container. Normal conversion and
+native inference consume the resulting safetensors and JSON and never open a
+PyTorch pickle container.
+"""
+
+from __future__ import annotations
+
+import argparse
+import gc
+import hashlib
+import json
+import os
+import pickletools
+from pathlib import Path
+from typing import Any
+from zipfile import ZipFile
+
+import numpy as np
+import torch
+import yaml
+from safetensors.torch import save_file
+
+
+UPSTREAM_REVISION = "a0732b642c0333077e127a2f56ab0014c196bca4"
+
+INPUTS = {
+    "clips": (
+        "motionbricks/out/G1-clip.ckpt",
+        "84afc7c229473351a24b0a7d79fc47be9dbb81bd12774285f2f60a3c0e9028df",
+    ),
+    "vqvae": (
+        "motionbricks/out/motionbricks_vqvae/version_1/checkpoints/model-step=2000000.ckpt",
+        "f12a09d46ad390a8e2eecbe7219b2472fcab6b59df0a13f6a40c35cb6da4d99a",
+    ),
+    "pose": (
+        "motionbricks/out/motionbricks_pose/version_1/checkpoints/model-step=2000000.ckpt",
+        "0223c352b308ba638a499cc5c92104da36cb1d04cea2f8ce61d54a2489f853f1",
+    ),
+    "root": (
+        "motionbricks/out/motionbricks_root/version_1/checkpoints/model-step=2000000.ckpt",
+        "d7299a9b1f5aca35730c36dfe7ea28075708ac8266bf384fe8e2ef9c9aee69c7",
+    ),
+    "joints": (
+        "motionbricks/out/motionbricks_pose/version_1/skeleton/joints.p",
+        "8a582b7020d1609a34a9ea5ddfa597c8727b3e726e38cc80ecefe68171f43ecd",
+    ),
+    "parents": (
+        "motionbricks/out/motionbricks_pose/version_1/skeleton/parents.p",
+        "4ba0237379480ef33e64b7b8564f1d38dcb3e1ad5bfe01652ea1b7c97ccacb71",
+    ),
+    "mean": (
+        "motionbricks/out/motionbricks_pose/version_1/stats/motion/mean.npy",
+        "ca390f0081e2373ab71e860a3546cb70cc11fdfac6ce525155403e047b66fdea",
+    ),
+    "std": (
+        "motionbricks/out/motionbricks_pose/version_1/stats/motion/std.npy",
+        "fca7dd6135cbe96504b1307a7db97e9004556937a2fc72d139077b962cee6bd7",
+    ),
+}
+
+CONFIGS = {
+    "vqvae": (
+        "motionbricks/out/motionbricks_vqvae/version_1/config.yaml",
+        "027a2d7ba5f49cadeadbcc9a6b0c6784d657d5a842e41ff820c5233f1cd6c1f3",
+    ),
+    "pose": (
+        "motionbricks/out/motionbricks_pose/version_1/config.yaml",
+        "273af770d328b458510ee6049fac8e38fa486c8792cc27b3515dddc094a7cd1f",
+    ),
+    "root": (
+        "motionbricks/out/motionbricks_root/version_1/config.yaml",
+        "b174f03a333f7f7857c3e2b8a32da517caddd198f228efeea2e203d046ce212a",
+    ),
+}
+
+ALLOWED_PICKLE_GLOBALS = {
+    "collections OrderedDict",
+    "torch BoolStorage",
+    "torch DoubleStorage",
+    "torch FloatStorage",
+    "torch IntStorage",
+    "torch LongStorage",
+    "torch._utils _rebuild_tensor_v2",
+}
+
+
+def sha256(path: Path) -> str:
+    digest = hashlib.sha256()
+    with path.open("rb") as stream:
+        while block := stream.read(8 << 20):
+            digest.update(block)
+    return digest.hexdigest()
+
+
+def verify(path: Path, expected: str) -> None:
+    actual = sha256(path)
+    if actual != expected:
+        raise ValueError(f"SHA-256 mismatch for {path}: {actual}, expected {expected}")
+
+
+def inspect_pickle_globals(path: Path) -> None:
+    with ZipFile(path) as archive:
+        names = [name for name in archive.namelist() if name.endswith("/data.pkl")]
+        if len(names) != 1:
+            raise ValueError(f"{path} has {len(names)} data.pkl entries")
+        data = archive.read(names[0])
+    globals_found = {
+        str(argument)
+        for opcode, argument, _ in pickletools.genops(data)
+        if opcode.name == "GLOBAL"
+    }
+    unexpected = globals_found - ALLOWED_PICKLE_GLOBALS
+    if unexpected:
+        raise ValueError(f"unexpected pickle globals in {path}: {sorted(unexpected)}")
+
+
+def plain(value: Any) -> Any:
+    if isinstance(value, dict):
+        return {str(key): plain(item) for key, item in value.items()}
+    if isinstance(value, (list, tuple)):
+        return [plain(item) for item in value]
+    if value is None or isinstance(value, (str, int, float, bool)):
+        return value
+    return repr(value)
+
+
+def tensor_bytes(value: torch.Tensor) -> bytes:
+    return value.detach().cpu().contiguous().reshape(-1).view(torch.uint8).numpy().tobytes()
+
+
+def tensor_record(name: str, value: torch.Tensor) -> dict[str, Any]:
+    return {
+        "name": name,
+        "dtype": str(value.dtype).removeprefix("torch."),
+        "shape": [int(item) for item in value.shape],
+        "numel": int(value.numel()),
+        "sha256": hashlib.sha256(tensor_bytes(value)).hexdigest(),
+    }
+
+
+def write_safetensors(path: Path, tensors: dict[str, torch.Tensor], source_hash: str) -> dict[str, Any]:
+    if not tensors:
+        raise ValueError(f"refusing to write empty tensor set to {path}")
+    ordered = {
+        name: value.detach().cpu().contiguous().clone()
+        for name, value in sorted(tensors.items())
+    }
+    temporary = path.with_suffix(path.suffix + ".tmp")
+    save_file(
+        ordered,
+        temporary,
+        metadata={
+            "format": "motionbricks-safe-v1",
+            "upstream_revision": UPSTREAM_REVISION,
+            "source_sha256": source_hash,
+        },
+    )
+    os.replace(temporary, path)
+    inventory = {
+        "path": path.name,
+        "sha256": sha256(path),
+        "tensor_count": len(ordered),
+        "parameter_count": sum(int(value.numel()) for value in ordered.values()),
+        "tensors": [tensor_record(name, value) for name, value in ordered.items()],
+    }
+    del ordered
+    return inventory
+
+
+def load_lightning(path: Path) -> tuple[dict[str, torch.Tensor], dict[str, Any], str]:
+    inspect_pickle_globals(path)
+    checkpoint = torch.load(path, map_location="cpu", weights_only=False)
+    if not isinstance(checkpoint, dict) or "state_dict" not in checkpoint:
+        raise ValueError(f"{path} is not a Lightning state dictionary")
+    state = checkpoint["state_dict"]
+    if not isinstance(state, dict) or any(not isinstance(value, torch.Tensor) for value in state.values()):
+        raise ValueError(f"{path} contains an invalid state_dict")
+    metadata = {
+        "global_step": plain(checkpoint.get("global_step")),
+        "epoch": plain(checkpoint.get("epoch")),
+        "pytorch_lightning_version": plain(checkpoint.get("pytorch-lightning_version")),
+        "hyper_parameters": plain(checkpoint.get("hyper_parameters", {})),
+    }
+    return state, metadata, sha256(path)
+
+
+def load_tensor_mapping(path: Path) -> tuple[dict[str, torch.Tensor], str]:
+    inspect_pickle_globals(path)
+    value = torch.load(path, map_location="cpu", weights_only=False)
+    if not isinstance(value, dict) or any(not isinstance(item, torch.Tensor) for item in value.values()):
+        raise ValueError(f"{path} is not a tensor mapping")
+    return value, sha256(path)
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--upstream-root", type=Path, required=True)
+    parser.add_argument("--output", type=Path, required=True)
+    args = parser.parse_args()
+
+    args.output.mkdir(parents=True, exist_ok=True)
+    resolved: dict[str, tuple[Path, str]] = {}
+    for key, (relative, expected) in INPUTS.items():
+        path = args.upstream_root / relative
+        verify(path, expected)
+        resolved[key] = (path, expected)
+    for relative, expected in CONFIGS.values():
+        verify(args.upstream_root / relative, expected)
+
+    manifest: dict[str, Any] = {
+        "format": "motionbricks-safe-manifest-v1",
+        "upstream_revision": UPSTREAM_REVISION,
+        "extractor": {
+            "python": os.sys.version,
+            "torch": torch.__version__,
+            "numpy": np.__version__,
+        },
+        "inputs": {
+            key: {"path": relative, "sha256": expected}
+            for key, (relative, expected) in INPUTS.items()
+        },
+        "configs": {},
+        "components": {},
+        "checkpoint_metadata": {},
+    }
+
+    for component in ("vqvae", "pose", "root"):
+        path, _ = resolved[component]
+        state, checkpoint_metadata, source_hash = load_lightning(path)
+        manifest["components"][component] = write_safetensors(
+            args.output / f"{component}.safetensors", state, source_hash
+        )
+        manifest["checkpoint_metadata"][component] = checkpoint_metadata
+        del state
+        gc.collect()
+
+    clip_path, clip_hash = resolved["clips"]
+    clips, _ = load_tensor_mapping(clip_path)
+    manifest["components"]["clips"] = write_safetensors(
+        args.output / "clips.safetensors", clips, clip_hash
+    )
+    del clips
+    gc.collect()
+
+    joints_path, joints_hash = resolved["joints"]
+    parents_path, _ = resolved["parents"]
+    inspect_pickle_globals(joints_path)
+    inspect_pickle_globals(parents_path)
+    joints = torch.load(joints_path, map_location="cpu", weights_only=False)
+    parents = torch.load(parents_path, map_location="cpu", weights_only=False)
+    mean = torch.from_numpy(np.load(resolved["mean"][0], allow_pickle=False))
+    std = torch.from_numpy(np.load(resolved["std"][0], allow_pickle=False))
+    support = {
+        "neutral_joints": joints,
+        "joint_parents": parents,
+        "motion_mean": mean,
+        "motion_std": std,
+    }
+    if any(not isinstance(value, torch.Tensor) for value in support.values()):
+        raise ValueError("support inputs did not decode to tensors")
+    manifest["components"]["support"] = write_safetensors(
+        args.output / "support.safetensors", support, joints_hash
+    )
+
+    for name, (relative, expected) in CONFIGS.items():
+        path = args.upstream_root / relative
+        value = yaml.safe_load(path.read_text(encoding="utf-8"))
+        manifest["configs"][name] = {
+            "path": relative,
+            "sha256": expected,
+            "value": value,
+        }
+
+    manifest_path = args.output / "manifest.json"
+    temporary = manifest_path.with_suffix(".json.tmp")
+    temporary.write_text(json.dumps(manifest, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+    os.replace(temporary, manifest_path)
+
+    for name, component in manifest["components"].items():
+        print(
+            f"{name}: {component['tensor_count']} tensors, "
+            f"{component['parameter_count']:,} values, {component['sha256']}"
+        )
+
+
+if __name__ == "__main__":
+    main()

reference/generate_fixtures.py

@@ -0,0 +1,338 @@
+#!/usr/bin/env python3
+"""Generate deterministic PyTorch fixtures from the pinned upstream modules.
+
+Run only in the reference container.  This script imports NVIDIA's actual
+network classes, loads the verified safetensors intermediates, and records
+inputs, selected layer outputs, and final outputs without opening a pickle.
+"""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import os
+import struct
+import sys
+from pathlib import Path
+from types import SimpleNamespace
+from typing import Any
+
+import numpy as np
+import torch
+from safetensors import safe_open
+
+
+UPSTREAM_REVISION = "a0732b642c0333077e127a2f56ab0014c196bca4"
+SAFE_HASHES = {
+    "pose": "01327768be7413111dc927947a95cfb3e9ee7c52acfa35a054e8c2f3b838b888",
+    "root": "d1529a8c9da915cb7dd0499272baba61db480660c0aae92b67fbe69828e83c5a",
+    "vqvae": "544782e605ed96d60bf999243ef8f44640ea021a5655ef20af2d2853c3e18b5b",
+}
+
+
+def sha256(path: Path) -> str:
+    digest = hashlib.sha256()
+    with path.open("rb") as stream:
+        while block := stream.read(8 << 20):
+            digest.update(block)
+    return digest.hexdigest()
+
+
+def verify(path: Path, expected: str) -> None:
+    actual = sha256(path)
+    if actual != expected:
+        raise ValueError(f"SHA-256 mismatch for {path}: {actual}, expected {expected}")
+
+
+class Rep:
+    pass
+
+
+def make_motion_rep() -> Rep:
+    """Minimal shape-compatible rep used only by upstream constructors."""
+    global_rep, local_rep, combined = Rep(), Rep(), Rep()
+    global_rep.root_mode = "global"
+    global_rep.indices = {
+        "all": np.arange(418),
+        "root": np.arange(5),
+        "global_root_pos": np.arange(3),
+        "global_root_pos_2d": np.arange(2),
+        "global_root_heading": np.arange(2, 4),
+        "ric_data": np.arange(99),
+        "global_rot_data": np.arange(99, 303),
+    }
+    local_rep.root_mode = "local"
+    local_rep.indices = {
+        "all": np.arange(413),
+        "root": np.arange(4),
+        "local_root_rot_vel": np.arange(2),
+        "local_root_vel": np.arange(2, 4),
+        "global_root_y": np.arange(1),
+        "ric_data": np.arange(99),
+        "global_rot_data": np.arange(99, 303),
+    }
+    dual = SimpleNamespace(global_motion_rep=global_rep, local_motion_rep=local_rep)
+    combined.dual_rep = dual
+    combined.root_mode = "global"
+    combined.indices = global_rep.indices
+    return combined
+
+
+def state(path: Path, prefix: str, select=lambda _name: True) -> dict[str, torch.Tensor]:
+    result: dict[str, torch.Tensor] = {}
+    with safe_open(path, framework="pt", device="cpu") as source:
+        for name in source.keys():
+            if name.startswith(prefix) and select(name):
+                result[name.removeprefix(prefix)] = source.get_tensor(name)
+    return result
+
+
+def ramp(shape: tuple[int, ...], scale: float, phase: float = 0.0) -> torch.Tensor:
+    count = int(np.prod(shape))
+    values = torch.arange(count, dtype=torch.float32)
+    return (torch.sin(values * 0.017 + phase) * scale).reshape(shape)
+
+
+def trace_modules(model: torch.nn.Module, output: dict[str, torch.Tensor]) -> list[Any]:
+    handles = []
+    traced_types = (torch.nn.Linear, torch.nn.Conv1d, torch.nn.TransformerEncoderLayer)
+    for name, module in model.named_modules():
+        if not name or not isinstance(module, traced_types):
+            continue
+
+        def capture(_module, _inputs, value, trace_name=name):
+            if isinstance(value, torch.Tensor):
+                if value.is_nested:
+                    value = value.to_padded_tensor(0.0)
+                output[f"trace.{trace_name}"] = value.detach().cpu().contiguous()
+
+        handles.append(module.register_forward_hook(capture))
+    return handles
+
+
+def pose_fixture(pose_type, safe: Path) -> dict[str, torch.Tensor]:
+    args = {
+        "cond_root_feature": "root_without_hip_height",
+        "cond_root_feature_is_from_motion_rep": "global",
+        "down_t": 2,
+        "local_pose_feature": "joint_positions_and_rotations_and_hip_height",
+        "max_tokens": 16,
+        "min_tokens": 6,
+        "n_embd": 1024,
+        "n_head": 16,
+        "n_layers": 16,
+        "pose_feat_width": 640,
+        "pose_root_mode": "pose",
+        "pose_token_mlp_num_layers": 2,
+        "pose_vqvae": {"code_dim": 256, "has_codebook": True, "nb_code": 100_000_000, "num_heads": 8},
+        "root_feat_width": 256,
+        "root_vqvae": {"code_dim": 60, "nb_code": 1024, "num_heads": 1},
+        "text_emb_dim": 4096,
+        "text_embeddings": None,
+        "token_length_feat_width": 128,
+    }
+    model = pose_type(make_motion_rep(), args).eval()
+    missing, unexpected = model.load_state_dict(state(safe / "pose.safetensors", "backbone_net."), strict=True)
+    if missing or unexpected:
+        raise ValueError(f"pose state mismatch: missing={missing}, unexpected={unexpected}")
+
+    result: dict[str, torch.Tensor] = {}
+    pose_tokens = (torch.arange(48).reshape(1, 6, 8) * 7 % 11).to(torch.int64)
+    local_root = ramp((1, 24, 4), 0.35, 0.1)
+    pose_cond = ramp((1, 24, 304), 0.2, 0.7)
+    has_pose = torch.zeros((1, 24), dtype=torch.bool)
+    has_pose[:, [0, 1, 22, 23]] = True
+    num_tokens = torch.tensor([[6]], dtype=torch.int64)
+    result.update({
+        "input.pose_tokens": pose_tokens,
+        "input.local_root_values": local_root,
+        "input.pose_cond": pose_cond,
+        "input.has_pose_cond": has_pose,
+        "input.num_tokens": num_tokens,
+    })
+    handles = trace_modules(model, result)
+    with torch.inference_mode():
+        output = model(pose_tokens, local_root, pose_cond, has_pose, num_tokens)
+    result["output.pose_logits"] = output["pose_logits"].contiguous()
+    for handle in handles:
+        handle.remove()
+    return result
+
+
+def root_fixture(root_type, safe: Path) -> dict[str, torch.Tensor]:
+    args = {
+        "activation": "relu", "depth": 4, "dilation_growth_rate": 3, "down_t": 2,
+        "global_root_feat_dim": 64, "global_root_feature": "root",
+        "input_feat_mlp_num_layers": 2,
+        "local_pose_feature": "joint_positions_and_rotations_and_hip_height",
+        "local_root_feat_dim": 64, "local_root_feature": "root",
+        "max_tokens": 16, "min_tokens": 6, "n_embd": 512, "n_head": 16,
+        "n_layers_root_token": 3, "n_layers_shared": 3, "norm": "None",
+        "pose_feat_dim": 256,
+        "pose_vqvae": {"code_dim": 60, "nb_code": 1024, "num_heads": 1},
+        "root_vqvae": {"code_dim": 60, "nb_code": 1024, "num_heads": 1},
+        "text_emb_dim": 4096, "text_embeddings": None,
+        "use_hard_num_token_emb_for_root_prediction": True, "width": 512,
+    }
+    model = root_type(args, make_motion_rep()).eval()
+    missing, unexpected = model.load_state_dict(state(safe / "root.safetensors", "backbone_net."), strict=True)
+    if missing or unexpected:
+        raise ValueError(f"root state mismatch: missing={missing}, unexpected={unexpected}")
+
+    result: dict[str, torch.Tensor] = {}
+    global_root = ramp((1, 8, 5), 0.3, 0.2)
+    local_root = ramp((1, 8, 4), 0.25, 0.9)
+    poses = ramp((1, 8, 304), 0.15, 1.7)
+    has_global = torch.tensor([[1, 1, 1, 1, 0, 0, 1, 1]], dtype=torch.bool)
+    has_local = torch.tensor([[1, 1, 1, 1, 0, 0, 1, 1]], dtype=torch.bool)
+    has_poses = torch.tensor([[1, 1, 1, 1, 0, 0, 1, 1]], dtype=torch.bool)
+    num_tokens = torch.tensor([[6]], dtype=torch.int64)
+    result.update({
+        "input.global_root_values": global_root, "input.has_global_root_values": has_global,
+        "input.local_root_values": local_root, "input.has_local_root_values": has_local,
+        "input.poses": poses, "input.has_poses": has_poses, "input.num_tokens": num_tokens,
+    })
+    handles = trace_modules(model, result)
+    with torch.inference_mode():
+        output = model(global_root, has_global, local_root, has_local, poses, has_poses, num_tokens)
+    result["output.num_token_logits"] = output["num_token_logits"].contiguous()
+    result["output.pred_num_tokens"] = output["pred_num_tokens"].contiguous()
+    result["output.pred_global_root_values"] = output["pred_global_root_values"].contiguous()
+    for handle in handles:
+        handle.remove()
+    return result
+
+
+def decoder_fixture(decoder_type, safe: Path) -> dict[str, torch.Tensor]:
+    model = decoder_type(
+        input_emb_width=413, output_emb_width=256, down_t=2, width=512, depth=4,
+        dilation_growth_rate=3, activation="relu", norm="None",
+        target_cond_dim=304, external_cond_dim=2, cond_fusion_last_layer=False,
+    ).eval()
+    decoder_state = state(safe / "vqvae.safetensors", "pose_net.decoder.")
+    missing, unexpected = model.load_state_dict(decoder_state, strict=True)
+    if missing or unexpected:
+        raise ValueError(f"decoder state mismatch: missing={missing}, unexpected={unexpected}")
+    codebook = state(
+        safe / "vqvae.safetensors", "pose_net.",
+        lambda name: name == "pose_net.quantizer.vq._codebook.embed",
+    )["quantizer.vq._codebook.embed"]
+
+    result: dict[str, torch.Tensor] = {}
+    indices = (torch.arange(48).reshape(1, 6, 8) * 3 + 1).remainder(10).to(torch.int64)
+    batch_index = torch.arange(indices.shape[0])[:, None, None]
+    head_index = torch.arange(8)[None, None, :]
+    quantized = codebook[head_index, indices].reshape(1, 6, 256).transpose(1, 2).contiguous()
+    target = ramp((1, 24, 304), 0.18, 0.4)
+    has_target = torch.zeros((1, 24), dtype=torch.bool)
+    has_target[:, [0, 1, 22, 23]] = True
+    external = ramp((1, 24, 2), 0.22, 1.1)
+    token_mask = torch.ones((1, 6), dtype=torch.bool)
+    result.update({
+        "input.indices": indices, "input.quantized": quantized,
+        "input.target_cond": target, "input.has_target_cond": has_target,
+        "input.external_cond": external, "input.token_mask": token_mask,
+    })
+    handles = trace_modules(model, result)
+    with torch.inference_mode():
+        result["output.motion"] = model(
+            quantized, external_cond=external, target_cond=target,
+            has_target_cond=has_target, token_mask=token_mask,
+        ).transpose(1, 2).contiguous()
+    for handle in handles:
+        handle.remove()
+    return result
+
+
+def tensor_record(name: str, value: torch.Tensor) -> dict[str, Any]:
+    raw = value.detach().cpu().contiguous().reshape(-1).view(torch.uint8).numpy().tobytes()
+    return {
+        "name": name, "dtype": str(value.dtype).removeprefix("torch."),
+        "shape": list(value.shape), "numel": value.numel(),
+        "sha256": hashlib.sha256(raw).hexdigest(),
+    }
+
+
+def write_fixture(path: Path, tensors: dict[str, torch.Tensor]) -> dict[str, Any]:
+    ordered = {name: value.detach().cpu().contiguous().clone() for name, value in sorted(tensors.items())}
+    dtype_names = {
+        torch.float32: "F32", torch.int64: "I64", torch.int32: "I32", torch.bool: "BOOL",
+    }
+    header: dict[str, Any] = {
+        "__metadata__": {
+            "format": "motionbricks-reference-fixture-v1",
+            "torch": torch.__version__,
+            "upstream_revision": UPSTREAM_REVISION,
+        }
+    }
+    payloads: list[bytes] = []
+    offset = 0
+    for name, value in ordered.items():
+        if value.dtype not in dtype_names:
+            raise ValueError(f"unsupported fixture dtype for {name}: {value.dtype}")
+        payload = value.reshape(-1).view(torch.uint8).numpy().tobytes()
+        header[name] = {
+            "dtype": dtype_names[value.dtype], "shape": list(value.shape),
+            "data_offsets": [offset, offset + len(payload)],
+        }
+        payloads.append(payload)
+        offset += len(payload)
+    encoded_header = json.dumps(header, separators=(",", ":"), ensure_ascii=False).encode("utf-8")
+    encoded_header += b" " * (-len(encoded_header) % 8)
+    temporary = path.with_suffix(path.suffix + ".tmp")
+    with temporary.open("wb") as stream:
+        stream.write(struct.pack("<Q", len(encoded_header)))
+        stream.write(encoded_header)
+        for payload in payloads:
+            stream.write(payload)
+        stream.flush()
+        os.fsync(stream.fileno())
+    os.replace(temporary, path)
+    return {
+        "path": path.name, "sha256": sha256(path), "tensor_count": len(ordered),
+        "tensors": [tensor_record(name, value) for name, value in ordered.items()],
+    }
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--upstream-root", type=Path, required=True)
+    parser.add_argument("--safe-directory", type=Path, required=True)
+    parser.add_argument("--output", type=Path, required=True)
+    args = parser.parse_args()
+    if not Path("/.dockerenv").exists():
+        raise RuntimeError("reference fixtures must be generated inside the container")
+    for name, expected in SAFE_HASHES.items():
+        verify(args.safe_directory / f"{name}.safetensors", expected)
+
+    sys.path.insert(0, str(args.upstream_root / "motionbricks"))
+    from motionbricks.motion_backbone.neural_modules.pose_backbone import pose_backbone_network
+    from motionbricks.motion_backbone.neural_modules.root_backbone import root_backbone_network
+    from motionbricks.vqvae.neural_modules.encdec_double_cond import DoubleCondDecoder
+
+    torch.manual_seed(7)
+    torch.set_num_threads(1)
+    torch.use_deterministic_algorithms(True)
+    args.output.mkdir(parents=True, exist_ok=True)
+    generated = {
+        "pose": write_fixture(args.output / "pose.safetensors", pose_fixture(pose_backbone_network, args.safe_directory)),
+        "root": write_fixture(args.output / "root.safetensors", root_fixture(root_backbone_network, args.safe_directory)),
+        "vq-decoder": write_fixture(
+            args.output / "vq-decoder.safetensors", decoder_fixture(DoubleCondDecoder, args.safe_directory)
+        ),
+    }
+    manifest = {
+        "format": "motionbricks-reference-fixtures-v1",
+        "upstream_revision": UPSTREAM_REVISION,
+        "torch": torch.__version__, "numpy": np.__version__, "fixtures": generated,
+    }
+    temporary = args.output / "manifest.json.tmp"
+    temporary.write_text(json.dumps(manifest, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+    os.replace(temporary, args.output / "manifest.json")
+    for name, record in generated.items():
+        print(f"{name}: {record['tensor_count']} tensors, {record['sha256']}")
+
+
+if __name__ == "__main__":
+    main()

scripts/convert_fixtures_to_gguf.py

@@ -0,0 +1,44 @@
+#!/usr/bin/env python3
+"""Package deterministic safetensors reference fixtures as GGUF v3."""
+
+from __future__ import annotations
+
+import argparse
+import importlib.util
+import sys
+from pathlib import Path
+
+from safetensors import safe_open
+
+
+def load_converter(path: Path):
+    spec = importlib.util.spec_from_file_location("motionbricks_gguf_converter", path)
+    if spec is None or spec.loader is None:
+        raise RuntimeError(f"cannot import {path}")
+    module = importlib.util.module_from_spec(spec)
+    sys.modules[spec.name] = module
+    spec.loader.exec_module(module)
+    return module
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--fixtures", type=Path, required=True)
+    parser.add_argument("--output", type=Path, required=True)
+    args = parser.parse_args()
+    converter = load_converter(Path(__file__).with_name("convert_to_gguf.py"))
+    args.output.mkdir(parents=True, exist_ok=True)
+    for fixture in ("pose", "root", "vq-decoder"):
+        source_path = args.fixtures / f"{fixture}.safetensors"
+        values = []
+        with safe_open(source_path, framework="numpy") as source:
+            for name in source.keys():
+                values.append((name, source.get_tensor(name)))
+        converter.write_component(
+            args.output / f"{fixture}.gguf", f"fixture-{fixture}", values,
+            converter.sha256(source_path),
+        )
+
+
+if __name__ == "__main__":
+    main()

scripts/convert_styles.py

@@ -0,0 +1,85 @@
+#!/usr/bin/env python3
+"""Convert the verified upstream G1 exemplar clips into checked style GGUFs."""
+
+from __future__ import annotations
+
+import argparse
+import importlib.util
+import json
+import sys
+from pathlib import Path
+
+import numpy as np
+from safetensors import safe_open
+
+
+CLIP_SHA256 = "7ea40c20130c8a9799d83c0438750b51a5be9b1e09357c4928887961fc992d33"
+STYLES = (
+    ("idle", 0.0, 6), ("slow_walk", 0.3, 6), ("walk", 1.0, 6),
+    ("hand_crawling", 0.5, 6), ("walk_boxing", 1.0, 11),
+    ("elbow_crawling", 0.8, 11), ("stealth_walk", 1.0, 6),
+    ("injured_walk", 0.5, 6), ("walk_stealth", 0.7, 6),
+    ("walk_happy_dance", 1.0, 6), ("walk_zombie", 0.6, 6),
+    ("walk_gun", 0.6, 6), ("walk_scared", 0.6, 6),
+    ("walk_left", 0.2, 4), ("walk_right", 0.2, 4),
+)
+
+
+def converter_module(path: Path):
+    spec = importlib.util.spec_from_file_location("motionbricks_converter", path)
+    if spec is None or spec.loader is None:
+        raise RuntimeError(f"cannot import {path}")
+    module = importlib.util.module_from_spec(spec)
+    sys.modules[spec.name] = module
+    spec.loader.exec_module(module)
+    return module
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--safe-directory", type=Path, required=True)
+    parser.add_argument("--output", type=Path, required=True)
+    args = parser.parse_args()
+    converter = converter_module(Path(__file__).with_name("convert_to_gguf.py"))
+    source = args.safe_directory / "clips.safetensors"
+    if converter.sha256(source) != CLIP_SHA256:
+        raise ValueError("upstream clip safetensors hash mismatch")
+    with safe_open(source, framework="numpy") as clips:
+        positions = clips.get_tensor("global_joint_positions")
+        rotations = clips.get_tensor("global_joint_rotations")
+        roots = clips.get_tensor("global_root_positions")
+        headings = clips.get_tensor("global_headings")
+        lengths = clips.get_tensor("num_frames_per_clip")
+    headings = headings.copy()
+    headings[3, 0] = 0.0
+    headings[5] -= 0.95
+    args.output.mkdir(parents=True, exist_ok=True)
+    records = {}
+    for index, (name, speed, allowed_count) in enumerate(STYLES):
+        frames = int(lengths[index])
+        allowed = np.zeros(11, dtype=np.int32)
+        allowed[:allowed_count] = 1
+        values = [
+            ("global_joint_positions", positions[index, :frames]),
+            ("global_joint_rotations", rotations[index, :frames].reshape(frames, 34, 9)),
+            ("global_root_positions", roots[index, :frames]),
+            ("global_headings", headings[index, :frames]),
+            ("allowed_tokens", allowed),
+        ]
+        records[name] = converter.write_component(
+            args.output / f"{name}.mbstyle", "style", values, CLIP_SHA256,
+            general_name=name,
+            extra_metadata=[
+                converter.kv_string("motionbricks.style_name", name),
+                converter.kv_f32("motionbricks.style_speed", speed),
+                converter.kv_u32("motionbricks.style_frames", frames),
+                converter.kv_u32("motionbricks.style_index", index),
+            ],
+        )
+    (args.output / "manifest.json").write_text(
+        json.dumps({"format": "motionbricks-style-bundle-v1", "styles": records},
+                   indent=2, sort_keys=True) + "\n", encoding="utf-8")
+
+
+if __name__ == "__main__":
+    main()

scripts/convert_to_gguf.py

@@ -0,0 +1,307 @@
+#!/usr/bin/env python3
+"""Convert verified MotionBricks safetensors into inference-only GGUF v3.
+
+This converter deliberately rejects PyTorch checkpoint files.  The pinned
+reference container must first extract the upstream pickle archives into the
+safe, deterministic safetensors lane documented in reference/README.md.
+"""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import os
+import struct
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Callable
+
+import numpy as np
+from safetensors import safe_open
+
+
+GGUF_MAGIC = b"GGUF"
+GGUF_VERSION = 3
+ALIGNMENT = 32
+
+GGML_TYPE_F32 = 0
+# ggml v0.20.2 / GGUF v3 enum value (the submodule is pinned with the bundle).
+GGML_TYPE_I32 = 26
+GGUF_TYPE_UINT32 = 4
+GGUF_TYPE_FLOAT32 = 6
+GGUF_TYPE_STRING = 8
+GGUF_TYPE_UINT64 = 10
+
+UPSTREAM_REVISION = "a0732b642c0333077e127a2f56ab0014c196bca4"
+SAFE_FORMAT = "motionbricks-safe-manifest-v1"
+BUNDLE_FORMAT = "motionbricks-gguf-bundle-v1"
+SAFE_HASHES = {
+    "pose": "01327768be7413111dc927947a95cfb3e9ee7c52acfa35a054e8c2f3b838b888",
+    "root": "d1529a8c9da915cb7dd0499272baba61db480660c0aae92b67fbe69828e83c5a",
+    "vqvae": "544782e605ed96d60bf999243ef8f44640ea021a5655ef20af2d2853c3e18b5b",
+    "support": "229b764411652b2ab0f824481d6daf897f701a97223029759444fc5bc241ea22",
+}
+
+JOINT_NAMES = (
+    "pelvis_skel",
+    "left_hip_pitch_skel", "left_hip_roll_skel", "left_hip_yaw_skel",
+    "left_knee_skel", "left_ankle_pitch_skel", "left_ankle_roll_skel", "left_toe_base",
+    "right_hip_pitch_skel", "right_hip_roll_skel", "right_hip_yaw_skel",
+    "right_knee_skel", "right_ankle_pitch_skel", "right_ankle_roll_skel", "right_toe_base",
+    "waist_yaw_skel", "waist_roll_skel", "waist_pitch_skel",
+    "left_shoulder_pitch_skel", "left_shoulder_roll_skel", "left_shoulder_yaw_skel",
+    "left_elbow_skel", "left_wrist_roll_skel", "left_wrist_pitch_skel",
+    "left_wrist_yaw_skel", "left_hand_roll_skel",
+    "right_shoulder_pitch_skel", "right_shoulder_roll_skel", "right_shoulder_yaw_skel",
+    "right_elbow_skel", "right_wrist_roll_skel", "right_wrist_pitch_skel",
+    "right_wrist_yaw_skel", "right_hand_roll_skel",
+)
+
+
+def encoded(value: str) -> bytes:
+    data = value.encode("utf-8")
+    return struct.pack("<Q", len(data)) + data
+
+
+def kv_string(key: str, value: str) -> bytes:
+    return encoded(key) + struct.pack("<I", GGUF_TYPE_STRING) + encoded(value)
+
+
+def kv_u32(key: str, value: int) -> bytes:
+    return encoded(key) + struct.pack("<II", GGUF_TYPE_UINT32, value)
+
+
+def kv_f32(key: str, value: float) -> bytes:
+    return encoded(key) + struct.pack("<If", GGUF_TYPE_FLOAT32, value)
+
+
+def kv_u64(key: str, value: int) -> bytes:
+    return encoded(key) + struct.pack("<IQ", GGUF_TYPE_UINT64, value)
+
+
+def aligned(value: int) -> int:
+    return (value + ALIGNMENT - 1) // ALIGNMENT * ALIGNMENT
+
+
+def sha256(path: Path) -> str:
+    digest = hashlib.sha256()
+    with path.open("rb") as stream:
+        while block := stream.read(8 << 20):
+            digest.update(block)
+    return digest.hexdigest()
+
+
+def compact_name(name: str) -> str:
+    """Keep upstream names readable while respecting GGML_MAX_NAME (64)."""
+    if len(name.encode("utf-8")) < 64:
+        return name
+    replacements = (
+        ("_root_token_transformer_encoder.layers.", "root.l."),
+        ("_shared_transformer_encoder.layers.", "shared.l."),
+        ("_transformer_encoder.layers.", "transformer.l."),
+        ("self_attn.", "attn."),
+        ("in_proj_weight", "qkv.weight"),
+        ("in_proj_bias", "qkv.bias"),
+        ("external_cond_blocks.", "xcond."),
+        ("target_cond_blocks.", "tcond."),
+    )
+    output = name
+    for old, new in replacements:
+        output = output.replace(old, new)
+    if len(output.encode("utf-8")) >= 64:
+        suffix = hashlib.sha256(name.encode("utf-8")).hexdigest()[:12]
+        output = output.encode("utf-8")[:48].decode("utf-8", "ignore") + "." + suffix
+    return output
+
+
+@dataclass
+class Tensor:
+    name: str
+    value: np.ndarray
+    kind: int
+    dimensions: tuple[int, ...]
+    offset: int
+
+    @property
+    def size(self) -> int:
+        return int(self.value.size) * 4
+
+    def bytes(self) -> bytes:
+        dtype = "<f4" if self.kind == GGML_TYPE_F32 else "<i4"
+        return np.asarray(self.value, dtype=dtype, order="C").tobytes(order="C")
+
+
+def load_selected(path: Path, select: Callable[[str], bool], strip: str) -> list[tuple[str, np.ndarray]]:
+    output: list[tuple[str, np.ndarray]] = []
+    with safe_open(path, framework="numpy") as source:
+        for original in source.keys():
+            if not select(original):
+                continue
+            name = original.removeprefix(strip)
+            value = source.get_tensor(original)
+            output.append((name, value))
+    if not output:
+        raise ValueError(f"selection produced no tensors from {path}")
+    return output
+
+
+def tensor_kind(component: str, name: str, value: np.ndarray) -> int:
+    if np.issubdtype(value.dtype, np.floating):
+        return GGML_TYPE_F32
+    if np.issubdtype(value.dtype, np.integer) or np.issubdtype(value.dtype, np.bool_):
+        return GGML_TYPE_I32
+    raise ValueError(f"unsupported tensor dtype for {component}:{name}: {value.dtype}")
+
+
+def write_component(path: Path, component: str, values: list[tuple[str, np.ndarray]],
+                    source_hash: str, *, general_name: str = "NVIDIA MotionBricks G1",
+                    extra_metadata: list[bytes] | None = None) -> dict[str, object]:
+    tensors: list[Tensor] = []
+    names: set[str] = set()
+    offset = 0
+    parameter_count = 0
+    for original_name, value in sorted(values):
+        name = compact_name(original_name)
+        if name in names:
+            raise ValueError(f"compacted tensor name collision: {name}")
+        names.add(name)
+        if value.ndim > 4:
+            raise ValueError(f"GGML supports at most four dimensions: {name} has {value.shape}")
+        kind = tensor_kind(component, name, value)
+        shape = tuple(int(item) for item in value.shape) or (1,)
+        tensor = Tensor(name, value, kind, tuple(reversed(shape)), offset)
+        tensors.append(tensor)
+        parameter_count += int(value.size)
+        offset = aligned(offset + tensor.size)
+
+    metadata = [
+        kv_string("general.architecture", "motionbricks"),
+        kv_string("general.name", general_name),
+        kv_u32("general.alignment", ALIGNMENT),
+        kv_u32("general.file_type", 0),
+        kv_u32("motionbricks.format_version", 1),
+        kv_string("motionbricks.component", component),
+        kv_string("motionbricks.skeleton", "g1skel34"),
+        kv_string("motionbricks.upstream_revision", UPSTREAM_REVISION),
+        kv_string("motionbricks.source_sha256", source_hash),
+        kv_u64("motionbricks.parameter_count", parameter_count),
+    ]
+    if extra_metadata:
+        metadata.extend(extra_metadata)
+    if component == "support":
+        metadata.append(kv_string("motionbricks.joint_names", ",".join(JOINT_NAMES)))
+
+    header = bytearray(GGUF_MAGIC)
+    header += struct.pack("<IQQ", GGUF_VERSION, len(tensors), len(metadata))
+    for item in metadata:
+        header += item
+    for tensor in tensors:
+        header += encoded(tensor.name)
+        header += struct.pack("<I", len(tensor.dimensions))
+        header += struct.pack("<" + "Q" * len(tensor.dimensions), *tensor.dimensions)
+        header += struct.pack("<IQ", tensor.kind, tensor.offset)
+    header += bytes(aligned(len(header)) - len(header))
+
+    temporary = path.with_suffix(path.suffix + ".tmp")
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with temporary.open("wb") as stream:
+        stream.write(header)
+        position = 0
+        for tensor in tensors:
+            stream.write(bytes(tensor.offset - position))
+            payload = tensor.bytes()
+            if len(payload) != tensor.size:
+                raise AssertionError(f"incorrect payload size for {tensor.name}")
+            stream.write(payload)
+            position = tensor.offset + len(payload)
+        # GGUF's declared data blob includes alignment after the final tensor.
+        stream.write(bytes(offset - position))
+        stream.flush()
+        os.fsync(stream.fileno())
+    os.replace(temporary, path)
+    result = {
+        "path": path.name,
+        "sha256": sha256(path),
+        "tensor_count": len(tensors),
+        "parameter_count": parameter_count,
+    }
+    print(f"wrote {path}: {len(tensors)} tensors, {parameter_count:,} values")
+    return result
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--safe-directory", type=Path, required=True)
+    parser.add_argument("--output", type=Path, required=True)
+    args = parser.parse_args()
+
+    safe_manifest = json.loads((args.safe_directory / "manifest.json").read_text(encoding="utf-8"))
+    if safe_manifest.get("format") != SAFE_FORMAT:
+        raise ValueError("not a compatible trusted-extraction manifest")
+    if safe_manifest.get("upstream_revision") != UPSTREAM_REVISION:
+        raise ValueError("trusted extraction came from a different upstream revision")
+    for component, expected in SAFE_HASHES.items():
+        path = args.safe_directory / f"{component}.safetensors"
+        actual = sha256(path)
+        recorded = safe_manifest["components"][component]["sha256"]
+        if actual != expected or recorded != expected:
+            raise ValueError(f"safe input hash mismatch for {component}: {actual}")
+
+    selections = {
+        "pose": load_selected(
+            args.safe_directory / "pose.safetensors",
+            lambda name: name.startswith("backbone_net.") and name != "backbone_net.initted",
+            "backbone_net.",
+        ),
+        "root": load_selected(
+            args.safe_directory / "root.safetensors",
+            lambda name: name.startswith("backbone_net."),
+            "backbone_net.",
+        ),
+        "vq-decoder": load_selected(
+            args.safe_directory / "vqvae.safetensors",
+            lambda name: name.startswith("pose_net.decoder.")
+            or name == "pose_net.quantizer.vq._codebook.embed",
+            "pose_net.",
+        ),
+        "support": load_selected(
+            args.safe_directory / "support.safetensors", lambda _name: True, ""
+        ),
+    }
+    source_for = {"pose": "pose", "root": "root", "vq-decoder": "vqvae", "support": "support"}
+    expected = {
+        "pose": (209, 136_588_272),
+        "root": (150, 34_122_833),
+        "vq-decoder": (51, 12_437_277),
+        "support": (4, 972),
+    }
+    components: dict[str, object] = {}
+    for component, values in selections.items():
+        actual = (len(values), sum(int(value.size) for _, value in values))
+        if actual != expected[component]:
+            raise ValueError(f"unexpected {component} inventory: {actual}, expected {expected[component]}")
+        source = source_for[component]
+        components[component] = write_component(
+            args.output / f"{component}.gguf", component, values, SAFE_HASHES[source]
+        )
+
+    bundle = {
+        "format": BUNDLE_FORMAT,
+        "upstream_revision": UPSTREAM_REVISION,
+        "skeleton": "g1skel34",
+        "joint_count": len(JOINT_NAMES),
+        "inference_parameter_count": sum(
+            int(components[name]["parameter_count"]) for name in ("pose", "root", "vq-decoder")
+        ),
+        "components": components,
+        "safe_manifest_sha256": sha256(args.safe_directory / "manifest.json"),
+    }
+    temporary = args.output / "manifest.json.tmp"
+    temporary.write_text(json.dumps(bundle, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+    os.replace(temporary, args.output / "manifest.json")
+    print(f"inference parameters: {bundle['inference_parameter_count']:,}")
+
+
+if __name__ == "__main__":
+    main()

scripts/download_gguf_weights.py

@@ -0,0 +1,117 @@
+#!/usr/bin/env python3
+"""Download and verify the published MotionBricks GGUF/style distribution."""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import os
+import shutil
+import sys
+import urllib.parse
+import urllib.request
+from pathlib import Path
+
+
+ROOT = Path(__file__).resolve().parent.parent
+DEFAULT_REPO = "LocalAI-io/MotionBricks-G1-GGML"
+DEFAULT_REVISION = "cc2a47603dbc203a4f18f35dd06ed3611833f506"
+DEFAULT_MANIFEST = ROOT / "scripts/hf/MotionBricks-G1-GGML/MANIFEST.json"
+FORMAT = "motionbricks-gguf-distribution-v1"
+UPSTREAM_REVISION = "a0732b642c0333077e127a2f56ab0014c196bca4"
+
+
+def digest(path: Path) -> str:
+    value = hashlib.sha256()
+    with path.open("rb") as stream:
+        for block in iter(lambda: stream.read(8 << 20), b""):
+            value.update(block)
+    return value.hexdigest()
+
+
+def valid(path: Path, entry: dict[str, object]) -> bool:
+    return (path.is_file() and path.stat().st_size == entry["bytes"]
+            and digest(path) == entry["sha256"])
+
+
+def safe_relative(value: object) -> Path:
+    path = Path(str(value))
+    if path.is_absolute() or ".." in path.parts or not path.parts:
+        raise ValueError(f"unsafe distribution path: {value!r}")
+    if path.parts[0] not in {"g1-f32", "styles"}:
+        raise ValueError(f"unexpected distribution path: {value!r}")
+    if path.suffix not in {".gguf", ".mbstyle", ".json"}:
+        raise ValueError(f"unexpected distribution file type: {value!r}")
+    return path
+
+
+def load_manifest(path: Path, repo: str) -> dict[str, object]:
+    value = json.loads(path.read_text(encoding="utf-8"))
+    if value.get("format") != FORMAT:
+        raise ValueError(f"unsupported manifest format in {path}")
+    if value.get("repository") != repo:
+        raise ValueError(f"manifest is for {value.get('repository')}, not {repo}")
+    if value.get("upstream_revision") != UPSTREAM_REVISION:
+        raise ValueError("manifest refers to an unexpected upstream revision")
+    files = value.get("files")
+    if not isinstance(files, list) or not files:
+        raise ValueError("manifest has no files")
+    for entry in files:
+        if (not isinstance(entry, dict) or not isinstance(entry.get("bytes"), int)
+                or entry["bytes"] <= 0 or not isinstance(entry.get("sha256"), str)
+                or len(entry["sha256"]) != 64):
+            raise ValueError("manifest contains a malformed file record")
+        safe_relative(entry.get("path"))
+    return value
+
+
+def download(url: str, destination: Path) -> None:
+    destination.parent.mkdir(parents=True, exist_ok=True)
+    temporary = destination.with_name(destination.name + ".download")
+    request = urllib.request.Request(url, headers={"User-Agent": "motion-bricks.cpp/0.1"})
+    try:
+        with urllib.request.urlopen(request) as response, temporary.open("wb") as output:
+            shutil.copyfileobj(response, output, length=8 << 20)
+            output.flush()
+            os.fsync(output.fileno())
+        os.replace(temporary, destination)
+    finally:
+        temporary.unlink(missing_ok=True)
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--output", type=Path, default=ROOT / "generated",
+                        help="destination containing g1-f32/ and styles/")
+    parser.add_argument("--repo", default=DEFAULT_REPO, help="Hugging Face model repository")
+    parser.add_argument("--revision", default=DEFAULT_REVISION,
+                        help="pinned Hugging Face commit or revision")
+    parser.add_argument("--manifest", type=Path, default=DEFAULT_MANIFEST,
+                        help="version-controlled distribution manifest")
+    args = parser.parse_args()
+
+    try:
+        manifest = load_manifest(args.manifest, args.repo)
+        quoted_repo = urllib.parse.quote(args.repo, safe="/")
+        quoted_revision = urllib.parse.quote(args.revision, safe="")
+        base = f"https://huggingface.co/{quoted_repo}/resolve/{quoted_revision}"
+        for entry in manifest["files"]:
+            relative = safe_relative(entry["path"])
+            destination = args.output / relative
+            if valid(destination, entry):
+                print(f"verified {destination}")
+                continue
+            print(f"downloading {relative} from {args.repo}@{args.revision}")
+            download(f"{base}/{urllib.parse.quote(relative.as_posix(), safe='/')}", destination)
+            if not valid(destination, entry):
+                raise ValueError(f"downloaded file failed size/SHA-256 verification: {destination}")
+    except (OSError, ValueError, urllib.error.URLError, json.JSONDecodeError) as error:
+        print(f"error: {error}", file=sys.stderr)
+        return 1
+    print("MotionBricks GGUF and style bundles are present and verified")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

scripts/hf/MotionBricks-G1-GGML/MANIFEST.json

@@ -0,0 +1,114 @@
+{
+  "files": [
+    {
+      "bytes": 1101,
+      "path": "g1-f32/manifest.json",
+      "sha256": "35321e8f760316e9a0e73619e23af4089deeedcc8efe7e7266fddbdb8d3c3cfc"
+    },
+    {
+      "bytes": 546369984,
+      "path": "g1-f32/pose.gguf",
+      "sha256": "6db82e5a67a355052f283bbcab104b71ecfc333dc8d9017c3812eb6f9650756e"
+    },
+    {
+      "bytes": 136504000,
+      "path": "g1-f32/root.gguf",
+      "sha256": "46268d77e5c15449d68a39ce6ec7145e9eb457c5114d5dca934bd3ab539b29db"
+    },
+    {
+      "bytes": 5472,
+      "path": "g1-f32/support.gguf",
+      "sha256": "5d41cae4bc494e612ef19e25f599351aafbc9ef1cb46d4ac3f1e42bb7ab07200"
+    },
+    {
+      "bytes": 49753440,
+      "path": "g1-f32/vq-decoder.gguf",
+      "sha256": "6a1114b6906b07fab9deb18d602b4e731e1b5794318b1643ffd0605692f62d1e"
+    },
+    {
+      "bytes": 9408,
+      "path": "styles/elbow_crawling.mbstyle",
+      "sha256": "8ce3e04aa92d91628f10824a2f19a0cc0ba5a9c16008cd95e091b05c9528dc54"
+    },
+    {
+      "bytes": 50624,
+      "path": "styles/hand_crawling.mbstyle",
+      "sha256": "5687f3cd037d7d0942df180727729e04c08d6f0af48b32e9bf793729c5c69fd8"
+    },
+    {
+      "bytes": 50624,
+      "path": "styles/idle.mbstyle",
+      "sha256": "ae800a700d29a8d1082d32c2c82e893aa292c6c18848ffd2c0c67c6f4d64531e"
+    },
+    {
+      "bytes": 14304,
+      "path": "styles/injured_walk.mbstyle",
+      "sha256": "b7b62643281b46ceb0a37fc336f201565b595afda21e93a2cbfc3dda3509a779"
+    },
+    {
+      "bytes": 3114,
+      "path": "styles/manifest.json",
+      "sha256": "762f7eadb5653af53bb9a03f812b724845b3af6967b76c5f52546de97f1edac4"
+    },
+    {
+      "bytes": 50624,
+      "path": "styles/slow_walk.mbstyle",
+      "sha256": "9e59ec536d22f61c53b430aecabbef92e694d6ab5caef077ac7d0cfbca6d73f0"
+    },
+    {
+      "bytes": 34112,
+      "path": "styles/stealth_walk.mbstyle",
+      "sha256": "4d2d82e40f9f43c1c15c201b45e30dfb194e4a28cf7fd8a23870394c4589d87a"
+    },
+    {
+      "bytes": 50624,
+      "path": "styles/walk.mbstyle",
+      "sha256": "c1657f56795f26ac22ab944cc6676dd9a7c12e37fc654b08e744a18963597d59"
+    },
+    {
+      "bytes": 17664,
+      "path": "styles/walk_boxing.mbstyle",
+      "sha256": "32349902a37d79f049e52a98929680ff18f9300a270ace1709f16d5d87d70892"
+    },
+    {
+      "bytes": 126400,
+      "path": "styles/walk_gun.mbstyle",
+      "sha256": "6b5f0f6febb92b1fbb090f246e48c4762c23f7d101bc2b371fd93a13a1425245"
+    },
+    {
+      "bytes": 34112,
+      "path": "styles/walk_happy_dance.mbstyle",
+      "sha256": "0900c03fbdcaf4f5fac8e4e3d4ebde5965a8cf561a4ecab07db256a136f3e2e8"
+    },
+    {
+      "bytes": 9408,
+      "path": "styles/walk_left.mbstyle",
+      "sha256": "7660e369e64bc711b153caba744c1ccb3d763060f87b368969fd1ec4819694e5"
+    },
+    {
+      "bytes": 9408,
+      "path": "styles/walk_right.mbstyle",
+      "sha256": "106419603b7844d3f2f804b4debbff47b1ec71969f8dd4c4b4dbaef36d4e5c83"
+    },
+    {
+      "bytes": 149504,
+      "path": "styles/walk_scared.mbstyle",
+      "sha256": "b88776e3d57c7008e94e2a51c8da19d0715a3a42565b47c2019cabb40b13578d"
+    },
+    {
+      "bytes": 34112,
+      "path": "styles/walk_stealth.mbstyle",
+      "sha256": "bbb4b69e29cd78cad102da433dc553f6dc16b6710f9a7d4c7df0148f1492f778"
+    },
+    {
+      "bytes": 149504,
+      "path": "styles/walk_zombie.mbstyle",
+      "sha256": "9ce2769010ecb20c5ad38d36f841ec72e29dd1e4556dff8f0ecb258855a9705b"
+    }
+  ],
+  "format": "motionbricks-gguf-distribution-v1",
+  "repository": "LocalAI-io/MotionBricks-G1-GGML",
+  "upstream_license": "NVIDIA Open Model License",
+  "upstream_repository": "NVlabs/GR00T-WholeBodyControl",
+  "upstream_revision": "a0732b642c0333077e127a2f56ab0014c196bca4"
+}

scripts/hf/MotionBricks-G1-GGML/NOTICE

@@ -0,0 +1,5 @@
+Licensed by NVIDIA Corporation under the NVIDIA Open Model License.
+
+Upstream model: NVlabs/GR00T-WholeBodyControl, motionbricks/, revision
+a0732b642c0333077e127a2f56ab0014c196bca4. This GGUF conversion grants no
+additional rights.

scripts/hf/MotionBricks-G1-GGML/README.md

@@ -0,0 +1,36 @@
+---
+license: other
+library_name: ggml
+tags: [gguf, ggml, motion-generation, unitree-g1, motionbricks]
+---
+
+# MotionBricks-G1-GGML
+
+Native F32 GGML/GGUF conversion of NVIDIA MotionBricks' released G1 pose,
+root, and VQ-decoder checkpoints, plus the 15 released style primitives. It is
+produced by
+[`motion-bricks.cpp`](https://github.com/localai-org/motion-bricks.cpp) for CPU and
+Vulkan inference.
+
+NVIDIA currently publishes MotionBricks through Git LFS rather than a separate
+Hugging Face model repository. This conversion is linked to the pinned
+[`NVlabs/GR00T-WholeBodyControl` revision](https://github.com/NVlabs/GR00T-WholeBodyControl/tree/a0732b642c0333077e127a2f56ab0014c196bca4/motionbricks).
+
+Install the complete checked bundle at `generated/g1-f32` and
+`generated/styles` with:
+
+```sh
+python scripts/download_gguf_weights.py
+```
+
+`MANIFEST.json` and `SHA256SUMS` record the source revision, exact paths,
+sizes, and SHA-256 hashes. The bundle contains 183,148,382 learned F32
+parameters and targets MotionBricks' released 34-joint Unitree G1 skeleton.
+
+## License and provenance
+
+The original checkpoints and this converted representation remain subject to
+the NVIDIA Open Model License in `UPSTREAM_LICENSE`. Redistribution requires
+retaining that agreement and NVIDIA's attribution in `NOTICE`. This conversion
+grants no additional rights. Use is also subject to NVIDIA's Trustworthy AI
+and trade-compliance terms described by that agreement.

scripts/hf/MotionBricks-G1-GGML/UPSTREAM_LICENSE

@@ -0,0 +1,186 @@
+================================================================================
+DUAL LICENSE NOTICE
+================================================================================
+
+This repository is dual-licensed. Different components are under different terms:
+
+1. SOURCE CODE - Apache License 2.0
+   All source code, scripts, and software components
+
+2. MODEL WEIGHTS - NVIDIA Open Model License
+   All trained model checkpoints and weights
+
+See below for the full text of each license.
+
+================================================================================
+PART 1: SOURCE CODE LICENSE (Apache License 2.0)
+================================================================================
+
+Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+
+
+================================================================================
+PART 2: MODEL WEIGHTS LICENSE (NVIDIA Open Model License)
+================================================================================
+
+NVIDIA OPEN MODEL LICENSE AGREEMENT
+
+Last Modified: October 24, 2025
+
+NVIDIA Corporation and its affiliates ("NVIDIA") grants permission to use machine
+learning models under specific conditions. Key permissions include creating
+derivative models and distributing them, with NVIDIA retaining no ownership claims
+over outputs generated by users.
+
+SECTION 1: DEFINITIONS
+
+1.1 "Derivative Model" means any modification of, or works based on or derived
+from, the Model, excluding outputs.
+
+1.2 "Legal Entity" means the union of the acting entity and all other entities
+that control, are controlled by, or are under common control with that entity.
+
+1.3 "Model" means the machine learning model, software, and any checkpoints,
+weights, algorithms, parameters, configuration files, and documentation that NVIDIA
+makes available under this Agreement.
+
+1.4 "NVIDIA Cosmos Model" means a multimodal Model that is covered by this Agreement.
+
+1.5 "Special-Purpose Model" means a Model that is limited to narrow,
+purpose-specific tasks.
+
+1.6 "You" or "Your" means an individual or Legal Entity exercising permissions
+granted by this Agreement.
+
+SECTION 2: CONDITIONS FOR USE, LICENSE GRANT, AI ETHICS AND IP OWNERSHIP
+
+2.1 Conditions for Use. You must comply with all terms and conditions of this
+Agreement. If You initiate copyright or patent litigation against any entity
+(including a cross-claim or counterclaim in a lawsuit) alleging that the Model
+constitutes direct or contributory infringement, then Your licenses under this
+Agreement shall terminate. If You circumvent any safety guardrails or safety
+measures built in to the Model without providing comparable alternatives, Your
+rights under this Agreement shall terminate. NVIDIA may update this Agreement at
+any time to comply with applicable law; Your continued use constitutes Your
+acceptance of the updated terms.
+
+2.2 License Grant. Subject to the terms and conditions of this Agreement, NVIDIA
+hereby grants You a perpetual, worldwide, non-exclusive, no-charge, royalty-free,
+revocable license to publicly perform, publicly display, reproduce, use, create
+derivative works of, make, have made, sell, offer for sale, distribute and import
+the Model.
+
+2.3 AI Ethics. Your use of the Model must be in accordance with NVIDIA's
+Trustworthy AI terms, which can be found at
+https://www.nvidia.com/en-us/agreements/trustworthy-ai/terms/.
+
+2.4 IP Ownership. NVIDIA owns the original Model and NVIDIA's Derivative Models.
+You own Your Derivative Models. NVIDIA makes no claim of ownership to outputs. You
+are responsible for outputs and their subsequent uses.
+
+SECTION 3: REDISTRIBUTION
+
+You may reproduce and distribute copies of the Model or Derivative Models thereof,
+with or without modifications, provided that You meet the following conditions:
+
+a. You must include a copy of this Agreement.
+
+b. You must include the following attribution notice, which can appear in the same
+location as other third-party notices or license information: "Licensed by NVIDIA
+Corporation under the NVIDIA Open Model License."
+
+c. If You are distributing a NVIDIA Cosmos Model, You must also include the phrase
+"Built on NVIDIA Cosmos" on the applicable website, in the user interface, in a
+blog, in an "about" page, or in product documentation.
+
+d. You may add Your own copyright statement to Your modifications and may provide
+additional or different license terms and conditions for use, reproduction, or
+distribution of Your modifications or for any Derivative Models as a whole,
+provided Your use, reproduction, and distribution otherwise complies with this
+Agreement.
+
+SECTION 4: SEPARATE COMPONENTS
+
+The Model may contain components that are subject to separate legal notices or
+governed by separate licenses (including Open Source Software Licenses), as may be
+described in any files made available with the Model. Your use of those separate
+components is subject to the applicable license. This Agreement shall control over
+the separate licenses for third-party Open Source Software to the extent that the
+separate license imposes additional restrictions. "Open Source Software License"
+means any software license approved by the Open Source Initiative, Free Software
+Foundation, or similar recognized organization, or a license identified by SPDX.
+
+SECTION 5: TRADEMARKS
+
+This Agreement does not grant permission to use the trade names, trademarks,
+service marks, or product names of NVIDIA, except as required for reasonable and
+customary use in describing the origin of the Model and reproducing the content of
+the notice.
+
+SECTION 6: DISCLAIMER OF WARRANTY
+
+NVIDIA provides the Model on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF
+ANY KIND, either express or implied, including, without limitation, any warranties
+or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+PARTICULAR PURPOSE. You are solely responsible for reviewing the documentation
+accompanying the Model and determining the appropriateness of using the Model, and
+You understand that Special-Purpose Models are limited to narrow, purpose-specific
+tasks and must not be deployed for uses that are beyond such tasks.
+
+SECTION 7: LIMITATION OF LIABILITY
+
+In no event and under no legal theory, whether in tort (including negligence),
+contract, or otherwise, unless required by applicable law (such as deliberate and
+grossly negligent acts) or agreed to in writing, will NVIDIA be liable to You for
+damages, including any direct, indirect, special, incidental, or consequential
+damages of any character arising as a result of this Agreement or out of the use
+or inability to use the Model or Derivative Models or outputs (including but not
+limited to damages for loss of goodwill, work stoppage, computer failure or
+malfunction, or any and all other commercial damages or losses), even if NVIDIA has
+been advised of the possibility of such damages.
+
+SECTION 8: INDEMNITY
+
+You will defend, indemnify and hold harmless NVIDIA and its affiliates, and their
+respective employees, contractors, directors, officers and agents, from and against
+any and all claims, damages, obligations, losses, liabilities, costs or debt, and
+expenses (including but not limited to attorney's fees) arising from Your use or
+distribution of the Model or Derivative Models or outputs.
+
+SECTION 9: FEEDBACK
+
+NVIDIA may use feedback You provide without restriction and without any
+compensation to You.
+
+SECTION 10: GOVERNING LAW
+
+This Agreement will be governed in all respects by the laws of the United States
+and of the State of Delaware, without regard to conflict of laws provisions. The
+federal and state courts residing in Santa Clara County, California shall have
+exclusive jurisdiction over any dispute arising out of this Agreement, and You
+hereby consent to the personal jurisdiction of such courts. However, NVIDIA shall
+have the right to seek injunctive relief in any court of competent jurisdiction.
+
+SECTION 11: TRADE AND COMPLIANCE
+
+You shall comply with all applicable import, export, trade, and economic sanctions
+laws, including without limitation the Export Administration Regulations and
+economic sanctions laws implemented by the Office of Foreign Assets Control, that
+restrict or govern the destination, end-user and end-use of NVIDIA products,
+technology, software, and services.
+
+---
+
+Version Release Date: October 24, 2025

scripts/publish_gguf.py

@@ -0,0 +1,151 @@
+#!/usr/bin/env python3
+"""Validate and optionally publish the MotionBricks GGUF distribution to HF."""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import io
+import json
+import sys
+from pathlib import Path
+
+
+ROOT = Path(__file__).resolve().parent.parent
+HF_REPO = "LocalAI-io/MotionBricks-G1-GGML"
+UPSTREAM_REPO = "NVlabs/GR00T-WholeBodyControl"
+UPSTREAM_REVISION = "a0732b642c0333077e127a2f56ab0014c196bca4"
+FORMAT = "motionbricks-gguf-distribution-v1"
+CARD_DIR = ROOT / "scripts/hf/MotionBricks-G1-GGML"
+
+
+def digest(path: Path) -> str:
+    value = hashlib.sha256()
+    with path.open("rb") as stream:
+        for block in iter(lambda: stream.read(8 << 20), b""):
+            value.update(block)
+    return value.hexdigest()
+
+
+def checked_json(path: Path, expected_format: str) -> dict[str, object]:
+    if not path.is_file():
+        raise ValueError(f"missing manifest: {path}")
+    value = json.loads(path.read_text(encoding="utf-8"))
+    if value.get("format") != expected_format:
+        raise ValueError(f"unexpected format in {path}")
+    return value
+
+
+def artifacts(model: Path, styles: Path) -> list[tuple[Path, str]]:
+    model_manifest = checked_json(model / "manifest.json", "motionbricks-gguf-bundle-v1")
+    style_manifest = checked_json(styles / "manifest.json", "motionbricks-style-bundle-v1")
+    if model_manifest.get("upstream_revision") != UPSTREAM_REVISION:
+        raise ValueError("model bundle came from an unexpected upstream revision")
+    result = [(model / "manifest.json", "g1-f32/manifest.json")]
+    for record in model_manifest["components"].values():
+        source = model / record["path"]
+        if digest(source) != record["sha256"]:
+            raise ValueError(f"model manifest SHA-256 mismatch: {source}")
+        result.append((source, f"g1-f32/{source.name}"))
+    result.append((styles / "manifest.json", "styles/manifest.json"))
+    for record in style_manifest["styles"].values():
+        source = styles / record["path"]
+        if digest(source) != record["sha256"]:
+            raise ValueError(f"style manifest SHA-256 mismatch: {source}")
+        result.append((source, f"styles/{source.name}"))
+    for source, destination in result:
+        if not source.is_file() or source.stat().st_size == 0:
+            raise ValueError(f"missing or empty artifact: {source}")
+        if source.suffix in {".gguf", ".mbstyle"}:
+            with source.open("rb") as stream:
+                if stream.read(4) != b"GGUF":
+                    raise ValueError(f"invalid GGUF magic: {source}")
+        path = Path(destination)
+        if path.is_absolute() or ".." in path.parts:
+            raise ValueError(f"unsafe destination: {destination}")
+    return sorted(result, key=lambda item: item[1])
+
+
+def distribution_manifest(repo: str, files: list[tuple[Path, str]]) -> tuple[dict[str, object], bytes]:
+    records = [
+        {"path": destination, "bytes": source.stat().st_size, "sha256": digest(source)}
+        for source, destination in files
+    ]
+    value = {
+        "format": FORMAT,
+        "repository": repo,
+        "upstream_repository": UPSTREAM_REPO,
+        "upstream_revision": UPSTREAM_REVISION,
+        "upstream_license": "NVIDIA Open Model License",
+        "files": records,
+    }
+    payload = json.dumps(value, indent=2, sort_keys=True).encode() + b"\n"
+    return value, payload
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--model", type=Path, default=ROOT / "generated/g1-f32")
+    parser.add_argument("--styles", type=Path, default=ROOT / "generated/styles")
+    parser.add_argument("--repo", default=HF_REPO)
+    parser.add_argument("--write-manifest", type=Path,
+                        help="write the checked distribution manifest to this path")
+    parser.add_argument("--upload", action="store_true")
+    parser.add_argument("--confirm-upstream-licence", action="store_true",
+                        help="required with --upload; confirms redistribution conditions were reviewed")
+    args = parser.parse_args()
+
+    try:
+        for required in (CARD_DIR / "README.md", CARD_DIR / "NOTICE", CARD_DIR / "UPSTREAM_LICENSE"):
+            if not required.is_file():
+                raise ValueError(f"missing publication asset: {required}")
+        files = artifacts(args.model, args.styles)
+        manifest, manifest_payload = distribution_manifest(args.repo, files)
+    except (OSError, ValueError, KeyError, json.JSONDecodeError) as error:
+        print(f"error: {error}", file=sys.stderr)
+        return 1
+
+    sums = "".join(f"{entry['sha256']}  {entry['path']}\n" for entry in manifest["files"])
+    total = sum(entry["bytes"] for entry in manifest["files"])
+    print(f"repo:  https://huggingface.co/{args.repo}")
+    print(f"files: {len(files)} model/style artifacts, {total / 1e9:.3f} GB")
+    for entry in manifest["files"]:
+        print(f"  {entry['sha256']}  {entry['bytes']:>12}  {entry['path']}")
+    if args.write_manifest:
+        args.write_manifest.parent.mkdir(parents=True, exist_ok=True)
+        args.write_manifest.write_bytes(manifest_payload)
+        print(f"wrote {args.write_manifest}")
+    if not args.upload:
+        print("[dry-run] nothing uploaded")
+        return 0
+    if not args.confirm_upstream_licence:
+        print("error: --upload requires --confirm-upstream-licence", file=sys.stderr)
+        return 2
+
+    try:
+        from huggingface_hub import CommitOperationAdd, HfApi
+
+        api = HfApi()
+        api.create_repo(args.repo, repo_type="model", exist_ok=True)
+        operations = [
+            CommitOperationAdd(path_in_repo="README.md", path_or_fileobj=CARD_DIR / "README.md"),
+            CommitOperationAdd(path_in_repo="NOTICE", path_or_fileobj=CARD_DIR / "NOTICE"),
+            CommitOperationAdd(path_in_repo="UPSTREAM_LICENSE", path_or_fileobj=CARD_DIR / "UPSTREAM_LICENSE"),
+            *(CommitOperationAdd(path_in_repo=destination, path_or_fileobj=source)
+              for source, destination in files),
+            CommitOperationAdd(path_in_repo="MANIFEST.json", path_or_fileobj=io.BytesIO(manifest_payload)),
+            CommitOperationAdd(path_in_repo="SHA256SUMS", path_or_fileobj=io.BytesIO(sums.encode())),
+        ]
+        commit = api.create_commit(
+            repo_id=args.repo, repo_type="model", operations=operations,
+            commit_message=f"Publish MotionBricks G1 GGUF bundle from {UPSTREAM_REVISION[:12]}",
+        )
+    except Exception as error:  # huggingface_hub supplies the useful API detail
+        print(f"error: Hugging Face upload failed: {error}", file=sys.stderr)
+        return 1
+    print(f"published: {commit.commit_url}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

src/agent.cpp

@@ -0,0 +1,266 @@
+#include "agent.hpp"
+
+#include "handles.hpp"
+#include "motion_rep.hpp"
+#include "planner.hpp"
+
+#include <algorithm>
+#include <array>
+#include <cmath>
+#include <cstddef>
+
+namespace motionbricks::detail {
+namespace {
+
+using mat3 = std::array<float, 9>;
+
+mat3 multiply(const mat3 & a, const mat3 & b) {
+    mat3 result{};
+    for (unsigned row = 0; row < 3U; ++row)
+        for (unsigned column = 0; column < 3U; ++column)
+            for (unsigned k = 0; k < 3U; ++k)
+                result[row * 3U + column] += a[row * 3U + k] * b[k * 3U + column];
+    return result;
+}
+
+mat3 transpose(const mat3 & value) {
+    return {value[0],value[3],value[6],value[1],value[4],value[7],value[2],value[5],value[8]};
+}
+
+mat3 y_rotation(float angle) {
+    const float cosine = std::cos(angle), sine = std::sin(angle);
+    return {cosine,0.0F,sine, 0.0F,1.0F,0.0F, -sine,0.0F,cosine};
+}
+
+std::array<float, 3> transform(const mat3 & matrix, const float * value) {
+    return {matrix[0]*value[0] + matrix[1]*value[1] + matrix[2]*value[2],
+            matrix[3]*value[0] + matrix[4]*value[1] + matrix[5]*value[2],
+            matrix[6]*value[0] + matrix[7]*value[1] + matrix[8]*value[2]};
+}
+
+std::array<float, 4> matrix_xyzw(const mat3 & matrix) {
+    std::array<float, 4> wxyz{};
+    const float trace = matrix[0] + matrix[4] + matrix[8];
+    if (trace > 0.0F) {
+        const float s = 2.0F * std::sqrt(std::max(0.0F, trace + 1.0F));
+        wxyz = {0.25F*s, (matrix[7]-matrix[5])/s, (matrix[2]-matrix[6])/s,
+                (matrix[3]-matrix[1])/s};
+    } else if (matrix[0] > matrix[4] && matrix[0] > matrix[8]) {
+        const float s = 2.0F * std::sqrt(std::max(0.0F, 1.0F+matrix[0]-matrix[4]-matrix[8]));
+        wxyz = {(matrix[7]-matrix[5])/s,0.25F*s,(matrix[1]+matrix[3])/s,(matrix[2]+matrix[6])/s};
+    } else if (matrix[4] > matrix[8]) {
+        const float s = 2.0F * std::sqrt(std::max(0.0F, 1.0F+matrix[4]-matrix[0]-matrix[8]));
+        wxyz = {(matrix[2]-matrix[6])/s,(matrix[1]+matrix[3])/s,0.25F*s,(matrix[5]+matrix[7])/s};
+    } else {
+        const float s = 2.0F * std::sqrt(std::max(0.0F, 1.0F+matrix[8]-matrix[0]-matrix[4]));
+        wxyz = {(matrix[3]-matrix[1])/s,(matrix[2]+matrix[6])/s,(matrix[5]+matrix[7])/s,0.25F*s};
+    }
+    const float norm = std::sqrt(wxyz[0]*wxyz[0]+wxyz[1]*wxyz[1]+wxyz[2]*wxyz[2]+wxyz[3]*wxyz[3]);
+    for (float & value : wxyz) value /= norm;
+    return {wxyz[1],wxyz[2],wxyz[3],wxyz[0]};
+}
+
+float wrap(float value) {
+    constexpr float pi = 3.14159265358979323846F;
+    return std::remainder(value, 2.0F*pi);
+}
+
+float spring(float current, float velocity, float target, float half_life, float time) {
+    constexpr float ln2 = 0.69314718056F;
+    const float y = (4.0F * ln2) / (half_life + 1.0e-5F) / 2.0F;
+    const float x = y * time;
+    const float decay = 1.0F / (1.0F + x + 0.48F*x*x + 0.235F*x*x*x);
+    const float j0 = current - target;
+    const float j1 = velocity + j0*y;
+    return (j0 + j1*time)*decay + target;
+}
+
+mb_status build_constraints(mb_agent & agent, const mb_command & command,
+                            const mb_style & style, transition_constraints & result,
+                            std::string & reason) {
+    encoded_frames context;
+    auto status = encode_context(*agent.model, agent.context_root_xyz,
+        agent.context_local_rotations_xyzw, agent.context_frames, context, reason);
+    if (status != MB_OK) return status;
+    std::copy(context.global_root.begin(), context.global_root.end(), result.global_root.begin());
+    std::copy(context.local_root.begin(), context.local_root.end(), result.local_root.begin());
+    std::copy(context.poses.begin(), context.poses.end(), result.poses.begin());
+    result.has_local_root[3] = 0U;
+    result.allowed_tokens = style.allowed_tokens;
+
+    const float current_x = context.global_root[0], current_z = context.global_root[2];
+    const float velocity_x = (context.global_root[5] - current_x) * 30.0F;
+    const float velocity_z = (context.global_root[7] - current_z) * 30.0F;
+    float direction_x = command.movement_direction[0];
+    float direction_z = command.movement_direction[2];
+    const float direction_norm = std::hypot(direction_x, direction_z);
+    if (direction_norm > 1.0e-5F) { direction_x /= direction_norm; direction_z /= direction_norm; }
+    else { direction_x = 0.0F; direction_z = 0.0F; }
+    const float desired_speed = command.target_speed >= 0.0F ? command.target_speed : style.speed;
+    const float target_x = command.has_world_target != 0U ? command.world_target[0]
+        : current_x + 2.0F * desired_speed * direction_x;
+    const float target_z = command.has_world_target != 0U ? command.world_target[2]
+        : current_z + 2.0F * desired_speed * direction_z;
+
+    const float current_heading = std::atan2(context.global_root[4], context.global_root[3]);
+    const float next_heading = std::atan2(context.global_root[9], context.global_root[8]);
+    const float heading_velocity = wrap(next_heading - current_heading) * 30.0F;
+    float desired_heading = command.has_world_target != 0U ? command.world_target_heading
+        : std::atan2(command.facing_direction[0], command.facing_direction[2]);
+    desired_heading = current_heading + wrap(desired_heading - current_heading);
+
+    std::array<float, 4> target_root_x{}, target_root_z{}, target_heading{};
+    for (unsigned frame = 0; frame < 4U; ++frame) {
+        const float time = 1.0F + static_cast<float>(frame) / 30.0F;
+        target_root_x[frame] = spring(current_x, velocity_x, target_x, 0.4F, time);
+        target_root_z[frame] = spring(current_z, velocity_z, target_z, 0.4F, time);
+        target_heading[frame] = spring(current_heading, heading_velocity, desired_heading, 0.17F, time);
+    }
+    const std::uint32_t first = style.frames == 4U ? 0U
+        : static_cast<std::uint32_t>(command.seed % (style.frames - 4U));
+    for (std::uint32_t frame = 0; frame < 4U; ++frame) {
+        const auto source_frame = first + frame;
+        const float correction = wrap(target_heading[frame] - style.global_headings[source_frame]);
+        const mat3 correction_matrix = y_rotation(correction);
+        auto * global = result.global_root.data() + (frame + 4U) * global_root_width;
+        const float * style_root_joint = style.global_joint_positions.data() +
+            (static_cast<std::size_t>(source_frame) * g1_joint_count) * 3U;
+        global[0] = target_root_x[frame];
+        global[1] = style.global_root_positions[source_frame * 3U + 1U] + style_root_joint[1];
+        global[2] = target_root_z[frame];
+        global[3] = std::cos(target_heading[frame]); global[4] = std::sin(target_heading[frame]);
+        std::copy_n(global, 3U, result.target_root_translations.data() + frame * 3U);
+        float * pose = result.poses.data() + (frame + 4U) * external_pose_width;
+        for (std::uint32_t joint = 1; joint < g1_joint_count; ++joint) {
+            const float * source = style.global_joint_positions.data() +
+                (static_cast<std::size_t>(source_frame) * g1_joint_count + joint) * 3U;
+            const auto position = transform(correction_matrix, source);
+            std::copy(position.begin(), position.end(), pose + (joint - 1U) * 3U);
+        }
+        constexpr std::size_t rotation_offset = 99U;
+        std::array<mat3, g1_joint_count> target_global_rotations{};
+        for (std::uint32_t joint = 0; joint < g1_joint_count; ++joint) {
+            const float * source = style.global_joint_rotations.data() +
+                (static_cast<std::size_t>(source_frame) * g1_joint_count + joint) * 9U;
+            mat3 source_matrix{};
+            std::copy_n(source, 9, source_matrix.begin());
+            const auto matrix = multiply(correction_matrix, source_matrix);
+            target_global_rotations[joint] = matrix;
+            float * six = pose + rotation_offset + joint * 6U;
+            six[0]=matrix[0]; six[1]=matrix[3]; six[2]=matrix[6];
+            six[3]=matrix[1]; six[4]=matrix[4]; six[5]=matrix[7];
+        }
+        for (std::uint32_t joint = 0; joint < g1_joint_count; ++joint) {
+            mat3 local = target_global_rotations[joint];
+            const auto parent = agent.model->joint_parents[joint];
+            if (parent >= 0)
+                local = multiply(transpose(target_global_rotations[static_cast<std::size_t>(parent)]),
+                                 target_global_rotations[joint]);
+            const auto xyzw = matrix_xyzw(local);
+            std::copy(xyzw.begin(), xyzw.end(), result.target_local_rotations_xyzw.begin() +
+                static_cast<std::ptrdiff_t>((static_cast<std::size_t>(frame) * g1_joint_count + joint) * 4U));
+        }
+    }
+    for (std::uint32_t frame = 0; frame < 3U; ++frame) {
+        const float * current = result.global_root.data() + (frame + 4U) * global_root_width;
+        const float * next = current + global_root_width;
+        float * local = result.local_root.data() + (frame + 4U) * local_root_width;
+        local[0] = wrap(target_heading[frame + 1U] - target_heading[frame]) * 30.0F;
+        local[1] = (next[0] - current[0]) * 30.0F;
+        local[2] = (next[2] - current[2]) * 30.0F;
+        local[3] = current[1];
+    }
+    std::copy_n(result.local_root.data() + 6U * local_root_width, local_root_width,
+                result.local_root.data() + 7U * local_root_width);
+    result.local_root[7U * local_root_width + 3U] = result.global_root[7U * global_root_width + 1U];
+    return MB_OK;
+}
+
+} // namespace
+
+mb_status seed_agent_from_style(mb_agent & agent, const mb_style & style,
+                                std::string & reason) {
+    if (agent.model == nullptr || style.frames < 4U) {
+        reason = "agent or initial style is invalid";
+        return MB_INVALID_ARGUMENT;
+    }
+    agent.context_frames = 4U;
+    agent.context_root_xyz.resize(12U);
+    agent.context_local_rotations_xyzw.resize(4U * g1_joint_count * 4U);
+    for (std::uint32_t frame = 0; frame < 4U; ++frame) {
+        const float * root_joint = style.global_joint_positions.data() + frame * g1_joint_count * 3U;
+        for (unsigned axis = 0; axis < 3U; ++axis)
+            agent.context_root_xyz[frame * 3U + axis] =
+                style.global_root_positions[frame * 3U + axis] + root_joint[axis];
+        for (std::uint32_t joint = 0; joint < g1_joint_count; ++joint) {
+            const float * source = style.global_joint_rotations.data() +
+                (static_cast<std::size_t>(frame) * g1_joint_count + joint) * 9U;
+            mat3 global{}; std::copy_n(source, 9, global.begin());
+            const auto parent = agent.model->joint_parents[joint];
+            mat3 local = global;
+            if (parent >= 0) {
+                const float * parent_source = style.global_joint_rotations.data() +
+                    (static_cast<std::size_t>(frame) * g1_joint_count +
+                     static_cast<std::size_t>(parent)) * 9U;
+                mat3 parent_global{}; std::copy_n(parent_source, 9, parent_global.begin());
+                local = multiply(transpose(parent_global), global);
+            }
+            const auto xyzw = matrix_xyzw(local);
+            std::copy(xyzw.begin(), xyzw.end(), agent.context_local_rotations_xyzw.begin() +
+                static_cast<std::ptrdiff_t>((static_cast<std::size_t>(frame) * g1_joint_count + joint) * 4U));
+        }
+    }
+    agent.current_motion.reset();
+    agent.current_frame = 0U;
+    agent.initial_style = &style;
+    return MB_OK;
+}
+
+mb_status plan_agent(mb_agent & agent, const mb_command & command,
+                     mb_motion & output, std::string & reason) {
+    const mb_style * style = command.style != nullptr ? command.style : agent.initial_style;
+    if (agent.model == nullptr || style == nullptr) {
+        reason = "agent plan requires a style";
+        return MB_INVALID_ARGUMENT;
+    }
+    if (agent.context_frames < 4U) {
+        const auto status = seed_agent_from_style(agent, *style, reason);
+        if (status != MB_OK) return status;
+    }
+    transition_constraints constraints;
+    auto status = build_constraints(agent, command, *style, constraints, reason);
+    if (status != MB_OK) return status;
+    status = run_transition(*agent.model, constraints, output, nullptr, reason);
+    if (status != MB_OK) return status;
+    output.target_frames = 4U;
+    output.target_root_translations.assign(constraints.target_root_translations.begin(),
+                                           constraints.target_root_translations.end());
+    output.target_local_rotations_xyzw.assign(constraints.target_local_rotations_xyzw.begin(),
+                                              constraints.target_local_rotations_xyzw.end());
+    return MB_OK;
+}
+
+mb_status advance_agent(mb_agent & agent, std::uint32_t frames,
+                        std::string & reason) {
+    if (!agent.current_motion || agent.current_motion->frames == 0U) {
+        reason = "agent has no planned motion";
+        return MB_INVALID_ARGUMENT;
+    }
+    agent.current_frame = std::min<std::uint32_t>(
+        agent.current_frame + frames, static_cast<std::uint32_t>(agent.current_motion->frames - 1U));
+    agent.context_frames = 4U;
+    agent.context_root_xyz.resize(12U);
+    agent.context_local_rotations_xyzw.resize(4U * g1_joint_count * 4U);
+    for (std::uint32_t frame = 0; frame < 4U; ++frame) {
+        const auto source = std::min<std::uint64_t>(agent.current_frame + frame,
+                                                   agent.current_motion->frames - 1U);
+        std::copy_n(agent.current_motion->root_translations.data() + source * 3U, 3,
+                    agent.context_root_xyz.data() + frame * 3U);
+        std::copy_n(agent.current_motion->local_rotations_xyzw.data() + source * g1_joint_count * 4U,
+                    g1_joint_count * 4U,
+                    agent.context_local_rotations_xyzw.data() + frame * g1_joint_count * 4U);
+    }
+    return MB_OK;
+}
+
+} // namespace motionbricks::detail

src/agent.hpp

@@ -0,0 +1,22 @@
+#pragma once
+
+#include <motionbricks/motionbricks.h>
+
+#include <cstdint>
+#include <string>
+
+struct mb_agent;
+struct mb_command;
+struct mb_motion;
+struct mb_style;
+
+namespace motionbricks::detail {
+
+mb_status seed_agent_from_style(mb_agent & agent, const mb_style & style,
+                                std::string & reason);
+mb_status plan_agent(mb_agent & agent, const mb_command & command,
+                     mb_motion & output, std::string & reason);
+mb_status advance_agent(mb_agent & agent, std::uint32_t frames,
+                        std::string & reason);
+
+} // namespace motionbricks::detail

src/capi.cpp

@@ -0,0 +1,552 @@
+#include <motionbricks/motionbricks.h>
+
+#include "error.hpp"
+#include "agent.hpp"
+#include "handles.hpp"
+#include "model.hpp"
+#include "style.hpp"
+
+#include <algorithm>
+#include <cmath>
+#include <cstdint>
+#include <memory>
+#include <new>
+#include <string>
+#include <string_view>
+
+namespace {
+
+using motionbricks::detail::fail;
+using motionbricks::detail::guard;
+
+bool valid_device(mb_device device) noexcept {
+    return device == MB_DEVICE_AUTO || device == MB_DEVICE_CPU || device == MB_DEVICE_VULKAN;
+}
+
+bool finite3(float x, float y, float z) noexcept {
+    return std::isfinite(x) && std::isfinite(y) && std::isfinite(z);
+}
+
+} // namespace
+
+extern "C" {
+
+uint32_t mb_abi_version(void) { return MB_ABI_VERSION; }
+
+const char * mb_status_string(mb_status status) {
+    switch (status) {
+    case MB_OK: return "ok";
+    case MB_INVALID_ARGUMENT: return "invalid argument";
+    case MB_OUT_OF_MEMORY: return "out of memory";
+    case MB_IO_ERROR: return "I/O error";
+    case MB_INVALID_FORMAT: return "invalid format";
+    case MB_INCOMPATIBLE_MODEL: return "incompatible model";
+    case MB_BACKEND_UNAVAILABLE: return "backend unavailable";
+    case MB_COMPUTE_FAILED: return "compute failed";
+    case MB_NOT_IMPLEMENTED: return "not implemented";
+    case MB_INTERNAL_ERROR: return "internal error";
+    default: return "unknown status";
+    }
+}
+
+mb_status mb_runtime_options_create(mb_runtime_options ** output,
+                                    char * error, uint64_t error_capacity) {
+    return guard(error, error_capacity, [&]() -> mb_status {
+        if (output == nullptr) return fail(MB_INVALID_ARGUMENT, error, error_capacity, "output is null");
+        *output = nullptr;
+        *output = new mb_runtime_options();
+        return MB_OK;
+    });
+}
+
+void mb_runtime_options_free(mb_runtime_options * value) { delete value; }
+
+mb_status mb_runtime_options_set_device(mb_runtime_options * value, mb_device device,
+                                        char * error, uint64_t error_capacity) {
+    return guard(error, error_capacity, [&]() -> mb_status {
+        if (value == nullptr) return fail(MB_INVALID_ARGUMENT, error, error_capacity, "options are null");
+        if (!valid_device(device)) return fail(MB_INVALID_ARGUMENT, error, error_capacity, "invalid device");
+        value->device = device;
+        return MB_OK;
+    });
+}
+
+mb_status mb_runtime_options_get_device(const mb_runtime_options * value, mb_device * output,
+                                        char * error, uint64_t error_capacity) {
+    return guard(error, error_capacity, [&]() -> mb_status {
+        if (value == nullptr || output == nullptr)
+            return fail(MB_INVALID_ARGUMENT, error, error_capacity, "options or output is null");
+        *output = value->device;
+        return MB_OK;
+    });
+}
+
+mb_status mb_runtime_options_set_threads(mb_runtime_options * value, uint32_t threads,
+                                         char * error, uint64_t error_capacity) {
+    return guard(error, error_capacity, [&]() -> mb_status {
+        if (value == nullptr) return fail(MB_INVALID_ARGUMENT, error, error_capacity, "options are null");
+        value->threads = threads;
+        return MB_OK;
+    });
+}
+
+mb_status mb_runtime_options_get_threads(const mb_runtime_options * value, uint32_t * output,
+                                         char * error, uint64_t error_capacity) {
+    return guard(error, error_capacity, [&]() -> mb_status {
+        if (value == nullptr || output == nullptr)
+            return fail(MB_INVALID_ARGUMENT, error, error_capacity, "options or output is null");
+        *output = value->threads;
+        return MB_OK;
+    });
+}
+
+mb_status mb_runtime_options_set_backend_directory(mb_runtime_options * value,
+                                                   const char * directory,
+                                                   char * error, uint64_t error_capacity) {
+    return guard(error, error_capacity, [&]() -> mb_status {
+        if (value == nullptr) return fail(MB_INVALID_ARGUMENT, error, error_capacity, "options are null");
+        value->backend_directory = directory != nullptr ? directory : "";
+        return MB_OK;
+    });
+}
+
+mb_status mb_runtime_options_get_backend_directory(const mb_runtime_options * value,
+                                                   const char ** output,
+                                                   char * error, uint64_t error_capacity) {
+    return guard(error, error_capacity, [&]() -> mb_status {
+        if (value == nullptr || output == nullptr)
+            return fail(MB_INVALID_ARGUMENT, error, error_capacity, "options or output is null");
+        *output = value->backend_directory.c_str();
+        return MB_OK;
+    });
+}
+
+mb_status mb_command_create(mb_command ** output, char * error, uint64_t error_capacity) {
+    return guard(error, error_capacity, [&]() -> mb_status {
+        if (output == nullptr) return fail(MB_INVALID_ARGUMENT, error, error_capacity, "output is null");
+        *output = nullptr;
+        *output = new mb_command();
+        return MB_OK;
+    });
+}
+
+void mb_command_free(mb_command * value) { delete value; }
+
+mb_status mb_command_set_style(mb_command * value, const mb_style * style,
+                               char * error, uint64_t error_capacity) {
+    return guard(error, error_capacity, [&]() -> mb_status {
+        if (value == nullptr) return fail(MB_INVALID_ARGUMENT, error, error_capacity, "command is null");
+        value->style = style;
+        return MB_OK;
+    });
+}
+
+mb_status mb_command_get_style(const mb_command * value, const mb_style ** output,
+                               char * error, uint64_t error_capacity) {
+    return guard(error, error_capacity, [&]() -> mb_status {
+        if (value == nullptr || output == nullptr)
+            return fail(MB_INVALID_ARGUMENT, error, error_capacity, "command or output is null");
+        *output = value->style;
+        return MB_OK;
+    });
+}
+
+mb_status mb_command_set_movement_direction(mb_command * value, float x, float y, float z,
+                                            char * error, uint64_t error_capacity) {
+    return guard(error, error_capacity, [&]() -> mb_status {
+        if (value == nullptr) return fail(MB_INVALID_ARGUMENT, error, error_capacity, "command is null");
+        if (!finite3(x, y, z)) return fail(MB_INVALID_ARGUMENT, error, error_capacity, "movement direction is not finite");
+        value->movement_direction = {x, y, z};
+        return MB_OK;
+    });
+}
+
+mb_status mb_command_get_movement_direction(const mb_command * value,
+                                            float * x, float * y, float * z,
+                                            char * error, uint64_t error_capacity) {
+    return guard(error, error_capacity, [&]() -> mb_status {
+        if (value == nullptr || x == nullptr || y == nullptr || z == nullptr)
+            return fail(MB_INVALID_ARGUMENT, error, error_capacity, "command or output is null");
+        *x = value->movement_direction[0];
+        *y = value->movement_direction[1];
+        *z = value->movement_direction[2];
+        return MB_OK;
+    });
+}
+
+mb_status mb_command_set_facing_direction(mb_command * value, float x, float y, float z,
+                                          char * error, uint64_t error_capacity) {
+    return guard(error, error_capacity, [&]() -> mb_status {
+        if (value == nullptr) return fail(MB_INVALID_ARGUMENT, error, error_capacity, "command is null");
+        if (!finite3(x, y, z)) return fail(MB_INVALID_ARGUMENT, error, error_capacity, "facing direction is not finite");
+        if (x * x + y * y + z * z <= 1.0e-12F)
+            return fail(MB_INVALID_ARGUMENT, error, error_capacity, "facing direction is zero");
+        value->facing_direction = {x, y, z};
+        return MB_OK;
+    });
+}
+
+mb_status mb_command_get_facing_direction(const mb_command * value,
+                                          float * x, float * y, float * z,
+                                          char * error, uint64_t error_capacity) {
+    return guard(error, error_capacity, [&]() -> mb_status {
+        if (value == nullptr || x == nullptr || y == nullptr || z == nullptr)
+            return fail(MB_INVALID_ARGUMENT, error, error_capacity, "command or output is null");
+        *x = value->facing_direction[0];
+        *y = value->facing_direction[1];
+        *z = value->facing_direction[2];
+        return MB_OK;
+    });
+}
+
+mb_status mb_command_set_target_speed(mb_command * value, float speed,
+                                      char * error, uint64_t error_capacity) {
+    return guard(error, error_capacity, [&]() -> mb_status {
+        if (value == nullptr) return fail(MB_INVALID_ARGUMENT, error, error_capacity, "command is null");
+        if (!std::isfinite(speed) || speed < -1.0F)
+            return fail(MB_INVALID_ARGUMENT, error, error_capacity, "target speed must be finite and at least -1");
+        value->target_speed = speed;
+        return MB_OK;
+    });
+}
+
+mb_status mb_command_get_target_speed(const mb_command * value, float * output,
+                                      char * error, uint64_t error_capacity) {
+    return guard(error, error_capacity, [&]() -> mb_status {
+        if (value == nullptr || output == nullptr)
+            return fail(MB_INVALID_ARGUMENT, error, error_capacity, "command or output is null");
+        *output = value->target_speed;
+        return MB_OK;
+    });
+}
+
+mb_status mb_command_set_world_target(mb_command * value, float x, float y, float z,
+                                      float heading, uint32_t enabled,
+                                      char * error, uint64_t error_capacity) {
+    return guard(error, error_capacity, [&]() -> mb_status {
+        if (value == nullptr) return fail(MB_INVALID_ARGUMENT, error, error_capacity, "command is null");
+        if (!finite3(x, y, z) || !std::isfinite(heading))
+            return fail(MB_INVALID_ARGUMENT, error, error_capacity, "world target is not finite");
+        if (enabled > 1) return fail(MB_INVALID_ARGUMENT, error, error_capacity, "enabled must be 0 or 1");
+        value->world_target = {x, y, z};
+        value->world_target_heading = heading;
+        value->has_world_target = enabled;
+        return MB_OK;
+    });
+}
+
+mb_status mb_command_get_world_target(const mb_command * value,
+                                      float * x, float * y, float * z,
+                                      float * heading, uint32_t * enabled,
+                                      char * error, uint64_t error_capacity) {
+    return guard(error, error_capacity, [&]() -> mb_status {
+        if (value == nullptr || x == nullptr || y == nullptr || z == nullptr ||
+            heading == nullptr || enabled == nullptr)
+            return fail(MB_INVALID_ARGUMENT, error, error_capacity, "command or output is null");
+        *x = value->world_target[0];
+        *y = value->world_target[1];
+        *z = value->world_target[2];
+        *heading = value->world_target_heading;
+        *enabled = value->has_world_target;
+        return MB_OK;
+    });
+}
+
+mb_status mb_command_set_seed(mb_command * value, uint64_t seed,
+                              char * error, uint64_t error_capacity) {
+    return guard(error, error_capacity, [&]() -> mb_status {
+        if (value == nullptr) return fail(MB_INVALID_ARGUMENT, error, error_capacity, "command is null");
+        value->seed = seed;
+        return MB_OK;
+    });
+}
+
+mb_status mb_command_get_seed(const mb_command * value, uint64_t * output,
+                              char * error, uint64_t error_capacity) {
+    return guard(error, error_capacity, [&]() -> mb_status {
+        if (value == nullptr || output == nullptr)
+            return fail(MB_INVALID_ARGUMENT, error, error_capacity, "command or output is null");
+        *output = value->seed;
+        return MB_OK;
+    });
+}
+
+mb_status mb_model_load(const char * bundle_directory, const mb_runtime_options * options, mb_model ** output,
+                        char * error, uint64_t error_capacity) {
+    return guard(error, error_capacity, [&]() -> mb_status {
+        if (output == nullptr) return fail(MB_INVALID_ARGUMENT, error, error_capacity, "output is null");
+        *output = nullptr;
+        if (bundle_directory == nullptr || *bundle_directory == '\0')
+            return fail(MB_INVALID_ARGUMENT, error, error_capacity, "bundle directory is empty");
+        if (options != nullptr && !valid_device(options->device))
+            return fail(MB_INVALID_ARGUMENT, error, error_capacity, "invalid device in runtime options");
+#if !defined(MOTIONBRICKS_HAVE_VULKAN)
+        if (options != nullptr && options->device == MB_DEVICE_VULKAN)
+            return fail(MB_BACKEND_UNAVAILABLE, error, error_capacity,
+                        "this build has no Vulkan backend");
+#endif
+        auto model = std::make_unique<mb_model>();
+        std::string reason;
+        const auto status = motionbricks::detail::load_model_bundle(bundle_directory, options, *model, reason);
+        if (status != MB_OK) return fail(status, error, error_capacity, reason);
+        *output = model.release();
+        return MB_OK;
+    });
+}
+
+void mb_model_free(mb_model * value) { delete value; }
+
+mb_status mb_model_get_parameter_count(const mb_model * value, uint64_t * output,
+                                       char * error, uint64_t error_capacity) {
+    return guard(error, error_capacity, [&]() -> mb_status {
+        if (value == nullptr || output == nullptr)
+            return fail(MB_INVALID_ARGUMENT, error, error_capacity, "model or output is null");
+        *output = value->parameter_count;
+        return MB_OK;
+    });
+}
+
+mb_status mb_model_get_joint_count(const mb_model * value, uint32_t * output,
+                                   char * error, uint64_t error_capacity) {
+    return guard(error, error_capacity, [&]() -> mb_status {
+        if (value == nullptr || output == nullptr)
+            return fail(MB_INVALID_ARGUMENT, error, error_capacity, "model or output is null");
+        *output = static_cast<std::uint32_t>(value->joint_names.size());
+        return MB_OK;
+    });
+}
+
+mb_status mb_model_get_joint_name(const mb_model * value, uint32_t joint, const char ** output,
+                                  char * error, uint64_t error_capacity) {
+    return guard(error, error_capacity, [&]() -> mb_status {
+        if (value == nullptr || output == nullptr)
+            return fail(MB_INVALID_ARGUMENT, error, error_capacity, "model or output is null");
+        if (joint >= value->joint_names.size())
+            return fail(MB_INVALID_ARGUMENT, error, error_capacity, "joint index is out of range");
+        *output = value->joint_names[joint].c_str();
+        return MB_OK;
+    });
+}
+
+mb_status mb_model_get_joint_parent(const mb_model * value, uint32_t joint, int32_t * output,
+                                    char * error, uint64_t error_capacity) {
+    return guard(error, error_capacity, [&]() -> mb_status {
+        if (value == nullptr || output == nullptr)
+            return fail(MB_INVALID_ARGUMENT, error, error_capacity, "model or output is null");
+        if (joint >= value->joint_parents.size())
+            return fail(MB_INVALID_ARGUMENT, error, error_capacity, "joint index is out of range");
+        *output = value->joint_parents[joint];
+        return MB_OK;
+    });
+}
+
+mb_status mb_model_get_neutral_joint_position(const mb_model * value, uint32_t joint,
+                                              float * x, float * y, float * z,
+                                              char * error, uint64_t error_capacity) {
+    return guard(error, error_capacity, [&]() -> mb_status {
+        if (value == nullptr || x == nullptr || y == nullptr || z == nullptr)
+            return fail(MB_INVALID_ARGUMENT, error, error_capacity, "model or output is null");
+        if (joint >= value->joint_names.size() || value->neutral_joints.size() != value->joint_names.size() * 3U)
+            return fail(MB_INVALID_ARGUMENT, error, error_capacity, "joint index is out of range");
+        *x = value->neutral_joints[static_cast<std::size_t>(joint) * 3U];
+        *y = value->neutral_joints[static_cast<std::size_t>(joint) * 3U + 1U];
+        *z = value->neutral_joints[static_cast<std::size_t>(joint) * 3U + 2U];
+        return MB_OK;
+    });
+}
+
+mb_status mb_style_load(const mb_model * model, const char * style_path, mb_style ** output,
+                        char * error, uint64_t error_capacity) {
+    return guard(error, error_capacity, [&]() -> mb_status {
+        if (output == nullptr) return fail(MB_INVALID_ARGUMENT, error, error_capacity, "output is null");
+        *output = nullptr;
+        if (model == nullptr || style_path == nullptr || *style_path == '\0')
+            return fail(MB_INVALID_ARGUMENT, error, error_capacity, "model or style path is null");
+        auto style = std::make_unique<mb_style>();
+        std::string reason;
+        const auto status = motionbricks::detail::load_style_file(style_path, *style, reason);
+        if (status != MB_OK) return fail(status, error, error_capacity, reason);
+        *output = style.release();
+        return MB_OK;
+    });
+}
+
+void mb_style_free(mb_style * value) { delete value; }
+
+mb_status mb_style_get_name(const mb_style * value, const char ** output, char * error, uint64_t error_capacity) {
+    return guard(error, error_capacity, [&]() -> mb_status {
+        if (value == nullptr || output == nullptr)
+            return fail(MB_INVALID_ARGUMENT, error, error_capacity, "style or output is null");
+        *output = value->name.c_str();
+        return MB_OK;
+    });
+}
+
+mb_status mb_style_set_speed(mb_style * value, float speed, char * error, uint64_t error_capacity) {
+    return guard(error, error_capacity, [&]() -> mb_status {
+        if (value == nullptr) return fail(MB_INVALID_ARGUMENT, error, error_capacity, "style is null");
+        if (!std::isfinite(speed) || speed < 0.0F)
+            return fail(MB_INVALID_ARGUMENT, error, error_capacity, "style speed must be finite and non-negative");
+        value->speed = speed;
+        return MB_OK;
+    });
+}
+
+mb_status mb_style_get_speed(const mb_style * value, float * output, char * error, uint64_t error_capacity) {
+    return guard(error, error_capacity, [&]() -> mb_status {
+        if (value == nullptr || output == nullptr)
+            return fail(MB_INVALID_ARGUMENT, error, error_capacity, "style or output is null");
+        *output = value->speed;
+        return MB_OK;
+    });
+}
+
+mb_status mb_agent_create(const mb_model * model, mb_agent ** output,
+                          char * error, uint64_t error_capacity) {
+    return guard(error, error_capacity, [&]() -> mb_status {
+        if (output == nullptr) return fail(MB_INVALID_ARGUMENT, error, error_capacity, "output is null");
+        *output = nullptr;
+        if (model == nullptr) return fail(MB_INVALID_ARGUMENT, error, error_capacity, "model is null");
+        auto agent = std::make_unique<mb_agent>();
+        agent->model = model;
+        *output = agent.release();
+        return MB_OK;
+    });
+}
+
+void mb_agent_free(mb_agent * value) { delete value; }
+
+mb_status mb_agent_reset(mb_agent * value, const mb_style * style, char * error, uint64_t error_capacity) {
+    return guard(error, error_capacity, [&]() -> mb_status {
+        if (value == nullptr || style == nullptr)
+            return fail(MB_INVALID_ARGUMENT, error, error_capacity, "agent or style is null");
+        std::string reason;
+        const auto status = motionbricks::detail::seed_agent_from_style(*value, *style, reason);
+        return status == MB_OK ? MB_OK : fail(status, error, error_capacity, reason);
+    });
+}
+
+mb_status mb_agent_set_context(mb_agent * value, const float * roots, const float * rotations,
+                               uint64_t frames, uint64_t joints,
+                               char * error, uint64_t error_capacity) {
+    return guard(error, error_capacity, [&]() -> mb_status {
+        if (value == nullptr || roots == nullptr || rotations == nullptr)
+            return fail(MB_INVALID_ARGUMENT, error, error_capacity, "agent or context data is null");
+        if (frames < 4U || joints != 34U || frames > 1000000U)
+            return fail(MB_INVALID_ARGUMENT, error, error_capacity, "context must contain at least four frames and 34 joints");
+        const auto root_count = static_cast<std::size_t>(frames) * 3U;
+        const auto rotation_count = static_cast<std::size_t>(frames) * 34U * 4U;
+        if (!std::all_of(roots, roots + root_count, [](float item) { return std::isfinite(item); }) ||
+            !std::all_of(rotations, rotations + rotation_count, [](float item) { return std::isfinite(item); }))
+            return fail(MB_INVALID_ARGUMENT, error, error_capacity, "context contains non-finite values");
+        value->context_root_xyz.assign(roots, roots + root_count);
+        value->context_local_rotations_xyzw.assign(rotations, rotations + rotation_count);
+        value->context_frames = frames;
+        value->current_motion.reset();
+        value->current_frame = 0U;
+        return MB_OK;
+    });
+}
+
+mb_status mb_agent_plan(mb_agent * value, const mb_command * command, mb_motion ** output,
+                        char * error, uint64_t error_capacity) {
+    return guard(error, error_capacity, [&]() -> mb_status {
+        if (output == nullptr) return fail(MB_INVALID_ARGUMENT, error, error_capacity, "output is null");
+        *output = nullptr;
+        if (value == nullptr || command == nullptr)
+            return fail(MB_INVALID_ARGUMENT, error, error_capacity, "agent or command is null");
+        auto motion = std::make_unique<mb_motion>();
+        std::string reason;
+        const auto status = motionbricks::detail::plan_agent(*value, *command, *motion, reason);
+        if (status != MB_OK) return fail(status, error, error_capacity, reason);
+        value->current_motion = std::make_unique<mb_motion>(*motion);
+        value->current_frame = 0U;
+        *output = motion.release();
+        return MB_OK;
+    });
+}
+
+mb_status mb_agent_advance(mb_agent * value, uint32_t frames, char * error, uint64_t error_capacity) {
+    return guard(error, error_capacity, [&]() -> mb_status {
+        if (value == nullptr) return fail(MB_INVALID_ARGUMENT, error, error_capacity, "agent is null");
+        std::string reason;
+        const auto status = motionbricks::detail::advance_agent(*value, frames, reason);
+        return status == MB_OK ? MB_OK : fail(status, error, error_capacity, reason);
+    });
+}
+
+void mb_motion_free(mb_motion * value) { delete value; }
+
+mb_status mb_motion_get_frame_count(const mb_motion * value, uint64_t * output, char * error, uint64_t error_capacity) {
+    return guard(error, error_capacity, [&]() -> mb_status {
+        if (value == nullptr || output == nullptr)
+            return fail(MB_INVALID_ARGUMENT, error, error_capacity, "motion or output is null");
+        *output = value->frames;
+        return MB_OK;
+    });
+}
+
+mb_status mb_motion_get_joint_count(const mb_motion * value, uint64_t * output, char * error, uint64_t error_capacity) {
+    return guard(error, error_capacity, [&]() -> mb_status {
+        if (value == nullptr || output == nullptr)
+            return fail(MB_INVALID_ARGUMENT, error, error_capacity, "motion or output is null");
+        *output = value->joints;
+        return MB_OK;
+    });
+}
+
+mb_status mb_motion_get_root_translations(const mb_motion * value, const float ** output, uint64_t * values,
+                                          char * error, uint64_t error_capacity) {
+    return guard(error, error_capacity, [&]() -> mb_status {
+        if (value == nullptr || output == nullptr || values == nullptr)
+            return fail(MB_INVALID_ARGUMENT, error, error_capacity, "motion or output is null");
+        *output = value->root_translations.data();
+        *values = value->root_translations.size();
+        return MB_OK;
+    });
+}
+
+mb_status mb_motion_get_local_rotations_xyzw(const mb_motion * value, const float ** output, uint64_t * values,
+                                             char * error, uint64_t error_capacity) {
+    return guard(error, error_capacity, [&]() -> mb_status {
+        if (value == nullptr || output == nullptr || values == nullptr)
+            return fail(MB_INVALID_ARGUMENT, error, error_capacity, "motion or output is null");
+        *output = value->local_rotations_xyzw.data();
+        *values = value->local_rotations_xyzw.size();
+        return MB_OK;
+    });
+}
+
+mb_status mb_motion_get_target_frame_count(const mb_motion * value, uint64_t * output,
+                                           char * error, uint64_t error_capacity) {
+    return guard(error, error_capacity, [&]() -> mb_status {
+        if (value == nullptr || output == nullptr)
+            return fail(MB_INVALID_ARGUMENT, error, error_capacity, "motion or output is null");
+        *output = value->target_frames;
+        return MB_OK;
+    });
+}
+
+mb_status mb_motion_get_target_root_translations(const mb_motion * value, const float ** output, uint64_t * values,
+                                                 char * error, uint64_t error_capacity) {
+    return guard(error, error_capacity, [&]() -> mb_status {
+        if (value == nullptr || output == nullptr || values == nullptr)
+            return fail(MB_INVALID_ARGUMENT, error, error_capacity, "motion or output is null");
+        *output = value->target_root_translations.data();
+        *values = value->target_root_translations.size();
+        return MB_OK;
+    });
+}
+
+mb_status mb_motion_get_target_local_rotations_xyzw(const mb_motion * value, const float ** output, uint64_t * values,
+                                                    char * error, uint64_t error_capacity) {
+    return guard(error, error_capacity, [&]() -> mb_status {
+        if (value == nullptr || output == nullptr || values == nullptr)
+            return fail(MB_INVALID_ARGUMENT, error, error_capacity, "motion or output is null");
+        *output = value->target_local_rotations_xyzw.data();
+        *values = value->target_local_rotations_xyzw.size();
+        return MB_OK;
+    });
+}
+
+} // extern "C"

src/cli.cpp

@@ -0,0 +1,58 @@
+#include <motionbricks/motionbricks.h>
+
+#include <array>
+#include <iostream>
+#include <memory>
+#include <string_view>
+
+namespace {
+
+struct model_deleter {
+    void operator()(mb_model * value) const noexcept { mb_model_free(value); }
+};
+
+int inspect(const char * directory) {
+    std::array<char, 1024> error{};
+    mb_model * raw = nullptr;
+    const auto status = mb_model_load(directory, nullptr, &raw, error.data(), error.size());
+    std::unique_ptr<mb_model, model_deleter> model(raw);
+    if (status != MB_OK) {
+        std::cerr << "model load failed (" << mb_status_string(status) << "): " << error.data() << '\n';
+        return 1;
+    }
+    std::uint64_t parameters = 0;
+    std::uint32_t joints = 0;
+    if (mb_model_get_parameter_count(model.get(), &parameters, error.data(), error.size()) != MB_OK ||
+        mb_model_get_joint_count(model.get(), &joints, error.data(), error.size()) != MB_OK) {
+        std::cerr << "model inspection failed: " << error.data() << '\n';
+        return 1;
+    }
+    std::cout << "architecture: motionbricks\n"
+              << "skeleton: g1skel34\n"
+              << "parameters: " << parameters << '\n'
+              << "joints: " << joints << '\n';
+    for (std::uint32_t joint = 0; joint < joints; ++joint) {
+        const char * name = nullptr;
+        std::int32_t parent = -1;
+        if (mb_model_get_joint_name(model.get(), joint, &name, error.data(), error.size()) != MB_OK ||
+            mb_model_get_joint_parent(model.get(), joint, &parent, error.data(), error.size()) != MB_OK) {
+            std::cerr << "joint inspection failed: " << error.data() << '\n';
+            return 1;
+        }
+        std::cout << "joint[" << joint << "]: " << name << " parent=" << parent << '\n';
+    }
+    return 0;
+}
+
+} // namespace
+
+int main(int argc, char ** argv) {
+    if (argc == 2 && std::string_view(argv[1]) == "abi") {
+        std::cout << "motion-bricks.cpp ABI " << mb_abi_version() << '\n';
+        return 0;
+    }
+    if (argc == 3 && std::string_view(argv[1]) == "inspect") return inspect(argv[2]);
+
+    std::cerr << "usage: motionbricks-cli abi | inspect BUNDLE_DIRECTORY\n";
+    return 2;
+}

src/decoder.cpp

@@ -0,0 +1,223 @@
+#include "decoder.hpp"
+
+#include "neural_runtime.hpp"
+
+#include <array>
+#include <cstddef>
+#include <cstdint>
+#include <memory>
+#include <string>
+#include <utility>
+#include <vector>
+
+#if defined(MOTIONBRICKS_HAVE_GGML)
+#include <ggml-backend.h>
+#include <ggml.h>
+#endif
+
+namespace motionbricks::detail {
+namespace {
+
+#if defined(MOTIONBRICKS_HAVE_GGML)
+
+struct context_deleter { void operator()(ggml_context * value) const noexcept { ggml_free(value); } };
+struct buffer_deleter {
+    void operator()(ggml_backend_buffer * value) const noexcept { ggml_backend_buffer_free(value); }
+};
+using context_ptr = std::unique_ptr<ggml_context, context_deleter>;
+using buffer_ptr = std::unique_ptr<ggml_backend_buffer, buffer_deleter>;
+
+ggml_tensor * weight(const neural_runtime & runtime, const std::string & name,
+                     std::string & reason) {
+    auto * result = neural_weight(runtime, "vq-decoder", name);
+    if (result == nullptr && reason.empty()) reason = "missing decoder weight: " + name;
+    return result;
+}
+
+ggml_tensor * linear(ggml_context * context, ggml_tensor * input,
+                     ggml_tensor * matrix, ggml_tensor * bias) {
+    return ggml_add(context, ggml_mul_mat(context, matrix, input), bias);
+}
+
+ggml_tensor * conv(ggml_context * context, ggml_tensor * input,
+                   ggml_tensor * kernel, ggml_tensor * bias,
+                   int padding, int dilation) {
+    // ggml_conv_1d deliberately lowers ordinary F32 convolutions through an
+    // F16 im2col buffer.  MotionBricks' residual decoder is sensitive enough
+    // for that loss to become visible, so retain F32 through the lowering.
+    auto * columns = ggml_im2col(context, kernel, input, 1, 0, padding, 0,
+                                dilation, 0, false, GGML_TYPE_F32);
+    auto * output = ggml_mul_mat(context,
+        ggml_reshape_2d(context, columns, columns->ne[0], columns->ne[2] * columns->ne[1]),
+        ggml_reshape_2d(context, kernel, kernel->ne[0] * kernel->ne[1], kernel->ne[2]));
+    output = ggml_reshape_3d(context, output, columns->ne[1], kernel->ne[2], columns->ne[2]);
+    auto * shaped_bias = ggml_reshape_2d(context, bias, 1, bias->ne[0]);
+    return ggml_add(context, output, shaped_bias);
+}
+
+ggml_tensor * channels_first_to_frames(ggml_context * context, ggml_tensor * input,
+                                       std::int64_t channels, std::int64_t frames) {
+    return ggml_cont_2d(context, ggml_transpose(context, input), channels, frames);
+}
+
+ggml_tensor * frames_to_channels_first(ggml_context * context, ggml_tensor * input,
+                                       std::int64_t frames, std::int64_t channels) {
+    return ggml_cont_2d(context, ggml_transpose(context, input), frames, channels);
+}
+
+ggml_tensor * residual_stack(ggml_context * context, const neural_runtime & runtime,
+                             ggml_tensor * input, unsigned stage, std::string & reason,
+                             std::vector<std::pair<std::string, ggml_tensor *>> & traces) {
+    static constexpr std::array dilations{27, 9, 3, 1};
+    auto * hidden = input;
+    for (unsigned block = 0; block < dilations.size(); ++block) {
+        const auto prefix = "decoder.model." + std::to_string(stage) + ".0.model." +
+                            std::to_string(block) + ".";
+        auto * branch = ggml_relu(context, hidden);
+        branch = conv(context, branch,
+            weight(runtime, prefix + "conv1.weight", reason),
+            weight(runtime, prefix + "conv1.bias", reason), dilations[block], dilations[block]);
+        traces.emplace_back("model." + std::to_string(stage) + ".0.model." +
+                            std::to_string(block) + ".conv1", branch);
+        branch = ggml_relu(context, branch);
+        branch = conv(context, branch,
+            weight(runtime, prefix + "conv2.weight", reason),
+            weight(runtime, prefix + "conv2.bias", reason), 0, 1);
+        traces.emplace_back("model." + std::to_string(stage) + ".0.model." +
+                            std::to_string(block) + ".conv2", branch);
+        hidden = ggml_add(context, hidden, branch);
+    }
+    return hidden;
+}
+
+#endif
+
+} // namespace
+
+mb_status run_vq_decoder(const neural_runtime & runtime,
+                         std::span<const float> quantized,
+                         std::span<const float> external_condition,
+                         std::span<const float> target_condition,
+                         std::span<const std::uint8_t> has_target_condition,
+                         std::uint32_t positions,
+                         std::vector<float> & motion,
+                         std::string & reason,
+                         std::vector<decoder_trace> * output_traces) {
+#if !defined(MOTIONBRICKS_HAVE_GGML)
+    (void)runtime; (void)quantized; (void)external_condition; (void)target_condition;
+    (void)has_target_condition; (void)positions; (void)motion; (void)output_traces;
+    reason = "this build has no GGML support";
+    return MB_BACKEND_UNAVAILABLE;
+#else
+    constexpr std::uint32_t latent_width = 256;
+    constexpr std::uint32_t external_width = 2;
+    constexpr std::uint32_t target_width = 304;
+    constexpr std::uint32_t output_width = 413;
+    const auto frames = positions * 4U;
+    if (positions < 1U || positions > 16U ||
+        quantized.size() != static_cast<std::size_t>(positions) * latent_width ||
+        external_condition.size() != static_cast<std::size_t>(frames) * external_width ||
+        target_condition.size() != static_cast<std::size_t>(frames) * target_width ||
+        has_target_condition.size() != frames) {
+        reason = "VQ decoder input shape mismatch";
+        return MB_INVALID_ARGUMENT;
+    }
+    constexpr std::size_t context_bytes = 32U * 1024U * 1024U;
+    context_ptr context(ggml_init({context_bytes, nullptr, true}));
+    if (!context) {
+        reason = "cannot allocate decoder graph metadata";
+        return MB_OUT_OF_MEMORY;
+    }
+    auto * latent_input = ggml_new_tensor_2d(context.get(), GGML_TYPE_F32, positions, latent_width);
+    auto * external_input = ggml_new_tensor_2d(context.get(), GGML_TYPE_F32, external_width, frames);
+    auto * target_input = ggml_new_tensor_2d(context.get(), GGML_TYPE_F32, target_width, frames);
+    auto * target_mask = ggml_new_tensor_2d(context.get(), GGML_TYPE_F32, 1, frames);
+    ggml_set_input(latent_input);
+    ggml_set_input(external_input);
+    ggml_set_input(target_input);
+    ggml_set_input(target_mask);
+
+    std::vector<std::pair<std::string, ggml_tensor *>> traces;
+    auto * initial_conv = conv(context.get(), latent_input,
+        weight(runtime, "decoder.model.0.weight", reason),
+        weight(runtime, "decoder.model.0.bias", reason), 1, 1);
+    traces.emplace_back("model.0", initial_conv);
+    auto * hidden = ggml_relu(context.get(), initial_conv);
+    for (unsigned stage_index = 0; stage_index < 2U; ++stage_index) {
+        const unsigned stage = stage_index + 2U;
+        const auto frame_group = 1U << (2U - stage_index);
+        const auto stage_positions = positions * (1U << stage_index);
+        const auto stage_frames = stage_positions * frame_group;
+
+        auto * target_embedding = linear(context.get(), target_input,
+            weight(runtime, "decoder.target_cond_blocks." + std::to_string(stage_index * 2U) + ".weight", reason),
+            weight(runtime, "decoder.target_cond_blocks." + std::to_string(stage_index * 2U) + ".bias", reason));
+        traces.emplace_back("target_cond_blocks." + std::to_string(stage_index * 2U), target_embedding);
+        auto * hidden_frames = channels_first_to_frames(context.get(), hidden, 512, stage_positions);
+        hidden_frames = ggml_reshape_2d(context.get(), hidden_frames, 512 / frame_group, stage_frames);
+        hidden_frames = ggml_add(context.get(), hidden_frames,
+            ggml_mul(context.get(), ggml_sub(context.get(), ggml_relu(context.get(), target_embedding), hidden_frames),
+                     target_mask));
+        hidden_frames = ggml_reshape_2d(context.get(), hidden_frames, 512, stage_positions);
+
+        auto * external_grouped = ggml_reshape_2d(
+            context.get(), external_input, external_width * frame_group, stage_positions);
+        auto * fused = ggml_concat(context.get(), hidden_frames, external_grouped, 0);
+        auto * fused_linear = linear(context.get(), fused,
+            weight(runtime, "decoder.external_cond_blocks." + std::to_string(stage_index * 2U) + ".weight", reason),
+            weight(runtime, "decoder.external_cond_blocks." + std::to_string(stage_index * 2U) + ".bias", reason));
+        traces.emplace_back("external_cond_blocks." + std::to_string(stage_index * 2U), fused_linear);
+        fused = ggml_relu(context.get(), fused_linear);
+        hidden = frames_to_channels_first(context.get(), fused, stage_positions, 512);
+        hidden = residual_stack(context.get(), runtime, hidden, stage, reason, traces);
+        hidden = ggml_interpolate(context.get(), hidden, hidden->ne[0] * 2, hidden->ne[1],
+                                  hidden->ne[2], hidden->ne[3], GGML_SCALE_MODE_NEAREST);
+        hidden = conv(context.get(), hidden,
+            weight(runtime, "decoder.model." + std::to_string(stage) + ".2.weight", reason),
+            weight(runtime, "decoder.model." + std::to_string(stage) + ".2.bias", reason), 1, 1);
+        traces.emplace_back("model." + std::to_string(stage) + ".2", hidden);
+    }
+    auto * post_conv = conv(context.get(), hidden,
+        weight(runtime, "decoder.model.4.weight", reason),
+        weight(runtime, "decoder.model.4.bias", reason), 1, 1);
+    traces.emplace_back("model.4", post_conv);
+    hidden = ggml_relu(context.get(), post_conv);
+    hidden = conv(context.get(), hidden,
+        weight(runtime, "decoder.model.6.weight", reason),
+        weight(runtime, "decoder.model.6.bias", reason), 1, 1);
+    traces.emplace_back("model.6", hidden);
+    auto * output = channels_first_to_frames(context.get(), hidden, output_width, frames);
+    if (!reason.empty()) return MB_INCOMPATIBLE_MODEL;
+    auto * graph = ggml_new_graph_custom(context.get(), 2048, false);
+    ggml_build_forward_expand(graph, output);
+    buffer_ptr buffer(ggml_backend_alloc_ctx_tensors(context.get(), neural_backend(runtime)));
+    if (!buffer) {
+        reason = "cannot allocate decoder compute buffer";
+        return MB_OUT_OF_MEMORY;
+    }
+    std::vector<float> mask(has_target_condition.begin(), has_target_condition.end());
+    ggml_backend_tensor_set(latent_input, quantized.data(), 0, ggml_nbytes(latent_input));
+    ggml_backend_tensor_set(external_input, external_condition.data(), 0, ggml_nbytes(external_input));
+    ggml_backend_tensor_set(target_input, target_condition.data(), 0, ggml_nbytes(target_input));
+    ggml_backend_tensor_set(target_mask, mask.data(), 0, ggml_nbytes(target_mask));
+    const auto status = ggml_backend_graph_compute(neural_backend(runtime), graph);
+    if (status != GGML_STATUS_SUCCESS) {
+        reason = std::string("decoder graph failed: ") + ggml_status_to_string(status);
+        return MB_COMPUTE_FAILED;
+    }
+    motion.resize(static_cast<std::size_t>(frames) * output_width);
+    ggml_backend_tensor_get(output, motion.data(), 0, motion.size() * sizeof(float));
+    if (output_traces != nullptr) {
+        output_traces->clear();
+        output_traces->reserve(traces.size());
+        for (const auto & [name, tensor] : traces) {
+            decoder_trace trace{name, std::vector<float>(static_cast<std::size_t>(ggml_nelements(tensor)))};
+            ggml_backend_tensor_get(tensor, trace.values.data(), 0, trace.values.size() * sizeof(float));
+            output_traces->push_back(std::move(trace));
+        }
+    }
+    return MB_OK;
+#endif
+}
+
+} // namespace motionbricks::detail

src/decoder.hpp

@@ -0,0 +1,29 @@
+#pragma once
+
+#include <motionbricks/motionbricks.h>
+
+#include <cstdint>
+#include <span>
+#include <string>
+#include <vector>
+
+namespace motionbricks::detail {
+
+class neural_runtime;
+
+struct decoder_trace {
+    std::string name;
+    std::vector<float> values;
+};
+
+mb_status run_vq_decoder(const neural_runtime & runtime,
+                         std::span<const float> quantized,
+                         std::span<const float> external_condition,
+                         std::span<const float> target_condition,
+                         std::span<const std::uint8_t> has_target_condition,
+                         std::uint32_t positions,
+                         std::vector<float> & motion,
+                         std::string & reason,
+                         std::vector<decoder_trace> * traces = nullptr);
+
+} // namespace motionbricks::detail

src/error.cpp

@@ -0,0 +1,25 @@
+#include "error.hpp"
+
+#include <algorithm>
+#include <cstring>
+#include <limits>
+
+namespace motionbricks::detail {
+
+void write_error(char * output, std::uint64_t capacity, std::string_view message) noexcept {
+    if (output == nullptr || capacity == 0) return;
+    const auto usable = capacity - 1;
+    const auto bounded = std::min<std::uint64_t>(usable,
+        static_cast<std::uint64_t>(std::numeric_limits<std::size_t>::max()));
+    const auto count = std::min<std::size_t>(message.size(), static_cast<std::size_t>(bounded));
+    if (count != 0) std::memcpy(output, message.data(), count);
+    output[count] = '\0';
+}
+
+mb_status fail(mb_status status, char * error, std::uint64_t error_capacity,
+               std::string_view message) noexcept {
+    write_error(error, error_capacity, message);
+    return status;
+}
+
+} // namespace motionbricks::detail