@bitmagic/cli 0.1.66-dev.1 → 0.1.66-dev.10

package/assets/character-skin-authoring/references/exporters.md

@@ -0,0 +1,134 @@
+# Installed character exporters
+
+The skill now includes the tested offline skin, optical-eye and rig-assembly helpers.
+Run `scripts/character_build.py` with an explicit `--workspace`; character assets live
+outside the skill so refreshes do not erase them. Python needs NumPy, Pillow and SciPy.
+Exact visibility recovery also needs Blender on PATH or `BITMAGIC_BLENDER`. These tools
+perform deterministic assembly of the agent's reviewed inputs, never semantic recognition.
+
+The retained workspace convention is:
+
+```text
+characters/ID/high/v1/
+  source/hy31pro.glb                    immutable source (name is a convention)
+  output/viewer-profile.json            {"height": physical height in metres}
+  materials/body-detail-profile.json    optional designed regional creases
+  materials/surface-patch-profile.json  optional licensed regional patches
+  materials/repair-profile.json        optional separately reviewed source defects
+  materials/v2/                        registered face inputs and intermediate maps
+  materials/v4/                        mixed-surface GLB and report
+  eyes/v1/                             independent fitted optical-eye revision
+  output/character.glb                  optional existing bound body mesh
+  rig-report.json                      optional validated rig provenance
+  runtime/v1/                          combined surface/eye/body variants
+highquality/materials/faces/ID.json      character-specific landmark registration
+highquality/references/                 licensed immutable exemplar files
+```
+
+Evidence/masks/eye profiles can be anywhere supplied explicitly. Relative command paths
+are workspace-relative. Keep their source/image hashes and projection receipts intact.
+Paths inside authored JSON retain their documented conventions; relocating evidence may
+require updating its source path without changing source bytes or camera contracts.
+
+## Commands
+
+Use [the profile schemas](profiles.md) for independently authored landmarks, exclusions,
+scale and optical dimensions. After preparing the facial profile:
+
+```sh
+python scripts/character_build.py --workspace /path/to/assets --id CHARACTER --stage face
+```
+
+The current face adapter uses the Lee Perry-Smith reference: `LeePerrySmith.glb`,
+`Infinite-Level_02_Disp_NoSmoothUV-4096.jpg` and `Map-COL.jpg` in
+`highquality/references/lee-perry-smith/`. Obtain the licensed originals explicitly and
+retain CC BY 3.0 attribution; the skill does not download them. The adapter writes its
+modification notice and hashes. Its calibrated relief amplitude is an authoring estimate,
+not measured capture scale. It does not transfer donor face geometry.
+
+After reviewing the dense semantic bake:
+
+```sh
+python scripts/character_build.py --workspace /path/to/assets --id CHARACTER \
+  --evidence evidence/CHARACTER --masks masks/CHARACTER
+```
+
+This preserves source geometry and writes mixed skin/hair/lip/nail materials plus the
+registered detail binding. The adapter currently requires one source mesh primitive,
+embedded textures, normals and non-overlapping anatomical UV ownership. It fails unsupported
+layouts rather than flattening them automatically. Multiple-material adapters remain work.
+`--check` validates required input presence without building; full geometry/hash contracts
+are checked by the exporters themselves. Neither check is visual acceptance.
+
+For eyes, first follow [the eye fitting workflow](eyes.md), then:
+
+```sh
+python scripts/character_build.py --workspace /path/to/assets --id CHARACTER \
+  --stage eyes --eyes-profile profiles/CHARACTER-eyes.json
+```
+
+The current optical texture adapter uses `blue_eye.png` and `LICENSE.md` from the CC0
+MakeHuman eye reference in `highquality/references/makehuman-eyes/`. Its source registration
+is specific to that donor atlas. Character opening contours, dimensions and fitting remain
+individually authored. Existing skinned cut edges/full facial rigs are not supported by
+this prototype; preserve them and use a suitable topology adapter.
+
+For a previously validated body binding:
+
+```sh
+python scripts/character_build.py --workspace /path/to/assets --id CHARACTER \
+  --stage assemble --input eyes/v1/character.glb --variant eyes
+```
+
+The assembler consumes the existing bound mesh and `rig-report.json`, verifies the output
+hash and negligible geometry displacement, then retains materials and eye layers while
+adding the body skin. It does not invent bones, fit a skeleton or simulate cloth. The
+playground's shared Blender rig fitting remains separate from this installed exporter.
+Use the project's existing rigging workflow to produce compatible inputs.
+
+A surfaces run can also take `--eyes-profile` and `--assemble` to execute the same stages
+in order. Each stage stops on failure and leaves a review candidate, never `viewerReady`.
+Review every changed region and both rendering backends before selecting a local preview.
+
+## Detail-binding seams
+
+Unused UV texels are not reliable vertex visibility samples at split seams. The exporter
+uses exact source-geometry rays for those vertices, then samples the same reviewed image
+annotations. It leaves occupied unknown/conflicted samples untouched and never changes
+fragment coverage. Geometric caches include source, cameras, positions, normals and
+algorithm version; annotation labels are re-read. Adjacent zero-weight triangle corners
+still receive coherent patch coordinates so interpolation cannot sample another atlas
+region. If an artifact persists, inspect coverage, geometry normals and source color
+separately before changing skin strength.
+
+Eye rest fitting retains `_BIND_SOURCE_POSITION` before moving source eyelid vertices.
+The assembly exporter consumes this authoring attribute for weight correspondence and
+removes it from the runtime attributes. Original vertices use their exact bound match;
+clipped vertices use a verified rigid-head field or closest-triangle barycentric weights.
+Points outside the bound surface tolerance fail rather than inheriting a nearby limb.
+The rendered fitted positions and morphs retain their shape during this transfer.
+
+Local preview selection now copies the exact reviewed GLB, render receipt, visual
+verdict and inspected images into a content-addressed `.previews` snapshot beside
+the candidate. An atomic `*.selected.json` pointer names that snapshot. Rebuilding
+the candidate or its review images does not mutate the selected preview. A failed
+review leaves the previous pointer intact. Engine consumers should resolve the
+selected snapshot for ordinary preview and use explicit candidate paths for QA.
+These snapshots remain local previews with recorded issues, not whole-character
+acceptance or a publication step.
+
+An explicitly authored `materials/geometry-repair-profile.json` can correct a local
+source defect during the mixed surface build. Select the defect center and clean
+support annulus from the exact evidence view; supply a bounded depth interval and
+maximum displacement. The quadratic patch follows surrounding curvature and feathers
+into unchanged geometry. Never infer that a painted marking should be removed:
+record the user's intent and preserve the source. Optional clean skin color donors
+and a painted dot replace the source's baked bump shading. Evidence UVs use Blender's
+bottom-left convention; decoded texture rows use top-left. The exporter converts
+this explicitly and pads only adjacent unused UV gutters.
+
+The repair keeps topology, UVs and `_BIND_SOURCE_POSITION`; subsequent eye fitting
+must preserve that attribute, and assembly uses it for the original rig weights.
+Rebuild both eyes and runtime assemblies after a repair. Inspect front and oblique
+views and both renderer backends before selecting the new snapshots. A displacement
+receipt alone does not prove that old normal-map or pigment shading is gone.

