Made of little things.

# Anatomy layers

## Fitting corrections and reproductive anatomy (25 October 2026)

Feature boundary: correct the existing body-map meshes and add paintable
reproductive structures to the organ layer. Preserve the app-owned white,
off-black and orange palette, 23/47/30 layout, all responsive tiers, and existing
optional SDK storage behavior. All geometry remains bundled. No new host domain,
network authority, identity, relay, or hard capability requirement is introduced.

The previous unrestricted nearest-bone fit attached portions of the abdominal
wall, hip and thigh to the arms. It stretched short surface edges by up to 20×.
Muscles now use anatomically constrained candidate chains and continuous weights.
The palm is fitted as one frame: metacarpal bases no longer converge on one point.
A shared distal-forearm transition aligns the radius/ulna with that carpal plane.
This is an illustrative rest fit, not a model of muscle forces or pronation.
Axial organ morphing now translates with the rig instead of stretching towards
the spine's first child (which could be the left clavicle).

The heart geometry retains its native atlas scale and placement. At the 1.72 m
reference, the combined atrial/ventricular wall bounding box is approximately
11.5 × 10.5 × 10.7 cm in world X/Y/Z (not the organ's anatomical axes). Ventricular
geometry is behind the sternum, between roughly the third and fifth costal
cartilage levels, with a leftward extent. This is consistent with the general
layout described in [OpenStax heart anatomy](https://openstax.org/books/anatomy-and-physiology-2e/pages/19-1-heart-anatomy).
It does not establish clinical accuracy or represent a specific patient's heart.
Great vessels and the entire pericardial assembly are not included.

The organ layer now has 92 structures: the original 70, 12 male atlas structures,
and 10 original female schematics. Male anatomy includes penile erectile bodies,
glans, testes, epididymides, deferent ducts, seminal vesicles and prostate. Female
schematics include uterus, cervix, vagina, ovaries, uterine tubes, outer labia and
clitoral glans. The non-pregnant schematic layout follows [OpenStax's female
reproductive anatomy](https://openstax.org/books/anatomy-and-physiology-2e/pages/27-2-anatomy-and-physiology-of-the-female-reproductive-system).
It is deliberately labeled schematic and remains partial. Other organs can
occlude internal reproductive structures; rotation is needed to see some surfaces.

`Illustrated anatomy` now applies to both skin and organs. Automatic mode uses
Male/Female; skipped, intersex and undisclosed values show neither reproductive
set unless manually overridden. Hidden meshes cannot be picked or captured as
visible evidence. Their saved marks remain intact; capture reports unavailable
anchors. A new stroke starts a separate concern if the selected concern contains
a surface hidden by the new anatomy choice.

All existing vertex/triangle ordering is preserved, including the original 70
organ structures. The model IDs remain at version 1; fitting revisions and output
hashes are recorded in provenance. The preparation scripts refuse to overwrite
an existing mesh if its triangle addresses change. New organ IDs are appended.
Regression fixtures record pre-fit coordinates for representative abdominal, hip
and thigh meshes; tests check edge stretch, stray limb influences, palm width,
wrist continuity, independent arm motion, organ proportions and sex filtering.

Rebuild using the skeleton command below, then prepare-atlas.py, then:

```sh
/Applications/Blender.app/Contents/MacOS/Blender --background --factory-startup \
  --python scripts/prepare-reproductive.py -- /path/to/isa_BP3D_4.0_obj_99.zip
```

Verification of this correction:

- `pnpm verify`: 57 tests passed, including 10 geometry regressions that failed
  before correction; type-check, guidance and production build passed.
- Full reconstruction in separate Blender 5.1.1 background processes passed
  the topology guards. Independent comparison with the prior Git revision
  confirmed all 238 skeletal, 345 muscle and 70 original organ triangle
  addresses unchanged; original organ coordinates also remain unchanged.
- Hosted four-layer workflow passed: real bone/muscle/organ painting, separate
  observations and saved poses, SDK save/reload, per-layer image sheets and
  scene restoration. The new anatomy workflow also passed both sexes,
  front/side/back views, reproductive surface painting, manual override, hiding
  and reload. Switching anatomy starts a separate concern when necessary.
- Hosted prototype regression passed: 200×160 minimum notice, 320×560,
  900×600, 1200×800 and 1600×1000 frames; 390×844, 360×640 and 844×390
  touch emulation; light/dark host themes and absent optional domains. Existing
  session/API-key persistence, accordion behavior and 23/47/30 layout passed.
- Conformance: 5 passed, 0 failed, 5 skipped. Manifest, wire and lifecycle
  evidence is still not covered by the conformance harness.
- The final single-file artifact is 18,136,459 bytes, with one app root and one
  inline script. SHA-256:
  `13192662d3769d117672fdb816813c5cb165597db4f27e44360c641dad391ffe`.
- New organ bundle: 92 structures, 107,553 triangles, 2,626,880 bytes. No runtime
  network loaders or host-domain changes; no AI-provider requests were made.

Final `soyli check` passed `space-playback-6` in Chromium 153.0.8010.12;
the source package is about 34.1 MB, below the 40 MiB limit. Test browsers and
background Blender processes were closed. The existing user-owned preview was
reused and remains running; the foreground Blender scene was not modified.

The sections below record the earlier slices and their historical verification.

## Second slice: muscles and organs (25 October 2026)

Extend the existing napplet with individually named muscle and organ meshes from
the official BodyParts3D atlas. Muscle geometry uses blended weights on the shared
rig so it can bend across joints. Major organs use the same pose frame; neither
deformation nor body-shape adjustment is a clinical simulation. Keep the released
skeleton topology untouched. Every new layer has a pinned asset/model version,
source attribution, bounded geometry and a catalog for saved-anchor validation.

All four layers share the observation, SDK-storage and evidence-capture workflow.
Preserve the white/off-black/orange interface, 23/47/30 layout, compact selector
and mobile tabs. Use restrained anatomy colors with distinct annotation colors.
A faint body outline provides orientation for soft-tissue layers but is not paintable.
No new host domains, network calls, relay use or hard requirements. Missing
optional storage retains the existing in-memory fallback. Future work is tracked
in [the roadmap](roadmap.md).

Verify real ray hits, stable names and laterality, deformation and shape changes,
cross-layer isolation, old drafts, save/reload and per-layer screenshots in the
host. Inspect standing, sitting and side/back views plus supported phone layouts.

## First slice (completed)

Extend the existing Body Journal napplet with an actual skeleton layer. Skin and
skeleton are independently selectable and paintable; muscles and organs remain
explicitly unavailable until their meshes and deformation are prepared.

Use named BodyParts3D 4.0 bone meshes from the official archive. Preserve FMA
identifiers, source names, a pinned binary topology version, and a reproducible
preparation script. The app code stays MIT; adapted anatomy data carries separate
CC BY 4.0 attribution, following the archive's license updated 2025-02-27.

Fit the reference skeleton to the existing MakeHuman rig. This is an illustrative
alignment between two reference bodies, not a reconstruction of an individual's
anatomy or measured joint biomechanics. Keep bones rigid when posing, adapt their
lengths to the rig, and do not inflate bones with body weight. Clinical/anatomical
review of fit remains outstanding.

Each localized observation belongs to one layer. Switching layers creates a new
observation on the next stroke when the selected observation belongs to another
layer. Selecting an existing observation restores its layer and saved pose.
Old observations and drafts default to skin. Triangle/barycentric anchors remain
specific to the named bone and asset version. Hidden-layer marks never move onto
another mesh. General symptoms need no anatomical layer.

Evidence capture switches to each observation's saved layer/pose and restores the
view afterward. Captions and structured text identify the chosen illustration
layer. Selecting a bone is a user annotation, never evidence that the bone is the
source of the symptom.

Keep the white/off-black/reddish-orange visual direction, 23/47/30 desktop split,
and mobile tabs. Provide a compact accessible layer selector, current-layer
feedback and source credit. All geometry is bundled; no new host capabilities or
network calls in app code. Existing optional SDK storage persists layer choices.

Input correction: two-finger trackpad scrolling zooms; secondary click-drag
(including a two-finger trackpad click held while moving) rotates in every tool.
Touchscreens retain two-finger orbit plus pinch; one-finger input uses the tool.

Verify bone picking, side/name identity, posed/morphed anchors, versioned draft
round trips, legacy defaults, isolated layers, evidence capture/restoration and
hosted responsive controls. Run the repository verification and conformance suite.

## Asset and reconstruction

The bundled asset is 2,499,084 bytes with 167,584 triangles across 238 named
structures. It includes costal cartilage and intervertebral discs in addition to
bones; this is not a count of individual human bones. Source FMA IDs and English
names are retained in `src/skeleton-catalog.ts`. Attribution is accessible from
the layer control. The geometry is decoded from embedded bytes; no runtime fetch
or remote loader is used.

To rebuild, download the official PART-OF archive linked in provenance.json,
extract its OBJ files, and run:

```sh
/Applications/Blender.app/Contents/MacOS/Blender --background --factory-startup \
  --python scripts/prepare-skeleton.py -- /path/to/extracted/partof_BP3D_4.0_obj_99
```

Prepared with Blender 5.1.1. The script creates its own temporary mesh objects in
a background process, leaving the user's open Blender scene untouched. It uses
individual long-bone segment transforms, shared transforms for paired bones,
per-digit alignment and rigid rig parenting. The axial skeleton is an approximate
alignment of the atlas reference; shoulders, wrists, feet and joint contact need
anatomical refinement. Not all skeletal articulations are modeled. Whole-body
height scales the illustration; rig segment lengths adapt to body shape while
bone cross-sections do not inflate with weight.

Never replace the released binary with changed topology under the same
`bp3d-skeleton-1` ID. A future re-export must version anchors or provide an
explicit migration. Source-file and generated-binary hashes are pinned in
`assets/skeleton/provenance.json`. No source OBJ archive is bundled.

## Data and boundary behavior

Draft v2 gains a validated per-observation `layer` field; omission means skin.
Session view gains an optional layer, with a legacy selected-observation fallback.
Model/structure IDs, triangle ranges and barycentric weights are validated before
restoration. The named atlas label is restored from the catalog. Cross-layer
marks are rejected rather than silently moved. SDK storage remains optional.

AI text has `illustratedLayer`; the evidence limitations explicitly say that a
bone selection does not establish symptom causation. Offscreen capture renders
one observation at a time, using its saved layer and pose. It restores the user's
layer, pose, view and marks even if image preparation fails. Muscle and organ
entries remain disabled until their assets and interactions are implemented.

## Verification (2026-10-25)

- `pnpm verify`: 41 tests passed, including pinned asset topology/geometry,
  skin and skeleton raycast isolation, named bone anchors through shape/pose/IK,
  saved-layer round trips, rejected cross-layer anchors and legacy skin defaults.
  TypeScript and single-file build passed.
- Hosted `test:layers:ui`: named left-femur painting; separate skin/skeleton
  observations; independent standing/sitting poses; SDK save/reload; layer-specific
  image sheets; restored view after capture; no unverified image sends. Synthetic
  test data only, no vendor requests. Images inspected from front, side and seated
  views, including generated close-ups.
- Hosted prototype regression: accordion behavior and 23/47/30 desktop split;
  forms, painting, pose changes, actual SDK storage, reload, optional-domain
  absence and light/dark hosts. App-owned white/off-black/orange palette retained.
- Frames: 200×160 minimum notice, 320×560, 900×600, 1600×1000, plus 390×844,
  360×640 and 844×390 touch emulation. Frame dimensions were explicitly set by
  test-only host styles. Compact layer selector does not overlap the head.
- Gesture unit and hosted checks: right-button rotation and wheel zoom in all
  three tools; touchscreen orbit/pinch with no stray stroke; remaining finger
  stays inert until lifted. The test harness now uses full-frame screenshots to
  avoid Chromium's clipped-screenshot offset in subsequent CDP touch events, and
  releases the intended touch ID. Physical phone/trackpad behavior is unverified.
- Conformance: 5 passed, 0 failed, 5 skipped; manifest/wire/lifecycle evidence was
  unavailable. No new host domains, relay use or runtime network loaders.

The existing user-owned soyLI preview was reused and left running. Test browsers
and separate background Blender processes were closed. Clinical/anatomical
validation, joint-contact accuracy and muscle/organ layers remain outstanding.

Final soyLI host check passed `space-playback-6` in Chromium 153.0.8010.12.
The single-file HTML is 7,468,482 bytes with one app document and one inline script;
SHA-256 `1750c97608cd5ffde53f6a75eba07b2466aaadcd72cad2fdf41e6531fa7fb4d2`.


## Muscle/organ assets and reconstruction

The new versioned assets are `bp3d-muscles-1` (345 named structures, 218,798
triangles, 5,339,664 bytes) and `bp3d-organs-1` (70 named structures, 92,510
triangles, 2,242,468 bytes). Catalog labels and FMA IDs come from the source OBJ
headers; disconnected pieces sharing a concept are joined. Unnamed source
meshes are excluded. No source archives are bundled. Attribution is in
`assets/anatomy/NOTICE.md` and the per-layer provenance files.

These are partial reference layers. Muscle coverage includes many limb, shoulder,
neck and back structures, with some tendons/tracts. Several large trunk muscles
are missing. Organ coverage includes cerebral surface regions/cerebellum, heart
walls, trachea, liver segments, stomach, bowel, spleen, pancreas, kidneys, adrenal
glands, ureters and bladder. Whole lungs, reproductive organs and detailed cavity
surfaces are not provided. Preserve the source's part names rather than implying
that a selected wall or segment represents the entire organ. The pale body
outline is orientation only and is excluded from picking and occlusion tests.

Rebuild in a separate background process with Blender 5.1.1:

```sh
/Applications/Blender.app/Contents/MacOS/Blender --background --factory-startup \
  --python scripts/prepare-atlas.py -- /path/to/isa_BP3D_4.0_obj_99.zip
```

The script reads the official IS-A archive, converts coordinates/units, welds
coincident vertices, decimates geometry, removes unused vertices, fits anatomical
landmarks to the reference rig, and assigns four normalized influences per muscle
vertex. Organs bind to axial rig segments. This supports illustrative posing;
it does not model muscle attachments/forces, organ motion or soft-tissue contact.
Body-shape changes adjust the rig fit without inflating organs with weight.
Change model IDs and define anchor migration before changing published topology.
The preceding skeleton binary and its anchor version are preserved.


## Second-slice verification (25 October 2026)

- `pnpm verify`: 45 tests passed, including seven anatomy-layer checks; type-check
  and single-file build passed. Tests exercise source/output hashes, unique names
  and FMA IDs, complete geometry, normalized weights, real ray hits on posed
  muscles and organs, persisted anchors, wrong-model/cross-layer rejection and
  legacy skin defaults.
- Hosted `test:layers:ui`: all four layers, actual left-femur/left-rectus-femoris/
  stomach picking, independent saved poses, real SDK storage/reload, four image
  sheets, captions and scene restoration passed. No provider request was made.
  Inspected muscle front/back/walking views, organs standing/lying views and
  targeted muscle/organ image sheets. Faint body context is non-paintable.
- Layer controls were checked at 1600×1000, 900×600, 320×560, 390×844, 844×390
  and the 200×160 minimum notice. These use explicit test-only iframe dimensions.
- Conformance: 5 passed, 0 failed, 5 skipped. Manifest evidence, wire traffic and
  lifecycle measurement remain unverified by that harness. No new host domains,
  runtime network loaders, relay access or browser-storage paths were introduced.
- Final HTML: 17,621,170 bytes, one app root and one inline script; SHA-256
  `b3f906b6ec015befde7fbcfc7a190ee1ee3079c39cd3bdd9d5094d92ce476bdf`.
  New assets total 7,582,132 bytes. The released skeleton asset was not changed.

Prepared in separate background Blender processes. The user's foreground scene
was not modified. Existing user-owned soyLI preview at http://127.0.0.1:4173/
was reused; no additional preview watcher was started. Atlas coverage, fit and
soft-tissue deformation remain approximate and have not been clinically reviewed;
performance on a physical phone remains unverified.


Hosted prototype regression also passed: accordion and 23/47/30 layout, live
shape/pose changes, existing API-key/session storage and reload, light/dark host
controls, 200×160/320×560/900×600/1600×1000 frames, and 390×844/360×640/844×390
touch emulation. The same built app remained usable in an opaque iframe with
storage/config/theme absent. Test browsers were closed after the checks.

Final `soyli check` passed profile `space-playback-6` in Chromium 153.0.8010.12;
source package 33,130,448 bytes, below the 40 MiB budget. The reused preview
remains running under its existing owner. No deployment or vendor call was made.