Made of little things.

# Rigged skin model

This stage replaces the segmented demonstration mannequin with a continuous,
rigged MakeHuman skin mesh prepared in Blender. It remains an illustrative adult
body map; neither shape nor pose is a physical examination.

## Build brief

- Keep Body Journal's ivory body, evergreen controls, coral marks and app-owned
  palette. Preserve the phone tabs and small-frame notice.
- Bundle geometry, UVs, skin weights, skeleton and shape targets in the single
  HTML artifact. No runtime downloads or new NAP capabilities.
- Use only MakeHuman core CC0 assets. Keep the upstream source/version, license,
  preparation script and exported asset provenance reproducible.
- Attach new marks to a versioned triangle and barycentric coordinates. Resolve
  their positions against the posed, morphed mesh, including saved drafts.
- Derive patient-side location descriptions in the canonical body, independently
  of the camera and pose. Treat labels as editable approximations.
- Keep the five pose presets and bounded limb controls. Preserve each concern's
  pose separately. Controls illustrate a position, not measured joint range.
- Keep old drafts readable; never silently reattach an old primitive-space mark
  to an unrelated triangle. Explain any old markings that need repainting.
- Keep region selection usable if WebGL or the model fails.

Acceptance: paint a knee, change height/weight, sit, adjust the leg, save and
restore. The mark must remain at the same skin location with patient laterality
unchanged. Check mesh silhouette, limb deformation and back-facing mark behavior.
Run the existing type/build/guidance/conformance checks and hosted desktop/touch
checks. Document limitations and evidence below when complete.

## Asset and runtime

