From a25e024d54ec3805d544f0d6b7729504020d2347 Mon Sep 17 00:00:00 2001
From: Hibryda <hibryda@protonmail.com>
Date: Thu, 19 Mar 2026 22:36:13 +0100
Subject: [PATCH] =?UTF-8?q?docs:=20add=20GPUI=20breakthrough=20(4.5%=20?=
 =?UTF-8?q?=E2=86=92=200.83%=20CPU)=20with=20shared-entity=20pattern?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/architecture/gpui-findings.md | 27 +++++++++++++++++++++++++--
 1 file changed, 25 insertions(+), 2 deletions(-)

diff --git a/docs/architecture/gpui-findings.md b/docs/architecture/gpui-findings.md
index d378fa9..c457c41 100644
--- a/docs/architecture/gpui-findings.md
+++ b/docs/architecture/gpui-findings.md
@@ -1,7 +1,30 @@
 # GPUI Framework — Detailed Findings
 
-**Date:** 2026-03-19
-**Source:** Hands-on prototyping (ui-gpui/, 2,490 lines) + source code analysis of GPUI 0.2.2 + Zed editor
+**Date:** 2026-03-19 (updated 2026-03-19 22:30)
+**Source:** Hands-on prototyping (ui-gpui/, 2,490 lines) + source code analysis of GPUI 0.2.2 + Zed editor + 4 parallel research agents
+
+## BREAKTHROUGH: 4.5% → 0.83% CPU
+
+**The #1 optimization rule in GPUI:** Never make animated state an Entity CHILD of the view that renders it. Make it a PEER Entity that the view READS.
+
+```
+WRONG (4.5% CPU):
+  Workspace → ProjectGrid → ProjectBox → PulsingDot (child Entity)
+  cx.notify() on PulsingDot → mark_view_dirty walks ancestors
+  → Workspace dirty → refreshing=true → ALL .cached() children miss
+
+RIGHT (0.83% CPU):
+  Workspace → ProjectGrid → ProjectBox (reads BlinkState)
+  BlinkState (peer Entity, not child)
+  cx.notify() on BlinkState → only dirties views that .read(cx) it
+  → ProjectBox dirty, Workspace/ProjectGrid NOT dirty → siblings cached
+```
+
+Key mechanisms:
+1. **`.cached(StyleRefinement::default())`** on Entity children → GPU scene replay (zero Rust code)
+2. **Shared state Entity** instead of child Entity → isolates dirty propagation
+3. **`mark_view_dirty()` walks ancestors** — this is GPUI's fundamental constraint
+4. **`refreshing=true` on cache miss** cascades down → children can't cache if parent is dirty
 
 ## Overview