# Hair for the authored person

`objects/people/authored/hair.js` supplies six hairstyles: bald, short, swept,
curls, bob and ponytail. It constructs hair and optional head accessories only;
it does not generate or replace skin, body, face or skull geometry.

The revised short style has a cropped crown, a part, and thinner sides/nape.
Swept hair uses one continuous sculpted surface with directional crown relief.
Curls use overlapping closed multi-turn locks, tilted into three-dimensional
clumps and distributed over the source scalp with explicit hairline coverage.
The ponytail has a gathered scalp surface, one ridged bundle, a dark tie and a
slightly varied tapered end. The revised styles use a separate, low-contrast
fibre material; the bob's original geometry, material and texture are retained.

## Interface

```js
const hair = createAuthoredHair(api, rig, shapedData, {
  hairStyle: 'swept', hair: 0x493124, seed: 29, detail: 0,
  sunHat: false, sunglasses: false, hatColor: 0xc5ae80,
});
hair.setHair('ponytail');
hair.getStats();
hair.dispose();
```

`api.THREE` is injected. Source positions remain decimeters, Y-up and +Z-forward;
the rig supplies metre-space head/tail landmarks and rest matrices. Source scalp
triangles are queried through a private BVH. Every revised scalp vertex receives
an exact source-surface fit, including a small edge clearance. Geometry is
transformed into the head bone's rest frame and follows the actor's stature.

`detail:0` is the scene LOD; `detail:1` increases surface and curl resolution.
Numeric hairstyle indices retain the six-style order above. Color/accessory
changes use the AuthoredPerson appearance API; hair.js itself adds no color
setter. All textures are generated locally, and this module imports nothing.

Style switching retains its allocated materials/textures and disposes the old
hairstyle geometry. Invalid styles are rejected before replacement or initial
allocation. Construction errors clean up partial resources. Disposal is
idempotent. Bald skips scalp ray sampling until a non-bald style is requested.
Hair has no per-frame fitting or geometry update; it follows the head rigidly.

## Geometry budgets

Counts below include both optional accessories. Without accessories, subtract
1,152 triangles at LOD0 or 2,068 at LOD1. Bald without accessories draws no mesh.
The final curl density uses the separately approved 40k/70k hair budgets; the
other styles remain below their earlier approximate budgets.

| Style | LOD0 triangles | LOD1 triangles |
| --- | ---: | ---: |
| Bald | 1,152 | 2,068 |
| Short | 5,632 | 11,028 |
| Swept | 5,632 | 11,028 |
| Curls | 36,976 | 69,204 |
| Bob | 5,952 | 16,396 |
| Ponytail | 6,900 | 13,632 |

## Preservation and verification

`tests/authored-hair.test.mjs` passes 48 style/LOD/adult-child/sex combinations.
It checks finite geometry, the agreed triangle bounds, replacement, invalid
input, disposal and injected-construction cleanup. Indexed scalp fitting matches
unpruned traversal exactly. The representative short-style comparison visits
46,101 triangles through the BVH versus 26,429,760 with full traversal. These are
operation counts, not a frame-time or construction-time benchmark.

`tests/authored-hair-preservation.test.mjs` compares bald and bob against the
unchanged release 0.2.2 hair module. All 16 adult/child male/female/LOD cases match
exactly, including accessories. Fingerprints include rendered geometry arrays
and indices, transforms, physical material parameters and texture pixels/sampling.
They exclude generated UUIDs and module query tags. This protects the accepted
bald/bob appearance rather than merely retaining the style names.

The [hair fixture](../tests/authored-hair.html) provides front, profile,
three-quarter and back views, dark/light colors, both LODs, source variants,
accessories and explicit lifecycle checks. Ponytail framing includes the whole
tip. Final groom11 views showed a coherent dense curly silhouette, continuous
short/swept hair surfaces, and a tied ponytail bundle. Styles remain deliberately
stylized; close magnification still shows modeled locks rather than individual
strands. Hair does not simulate strand dynamics, cloth-like motion or exact
hair-light scattering.

Evidence:

- Final Node checks
- Exact bald/bob preservation
- Final browser checks and visual observations

Final browser lifecycle checks passed all four groups: both LODs across six
styles, replacement and invalid-input behavior, source-head age/sex variants,
and absence of runtime/shader errors. Each LOD disposed all 16 tracked visible
resources exactly once. The browser console contained no warnings or errors,
and the temporary review tab was closed. The source was subsequently stamped
`v023` by release integration; this changes import query tags only.