The pinned source is [MPFB v2.0.17](https://github.com/makehumancommunity/mpfb2/tree/v2.0.17),
commit `80919fa`. Core assets and generated output are CC0 under its
[license statement](https://github.com/makehumancommunity/mpfb2/blob/v2.0.17/LICENSE.md).
The exported binary is 2,577,916 bytes: 13,380 vertices, 26,756 triangles, UVs,
four normalized bone weights per vertex, 53 bone relationships, and nine shape
samples (three body-shape values × three weight values). No helper geometry,
textures, MPFB code or network loader is shipped.

`src/skin-model.ts` interpolates shape samples and refits joint positions before
skinning. Height scales the illustration; weight maps approximately through BMI
to a shape parameter. Sex selection chooses a source shape endpoint; unanswered,
intersex and prefer-not-to-say retain the intermediate illustration. Age is not
used to change the model. These choices do not predict personal anatomy.

Each new mark stores model ID `mpfb-skin-1`, triangle index, barycentric coordinates,
UV, canonical point and an approximate region label. Positions are resolved from
posed vertices, so camera, pose and shape changes never rewrite the stored anchor.
Topology/vertex ordering changes require a new model ID and an explicit migration.
Draft version 2 retains version-1 text and markings, but old primitive-space marks
are not rendered on unrelated skin. The concern editor explains this and offers
clear-old-markings and repainting. Storage remains the existing optional SDK domain.

The atlas uses canonical coordinates and skin-weight regions. It distinguishes
patient laterality, limb thirds, knee/elbow surfaces, hands/fingers, neck, torso,
ankle/foot areas. A stroke spanning multiple regions retains them in the reviewed
AI payload as `approximatePaintedSurfaceAreas`; the main location stays editable. The atlas
is approximate and has not been reviewed by an anatomist or clinician. It makes
no claim about underlying organs, muscles, nerves or diagnoses.

Marks are surface-aligned circular dabs. Their centers are exact skin anchors;
brush footprint edges do not conform to strong curvature like a geodesic mask.
The rig has bounded elbow/knee hinges and illustrative limb dragging. It has no
whole-body collision system or clinical range-of-motion calibration. Highly
flexed joints can pinch under linear skinning. Internal layers remain deferred.

## Rebuild / edit

Open `assets/skin/body-skin.blend` in Blender to inspect the mesh, UVs, weights,
shape keys and armature. Its shape keys are editable authoring samples; runtime
joint refitting is implemented in the app, not as Blender drivers.

To reproduce from source, download the official tag archive, extract it outside
the repository, then run a separate Blender background build:

```sh
BLENDER_USER_RESOURCES=/tmp/body-journal-blender-user \
  /Applications/Blender.app/Contents/MacOS/Blender --background --factory-startup \
  --python scripts/prepare-skin.py -- /path/to/mpfb2-source .napplet-space/skin-authoring
```

The disposable Blender resource directory avoids altering the user's installed
extensions or saved preferences. The script creates an isolated authoring scene,
fits the game-engine rig, straightens the arms into a relaxed A pose, removes
helpers from the export, generates shape samples and writes the binary, editable
blend and provenance JSON. Copy only those three reviewed outputs to `assets/skin/`.
Keep the source asset license there. The original active Blender scene is preserved;
the inspected model was appended into a separate “Body Journal — skin study” scene.

The app decodes bundled bytes directly into Three.js geometry. It does not use a
network-capable model loader or fetch a blob URL. Asset source and the final HTML
remain within soyLI's documented size limits.

## Verification

`pnpm test:skin` checks the pinned asset hash and skin weights, actual front/back
knee raycasts and patient laterality, a mark on the deformed mesh after reshaping,
sitting and limb adjustment, draft round-trip, malformed anchors and old drafts.
The normal `pnpm verify` command includes these tests.

The hosted smoke test checks the actual `mpfb-skin-1` model, a visible-foot drag
that moves its knee mark, loading the example after changing pose, live measurements, painting, per-concern poses, and
actual SDK draft storage. Screenshots cover the standard four frames, large
1200×800/1600×1000, touch emulation at 390×844, 360×640 and 844×390, both host themes
and an opaque iframe without optional domains. Real phone hardware and clinical
accuracy remain unverified.

Final local checks on 2026-10-24: `pnpm verify` passed all 23 tests, TypeScript and
build; hosted UI and synthetic AI UI checks passed without browser errors;
conformance passed 5, failed 0 and skipped 5 (manifest/wire/lifecycle evidence
was not supplied). `soyli check` passed with profile `space-playback-6`, Chromium
153.0.8010.12. Final HTML: 4,077,928 bytes; SHA-256
`18078d9ecc7cb9bf4cb64ec093f8ec4feb35e74f33a4b53dd093887c9872496a`.
The build contains no external scripts or fetch/WebSocket/browser-storage paths.
No live inference calls, publication or deployment were made.

## External anatomy extension (2026-10-25)

The original CC0 skin binary and triangle indices remain unchanged. Original MIT
schematic meshes in `src/external-anatomy.ts` add penis shaft/glans, left/right
scrotal skin, outer/inner labia, clitoral hood and vestibular opening areas.
`external-anatomy-1` anchors name the component and its fixed sphere topology;
they follow the pelvis and body-shape attachment point. Labels describe external
surfaces, not internal testes, vaginal tissue or inferred disease. The forms
allow a separate illustration override; sex assigned at birth is not treated as
a complete description of someone’s current anatomy.

These are simplified region-selection illustrations, not a clinically validated
anatomical atlas or an exact depiction of individual anatomy. They are authored
in code and are not present in the earlier base `.blend` export. Switching to
a different anatomy keeps existing marks in the session; unavailable surfaces
are reported explicitly during image review instead of reattaching them.

### Attachment correction and navigation (2026-10-25)

The extension now fits between two stable vertices on the pubic/perineal skin,
re-evaluated after morphing and skinning. Labial surfaces follow that slope;
their ends recess into the skin. Shaft and scrotal roots sit farther back, with
the hanging components counter-rotated against the fitted slope. Component
names, triangle ordering and barycentric addresses are preserved. The base
binary and earlier Blender scene are unchanged.

The visual direction remains the current white/off-black interface, gray body
and reddish-orange emphasis. No new host capabilities are needed. Temporary
camera gestures work in every tool: secondary-button drag, two-finger touch
translation. Trackpad scrolling and pinch zoom (corrected below). A pending touch
does not paint until it becomes a one-finger drag or tap; two-finger takeover
ends any active tool drag, and its remaining finger stays inert until lifted.
Cancellation and focus loss clear gesture state.

Regression checks cover embedded roots across all nine shape samples in standing
and sitting, unchanged saved surface anchors, tool arbitration, pinch, touch
cancellation and trackpad scroll. Hosted checks cover right drag and two-finger
touch in Rotate/Mark/Pose without stray observations, followed by one-finger
painting. Browser touch is emulated; physical phone/trackpad hardware has not
been checked. Front/oblique inspection includes male/female illustrations,
different body sizes, sitting, lying and jogging.

Local verification: `pnpm verify` passed 38 tests, TypeScript and build;
`pnpm test:conformance` passed 5, failed 0, skipped 5 (manifest/wire/lifecycle
evidence unavailable). `soyli check` passed with `space-playback-6` in Chromium
153.0.8010.12. Hosted anatomy, gesture and prototype smoke checks passed,
including 200×160, 320×560, 900×600 and 1600×1000, touch portrait/landscape,
both host themes and missing optional domains. Owned previews were stopped.

### Skeleton layer and trackpad correction

The base skin topology is unchanged. `SkinModel` now hosts a separate anatomical
skeleton, selectable through the layer control; see [anatomy layers](anatomy-layers.md).
Trackpad two-finger scrolling zooms. Secondary click-drag rotates in every tool.
Touchscreen orbit/pinch behavior remains separate from trackpad wheel events.