feat(avatar): every hair piece colored and built-in headpieces (0.9.0)

[DoodleBears]

Summary

This is the rendering side of BotHarness/DeepSeekBot#1217, released as @botharness/pixel-avatar 0.9.0. It adds asset version 4.

• Per-piece hair colors. bangsColor, backHairColor and strandColor join leftSideHairColor / rightSideHairColor, and each defaults to hairColor. A piece is recolored only on the pixels it owns: visible back-hair pixels, or that piece's live hair pixels, plus the outline next to them. Recipes that set only side colors keep the previous algorithm byte for byte.
• Single strand. strand (ahoge, curl, double) is split out of today's ahoge into its own piece. It is shaded like hair and hidden wherever the hair is hidden (hiddenChoices lists strand).
• Built-in headpieces. The headpiece slot holds catears, bunnyears, horseears, horns, halo or the new wings, or a Custom Part, worn together with any accessory.
  • The row that meets the head goes behind the hair and the rest in front. The halo's back arc is behind the head.
  • When the head turns, the far side of a pair is hidden, following the pointed-ear rule.
• Migration only on edit.
  • withPieces(recipe) raises a recipe to version 4 and moves an accessory that is now a headpiece into the empty headpiece slot. It runs only when the Human edits. Saved recipes keep the old accessory and render byte-identically.
  • withBuiltInHeadpiece / builtInHeadpiece set and read the built-in headpiece.
  • withCustomPart keeps a version 4 recipe at version 4. wornPart ignores a built-in headpiece.

Older consumers reject version 4 through isPixelAvatarRecipe, so they can show a saved snapshot.

Verification

• pnpm verify passed: format, lint, typecheck, and 99 tests.
• Existing golden fixtures (botharness-golden, species*, custom-part) are unchanged.
• The new pieces.test.ts covers:
  • validation by version
  • migration only through withPieces
  • a headpiece worn with an accessory
  • the base behind the hair, and the far side hidden at ±30°
  • each piece color confined to its piece
  • new pieces-golden.json entries for every headpiece and strand (front, turns and mouth layers), plus per-piece colors

Refs: BotHarness/DeepSeekBot#1217

🤖 Generated with Claude Code

https://claude.ai/code/session_01MozvQ2eMvqX1MzSqm9G2o8

---

Generated by Claude Code

[coderabbitai]

Note

Currently processing new changes in this PR. This may take a few minutes, please wait...

⚙️ Run configuration

• Configuration used: defaults
• Review profile: CHILL
• Plan: Advanced
• Run ID: 529d5bcc-4a96-4d13-beca-fb3b8e4d8d10

📥 Commits

Reviewing files that changed from the base of the PR and between 4a5eea3 and c961f22.

📒 Files selected for processing (8)

• CHANGELOG.md
• packages/avatar/README.md
• packages/avatar/package.json
• packages/avatar/src/figure.ts
• packages/avatar/src/index.ts
• packages/avatar/src/recipe.ts
• packages/avatar/test/fixtures/pieces-golden.json
• packages/avatar/test/pieces.test.ts

 ________________________________________________________________________________________________________________________
< Don't assume it - prove it. Prove your assumptions in the actual environment - with real data and boundary conditions. >
 ------------------------------------------------------------------------------------------------------------------------
  \
   \   \
        \ /\
        ( )
      .( o ).

✨ Finishing Touches

📝 Generate docstrings

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[DoodleBears]

@coderabbitai review

---

Generated by Claude Code

[coderabbitai]

⚠️ Action not completed

Review rate limited.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[DoodleBears]

CodeRabbit is rate-limited (one review per hour), so an independent review agent checked this diff instead.

Confirmed: v1–v3 validate and render unchanged, and older consumers reject v4. It found no holes in the v4 key accounting or in canonicalRecipe.

Fixed in c961f22, with regression tests:

• Piece-color path: v4 now always uses the owner-based piece recolor, so a piece color equal to the hair color no longer changes how the side colors render.
• Pixels a piece owns: these now exclude the crown, drawn-over, eye and glasses pixels. Hair-colored ear tips no longer take bangsColor, and the eye color no longer appears in the head layer when turned.
• Flower petals: they ignore backHairColor.
• withPieces is idempotent on v4: an accessory the Human picks no longer moves into the headpiece slot on the next edit.
• Strand:
  • it is hidden when there are no bangs;
  • it never covers bangs or side hair;
  • it is left out of the hair-shading bounds, so it only changes its own pixels.
• Recolor speed: each piece-color variant is rendered once per color.

pieces-golden.json is regenerated, and every other golden fixture is unchanged. pnpm verify passes: 102 tests.

---

Generated by Claude Code