@call-me-sensei/toonlab 0.1.1

package/ATTRIBUTION.md

@@ -0,0 +1,40 @@
+# Asset attribution
+
+Code is MIT-licensed by Hyperbond Studio PTE. LTD. (see LICENSE). The assets bundled in this repository:
+
+## Bundled assets
+
+| Asset | Location | License | Source |
+|---|---|---|---|
+| Mannequin character (45 embedded animation clips) | `public/characters/mannequin.glb` | CC0 1.0 | [Quaternius — Universal Animation Library](https://quaternius.com/packs/universalanimationlibrary.html), recolored to neutral grays. See `public/characters/LICENSE.md`. |
+| Landscape textures (grassy-land, land, mountain, rock, sand, tree-trunk) | `labs/shared/textures/` | CC0 1.0 | First-party (created by the toonlab authors), dedicated to the public domain. |
+
+Everything else that renders — water, sky, grass, flowers, trees, foliage,
+splashes, post-processing — is procedural code, no asset files.
+
+## Not bundled (bring your own)
+
+The labs can additionally load content from a gitignored `assets-local/`
+folder that is **not** part of this repository:
+
+- **Mixamo animation clips** (`assets-local/animations/*.fbx`) — the retarget
+  pipeline plays Adobe Mixamo clips on any humanoid model. Download clips
+  with your own Adobe account from [mixamo.com](https://www.mixamo.com) and
+  drop them in; Adobe's terms do not permit us to redistribute the files.
+  Without them, models fall back to their own embedded clips (the bundled
+  mannequin covers idle/walk/run/jump/swim/tread natively).
+- **Your models** (`assets-local/models/`) — PMX/VRM/GLB/FBX/OBJ characters
+  for testing; or pass any hosted URL via the HUD's Model URL field /
+  `?model=`. Make sure you have the rights to any model you load.
+- **Scanned props/environments** (`assets-local/environments/`) — licensed
+  packs (Fab/Megascans etc.) can be dropped in for the demo scenes;
+  the scenes render procedural stand-ins when they're absent.
+
+## Recommended free sources
+
+- [Quaternius](https://quaternius.com) — CC0 models + the Universal
+  Animation Library (v1 and v2 free tiers).
+- [Poly Haven](https://polyhaven.com) — CC0 textures/HDRIs/models.
+- [Kenney](https://kenney.nl) — CC0 game assets.
+- [OpenGameArt](https://opengameart.org) — filter by CC0/CC-BY.
+- [VRoid Hub](https://hub.vroid.com) — VRM avatars (check per-model terms).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hyperbond Studio PTE. LTD.
+
+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.

package/README.md

@@ -0,0 +1,125 @@
+# ToonLab by Call Me Sensei
+
+ToonLab by Call Me Sensei is a stylized anime-style game starter kit and
+runtime library for [Three.js](https://threejs.org/). Its goal is to simplify
+Three.js game development: you get a better-looking anime/stylized game
+without having to develop shaders yourself, and procedurally generated assets
+(trees, rocks, grass, water, sky) reduce content complexity so you can focus
+on your core game logic instead. Clone it and a toon-shaded character is
+walking and swimming through a fully stylized world: cel-shaded characters,
+painterly environments, interactive water, procedural vegetation and sky,
+post-processing, and a schema-driven tuning panel. Use it as a starter kit,
+or import the pieces you need as a library (`@call-me-sensei/toonlab` on npm,
+subpath exports per cluster).
+
+## Quickstart
+
+```bash
+git clone https://github.com/call-me-sensei/toonlab.git && cd toonlab
+npm install
+npm run dev
+```
+
+Vite serves the labs at `http://localhost:5175`. See
+[Getting started](docs/getting-started.md) for a tour.
+
+## The labs
+
+Runnable demos in `labs/` (not published to npm). Switch between them with
+the HUD Scene select:
+
+- **Shader Lab** (`/`) — character + environment shader tuning: every toon
+  and environment setting as a live control, preset export/import, debug
+  views.
+- **Playground** (`/playground/`) — third-person character controller
+  in gameplay scenes: calm lake, river crossing, ocean beach with breaking
+  waves, and an indoor room. Walk, jump, swim, splash.
+- **Rock Lab** (`/rock-lab/`) — procedural stylized rocks, cliffs,
+  heightfields, sculpt edits, and GLB export.
+- **Tree Lab** (`/tree-lab/`) — procedural stylized trees,
+  flowers, sketches, recipes, and GLB export.
+
+Every URL parameter has a HUD control, lab state persists per lab in
+`localStorage`, and **Reset Lab** clears it. Point any lab at your own model
+with the Model URL input or `?model=` — see
+[Characters](docs/characters.md).
+
+## What's inside
+
+| Cluster | Import | What you get |
+|---|---|---|
+| Toon character shading | `@call-me-sensei/toonlab/toon` | Modern anime character shader: cel bands with art-directed face lighting, skin-tone shadow management, shadow-color HSV control, scene/self/contact shadows, average-shadow smoothing, rim light (fresnel or screen-space depth), stylized + anisotropic hair highlights, eye catchlights, role-aware specular, source map routing (normal/AO/emissive/MatCap/ramp/detail), inverted-hull outlines, glitter, stickers, perspective removal, shell fur, dither fades — 23 settings groups, all preset-serializable. [Docs](docs/toon-shading.md) |
+| Environment shading | `@call-me-sensei/toonlab/environment` | Modern anime-style scene shader for texture packs, standard glTF, and untextured scenes: material-role classification, wrapped lighting, packed-map hints, window cutouts, sun/lamp rigs, time-of-day, six-direction ambient probe, planar floor reflections, BVH vertex-AO baking, height fog, cloud shadows. [Docs](docs/environment.md) |
+| Water | `@call-me-sensei/toonlab/water` | Fully procedural interactive water: Gerstner wave stack with a calm→storm dial, wave sets, plunging breakers you can surf, three-stop absorption color, refraction/caustics/foam, GPU ripple sim, splashes, wakes, rain, kelp, underwater view — with a CPU mirror of the whole spectrum for buoyancy. [Docs](docs/water.md) |
+| Vegetation | `@call-me-sensei/toonlab/vegetation` | Instanced grass and flower fields (wind, push-away, scene + cloud shadows, backlit translucency) and procedural stylized trees with a serializable recipe system. [Docs](docs/vegetation-sky.md) |
+| Sky | `@call-me-sensei/toonlab/sky` | Procedural gradient/sun/painterly-cloud/star dome that also shows up in water reflections. [Docs](docs/vegetation-sky.md) |
+| Post-processing | `@call-me-sensei/toonlab/post` | Optional single-pipeline compositor: character-aware bloom, color grade, LUT, vignette, screen outline, depth cue — schema-driven, preset-serializable. [Docs](docs/post-processing.md) |
+| Character pipeline | `@call-me-sensei/toonlab/character` | Bone-role adapters for VRM/MMD/Mixamo/Rigify rigs, native-clip conventions, Mixamo retarget helpers, and a procedural freestyle swim clip. [Docs](docs/characters.md) |
+| Model loaders | `@call-me-sensei/toonlab/loaders` | Optional GLB/glTF, VRM 0+1, PMX/PMD, FBX, OBJ, and text-USDZ loading helpers. Kept off the root import so apps that do not load models avoid loader dependencies. [Docs](docs/characters.md) |
+| Debug panel | `@call-me-sensei/toonlab/debug` | One-line schema-driven tuning GUI for any settings module — the same panel the labs use. [Docs](docs/debug-panel.md) |
+
+Zero texture assets in the library: water, sky, grass, flowers, trees, and
+splashes are all procedural. The one bundled model is a CC0 mannequin with 45
+embedded animation clips.
+
+## Library usage
+
+```js
+import { applyToonShader, createToonSettings } from '@call-me-sensei/toonlab/toon';
+
+const settings = createToonSettings({
+  preset: 'default',
+  skinTone: {
+    skinShadowBrightness: 0.94,
+  },
+});
+
+applyToonShader(characterRoot, { settings });
+```
+
+```js
+import { WaterSurface } from '@call-me-sensei/toonlab/water';
+import { StylizedSky } from '@call-me-sensei/toonlab/sky';
+
+const water = new WaterSurface({ width: 200, depth: 200, preset: 'lake' });
+scene.add(water);
+const sky = new StylizedSky();
+scene.add(sky);
+
+// per frame, before renderer.render(scene, camera):
+water.update(renderer, scene, camera, delta);
+sky.update(delta, camera);
+```
+
+Inside this repo the labs import from `../../src/...`; the `@call-me-sensei/toonlab/...`
+specifiers are what you use once the package is installed from npm. The
+shader clusters are TSL/NodeMaterial modules for Three's WebGPU renderer
+stack, with WebGL2 fallback through the same TSL path.
+
+## Documentation
+
+- [Getting started](docs/getting-started.md) — clone, run, tour the labs,
+  load your own models.
+- [Toon character shading](docs/toon-shading.md)
+- [Environment shading](docs/environment.md)
+- [Water](docs/water.md)
+- [Vegetation and sky](docs/vegetation-sky.md)
+- [Post-processing](docs/post-processing.md)
+- [Characters and animation](docs/characters.md)
+- [Debug panel](docs/debug-panel.md)
+- [Settings reference](docs/settings-reference.md) — every tunable field,
+  generated from the schemas (`node scripts/generate-settings-reference.mjs`).
+- [Shader constants](docs/shader-constants.md) — the deliberately unexposed
+  constants and where they live.
+
+## AI coding agents
+
+The GitHub repo includes downloadable runtime-usage guidance for Codex, Claude
+Code, Cursor, and other coding agents under `agents/`. These files help
+developers use ToonLab in their own apps and are not part of the npm package.
+
+## License
+
+Code is [MIT](LICENSE), copyright Hyperbond Studio PTE. LTD. Bundled assets are CC0 — see
+[ATTRIBUTION.md](ATTRIBUTION.md) for credits and for the bring-your-own
+conventions (Mixamo clips, your own models, licensed scan packs).

package/package.json

@@ -0,0 +1,97 @@
+{
+  "name": "@call-me-sensei/toonlab",
+  "version": "0.1.1",
+  "description": "Stylized (anime/toon) game starter kit for Three.js: character toon shading, environment shading, water, vegetation, sky, and post-processing",
+  "license": "MIT",
+  "author": "Hyperbond Studio PTE. LTD. (Call Me Sensei)",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/call-me-sensei/toonlab.git"
+  },
+  "homepage": "https://github.com/call-me-sensei/toonlab#readme",
+  "bugs": {
+    "url": "https://github.com/call-me-sensei/toonlab/issues"
+  },
+  "keywords": [
+    "three",
+    "threejs",
+    "toon",
+    "cel-shading",
+    "anime",
+    "shader",
+    "water",
+    "game-starter"
+  ],
+  "type": "module",
+  "main": "./src/index.js",
+  "module": "./src/index.js",
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE",
+    "ATTRIBUTION.md"
+  ],
+  "exports": {
+    ".": "./src/index.js",
+    "./toon": "./src/toon/index.js",
+    "./environment": "./src/environment/index.js",
+    "./water": "./src/water/index.js",
+    "./vegetation": "./src/vegetation/index.js",
+    "./sky": "./src/sky/index.js",
+    "./post": "./src/post/index.js",
+    "./rockgen": "./src/rockgen/index.js",
+    "./debrisgen": "./src/debrisgen/index.js",
+    "./character": "./src/character/index.js",
+    "./loaders": "./src/loaders/index.js",
+    "./debug": "./src/debug/index.js",
+    "./toon-settings": "./src/toon/toonSettings.js",
+    "./water-settings": "./src/water/waterSettings.js",
+    "./grass": "./src/vegetation/stylizedGrass.js",
+    "./post-processing": "./src/post/postProcessing.js"
+  },
+  "scripts": {
+    "assets:characters": "node scripts/generate-local-character-assets.mjs",
+    "assets:environments": "node scripts/generate-local-environment-assets.mjs",
+    "assets:local": "npm run assets:characters && npm run assets:environments",
+    "dev": "vite",
+    "build": "vite build",
+    "baseline:compare": "node scripts/compare-baselines.mjs",
+    "preview": "vite preview",
+    "baseline:capture": "node scripts/baseline-capture.mjs",
+    "verify:rockgen": "node scripts/verify-rockgen.mjs",
+    "visual:check": "node scripts/visual-check.mjs"
+  },
+  "peerDependencies": {
+    "@pixiv/three-vrm": "^3.5.4",
+    "three-mesh-bvh": "^0.8.3",
+    "three-stdlib": "^2.36.1",
+    "three": "^0.185.1"
+  },
+  "peerDependenciesMeta": {
+    "@pixiv/three-vrm": {
+      "optional": true
+    },
+    "three-mesh-bvh": {
+      "optional": true
+    },
+    "three-stdlib": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@pixiv/three-vrm": "^3.5.4",
+    "@react-three/drei": "^10.7.7",
+    "@react-three/fiber": "^9.6.1",
+    "@react-three/rapier": "^2.2.0",
+    "@vitejs/plugin-react": "^4.7.0",
+    "ecctrl": "^1.0.97",
+    "lucide-react": "^1.23.0",
+    "playwright": "^1.60.0",
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7",
+    "three": "^0.185.1",
+    "three-mesh-bvh": "^0.8.3",
+    "three-stdlib": "^2.36.1",
+    "vite": "^5.0.0"
+  }
+}

package/src/character/characterRig.js

@@ -0,0 +1,353 @@
+// Canonical humanoid bone roles and per-convention name adapters.
+//
+// The retarget pipeline in ecctrlMain.jsx does a world-space bake that only
+// needs to know WHICH target bone plays WHICH humanoid role — everything else
+// (rest-pose differences, hierarchy mismatches) is solved numerically. This
+// module owns that role knowledge so the pipeline itself stays rig-agnostic:
+// roles follow the VRM humanoid naming (the only spec'd humanoid standard in
+// the glTF world), and each supported convention (VRM, MMD/PMX, Mixamo-named
+// skeletons) contributes a small name table mapping onto those roles.
+//
+// Animation sources are Mixamo FBX clips, so each role also carries its
+// Mixamo bone name; a resolved rig is ultimately a pair of maps between
+// target bone names and Mixamo source names.
+
+// Mixamo bone per VRM humanoid role. Also the source-side chain map used for
+// rest-pose direction corrections lives on these names (MIXAMO_CHAIN_CHILD).
+const MIXAMO_BONE_BY_ROLE = Object.freeze({
+  hips: 'mixamorigHips',
+  spine: 'mixamorigSpine',
+  chest: 'mixamorigSpine1',
+  upperChest: 'mixamorigSpine2',
+  neck: 'mixamorigNeck',
+  head: 'mixamorigHead',
+
+  leftShoulder: 'mixamorigLeftShoulder',
+  leftUpperArm: 'mixamorigLeftArm',
+  leftLowerArm: 'mixamorigLeftForeArm',
+  leftHand: 'mixamorigLeftHand',
+  rightShoulder: 'mixamorigRightShoulder',
+  rightUpperArm: 'mixamorigRightArm',
+  rightLowerArm: 'mixamorigRightForeArm',
+  rightHand: 'mixamorigRightHand',
+
+  leftThumbMetacarpal: 'mixamorigLeftHandThumb1',
+  leftThumbProximal: 'mixamorigLeftHandThumb2',
+  leftThumbDistal: 'mixamorigLeftHandThumb3',
+  leftIndexProximal: 'mixamorigLeftHandIndex1',
+  leftIndexIntermediate: 'mixamorigLeftHandIndex2',
+  leftIndexDistal: 'mixamorigLeftHandIndex3',
+  leftMiddleProximal: 'mixamorigLeftHandMiddle1',
+  leftMiddleIntermediate: 'mixamorigLeftHandMiddle2',
+  leftMiddleDistal: 'mixamorigLeftHandMiddle3',
+  leftRingProximal: 'mixamorigLeftHandRing1',
+  leftRingIntermediate: 'mixamorigLeftHandRing2',
+  leftRingDistal: 'mixamorigLeftHandRing3',
+  leftLittleProximal: 'mixamorigLeftHandPinky1',
+  leftLittleIntermediate: 'mixamorigLeftHandPinky2',
+  leftLittleDistal: 'mixamorigLeftHandPinky3',
+
+  rightThumbMetacarpal: 'mixamorigRightHandThumb1',
+  rightThumbProximal: 'mixamorigRightHandThumb2',
+  rightThumbDistal: 'mixamorigRightHandThumb3',
+  rightIndexProximal: 'mixamorigRightHandIndex1',
+  rightIndexIntermediate: 'mixamorigRightHandIndex2',
+  rightIndexDistal: 'mixamorigRightHandIndex3',
+  rightMiddleProximal: 'mixamorigRightHandMiddle1',
+  rightMiddleIntermediate: 'mixamorigRightHandMiddle2',
+  rightMiddleDistal: 'mixamorigRightHandMiddle3',
+  rightRingProximal: 'mixamorigRightHandRing1',
+  rightRingIntermediate: 'mixamorigRightHandRing2',
+  rightRingDistal: 'mixamorigRightHandRing3',
+  rightLittleProximal: 'mixamorigRightHandPinky1',
+  rightLittleIntermediate: 'mixamorigRightHandPinky2',
+  rightLittleDistal: 'mixamorigRightHandPinky3',
+
+  leftUpperLeg: 'mixamorigLeftUpLeg',
+  leftLowerLeg: 'mixamorigLeftLeg',
+  leftFoot: 'mixamorigLeftFoot',
+  leftToes: 'mixamorigLeftToeBase',
+  rightUpperLeg: 'mixamorigRightUpLeg',
+  rightLowerLeg: 'mixamorigRightLeg',
+  rightFoot: 'mixamorigRightFoot',
+  rightToes: 'mixamorigRightToeBase',
+});
+
+export const HUMANOID_ROLES = Object.freeze(Object.keys(MIXAMO_BONE_BY_ROLE));
+
+// Source-side chain children for rest-pose direction corrections (Mixamo rigs
+// are T-pose; targets are often A-pose). Keyed by Mixamo names because the
+// correction compares source bone directions against target bone directions.
+export const MIXAMO_CHAIN_CHILD = Object.freeze({
+  mixamorigLeftShoulder: 'mixamorigLeftArm',
+  mixamorigLeftArm: 'mixamorigLeftForeArm',
+  mixamorigLeftForeArm: 'mixamorigLeftHand',
+  mixamorigLeftHand: 'mixamorigLeftHandMiddle1',
+  mixamorigRightShoulder: 'mixamorigRightArm',
+  mixamorigRightArm: 'mixamorigRightForeArm',
+  mixamorigRightForeArm: 'mixamorigRightHand',
+  mixamorigRightHand: 'mixamorigRightHandMiddle1',
+  mixamorigLeftUpLeg: 'mixamorigLeftLeg',
+  mixamorigLeftLeg: 'mixamorigLeftFoot',
+  mixamorigLeftFoot: 'mixamorigLeftToeBase',
+  mixamorigRightUpLeg: 'mixamorigRightLeg',
+  mixamorigRightLeg: 'mixamorigRightFoot',
+  mixamorigRightFoot: 'mixamorigRightToeBase',
+});
+
+// MMD/PMX bone names per role. Multiple entries per role are all animated:
+// many rigs (incl. many anime-game models) bind the leg skin weights to the "D"
+// deform bones, which only follow the FK bones through MMD's grant system
+// (needs MMDAnimationHelper) — animating both moves every variant. The LAST
+// existing entry is the preferred one for chain/inverse lookups, matching the
+// deform-bone preference the old hardcoded tables had.
+const MMD_BONES_BY_ROLE = Object.freeze({
+  hips: ['下半身'],
+  spine: ['上半身'],
+  chest: ['上半身3'],
+  upperChest: ['上半身2'],
+  neck: ['首'],
+  head: ['頭'],
+
+  leftShoulder: ['左肩'],
+  leftUpperArm: ['左腕'],
+  leftLowerArm: ['左ひじ'],
+  leftHand: ['左手首'],
+  rightShoulder: ['右肩'],
+  rightUpperArm: ['右腕'],
+  rightLowerArm: ['右ひじ'],
+  rightHand: ['右手首'],
+
+  leftThumbMetacarpal: ['左親指０'],
+  leftThumbProximal: ['左親指１'],
+  leftThumbDistal: ['左親指２'],
+  leftIndexProximal: ['左人指１'],
+  leftIndexIntermediate: ['左人指２'],
+  leftIndexDistal: ['左人指３'],
+  leftMiddleProximal: ['左中指１'],
+  leftMiddleIntermediate: ['左中指２'],
+  leftMiddleDistal: ['左中指３'],
+  leftRingProximal: ['左薬指１'],
+  leftRingIntermediate: ['左薬指２'],
+  leftRingDistal: ['左薬指３'],
+  leftLittleProximal: ['左小指１'],
+  leftLittleIntermediate: ['左小指２'],
+  leftLittleDistal: ['左小指３'],
+
+  rightThumbMetacarpal: ['右親指０'],
+  rightThumbProximal: ['右親指１'],
+  rightThumbDistal: ['右親指２'],
+  rightIndexProximal: ['右人指１'],
+  rightIndexIntermediate: ['右人指２'],
+  rightIndexDistal: ['右人指３'],
+  rightMiddleProximal: ['右中指１'],
+  rightMiddleIntermediate: ['右中指２'],
+  rightMiddleDistal: ['右中指３'],
+  rightRingProximal: ['右薬指１'],
+  rightRingIntermediate: ['右薬指２'],
+  rightRingDistal: ['右薬指３'],
+  rightLittleProximal: ['右小指１'],
+  rightLittleIntermediate: ['右小指２'],
+  rightLittleDistal: ['右小指３'],
+
+  leftUpperLeg: ['左足', '左足D'],
+  leftLowerLeg: ['左ひざ', '左ひざD'],
+  leftFoot: ['左足首', '左足首D'],
+  leftToes: ['左つま先', '左足先EX'],
+  rightUpperLeg: ['右足', '右足D'],
+  rightLowerLeg: ['右ひざ', '右ひざD'],
+  rightFoot: ['右足首', '右足首D'],
+  rightToes: ['右つま先', '右足先EX'],
+});
+
+// Blender Rigify deform-bone names (the bundled mannequin and other
+// Rigify-exported GLBs). GLTFLoader sanitizes node names on load (dots and
+// other reserved characters are stripped: "DEF-upper_arm.L" arrives as
+// "DEF-upper_armL"), so this table is matched loosely — see looseBoneName().
+const RIGIFY_BONES_BY_ROLE = Object.freeze({
+  hips: ['DEF-hips'],
+  spine: ['DEF-spine.001'],
+  chest: ['DEF-spine.002'],
+  upperChest: ['DEF-spine.003'],
+  neck: ['DEF-neck'],
+  head: ['DEF-head'],
+
+  leftShoulder: ['DEF-shoulder.L'],
+  leftUpperArm: ['DEF-upper_arm.L'],
+  leftLowerArm: ['DEF-forearm.L'],
+  leftHand: ['DEF-hand.L'],
+  rightShoulder: ['DEF-shoulder.R'],
+  rightUpperArm: ['DEF-upper_arm.R'],
+  rightLowerArm: ['DEF-forearm.R'],
+  rightHand: ['DEF-hand.R'],
+
+  leftThumbMetacarpal: ['DEF-thumb.01.L'],
+  leftThumbProximal: ['DEF-thumb.02.L'],
+  leftThumbDistal: ['DEF-thumb.03.L'],
+  leftIndexProximal: ['DEF-f_index.01.L'],
+  leftIndexIntermediate: ['DEF-f_index.02.L'],
+  leftIndexDistal: ['DEF-f_index.03.L'],
+  leftMiddleProximal: ['DEF-f_middle.01.L'],
+  leftMiddleIntermediate: ['DEF-f_middle.02.L'],
+  leftMiddleDistal: ['DEF-f_middle.03.L'],
+  leftRingProximal: ['DEF-f_ring.01.L'],
+  leftRingIntermediate: ['DEF-f_ring.02.L'],
+  leftRingDistal: ['DEF-f_ring.03.L'],
+  leftLittleProximal: ['DEF-f_pinky.01.L'],
+  leftLittleIntermediate: ['DEF-f_pinky.02.L'],
+  leftLittleDistal: ['DEF-f_pinky.03.L'],
+
+  rightThumbMetacarpal: ['DEF-thumb.01.R'],
+  rightThumbProximal: ['DEF-thumb.02.R'],
+  rightThumbDistal: ['DEF-thumb.03.R'],
+  rightIndexProximal: ['DEF-f_index.01.R'],
+  rightIndexIntermediate: ['DEF-f_index.02.R'],
+  rightIndexDistal: ['DEF-f_index.03.R'],
+  rightMiddleProximal: ['DEF-f_middle.01.R'],
+  rightMiddleIntermediate: ['DEF-f_middle.02.R'],
+  rightMiddleDistal: ['DEF-f_middle.03.R'],
+  rightRingProximal: ['DEF-f_ring.01.R'],
+  rightRingIntermediate: ['DEF-f_ring.02.R'],
+  rightRingDistal: ['DEF-f_ring.03.R'],
+  rightLittleProximal: ['DEF-f_pinky.01.R'],
+  rightLittleIntermediate: ['DEF-f_pinky.02.R'],
+  rightLittleDistal: ['DEF-f_pinky.03.R'],
+
+  leftUpperLeg: ['DEF-thigh.L'],
+  leftLowerLeg: ['DEF-shin.L'],
+  leftFoot: ['DEF-foot.L'],
+  leftToes: ['DEF-toe.L'],
+  rightUpperLeg: ['DEF-thigh.R'],
+  rightLowerLeg: ['DEF-shin.R'],
+  rightFoot: ['DEF-foot.R'],
+  rightToes: ['DEF-toe.R'],
+});
+
+// MMD's translation carrier: hip sway/bob is baked onto センター so any stance
+// stays balanced over the capsule. Non-MMD rigs carry it on the hips bone.
+const MMD_CENTER_BONE = 'センター';
+
+function looseBoneName(name) {
+  return String(name || '').replace(/[^0-9A-Za-z_\-぀-ヿ一-鿿！-｠]/g, '');
+}
+
+export function normalizeMixamoBoneName(name) {
+  return String(name || '')
+    .replace(/^mixamorig:/, 'mixamorig')
+    .replace(/:/g, '');
+}
+
+function buildRig(type, entries, { hipCarrierName = null } = {}) {
+  // entries: [{ targetName, mixamoName }] in preference order per mixamo name
+  // (later entries override earlier ones in the inverse map).
+  const targetToMixamo = new Map();
+  const mixamoToTarget = new Map();
+  for (const { targetName, mixamoName } of entries) {
+    if (!targetToMixamo.has(targetName)) targetToMixamo.set(targetName, mixamoName);
+    mixamoToTarget.set(mixamoName, targetName);
+  }
+  if (targetToMixamo.size === 0) return null;
+
+  return {
+    type,
+    targetToMixamo,
+    mixamoToTarget,
+    hipCarrierName: hipCarrierName || mixamoToTarget.get(MIXAMO_BONE_BY_ROLE.hips) || null,
+  };
+}
+
+function resolveVrmRig(vrm) {
+  const humanoid = vrm?.humanoid;
+  if (!humanoid?.getRawBoneNode) return null;
+
+  const entries = [];
+  for (const [role, mixamoName] of Object.entries(MIXAMO_BONE_BY_ROLE)) {
+    const node = humanoid.getRawBoneNode(role);
+    if (node?.name) entries.push({ targetName: node.name, mixamoName });
+  }
+
+  return buildRig('vrm', entries);
+}
+
+function resolveMmdRig(boneNames) {
+  const entries = [];
+  for (const [role, targetNames] of Object.entries(MMD_BONES_BY_ROLE)) {
+    const mixamoName = MIXAMO_BONE_BY_ROLE[role];
+    for (const targetName of targetNames) {
+      if (boneNames.has(targetName)) entries.push({ targetName, mixamoName });
+    }
+  }
+
+  return buildRig('mmd', entries, {
+    hipCarrierName: boneNames.has(MMD_CENTER_BONE) ? MMD_CENTER_BONE : null,
+  });
+}
+
+function resolveRigifyRig(boneNames) {
+  const actualByLooseName = new Map();
+  for (const boneName of boneNames) actualByLooseName.set(looseBoneName(boneName), boneName);
+
+  const entries = [];
+  for (const [role, candidates] of Object.entries(RIGIFY_BONES_BY_ROLE)) {
+    const mixamoName = MIXAMO_BONE_BY_ROLE[role];
+    for (const candidate of candidates) {
+      const targetName = actualByLooseName.get(looseBoneName(candidate));
+      if (targetName) entries.push({ targetName, mixamoName });
+    }
+  }
+
+  return buildRig('rigify', entries);
+}
+
+function resolveMixamoNamedRig(boneNames) {
+  const mixamoNames = new Set(Object.values(MIXAMO_BONE_BY_ROLE));
+  const entries = [];
+  for (const boneName of boneNames) {
+    const normalized = normalizeMixamoBoneName(boneName);
+    if (mixamoNames.has(normalized)) entries.push({ targetName: boneName, mixamoName: normalized });
+  }
+
+  return buildRig('mixamo', entries);
+}
+
+// Resolves how a loaded character's bones map onto the canonical roles.
+// Returns { type, targetToMixamo, mixamoToTarget, hipCarrierName } or null
+// when no known convention matches (retargeting is impossible then).
+export function resolveCharacterRig(targetMesh, { vrm = null } = {}) {
+  if (vrm) {
+    const rig = resolveVrmRig(vrm);
+    if (rig) return rig;
+  }
+
+  const bones = targetMesh?.skeleton?.bones || [];
+  const boneNames = new Set(bones.map((bone) => bone.name));
+  if (boneNames.size === 0) return null;
+
+  const mmdRig = boneNames.has('下半身') || boneNames.has(MMD_CENTER_BONE)
+    ? resolveMmdRig(boneNames)
+    : null;
+  if (mmdRig) return mmdRig;
+
+  return resolveMixamoNamedRig(boneNames) || resolveRigifyRig(boneNames);
+}
+
+// Preferred target bone name for a canonical role (the skin-weighted variant
+// on rigs that split FK/deform bones), or null when the model lacks it.
+export function targetBoneNameForRole(rig, role) {
+  const mixamoName = MIXAMO_BONE_BY_ROLE[role];
+  return (mixamoName && rig?.mixamoToTarget.get(mixamoName)) || null;
+}
+
+// Every target bone playing a canonical role — MMD leg roles return both the
+// FK bone and its "D" deform twin, so procedural clips can drive all variants
+// the way the retarget bake does.
+export function targetBoneNamesForRole(rig, role) {
+  const mixamoName = MIXAMO_BONE_BY_ROLE[role];
+  if (!mixamoName || !rig) return [];
+
+  const names = [];
+  for (const [targetName, candidateMixamoName] of rig.targetToMixamo) {
+    if (candidateMixamoName === mixamoName) names.push(targetName);
+  }
+  return names;
+}