From e6391e0b3236ab435ce628aa85d688b1f2ca23a0 Mon Sep 17 00:00:00 2001
From: Savya Bikram Shah <tropedotuber@gmail.com>
Date: Wed, 27 May 2026 10:20:48 +0545
Subject: [PATCH] Readme update

---
 Readme.md | 46 +++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 41 insertions(+), 5 deletions(-)

diff --git a/Readme.md b/Readme.md
index 9ccfcf6..6a43be2 100644
--- a/Readme.md
+++ b/Readme.md
@@ -320,6 +320,30 @@ public readonly struct PaintCommandDTO {
 }
 ```
 
+### Paper (RT rig + input bridge)
+
+```csharp
+namespace Darkmatter.Core.Paper;
+
+public interface IPaperRig {
+    Camera ArtCamera { get; }              // offscreen, targetTexture = Surface
+    RenderTexture Surface { get; }         // 2048×2048 ARGB32; the paper itself
+    Transform PaperRoot { get; }           // parent of regions/pieces/paper bg
+    Vector2 DesignSize { get; }            // world units, e.g. (20, 20)
+    Rect DesignRect { get; }               // centered on origin, DesignSize wide
+}
+
+public interface IArtInputBridge {
+    // Converts a screen-space pointer (Input System) to art-world coords
+    // inside the RT. Returns false if the pointer is outside the RawImage.
+    bool TryScreenToArtWorld(Vector2 screenPos, out Vector2 artWorldPos);
+}
+```
+
+- `IPaperRig` is implemented by `PaperRig : MonoBehaviour` in the ColorBook scene.
+- `IArtInputBridge` does the screen → RawImage local → UV → `ArtCamera.ViewportToWorldPoint` chain.
+- All consumers (Coloring, ShapeBuilder, Capture, particle effects) read these from DI; they never touch `Screen.width/height` directly.
+
 ### History
 
 ```csharp
@@ -363,10 +387,14 @@ public interface IGalleryService {
 namespace Darkmatter.Core.Capture;
 
 public interface ICaptureService {
-    UniTask<byte[]> CaptureAsync(Camera artCamera, Sprite paperBackground, int width = 2048, int height = 2048);
+    // No camera or paperBg args — capture reads directly from IPaperRig.Surface.
+    // Dimensions inherited from the RT; no resize, no compositing.
+    UniTask<byte[]> CaptureAsync();
 }
 ```
 
+`ICaptureService` resolves `IPaperRig` via DI and reads `Surface` directly. The paper background is already baked into the RT because it sits in `PaperRoot` under the ArtCamera. No special compositing pass is ever needed.
+
 ### Signals
 
 ```csharp
@@ -404,19 +432,27 @@ public readonly struct ArtworkSavedSignal {
 - Presents a scrollable grid of thumbnails (Canvas).
 - On select → fires `DrawingSelectedSignal(templateId)` and unloads the catalog UI.
 
+### `Paper`
+
+- Scene-scoped infrastructure. Lives in `ColorBook.unity` only.
+- Owns `PaperRig` (MonoBehaviour) — exposes `ArtCamera`, the `RenderTexture Surface`, `PaperRoot` transform, and the design rect.
+- Owns `ArtInputBridge` — converts pointer screen positions to art-world coords inside the RT.
+- Registered in `ColorBookLifetimeScope` via `PaperRigModule`. All other features in the scene resolve `IPaperRig` / `IArtInputBridge` from DI.
+- Lifetime is scene-scoped: created on scene load, destroyed on scene unload. RT is allocated in `Awake`, released in `OnDestroy`.
+
 ### `ShapeBuilder`
 
 - Listens to `DrawingSelectedSignal`.
-- Loads template via `IDrawingTemplateLoader`, instantiates shape pieces at random off-slot positions.
-- Per piece: drag with `ShapePieceView` (sprite + collider). On drop, check distance to `SlotPosition` against `SnapRadius`; if within, snap and lock.
+- Loads template via `IDrawingTemplateLoader`, parents shape pieces under `IPaperRig.PaperRoot` at off-slot positions inside the design rect.
+- Per piece: drag with `ShapePieceView` (sprite + collider). Pointer events go through `IArtInputBridge.TryScreenToArtWorld`. On drop, check distance to `SlotPosition` against `SnapRadius`; if within, snap and lock.
 - Fires `ShapeAssembledSignal` when all pieces locked.
 
 ### `Coloring`
 
 - Listens to `ShapeAssembledSignal`.
-- Spawns one `ColorRegionView` per `ColorRegionDTO` (sprite + polygon collider on Artwork layer).
+- Spawns one `ColorRegionView` per `ColorRegionDTO` under `IPaperRig.PaperRoot` (sprite + polygon collider on `Artwork` layer).
 - Listens to palette selection (current color held in `ColoringStateRepository`).
-- On region tap: builds `PaintRegionCommand(regionId, oldColor, newColor)`, pushes to `IUndoStack`.
+- On pointer down: `IArtInputBridge.TryScreenToArtWorld(screenPos, out var artPos)` → `Physics2D.OverlapPoint(artPos, artworkMask)` → if hit, build `PaintRegionCommand(regionId, oldColor, newColor)`, push to `IUndoStack`.
 - Command sets `SpriteRenderer.color` on undo/redo.
 - Fires `ColorAppliedSignal` for SFX / sparkle effects.