package/assets/character-skin-authoring/references/eyes.md

@@ -0,0 +1,215 @@
+# Optical eyes after reviewed ocular exclusions
+
+This is an independent, opt-in asset revision. A working eye pilot does not certify the
+skin maps or body rig. Preserve the source, material revision and existing animation.
+The current adapter supports a single, unskinned source mesh and two eyes; it refuses
+existing facial morphs and skinned cut edges. Do not silently flatten a rig to bypass it.
+
+## Availability
+
+The [installed exporter runner](exporters.md) now includes the optical-eye builder and
+its dependencies. Supply an explicit workspace and independently authored fit; exemplar
+textures remain external licensed inputs. The playground browser review harness is still
+separate. Confirm the installed engine supports the optical-eye contract before adoption.
+
+## Vision fit
+
+Prepare exact close front and both oblique source views with `skin_views.py prepare`.
+Use enough pixels to distinguish the iris, visible eye opening, inner corner and lids.
+Record each iris center/radius, an ordered convex opening contour and the lower contour
+indices on the original image. Record anatomical left/right explicitly; image orientation
+is not a side label. Do not reuse another character's target pixels or eye centers.
+
+Write a profile following `highquality/materials/eyes/b3843.json`. Source and evidence
+hashes are mandatory. Globe radius, corneal bulge, pupil ratio, pigment and depth offset
+are authored estimates in metres. Verify those estimates against side views and physical
+character height. An opening wider than the globe requires corner tissue; moving the
+eyeball forward until it fills the hole is not a valid substitute.
+
+Run `python highquality/src/eye_assets.py --profile PROFILE`. The builder ray-fits each
+eye against source geometry and writes `characters/ID/high/v1/eyes/v1/`. It clips openings
+at the reviewed contour with barycentric attribute interpolation. It creates separate
+sclera, recessed iris, pupil, cornea, orbital mucosa, lid contact and tear meniscus surfaces.
+It adds actual eyelid position/normal morphs and gaze/blink clips. Inspect the closed lids:
+the builder's deformation is a starting fit, not an anatomically validated universal rig.
+
+## Shared rendering and control contract
+
+- Eye nodes have `extras.characterEye=true` and `forwardAxis=+Z`; local +Y is up.
+- `CharacterEyeController` applies local yaw/pitch relative to the authored rest fit and
+  drives `eyeBlinkLeft`/`eyeBlinkRight`. It never scales the eyeballs or changes body bones.
+  Give these channels one owner: either this controller or an AnimationMixer clip.
+- Corneal transmission/IOR use standard glTF physical-material extensions on both backends.
+  Source ocular textures are not a replacement for a clear cornea and recessed iris.
+- The MakeHuman eye source is CC0; retain its license, immutable source hash and adaptation
+  record. The current texture uses reviewed planar atlas registration and authored pigment.
+  It is not a captured iris of the generated character and has finite source resolution.
+
+## Review gate
+
+Use the viewer's **Optical eyes · fit preview** option; toggling must preserve the camera.
+Inspect front, both three-quarter views and profile; then gaze in both directions, half
+blink, independent winks and full closure. Play the exported clip as well as testing sliders.
+Check upper-lid contact, inner/outer corners, tear edge, iris parallax, refraction, texture
+orientation, eyeball penetration and closed-lid normals. Check WebGL and WebGPU.
+
+`highquality/tests/eye_fit_smoke.mjs` exercises the local viewer and writes screenshots.
+Read those images: zero renderer errors does not establish good optical fit. Keep
+`optical_fit_review_required` until visual checks pass. Next production work includes
+regional scleral scattering, richer iris relief, fitting across characters, refined lid shape and composition with a complete facial/body rig. Do not call this MetaHuman
+parity based on the presence of corneal transmission alone.
+
+## Separate source defects from optical defects
+
+If a closed eyelid shows bright fragments, hide all generated optical layers temporarily.
+If the fragments remain, inspect the original unlit face and material-region evidence.
+Do not keep moving the eyeball to compensate for source albedo, normals or incorrect lid
+labels. A bright painted streak and a geometric hole require different corrections.
+
+A narrowly authored source-albedo defect can use a separate UV selection and
+`texture_repair.py`: harmonic interpolation in linear light changes only selected texels,
+with outside pixels byte-identical. Keep that selection separate from anatomical labels,
+archive its projection evidence and inspect the repair. It does not reconstruct eyelid
+geometry, lashes or missing detail. The djinn trial still requires eyelid surface work.
+Eye profiles explicitly choose `skinRevision` so a later skin build cannot silently change
+an already-reviewed eye fit. The current adapter accepts v2/v3/v4 and keeps output hashes.
+
+
+Orbital backing must remain behind the recessed iris and pupil at every blink and gaze angle. Do not reuse the corneal-envelope eyelid deformation for backing tissue: even a small inset can still place it ahead of the iris. Validate partial blinks and isolate optical layers when diagnosing occlusion. Current prototype keeps its dense backing head-fixed. Continue its recessed depth envelope beyond the globe at the canthi too; retaining source-surface depth outside the globe can leave a visible triangle ahead of the closing lid.
+
+
+Before generating blink targets, inspect the neutral lid/globe intersection. The playground
+can opt into `conformOpenLids` to push intersecting tissue outside the explicitly fitted
+globe. This is geometry fitting around authored landmarks, not automatic anatomical
+recognition. Do not pull the surrounding orbital skin inward merely to follow a sphere;
+keep a smooth support band and stationary canthi. Inspect partial and full closure anew.
+
+
+The playground now exports gaze-follow lid targets as well as blink targets. The engine
+uses `eyeLidLookUpLeft/Right` and `eyeLidLookDownLeft/Right` at ±0.35 radians pitch;
+full closure suppresses gaze follow independently for each eye. Inspect both directions,
+partial blinks and winks. A controller test validates channel ownership, not the surface fit.
+
+
+## Reconstructed lid bands (experimental playground option)
+
+When the source eye margin is damaged, explicitly author a paired `outerLidPx` contour
+around the existing `openingPx`. The outer contour must contain the aperture. The builder
+ray-samples the original boundary and reconstructs only the intervening strip, preserving
+its outer position/normal and following the fitted optical envelope at its inner edge.
+This is designed topology and needs neutral, oblique, partial and full-blink inspection.
+It does not recover missing anatomy automatically.
+
+Source albedo can contain painted eye shadows or highlights. Stretching those into a
+closed lid is a source-color defect. Optional `lidSkinSamplesPx` records at least three
+explicitly reviewed clean skin donors in the same exact evidence view. Their linear colors
+supply invented inner-lid pigment, blended to the sampled outer edge. Inspect the join;
+never label this as scan-derived detail. The djinn trial still has outer-transition and
+corner limitations. Keep this feature opt-in until its fit is acceptable.
+
+For geometry diagnostics, hide cornea, sclera, iris, pupil, contact, tear and lashes, but
+retain reconstructed `eyelid-skin`. Hiding that skin too produces an intentional hole and
+invalidates the closure diagnostic. Inspect unlit albedo separately from geometry normals.
+The playground regression now renders front, both obliques, profile, both yaw directions, and an oblique full blink. Eye review receipts must identify the exact selected output hash, including assembled
+variants; a previous screenshot cannot validate an output rebuilt afterward.
+
+## Authored brow strands (playground option)
+
+A painted brow can retain its color but still lack visible strand depth. The optional
+`browGroom` on each fitted eye accepts an independently reviewed `polygonPx`, at least
+two `combGuidesPx` start/end pairs in that same exact view, `strandCount`, `seed`,
+`radiusM`, `lengthRangeM` and `colorLinear`. The local `brow_groom.py` ray-projects roots
+onto the nearest visible source surface and projects the authored comb directions into
+its tangent plane. It constructs tapered short fibers; it performs no hair recognition.
+Do not classify a dark supraorbital shadow as a brow without inspecting the source.
+
+Record these as designed hairs, inspect both sides and profile, and preserve the underlying
+source. The strands attach to the head; they do not yet follow expressive brow morphs.
+Fine strands can alias without temporal antialiasing or a filtered hair LOD. This prototype
+is not a replacement for a production groom/simulation system. The b5359 trial uses a
+separate medial-corner tissue surface too; review its fit during closure independently.
+A reconstructed lid-band trial on b5359 was rejected because its pale angular transition
+looked worse. Do not assume that enabling every optional reconstruction improves a fit.
+
+## Corner lining
+
+A deep backing disk can leave a dark gap between the globe and the medial lid opening.
+The optional `canthusWalls` profile lists explicit upper/corner/lower `contourIndices`
+and a designed `colorLinear`. The narrow lining joins those reviewed source-lid points
+to a recessed globe rim. Only the lid edge follows blink/gaze targets; the globe edge stays
+fixed, outside the iris envelope over the reviewed ±0.35 radian gaze range. Do not apply
+the corneal closure deformation to the whole socket. Inspect partial closure and both
+obliques after fitting; source corners and dimensions differ between characters.
+This is designed lining, not transferred scan anatomy. The CC0 MakeHuman topology was
+visually inspected as an anatomical reference; no donor mesh is embedded by this option.
+When a reconstructed lid band replaces the source margin, set its lining's
+`contactMethod: "reconstructed-lid-v1"` to use the same aperture depth calculation.
+Otherwise the lining can follow a removed source surface and protrude below the new
+lid. This joins the support consistently; it does not supply a realistic caruncle or
+make an oversized authored corner anatomical. Inspect those separately.
+
+If a source has no separately classified ocular material, inspect the exact eye views
+and explicitly set `openingAuthority: "reviewed-contours"`. The adapter then uses the
+authored contours to remove the source surface. It still verifies source/image hashes
+and rejects a cut that removes no interior triangles. Never infer the opening from
+skin color or copy another character's contour; narrow hooded lids need their own fit.
+
+Eyelid normal targets transport the imported shading normals with the shortest rotation
+between the rest and deformed geometric normals. This preserves the imported normal's
+angle to the surface while the lid moves. The neutral mesh retains its authored normals;
+unused vertices keep their original normals. Inspect both the neutral and fully closed
+pose after changing a fit, since valid normals cannot correct a poor anatomical shape.
+
+Review each eye at eye-sized framing as well as face-sized framing. Inspect a neutral
+eye and an oblique fully closed eye separately. A smooth globe can hide a polygonal
+opening at face scale; a successful blink protocol does not establish anatomical quality.
+In the playground, `CLOSE_EYES=1` adds these views and `REVIEW_SUFFIX` keeps experiments
+separate. Use `SELECTED_EYES=1` to compare with the reviewed snapshot, rather than the
+latest candidate. Explicitly unset `BACKEND` for a complete two-backend review.
+
+An optional `contourRefinement` with `method: "convex-quadratic-v1"` and
+`samplesPerLandmark: 8` rounds the segments between reviewed landmarks, staying inside
+the original convex opening and preserving the two shared upper/lower eye corners.
+For a reconstructed band, set `outerBoundary: "preserve-authored"` to retain every
+segment of the reviewed outer source cut. Rounding that cut inward can leave pieces of
+the damaged original eye margin behind. Paired outer points are then subdivided without
+changing the cut; only the visible inner aperture is rounded. The older `rounded` outer
+mode remains available for reproducibility, and requires its own review.
+Indexed tissue chains are refined together. The fitted output
+records the original points and maximum inset; it is safe to rebuild without applying
+the refinement twice. This is a geometric interpolation of the agent's landmarks, not
+an inferred anatomical contour. Inspect the result before selecting it: rounding alone
+does not fix tissue depth, color, contact or deformation.
+
+`outerEdgeSampling: "source-intersections-v1"` on an eye adds the original triangle-edge
+crossings to the paired lid-band sampling. Its outer rim then follows the piecewise
+source surface rather than bridging over small source ridges between uniform samples.
+It preserves the authored cut and adds no anatomical selection. Keep checking the
+closed pose: normal continuity and an actual eyelid fold need their own review.
+
+If a designed `caruncle` is hidden behind an authored lining, its optional
+`support: "corner-lining-v1"` positions it on the corresponding lining depth. It must
+reference a corner in exactly one `canthusWalls` chain. The helper rejects centers
+outside that lining's supported interval and rejects a tissue footprint that intersects
+the iris envelope over the reviewed gaze range. Medial tissue may overlap peripheral
+sclera; forcing it behind the entire sphere would hide it again and distort its shape.
+The dimensions, placement and color remain explicit authored choices. This construction
+is a prototype anatomical insert, not a scanned tear duct or a proof of eye realism.
+
+For a reconstructed band that produces radial fan creases, `fairLidDepth: true`
+uses harmonic depth fairing across the whole projected strip mesh. Both authored
+rims remain fixed; projected columns interpolate the paired contours directly,
+preventing independent Hermite tangents from bunching them at the canthi. The
+result is refitted outside the optical envelope before computing normals and
+blink targets. This is geometry repair, not a wrinkle texture filter. It does not
+resolve an incorrect boundary shape or source pigment automatically. Inspect both
+corners, neutral and full closure, obliques and gaze before selecting the asset.
+
+A front silhouette alone cannot establish corner depth. `cornerDepths` optionally
+records explicitly reviewed `pixel`, `depthM` (relative to the globe center, positive
+forward), and `radiusM` for a corner. Local source support fades toward that depth;
+the reconstructed lid and lining share a smooth tangent continuation from 85% of
+the globe radius toward the corner. The curve stays outside the globe. Its angular
+influence has a full-strength central half-width and smooth outer falloff. Inspect
+both close lateral views (`SIDE_EYES=1`) and closure. Never assign these corrections
+across characters without independently reviewing their actual depth and silhouette.

