M4.11: docs: architecture, parity and ROADMAP cover nested comps and motion blur

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

ROADMAP.md

@@ -10,7 +10,7 @@ once.
 | M1 | Keyframes: temporal and spatial interpolation, Easy Ease, roving, velocity | Done |
 | M2 | Compositing: 38 blend modes, track mattes, parenting, adjustment layers | Done |
 | M3 | Project operations: settings dialogs, layer commands, `.ecproj`, undo, After Effects menu bar | Done (unsaved-changes prompts, Solid / Layer Settings, lock-aware layer commands, safe project files; View ▸ New Viewer still opens only the one locked viewer) |
-| M4 | Preview: precomps, motion blur, cached playback | Mostly done |
+| M4 | Preview: precomps, motion blur, cached playback | Mostly done (Preserve frame rate / resolution when nested, one motion blur gate, RAM preview fixes, Cache Frames When Idle; left: motion blur of collapsed precomps and of animated layer content) |
 | M5 | Timeline depth: graph editor, keyframe clipboard and dialogs, time remapping, pick-whips, expression editor | Done |
 | M6 | Shapes, masks and footage: shape operators, masks and the pen tool, video and image import | Done |
 | M7 | 3D: 3D layers, cameras, lights, shadows, depth of field, 3D views and camera tools | In review |

docs/architecture.md

@@ -299,6 +299,19 @@ Continuously Rasterize: the source is rasterised at its on-screen scale. Quality
 nearest-neighbour, Wireframe draws the layer bounds. Slip edit (`layer.slip`, Alt+PageUp/Down,
 dragging the source bar in the timeline) moves the source under fixed in/out points.
 
+**Nested comps** show nothing before they start or after they end (`Comp::covers`), even when
+the precomp layer is trimmed or remapped past them. A comp with **Preserve frame rate when nested
+or in render queue** shows only its own frames when nested (`EvalCtx::nested_time` floors the
+precomp layer's source time to its frame rate) and renders at its own rate in the Render Queue;
+one with **Preserve resolution when nested** renders at full size inside a comp drawn at a lower
+resolution (the buffer's scale places it).
+
+**Motion blur** has one gate, `Renderer::mb_on`: the render options (Render Settings ▸ Motion
+Blur, previews), the comp's switch and the layer's switch, limited by the precomp layers above
+when switches affect nested comps. Layer motion, mask motion blur (the comp's Samples Per Frame,
+four in Draft), effects that read the shutter and Advanced 3D all follow it, and the layer cache
+key of a layer with masks or effects records it.
+
 **Motion tracking** (Animation ▸ Track Motion / Stabilize Motion, Window ▸ Tracker): a tracker
 is a `Tracker` group under the layer's Motion Trackers group, with Track Point groups (Feature
 Center, Feature Size, Search Offset, Search Size, Confidence, Attach Point, Attach Point Offset)

docs/parity.md

@@ -383,6 +383,22 @@ Browser in the web app (landed in M13.10: browser storage and File System Access
   wrong signatures and versions, fuel exhaustion, traps and bit-identical output; script
   `Socket` validates ports, and ScriptUI resource strings accept trailing array commas.
 
+## Update: M4.9–M4.11 nested comps and motion blur
+
+- **Composition Settings ▸ Advanced ▸ Preserve frame rate when nested or in render queue** and
+  **Preserve resolution when nested** (model, renderer, Render Queue, dialog, `comp.settings`,
+  `comp.info`, `CompItem.preserveNestedFrameRate` / `preserveNestedResolution`; Pre-compose
+  copies them).
+- **Nested comps past their end** show nothing (flattened, through a proxy, or collapsed); they
+  kept drawing layers whose bars ran on.
+- **Motion blur gate**: mask motion blur, effects that read the shutter and Advanced 3D follow
+  the render options and the precomp layers' switches like layer motion does; mask motion blur
+  uses the comp's Samples Per Frame.
+
+Not yet: collapsed precomps don't blur with the precomp layer's own motion or the parent
+camera's; animated content inside a layer (shape paths, text animators, nested frames) isn't
+re-rendered per sub-sample; nested comp markers on the precomp layer bar.
+
 ## Update: M4.5–M4.8 cached playback
 
 - **RAM preview keys** carry the render options (Fast Previews Draft / Fast Draft, Realtime