SetNextWindowCached(key): opt-in cached windows on top of the refresh policy (skip contents while idle), t_cached_window test, README snippet

.github/README.md

@@ -244,6 +244,20 @@ Measured headless (Luau CLI, Studio-like native code generation), demo window op
 
 Most of the remaining cost is widget logic (your UI code and Dear ImGui's per-widget work), which runs every frame by design. Use `ImGuiListClipper` for long lists.
 
+Windows that rarely change can opt in to caching: `ImGui.SetNextWindowCached(key)` keeps last frame's drawing and makes `Begin` return `visible = false`, so your code for that window doesn't run. It refreshes when `key` changes, while the window is hovered, focused or active (plus one frame after), and when it appears, moves, resizes, scrolls, collapses or is docked. An idle 200-widget window goes from ~2.2 ms to ~0.15 ms per frame.
+
+```lua
+local stats = { version = 0, kills = 0 }
+local function StatsWindow()
+    ImGui.SetNextWindowCached(stats.version) -- bump stats.version whenever stats change
+    local _, visible = ImGui.Begin("Stats")
+    if visible then -- false while the cached contents are reused
+        ImGui.Text("Kills: %d", stats.kills)
+    end
+    ImGui.End()
+end
+```
+
 ### Testing
 
 `tools/test/run.py` runs any LocalScript headless against a mocked Roblox (`tools/test/roblox_mock.luau`):

.github/workflows/release.yml

@@ -47,6 +47,8 @@ jobs:
           luajit -bl dist/love-nodemo/imgui_love.lua > /dev/null
           python3 tools/test/run.py --main tools/test/scripts/t_readme.luau --frames 30 --quiet --roblox --timeout 300 | tee /tmp/r.txt
           grep -q "README OK" /tmp/r.txt
+          python3 tools/test/run.py --main tools/test/scripts/t_cached_window.luau --frames 130 --quiet --roblox --timeout 300 | tee /tmp/c.txt
+          grep -q "CACHED OK" /tmp/c.txt
           python3 tools/bundle.py --target love >/dev/null
           luajit tools/test/love/t_drawhash.lua 60 Widgets,Basic
           luajit tools/test/love/t_examples.lua