@bitmagic/cli 0.1.66-dev.5 → 0.1.66-dev.7

package/README.md

@@ -217,7 +217,7 @@ browser reloads itself on every change and the assets panel shows each generatio
 | `bitmagic trailer publish <file.mp4> [--no-attach]` | Upload a trailer (`.mp4`/`.webm`, ≤ 200 MiB, header-checked so a renamed image is refused before upload) to the CDN under `game-media/<gameId>/` and put it at the front of the game page gallery. Re-running replaces the previous trailer (remembered in `.bitmagic/trailer/published.json`); the page is capped at 12 media items. Works before the first publish — the page goes live on the first `bitmagic publish --visibility public`. `--no-attach` uploads only. |
 | `bitmagic forge --prompt "..." [--city\|--dungeon\|--platformer\|--freeform] [--name <name>] [--resume <jobId>]` | Design and bake a whole playable level into `world.json`. Costs sparks, and takes many minutes — the bake alone can take twenty. `--resume <jobId>` picks a failed run back up from the last step that finished, rather than redoing the whole thing. |
 | `bitmagic forge --edit "..." [--level <id or name>]` | Change a detail of a level this project forged — a door style, the light fixtures, a prop — without re-forging it. The stored design is patched and only what the change touches is re-made; the level is replaced in place. See [Editing a forged level](#editing-a-forged-level). |
-| `bitmagic tools <list\|path\|install> [bundle]` | The script bundles the CLI ships for skills that drive Blender or Python (`blender-level`, `unity-import`): what they are, where this install keeps them, and `install` to copy one into the project's `tools/`. Local, no network, no sparks. |
+| `bitmagic tools <list\|path\|install> [bundle]` | The script bundles the CLI ships for skills that drive Blender, Python or Node (`blender-level`, `unity-import`, `metahuman`): what they are, where this install keeps them, and `install` to copy one into the project's `tools/`. Local, no network, no sparks. |
 | `bitmagic levels <list\|add\|rename\|set-start\|remove> ...` | Manage the levels `forge` creates: which one boots, their names, registering a bake you already have, deleting one. Local, no network, no sparks. See **Managing levels** below. |
 
 Every command exits non-zero on failure with a single-line message (no stack trace) and, where a
@@ -531,6 +531,32 @@ before. Without a prior user gesture the browser blocks autoplay, and the engine
 immediately — so the cutscene silently does not run. `engine/agent-docs/video-cutscenes.md` covers
 that and what to freeze while a cutscene plays.
 
+## Spoken lines
+
+`bitmagic generate speech --text "Halt, traveler. You shall not pass."` speaks a line, writes it
+into `world.json` as an audio asset, and prints the `engine.playSound("<id>")` call that plays it.
+Unlike a music bed it is registered as a **one-shot, not a loop** — dialogue plays when something
+triggers it.
+
+`--voice` picks who says it: `narrator` (the default), `male`, `female`, or a raw Eleven Labs
+`voice_id` if you have cloned one of your own. `--model` switches model, and `--stability`,
+`--similarity-boost`, `--style` and `--speed` are passed through to Eleven Labs when you want them;
+leave them alone and Eleven Labs' own defaults apply.
+
+It is **billed per second of audio produced**, not per character of text. A sentence costs about a
+spark. The estimate charged up front comes from the length of the text; what you actually pay comes
+from the finished audio.
+
+Like `generate music`, it can write a file instead of a game asset:
+
+```bash
+bitmagic generate speech --text "Halt, traveler." --out line.mp3 --no-world
+```
+
+`--out` saves the MP3, `--no-world` leaves `world.json` untouched. That pair is the input to the
+MetaHuman lip-sync tool (`tools/lipsync/make_line.py --audio line.mp3`), where a spoken line is
+cut into mouth cues rather than played as-is. Use `--out` on its own to keep both.
+
 ## Reference image
 
 When a game has a strong setting — a tropical island, a neon city — one accepted concept image can
@@ -1306,6 +1332,15 @@ by the engine's `MeshLevel`. The scaffolded `building-levels-in-blender` skill w
 its first section says when that path applies (a frontier model, and Blender installed) and sends
 everything else to `bitmagic forge`.
 
+## Importing a MetaHuman
+
+An Epic MetaHuman (a UE 5.7 glTF export from the smorchj/metahuman-to-glb pipeline) can be the
+game's playable high-res character without voxelization. The scaffolded `importing-metahumans` skill
+carries the whole path — `bitmagic tools install metahuman` lands the GLB preparation scripts, the
+runtime module (`src/work/metahuman/`), the lip-sync tool and a headless verification rig — and names
+each failure a raw export produces (arms crossed into the chest, a torn shirt, hair left behind by a
+head turn, tinted skin, black eyes) with the fix that resolved it.
+
 ## Art style
 
 A 3D game is voxel-built unless `src/work/game.json` says otherwise:

package/assets/character-skin-authoring/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: character-skin-authoring
+description: Use vision to author and review exposed-skin maps on textured 3D characters, including faces, hands and bodies. Prepare exact model views, annotate visible anatomy, project evidence into UV space, and review skin detail placement. Eye construction is a separate workflow.
+---
+
+# Vision-led character skin authoring
+
+The local agent makes anatomical/material decisions from images. Do not replace those decisions with RGB thresholds, world-height cutoffs, race/name rules, or another automated classifier. Deterministic tools handle projection and bookkeeping. The creator's existing agent subscription supplies vision; this workflow requires no hosted segmentation service.
+
+## Establish evidence
+
+Locate the model, its physical height, materials, texture resolution and rig. Keep the original immutable and write a separate material revision. Inspect the original generated image when available, but make the **actual mesh and its textures** authoritative: the generated mesh may differ from that image.
+
+Use the local `scripts/skin_views.py` helper to create unlit, occlusion-correct views with their UV correspondences. Read [the projection contract](references/projection.md) for commands and formats. It requires local Blender and a Python environment with NumPy/Pillow. The helper performs no semantic recognition. Verify orientation from the resulting images; its axes are not anatomical labels.
+
+Start with a full-body survey from opposite directions. Then frame each exposed region closely enough to see its boundaries. Inspect the face from front and both sides; inspect both hands from palm and dorsal sides and oblique angles showing finger webs. Inspect ears, neck, chest, arms, legs, feet or any other exposed region actually present. Add cameras when existing views cannot show a surface. Do not infer a hidden palm from a dorsal hand image or project a front silhouette through to the back.
+
+## Author the maps using vision
+
+For each viewed surface, annotate pixel polygons as `skin`, `dorsal_hand`, `palm`, `sole`, `lips`, `eyes`, `hair`, `nails`, or `non_skin`. `unknown` is explicit unresolved evidence. Use separate polygons for exclusions, ordered after enclosing polygons. Do not give an indistinct nail facial pores merely because the rest of the hand is clear. Record why a boundary is ambiguous; obtain a closer/different view before resolving it. Scars, freckles, tattoos and makeup usually remain skin with appearance annotations, not separate non-skin regions. Tight cloth is still cloth; green skin is still skin. If garment colour spills onto anatomically visible skin in the source albedo, record a texture defect separately from the semantic mask. A correct skin label cannot repair that colour.
+
+Review the colored annotation overlay on the **same source image**, then review the **baked atlas reprojected onto every prepared view**, including unannotated side views. Use the dense visibility bake at a resolution appropriate to the source atlas; sparse splatting is a diagnostic, not a finished mask. Include the filename, image dimensions and source hash with every annotation set. If a tool displays a resized image, convert coordinates back to the recorded dimensions. Never claim to have visually reviewed an image you have not opened.
+
+The helper deliberately leaves unobserved UV texels unknown and reports contradictory labels. Do not grow a skin mask across unknown areas to make a coverage statistic look good. Get additional views, increase sampling resolution, or use a reviewed Blender texture-paint correction. Mirrored/overlapping UVs can make conflicting anatomical labels impossible in one atlas: document that and create separate material/UV regions rather than average the labels.
+
+## Apply region-appropriate detail
+
+For material application and engine integration, read [material application](references/materials.md). The [installed exporters](references/exporters.md) assemble reviewed inputs in an explicit external workspace. After coverage passes review, register landmarks and surface scale for each detail patch. Use licensed exemplars and retain attribution and modification provenance. The b3662 face pilot in this repository demonstrates registered scan detail; its coordinates are **not** a universal face template.
+
+- Face: region-specific pores, fine relief, oiliness and pigment. Exclude eye surfaces, lashes, brows, lips and facial hair from the ordinary pore layer; preserve actual folds and identity.
+- Dorsal hands/fingers: knuckle folds, tendons and finer hand texture. Nails receive their own response.
+- Palms/soles: glabrous skin with appropriate creases/ridges and roughness; do not stamp facial follicles onto it.
+- Neck, torso, limbs, ears: use suitable regional detail and scale. Preserve the character's natural variation; do not transplant a donor's beard, identity marks or complexion.
+
+Blend patch boundaries in surface space and check physical scale. A silhouette or clothing boundary needs a coverage edge; two adjacent skin patches need a continuous transition. Keep skin nonmetallic and preserve clothing/armor materials. Use the existing registered detail/SSS renderer where available; do not invent new renderer hooks or claim the projection helper installs materials by itself.
+
+## Review and handoff
+
+Inspect colored material regions and final shaded results separately. Use fixed cameras under diffuse, specular, side, studio and back lighting. Check full-body, face-sized and close detail views, plus a representative pose when the model is rigged. Confirm both hands, finger webs, nails, ears and every other exposed area; inspect clothing edges without revisiting unrelated deferred edits.
+
+Record results per character and region: `reviewed`, `needs_view`, `conflict`, or `needs_detail_asset`. Archive source hashes, views, annotations, projected labels, atlas registration, licenses and review images together. Only call a character complete when its exposed regions are reviewed and the **applied** maps have been inspected. A parseable annotation file or a successful bake is not semantic validation.
+
+Review the face and ocular exclusion before eye geometry/shading work; use the separate [optical-eye workflow](references/eyes.md) when that work is requested. Eye progress does not mark unresolved body skin as complete. This workflow is maintained in the GDK CLI assets and installed into supported agent skill directories from the same source. Keep per-character evidence and candidates outside those refreshed directories.

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.