package/assets/character-skin-authoring/references/materials.md

@@ -0,0 +1,115 @@
+# Applying reviewed skin maps
+
+The projection helper creates evidence and labels. It does not generate a body rig or
+reconstruct missing anatomical detail. Keep source models immutable and store character
+work outside this shipped skill, because GDK upgrades refresh the skill files.
+
+## Prepare the material revision
+
+Use the project's existing character loader and material pipeline. In the Bitmagic engine,
+read `agent-docs/character-surfaces.md` and use `RealisticCharacter.create(root, options)`
+when that API is available. Do not assume a published engine version already contains it:
+inspect the installed engine declarations first. Preserve working standard glTF materials
+when the specialized adapter is unavailable and report that rendering integration remains.
+Do not silently upgrade the engine or edit unrelated existing character types.
+
+Author maps from licensed skin exemplars or the creator's own assets. Register the exemplar
+to this character's reviewed facial landmarks and physical scale; never reuse another
+character's target coordinates. Keep donor identity, tattoos, beard and complexion out of
+relief transfer. Use anatomically appropriate detail for hands, palms, feet and body areas.
+A generic repeated face tile is a preview fallback, not a finished regional detail library.
+Retain attribution, source hashes, transformations and the authored physical amplitude.
+For visible regional creases, the agent may author curves in exact evidence-image
+coordinates and bake physically scaled relief onto independently labelled visible skin.
+Record these as designed enhancements, not captured measurements. Keep glabrous palm
+detail separate from facial follicles, and inspect the result at hand-sized framing.
+The [regional detail helpers](regional-detail.md) evaluate authored crease curves and
+licensed roughness patches without making anatomical decisions.
+
+The source UV label map is top-left image data. Convert to the exporter/runtime's UV
+convention exactly once. Bake source albedo as sRGB; roughness, metalness, masks, normals
+and packed detail as linear data. Confirm with a known neutral patch and a source-material
+comparison under identical lighting. A global saturation adjustment cannot diagnose a
+color-space conversion bug.
+
+## Specialized engine contract
+
+Explicit material extras opt into the character adapter. Untagged materials remain native.
+For mixed skin/clothing primitives, `skinSurfaceBlend: true` uses atlas alpha as per-pixel
+skin coverage. The packed linear RGBA atlas stores signed height around .5, roughness,
+chromatic residual around .5 and coverage. `skinAtlasHeightRangeM` sets physical height.
+`skinAtlasTexture` and optional `skinExpressionTexture` refer to embedded glTF texture
+indices. `_FACE_UV` supplies atlas coordinates; `_FACE_WEIGHT` supplies coverage weighting.
+`_SCATTER` is a fallback transmission attribute. Read the installed engine contract for
+exact current fields rather than guessing their implementation.
+
+Check physical texel density before increasing relief strength: a 4K full-body texture
+can still sample the face at roughly half a millimetre per texel. In engines supporting
+`skinFacialAtlasTexture`, retain the registered facial detail separately from body coverage.
+The `skinFacialAtlasLayout: "detail-expression-halves-v1"` contract packs facial detail in
+the left half and facial expression in the right half of one linear texture; its detail
+height uses the same physical range as the body atlas. `_FACIAL_DETAIL` packs independently registered UV in XY and geometry-verified projection
+visibility in Z, retaining the WebGPU vertex-buffer budget on skinned meshes.
+This layer replaces facial detail baked into the body atlas, not skin coverage. Body
+expression must be neutral for this layout. Packing replaces its shader sampler rather
+than adding samplers beyond WebGL's budget. Compare the actual backends, preserve physical
+filter widths when changing resolution, and check that coverage remains byte-identical.
+
+The same packed texture can reserve additional rows for independently reviewed body
+patches while keeping the original face texels. `skinFacialAtlasRegion` then records the
+face rectangle within the detail half, and each vertex's `_FACIAL_DETAIL` coordinates
+already address its assigned region. Reconstructed eyelids must use that rectangle too.
+Keep patch alpha as detail blending only: the body atlas still owns skin coverage. This
+retains the sampler and vertex-buffer budget instead of adding one material per patch.
+
+Resolve embedded textures through the engine GLTF loader parser. Keep the scene diffusion
+and transmission passes and the body AnimationMixer caller-owned. The adapter exposes
+independent eye controls, preserves source materials on disposal, and does not create a
+missing skeleton. Keep specular reflection outside diffuse scattering. A blurred beauty
+image is not subsurface diffusion. Author channel diffusion ratios in asset metadata;
+never infer skin type from character ID, race, height or RGB thresholds.
+
+At a known skin/hair/lip boundary, material weights must sum to one; independent fades
+expose the native response as a glossy line. Fill filtering gutters in UNUSED UV atlas
+space from the nearest occupied texel, but never grow labels into unseen surface regions.
+Check the actual zero-coverage and full-coverage endpoints against the native and skin
+materials. Preserve armor, cloth, hair and optical surfaces during skin changes.
+
+## Source defects and acceptance
+
+Separate source pigment spill, baked lighting, UV seams, normal errors, geometric creases
+and missing coverage. Inspect unlit source, material labels and shaded results independently.
+Color repair needs a separate authored selection. When a defect crosses UV islands, use
+reviewed clean swatches in surface space; atlas-space harmonic fill may retain contaminated
+island boundaries. A color repair cannot reconstruct missing hand geometry or eyelids.
+
+Review all exposed regions and fixed-camera detail on both supported rendering backends.
+Store region verdicts, current output hashes and review images beside the character. A
+successful export or low conflict count is not visual acceptance. Keep incomplete regions
+explicit and continue gathering views or authoring detail rather than calling a face-only
+pass a complete character.
+
+When a project uses the `viewerReady` metadata convention, `scripts/select_preview.py`
+can validate the mechanical handoff. Supply `--asset`, `--metadata`, `--render-report`
+and `--visual-verdict`. The render report is an array containing both `webgl` and
+`webgpu` receipts with matching `actual`, empty `errors`, and the current `outputSha256`.
+For combined runtime reports use `--variant eyes` or `--variant surfaces` to read
+`assetHashes` instead. The agent-written verdict must identify the same output hash,
+use `status: "local_preview_with_known_issues"` and `wholeCharacterAccepted: false`,
+and list actually inspected images as `visuallyInspected: [{file, sha256}]`, relative
+to that verdict. The helper checks current image bytes before selecting the preview.
+It does not inspect those images, publish an asset, or declare the character finished.
+
+Use the [installed exporters](exporters.md) to build these authored inputs into GLBs.
+[The playground example](playground.md) records the tested asset layout and review harness;
+its browser review commands still require that separate checkout.
+
+
+### Regional height composition
+
+Independently registered body patches may declare `skinRegionalAtlasHeightMode: "additive-v1"` with `skinFacialAtlasRegion: [0, 0, 1, faceEndV]`, where `0 < faceEndV < 1`. The face occupies the atlas's top rows; body patches occupy rows below it. In those body rows, patch relief adds to the underlying body height rather than replacing authored palm creases or other regional folds. Facial relief retains replacement behavior, and body coverage is unchanged. Roughness still blends to the authored patch value. Assets without this explicit mode retain their previous replacement behavior.
+
+This uses the existing packed texture and VEC3 binding on WebGL and WebGPU; it adds no sampler or vertex attribute. Do not compensate for erased crease layers by increasing microdetail strength. Check the composition with the patch enabled and disabled at the same camera, and retain the physical amplitude of each layer.
+
+
+Regional bindings need coherent UV coordinates at every corner of a triangle touching the patch, including corners with zero detail weight. A zero-weight corner still participates in UV interpolation. Leaving its old facial coordinates in place can make the triangle sample unrelated atlas texels. Extend coordinate support by adjacent triangles while keeping their detail weight zero and semantic coverage unchanged; reject overlapping active patch bindings or split the geometry explicitly.

