# PR stack Six PRs, each reviewable and mergeable on its own, following the stack convention in `umamo/README.md` § Contributors. Each one has a reason to exist before the next one uses it. ## PR 1 — `:format`: glTF/GLB reader Read-only. Container rules, buffer views, accessors, scene graph, skins. No rendering, no UI. Why first: the container rules are the part most likely to be wrong, and they are testable without a GPU or an asset. Alignment rejection, chunk padding, truncation, and the more-than-one-chunk case are all pure. Depends on nothing. `kotlinx-serialization-json` is already a `:format` dependency. Reuse `UmaManifest.kt`'s JSON depth guard (`UMA_MAXIMUM_JSON_DEPTH`) for the glTF JSON chunk. An accessor that reads past its buffer view's `byteLength` is an error, not a zero fill. Tests: `GlbContainerTest`, `GltfAccessorTest`. Corpus gate under `test/corpus/gltf/`, skipped when empty, like every other corpus test. ## PR 2 — `:render`: seam additions `PrimitiveTopology`, `DepthState`, `depthAttachment`, `WorldToClip`, `ReferenceMeshSpec`, the two draw calls, and the GL implementation. Nothing uses them yet. Why it must be its own PR: it touches every backend, including the GLES and Metal stubs, which have to answer for the new `PipelinePurpose` values explicitly. A seam change that arrives attached to a feature cannot be bisected when a backend breaks. Defaults on `RenderPipelineSpec` keep every existing call site compiling unchanged, so this PR has no behavioural diff for the puppet path. That is the test that it is honest. Tests: `ReferenceDepthGateTest`, GL-gated, shaped like `WorldAxisLinesTest.kt` — a flat-shaded triangle at a known camera must rasterize the expected pixels, and the depth test must reject a triangle behind it. Skips via a JUnit assumption in a display-less environment. ## PR 3 — `:runtime` + `:edit`: the reference layer model and the pose `ReferenceLayer`, the joint set with per-joint clamps, forward kinematics, CPU skinning. Pure data and pure functions, no GL, no UI. Why before the renderer: the pose is the part a test can pin. Bone length invariance, joint origin invariance, orthonormality, and a weighted blend between two poses are all facts about the model, not about the GPU. Tests: `MannequinFkTest`, `ReferenceLayerTest`, `SkinningTest`. ## PR 4 — `:render`: the reference renderer Consumes PR 1's scene and PR 3's pose. Builds the camera matrix, uploads the mesh, draws the flat fill and the wireframe, resolves the pose on pose-change frames only. Draw order `Above` and `Below` only. Depth-sorted occlusion against the puppet is not in this PR: it needs the puppet to write depth from drawable Z, and the puppet path has no depth today. Tests: `ReferenceDrawPlanTest` (pure), `ReferenceRenderGateTest` (GL-gated). ## PR 5 — `:ui`: the overlay Overlays toggle in the viewport header, the Properties section, the commands through `CommandRegistry`, keymap entries, `strings.xml` entries. Why last of the functional ones: it is the only PR that changes what a user sees, and it depends on everything above existing. Commands: `reference.import`, `reference.reset-pose`, `reference.fit`, `reference.toggle-visibility`, `reference.link-camera`, `reference.clear`. Tests: `CommandTableOrderTest` and `CommandRoutingTest` cases for the new commands, plus the area-scoped routing — the reference commands belong to the viewport area, not the UV editor. ## PR 6 — `:format` + `:ui`: UMA persistence The `reference` entry, the bridge type, the writer and loader wiring. Why last: persistence is only worth designing once the shape of the object is settled by PR 3, and the entry must be additive and ignorable — a reader that does not know `reference` skips it and the document still opens. Tests: `UmaEntrySchemaTest` case, `UmaReferenceRoundTripTest`, and the export-contamination gate: a document with a reference layer present must still produce a byte-identical CMO3 for the puppet. That gate is the one that catches the layer leaking into the format. ## Out of order on purpose PR 2 could be folded into PR 4 and PR 6 into PR 3. They are separate because a seam change and a persistence change are the two things most likely to break something that does not use them, and a stack that can be bisected is the point of the convention.