package/assets/character-skin-authoring/references/playground.md

@@ -0,0 +1,78 @@
+# Applying the reviewed maps in the character-forger playground
+
+The maintained helpers are in `highquality/src/` at the character-forger repository root.
+They are not standalone engine binaries. Use the project's Python with NumPy, Pillow and
+SciPy, and Blender for projection. Keep this adapter's single mesh/primitive limitation
+explicit; do not silently flatten a rigged or instanced scene to make it pass.
+
+1. Prepare and annotate exact views; dense-bake with `--surface-data --triangle-labels`.
+2. Author `highquality/materials/faces/ID.json` from this character's face view. The target
+   bounds describe normalized body X/Z in Blender world space. Pixel dimensions belong to
+   their respective source and target views. Reusing donor correspondence is valid; reusing
+   another character's target landmarks is not. Hair surrounding a face is an enclosure,
+   not one filled exclusion polygon covering the face.
+3. Run `python highquality/src/build_face_detail.py --id ID`. It registers band-limited
+   licensed scan relief and emits attribution. The amplitude is an authoring estimate,
+   not measured displacement. Empty coverage is an error requiring a profile correction.
+4. Run `python highquality/src/vision_materials.py --id ID --masks MASK_REVISION --evidence EVIDENCE`.
+   The adapter writes `characters/ID/high/v1/materials/v2/character.glb` and a report. It
+   preserves source geometry/buffer bytes, nodes, existing skin data and animation data.
+   This does not add a missing body rig. Inputs are currently the immutable HY source.
+5. Rebuild the viewer with `node hero/viewer/build.mjs`. Run
+   `CHARACTER_ID=ID node highquality/tests/vision_skin_smoke.mjs` on both renderers, then
+   inspect the screenshots. Tests check loading and camera stability, not anatomical truth.
+
+The detail atlas uses source UVs and includes all explicitly observed skin. Face detail is
+registered from a licensed scan; other follicular skin currently uses reduced scan relief.
+Palms/soles use authored nonfollicular ridges. This is not a library of captured regional
+hand/foot exemplars. Source geometry retains its existing larger creases. The report keeps
+unresolved labels and texture defects visible.
+
+Engine contract: explicitly tagged skin/hair materials opt into `createCharacterSurfaceMaterial`.
+RGBA detail stores signed height around .5, roughness, chromatic residual and coverage.
+`_FACE_UV` supplies coordinates, `_FACE_WEIGHT` coverage, `_SCATTER` the fallback transmission
+attribute. Atlas data is linear; albedo is sRGB. The helper excludes defective HY normals on
+labelled skin, keeps native materials elsewhere, and performs geometry-corresponding skin
+UV seam colour equalization. It cannot remove arbitrary baked lighting or interior texture
+stitches merely by correcting normal maps.
+
+Material reports remain `shaded_review_required` until actual exposed regions and rendered
+maps have been reviewed. Do not convert low conflict counts into a whole-character quality
+claim. The b3658 scalp albedo stitch, ambiguous nails and b3843 palm colour spill are examples
+of asset defects that require separate correction.
+
+## Per-pixel material boundaries
+
+After the v2 evidence build, `python highquality/src/vision_blend_materials.py --id ID`
+creates an opt-in v3 revision. `--all-surfaces` creates v4 with hair/lip/nail PBR maps
+as well. Both preserve geometry. They currently require one shared source material/UV
+layout; unsupported native specular or fiber maps fail rather than being overwritten.
+
+`skinSurfaceBlend: true` makes the engine use atlas alpha for skin response, including
+diffusion and thin-skin transmission. Zero coverage retains the native response. Coverage
+must have UV gutters: copy nearest occupied texels into unused atlas space, never into
+unobserved surface regions. This distinction fixes false seams without inventing anatomy.
+At skin/hair/lip boundaries, known material weights must sum to one. Independently fading
+both sides to zero exposes the source material as a bright halo.
+
+V4 expresses fiber and lip response through standard glTF ORM/specular/anisotropy/sheen
+maps. The current fiber direction is provisional; author a comb-flow field before calling
+hair finished. Its skin inspector shows actual skin coverage (white), not an entire mixed
+primitive falsely labelled as skin. `viewerReady` only selects a tested local preview;
+it is not the region-level semantic or final character quality approval.
+
+## Runtime adoption
+
+The engine now provides `RealisticCharacter.create(root, options)` for the loaded GLTF.
+Use the engine's `createGltfLoader()` and resolve embedded atlas indices through its parser.
+The adapter validates UV attributes, retains native untagged materials, preserves coverage
+when detail is disabled, and exposes independent eye controls. It commits material changes
+only after texture resolution succeeds. Scene postprocessing and the body mixer remain
+caller-owned. See the GDK engine document `agent-docs/character-surfaces.md` for ownership
+and pass ordering; do not copy the lab's former material-loading loops into each game.
+
+For a rigged playground derivative, use `highquality/src/assemble_character.py` after
+shared Blender binding. It converts refined geometry to canonical bind coordinates and
+keeps canonical inverse-bind matrices; exercise pose reset and body motion, not only a
+rest-position comparison. Unrigged material/eye previews can coexist with a rigged body
+variant. Determine normalization from the loaded asset, not a catalog-wide rigging flag.

package/assets/character-skin-authoring/references/profiles.md

@@ -0,0 +1,97 @@
+# Face and eye profile authoring
+
+These schemas describe authored inputs to the installed exporters. Values that locate
+anatomy must come from images of this character. Keep the physical dimensions and source
+hashes beside the profile; never copy another character's target coordinates.
+
+## Facial detail registration
+
+Write `highquality/materials/faces/ID.json` with:
+
+- `version: 2`, `id`, `sourceSha256`, `evidenceImage` (workspace-relative), and
+  `evidenceImageSha256` identifying the exact source and reviewed frontal image.
+- `annotationImageSize`: the square target image's actual pixel dimension.
+- `bounds: [minX, minZ, maxX, maxZ]`: the target image rectangle in normalized body
+  coordinates. The current adapter requires a frontal view with direction `[0,1,0]`
+  and up `[0,0,1]`; align an arbitrarily oriented source explicitly before preparing
+  evidence. Normalized X is `(worldX - boundsCenterX) / bodyHeight`; normalized Z is
+  `(worldZ - boundsCenterZ) / bodyHeight + .5`. For a frontal evidence camera, its
+  `targetOffset` and `span` give this rectangle directly:
+  `[offsetX-span/2, .5+offsetZ-span/2, offsetX+span/2, .5+offsetZ+span/2]`.
+- `sourceBounds` and `sourceAnnotationImageSize`: the donor registration view's
+  rectangle and pixel size. Generate and inspect it with the helper below.
+- `landmarkNames`, `sourcePixels`, `targetPixels`: equal-length ordered arrays of
+  corresponding points. Use a well-spread non-collinear set spanning forehead,
+  temples, cheek/jaw/chin boundary, eye corners, nose and mouth. These define the
+  correspondence and its supported hull; points outside the hull receive no face detail.
+- `regions: {"eyes": [...], "brows": [...], "lips": [...]}`: each list contains polygons
+  of target image pixels. These exclude those regions from ordinary facial detail.
+  Include facial-hair exclusions in the exclusion polygons too. Empty lists are valid
+  only when that exclusion is actually absent in the selected patch.
+- `atlasSize`: 2048 or 4096. `independentFacialDetail: true` retains the full facial
+  resolution in the packed runtime atlas.
+- `detailHeightRangeM`: full signed encoding range in metres (zero is .5).
+  `detailAmplitudeM`: authored donor-band calibration, not measured scan amplitude.
+  Compare the resulting relief at face-sized framing under side light; do not compensate
+  for missing texel density by increasing amplitude.
+- `diffusionProfile`: three positive authored channel falloff ratios, such as the
+  renderer's human-skin default `[1,.55,.3]`. Fantasy skin ratios are appearance choices.
+
+Generate the fixed licensed donor's reference image without a playground checkout:
+
+```sh
+python scripts/prepare_face_reference.py --workspace /path/to/assets \
+  --out /path/to/assets/evidence/donor --size 900
+```
+
+Use `donor-front.png` and `registration-view.json` to author `sourcePixels`. Pixel origin
+is top-left for both source and target. The helper uses the same donor projection and
+UV convention as the atlas builder; choosing points from a differently framed photo
+will misregister the relief. It renders the existing licensed files and downloads nothing.
+
+## Optical eye fit
+
+An eye profile has `id`, `sourceSha256`, `evidence` (absolute prepared-view folder),
+`skinRevision: "v4"`, and exactly two entries in `eyes`. Each entry requires:
+
+- `name`, `anatomicalSide: "left" | "right"`, and `view`, matching a manifest view.
+- `irisCenterPx: [x,y]`, `irisRadiusPx`, and `openingPx`: an ordered convex aperture
+  polygon in that exact view. Inspect both obliques before choosing the final depth.
+- `upperContourIndices` and `lowerContourIndices`: ordered indices along the corresponding
+  aperture edges, including their corners. These guide contacts, lashes and closure.
+- `globeRadiusM`, `corneaBulgeM`, `frontOffsetM`, `pupilRatio`, `irisColorLinear` (RGB).
+  These are designed optical dimensions and pigment. The iris must fit inside the globe;
+  confirm against the character's physical height and side views.
+
+Use `openingAuthority: "reviewed-contours"` only after explicitly inspecting the aperture
+when the source has no separately classified ocular primitive. `conformOpenLids: true`
+pushes intersecting source lid tissue outside the fitted globe; inspect its effect.
+Optional `lashes` uses `upperCount`, `lowerCount`, `upperLengthM`, `lowerLengthM`,
+`radiusM` and an authoring note. Reconstructed bands (`outerLidPx`, `lidSkinSamplesPx`),
+corner lining (`canthusWalls`), medial tissue (`caruncle`) and brow strands (`browGroom`)
+are described in [eyes.md](eyes.md). Start with the source-preserving fit; optional
+reconstruction is not automatically an improvement, as the rejected elf trial showed.
+
+The current blink is a fitted geometric morph, not a biomechanical eyelid simulation.
+Preserve source folds unless an independently reviewed correction improves the result.
+Simple smoothing of the closed support band was rejected because it created visible
+rings. Treat any future smoothing as a new fit experiment requiring matched neutral
+and closed-eye review.
+
+### Several independent source-color repairs
+
+`materials/repair-profile.json` may retain the single-operation form or contain
+`{"repairs": [operation, ...]}`. Each operation has its own `mask`, `purpose`,
+optional `cleanSwatches`, `blendWidthM` and optional `evidence` workspace path.
+The latter permits fresh, color-faithful swatch views without invalidating a
+separate anatomical bake whose camera/geometry evidence is unchanged. Source,
+image and correspondence hashes are checked. Every donor must still land on
+independently classified skin. Operations run in order and report separately;
+use disjoint selections unless the overlap is explicitly intentional.
+
+Baked illumination in a generated albedo can make a correctly lit surface dark
+or plastic. Inspect the unlit runtime albedo and color-faithful evidence first.
+A swatch-based correction is an art-directed reconstruction, not measured
+reflectance recovery. Do not globally brighten skin or infer defects from RGB.
+Review the selected region, donor color, transitions and the final relit result;
+retain the original and the rejected candidates.