From cd767445129bf5c32c9e5ef043704b91d9f0f908 Mon Sep 17 00:00:00 2001
From: Ruben Nogueira <40404708+rubnogueira@users.noreply.github.com>
Date: Sat, 10 Oct 2026 12:19:32 +0100
Subject: [PATCH 01/27] perf(react): skip unchanged style and custom prop
 updates

---
 .changeset/skip-unchanged-style-updates.md    |  10 ++
 packages/native/js/mutations.ts               |  43 +++++
 .../src/__tests__/mutation-lifecycle.test.tsx |  49 ++++++
 .../src/__tests__/style-updates.test.tsx      | 157 ++++++++++++++++++
 packages/react/src/reconciler/host-config.ts  |  96 ++++++++---
 5 files changed, 333 insertions(+), 22 deletions(-)
 create mode 100644 .changeset/skip-unchanged-style-updates.md
 create mode 100644 packages/react/src/__tests__/style-updates.test.tsx

diff --git a/.changeset/skip-unchanged-style-updates.md b/.changeset/skip-unchanged-style-updates.md
new file mode 100644
index 000000000..2e5ae6e1d
--- /dev/null
+++ b/.changeset/skip-unchanged-style-updates.md
@@ -0,0 +1,10 @@
+---
+'@gpuix/react': patch
+'@gpuix/native': patch
+---
+
+A re-render no longer resends styles and custom props that did not change. React calls `commitUpdate` for every element a parent re-rendered, and the reconciler used to serialize and send each one's `style` every time, which cost a JSON round trip and a style intern per element per commit. It now compares values, so `style={{ ... }}` rebuilt with the same contents sends nothing. The custom prop diff is also linear instead of quadratic in the number of props.
+
+A style change on an element React has hidden (Suspense, Activity) no longer makes it visible again: it keeps `visibility: hidden` until React unhides it.
+
+`@gpuix/native/host` exports `sameMutationValue(left, right)` for adapters that diff the same payloads.
diff --git a/packages/native/js/mutations.ts b/packages/native/js/mutations.ts
index 8168ef0bd..857eebff8 100644
--- a/packages/native/js/mutations.ts
+++ b/packages/native/js/mutations.ts
@@ -133,6 +133,49 @@ export function isReservedProp(name: string): boolean {
   return RESERVED_PROPS.has(name) || EVENT_PROP_NAMES.has(name)
 }
 
+/**
+ * Structural equality for the JSON values a mutation carries: styles and
+ * custom props. A key whose value is `undefined` counts as absent, because
+ * `JSON.stringify` drops it, so `{ color: undefined }` and `{}` reach Rust as
+ * the same payload and must compare equal here.
+ *
+ * Only plain objects, arrays and primitives are compared. A function or class
+ * instance is equal to itself and nothing else.
+ */
+export function sameMutationValue(left: unknown, right: unknown): boolean {
+  if (left === right) return true
+  // NaN serializes to null on both sides, and -0 to 0, so neither is a change.
+  if (typeof left === "number" && typeof right === "number") return left !== left && right !== right
+  if (typeof left !== "object" || typeof right !== "object" || left === null || right === null) {
+    return false
+  }
+  if (Array.isArray(left)) {
+    if (!Array.isArray(right) || left.length !== right.length) return false
+    for (let index = 0; index < left.length; index++) {
+      if (!sameMutationValue(left[index], right[index])) return false
+    }
+    return true
+  }
+  if (Array.isArray(right)) return false
+  const leftProto = Object.getPrototypeOf(left)
+  if (leftProto !== Object.prototype && leftProto !== null) return false
+  if (Object.getPrototypeOf(right) !== leftProto) return false
+  const leftRecord = left as Record<string, unknown>
+  const rightRecord = right as Record<string, unknown>
+  let defined = 0
+  for (const key in leftRecord) {
+    const value = leftRecord[key]
+    if (value === undefined) continue
+    defined++
+    if (!sameMutationValue(value, rightRecord[key])) return false
+  }
+  let rightDefined = 0
+  for (const key in rightRecord) {
+    if (rightRecord[key] !== undefined) rightDefined++
+  }
+  return defined === rightDefined
+}
+
 export function serializeCustomProp(
   value: object | string | number | boolean | null | undefined
 ): string | object | number | boolean | null {
diff --git a/packages/react/src/__tests__/mutation-lifecycle.test.tsx b/packages/react/src/__tests__/mutation-lifecycle.test.tsx
index 76eedf5c7..99e55aa82 100644
--- a/packages/react/src/__tests__/mutation-lifecycle.test.tsx
+++ b/packages/react/src/__tests__/mutation-lifecycle.test.tsx
@@ -71,6 +71,55 @@ describe("host config hideInstance", () => {
     hostConfig.unhideInstance(instance, props)
     expect(renderer.styles.at(-1)).toEqual(props.style)
   })
+
+  function hiddenFixture(props: Props) {
+    const renderer = recordingRenderer()
+    const container: Container = {
+      nativeRenderer: {},
+      renderer,
+      ids: { nextElementId: 0 },
+      eventHandlers: new Map(),
+      windowKeyEventHandlers: {},
+      windowKeyEventId: 0,
+      windowSelectionEventId: 0,
+    }
+    const instance = hostConfig.createInstance(
+      "div",
+      props,
+      container,
+      null as unknown as HostContext
+    )
+    return { renderer, instance }
+  }
+
+  it("keeps an element hidden when its style changes", () => {
+    const before: Props = { style: { width: 80, hover: { backgroundColor: "#a6e3a1" } } }
+    const after: Props = { style: { width: 120, hover: { backgroundColor: "#a6e3a1" } } }
+    const { renderer, instance } = hiddenFixture(before)
+
+    hostConfig.hideInstance(instance)
+    hostConfig.commitUpdate(instance, "div", before, after, null)
+    expect(renderer.styles.at(-1)).toEqual({ width: 120, visibility: "hidden" })
+
+    hostConfig.unhideInstance(instance, after)
+    expect(renderer.styles.at(-1)).toEqual(after.style)
+  })
+
+  it("does not resend an unchanged style while hidden", () => {
+    const { renderer, instance } = hiddenFixture({ style: { width: 80 } })
+    hostConfig.hideInstance(instance)
+    const sent = renderer.styles.length
+
+    hostConfig.commitUpdate(
+      instance,
+      "div",
+      { style: { width: 80 } },
+      { style: { width: 80 } },
+      null
+    )
+
+    expect(renderer.styles).toHaveLength(sent)
+  })
 })
 
 describeNative("mutation lifecycle", () => {
diff --git a/packages/react/src/__tests__/style-updates.test.tsx b/packages/react/src/__tests__/style-updates.test.tsx
new file mode 100644
index 000000000..98a14edbe
--- /dev/null
+++ b/packages/react/src/__tests__/style-updates.test.tsx
@@ -0,0 +1,157 @@
+import { describe, expect, it } from "vitest"
+import { createTestRoot, hasNativeTestRenderer } from "../testing.js"
+
+const describeNative = hasNativeTestRenderer ? describe : describe.skip
+
+type Op = [string, ...unknown[]]
+
+/** Every op that crossed into Rust, per `applyBatch` call. */
+function recordBatches(renderer: { applyBatch(json: string): unknown }) {
+  const batches: Op[][] = []
+  const original = renderer.applyBatch.bind(renderer)
+  renderer.applyBatch = (json: string) => {
+    batches.push(JSON.parse(json) as Op[])
+    return original(json)
+  }
+  return {
+    batches,
+    ops: (name: string) => batches.flat().filter((op) => op[0] === name),
+    clear: () => {
+      batches.length = 0
+    },
+  }
+}
+
+describeNative("style and custom prop updates", () => {
+  it("sends nothing when a re-render rebuilds an equal style object", () => {
+    const { render, renderer, unmount } = createTestRoot()
+    const view = (color: string) => (
+      <div style={{ width: 100, height: 40, backgroundColor: "#111", hover: { backgroundColor: color } }}>
+        <text style={{ color: "#fff" }}>hello</text>
+      </div>
+    )
+    try {
+      render(view("#222"))
+      const sent = recordBatches(renderer)
+
+      render(view("#222"))
+      render(view("#222"))
+
+      expect(sent.batches).toEqual([])
+    } finally {
+      unmount()
+    }
+  })
+
+  it("sends only the element whose style changed", () => {
+    const { render, renderer, unmount } = createTestRoot()
+    const view = (hovered: string) => (
+      <div style={{ width: 100, height: 40 }}>
+        <div style={{ height: 10, backgroundColor: "#111" }} />
+        <div style={{ height: 10, backgroundColor: hovered }} />
+      </div>
+    )
+    try {
+      render(view("#222"))
+      const sent = recordBatches(renderer)
+
+      render(view("#333"))
+
+      const styles = sent.ops("setStyle")
+      expect(styles).toHaveLength(1)
+      expect(styles[0]![2]).toEqual({ height: 10, backgroundColor: "#333" })
+    } finally {
+      unmount()
+    }
+  })
+
+  it("reaches a changed nested state style", () => {
+    const { render, renderer, unmount } = createTestRoot()
+    const view = (hover: string) => (
+      <div style={{ width: 100, height: 40, hover: { backgroundColor: hover } }} />
+    )
+    try {
+      render(view("#222"))
+      const sent = recordBatches(renderer)
+
+      render(view("#444"))
+
+      expect(sent.ops("setStyle")).toHaveLength(1)
+    } finally {
+      unmount()
+    }
+  })
+
+  it("resets a style that was removed", () => {
+    const { render, renderer, unmount } = createTestRoot()
+    try {
+      render(<div style={{ width: 100, height: 40, backgroundColor: "#111" }} />)
+      const sent = recordBatches(renderer)
+
+      render(<div />)
+
+      const styles = sent.ops("setStyle")
+      expect(styles).toHaveLength(1)
+      expect(styles[0]![2]).toEqual({})
+    } finally {
+      unmount()
+    }
+  })
+
+  it("treats an undefined style value as absent", () => {
+    const { render, renderer, unmount } = createTestRoot()
+    try {
+      render(<div style={{ width: 100, height: 40, backgroundColor: undefined }} />)
+      const sent = recordBatches(renderer)
+
+      render(<div style={{ width: 100, height: 40 }} />)
+
+      expect(sent.batches).toEqual([])
+    } finally {
+      unmount()
+    }
+  })
+
+  it("sends a custom prop once per change, not once per render", () => {
+    const { render, renderer, unmount } = createTestRoot()
+    const view = (label: string, handler: () => void) => (
+      <div
+        aria-label={label}
+        highlight={{ query: "needle" }}
+        onClick={handler}
+        style={{ width: 100, height: 40 }}
+      />
+    )
+    try {
+      render(view("one", () => {}))
+      const sent = recordBatches(renderer)
+
+      // A new handler and a new but equal `highlight` object on every render.
+      render(view("one", () => {}))
+      expect(sent.ops("setCustomProp")).toEqual([])
+
+      render(view("two", () => {}))
+      const props = sent.ops("setCustomProp")
+      expect(props).toHaveLength(1)
+      expect(props[0]!.slice(2)).toEqual(["aria-label", "two"])
+    } finally {
+      unmount()
+    }
+  })
+
+  it("clears a custom prop that is no longer passed", () => {
+    const { render, renderer, unmount } = createTestRoot()
+    try {
+      render(<div aria-label="one" style={{ width: 100, height: 40 }} />)
+      const sent = recordBatches(renderer)
+
+      render(<div style={{ width: 100, height: 40 }} />)
+
+      const props = sent.ops("setCustomProp")
+      expect(props).toHaveLength(1)
+      expect(props[0]!.slice(2)).toEqual(["aria-label", null])
+    } finally {
+      unmount()
+    }
+  })
+})
diff --git a/packages/react/src/reconciler/host-config.ts b/packages/react/src/reconciler/host-config.ts
index c13318d79..8c875c430 100644
--- a/packages/react/src/reconciler/host-config.ts
+++ b/packages/react/src/reconciler/host-config.ts
@@ -10,6 +10,7 @@ import {
   BUILT_IN_TYPES,
   EVENT_PROPS,
   isReservedProp,
+  sameMutationValue,
   serializeCustomProp,
   UNIVERSAL_PROPS,
 } from "@gpuix/native/host"
@@ -40,6 +41,12 @@ interface HostNodeState {
   container: Container
   initialChildren: HostNode[]
   mounted: boolean
+  /**
+   * React hid this element (Suspense, Activity). Its native style carries
+   * `visibility: hidden`, so a style update must keep that rather than
+   * overwrite it with the visible one.
+   */
+  hidden: boolean
 }
 
 const hostNodeStates = new WeakMap<HostNode, HostNodeState>()
@@ -123,12 +130,36 @@ function diffEventListeners(
 
 // ── Style helper ─────────────────────────────────────────────────────
 
+const NO_STYLE = {}
+
 function sendStyle(renderer: MutationRenderer, id: number, props: Props): void {
   const style = props.style
   if (style == null || Object.keys(style).length === 0) return
   renderer.setStyle(id, style)
 }
 
+/**
+ * Whether two `style` props reach Rust as the same payload. An absent style and
+ * an empty one are the same, and so are two objects holding the same values:
+ * `style={{ ... }}` is a new object on every render, so reference equality
+ * alone would resend every styled element on every commit.
+ *
+ * Like React DOM, this does not see a style object mutated in place and passed
+ * again. Pass a new object when a style changes.
+ */
+function sameStyle(left: Props["style"], right: Props["style"]): boolean {
+  return left === right || sameMutationValue(left ?? NO_STYLE, right ?? NO_STYLE)
+}
+
+/** The style a hidden element keeps: its own, minus the states, plus `visibility: hidden`. */
+function hiddenStyle(style: Props["style"]) {
+  // Hover and active go, because a hidden element must stay hidden. A hover
+  // style that sets `visibility` would otherwise paint an element React
+  // asked to hide.
+  const { hover: _hover, active: _active, ...base } = style ?? {}
+  return { ...base, visibility: "hidden" }
+}
+
 // ── Custom prop forwarding ───────────────────────────────────────────
 
 // Props that are handled by the reconciler directly (not forwarded as custom props).
@@ -147,7 +178,13 @@ function syncCustomProps(
   }
 }
 
-/** Diff and send changed custom props to Rust. */
+/**
+ * Diff and send changed custom props to Rust.
+ *
+ * Compared by value after serialization: a handler or an inline object is new on
+ * every render, and a function serializes to `null` either way, so resending it
+ * would only make Rust parse and discard the same value again.
+ */
 function diffCustomProps(
   renderer: MutationRenderer,
   id: number,
@@ -156,24 +193,32 @@ function diffCustomProps(
   newProps: Props
 ): void {
   const builtIn = BUILT_IN_TYPES.has(type)
-  const oldEntries = Object.entries(oldProps)
-  const newKeys = Object.keys(newProps)
+  const previous = oldProps as Record<string, unknown>
+  const next = newProps as Record<string, unknown>
   // Updated or added props
-  for (const [key, value] of Object.entries(newProps)) {
+  for (const key in next) {
     if (isReservedProp(key)) continue
     if (builtIn && !UNIVERSAL_PROPS.has(key)) continue
-    const oldValue = oldEntries.find(([oldKey]) => oldKey === key)?.[1]
-    if (oldValue !== value) {
-      renderer.setCustomProp(id, key, serializeCustomProp(value))
+    const value = next[key]
+    const oldValue = previous[key]
+    if (value === oldValue) continue
+    const serialized = serializeCustomProp(value as Parameters<typeof serializeCustomProp>[0])
+    if (
+      key in previous &&
+      sameMutationValue(
+        serializeCustomProp(oldValue as Parameters<typeof serializeCustomProp>[0]),
+        serialized
+      )
+    ) {
+      continue
     }
+    renderer.setCustomProp(id, key, serialized)
   }
   // Removed props
-  for (const key of Object.keys(oldProps)) {
+  for (const key in previous) {
     if (isReservedProp(key)) continue
     if (builtIn && !UNIVERSAL_PROPS.has(key)) continue
-    if (!newKeys.includes(key)) {
-      renderer.setCustomProp(id, key, null)
-    }
+    if (!(key in next)) renderer.setCustomProp(id, key, null)
   }
 }
 
@@ -189,7 +234,8 @@ function materialize(node: HostNode): HostNodeState {
   const renderer = state.container.renderer
   if ("type" in node) {
     renderer.createElement(node.id, node.type)
-    sendStyle(renderer, node.id, node.props)
+    if (state.hidden) renderer.setStyle(node.id, hiddenStyle(node.props.style))
+    else sendStyle(renderer, node.id, node.props)
     syncEventListeners(state.container, node.id, node.props)
     syncCustomProps(renderer, node.id, node.type, node.props)
   } else {
@@ -231,6 +277,7 @@ export const hostConfig = {
       container: rootContainerInstance,
       initialChildren: [],
       mounted: false,
+      hidden: false,
     })
     return instance
   },
@@ -318,6 +365,7 @@ export const hostConfig = {
       container: rootContainerInstance,
       initialChildren: [],
       mounted: false,
+      hidden: false,
     })
     return instance
   },
@@ -354,10 +402,17 @@ export const hostConfig = {
     newProps: Props,
     _internalInstanceHandle: unknown
   ): void {
-    const container = containerFor(instance)
-    // Always resend style — per-element JSON is small, and this avoids
-    // bugs from same-reference mutations or style removal.
-    container.renderer.setStyle(instance.id, newProps.style ?? {})
+    const state = stateFor(instance)
+    const { container } = state
+    // `commitUpdate` runs for every host element whose props object is new,
+    // which is every element a parent re-rendered. Most of those did not change
+    // their style, so send it only when it did.
+    if (!sameStyle(oldProps.style, newProps.style)) {
+      container.renderer.setStyle(
+        instance.id,
+        state.hidden ? hiddenStyle(newProps.style) : (newProps.style ?? {})
+      )
+    }
     diffEventListeners(container, instance.id, oldProps, newProps)
     // Custom prop diff (for non-div/text elements)
     diffCustomProps(container.renderer, instance.id, instance.type, oldProps, newProps)
@@ -386,15 +441,12 @@ export const hostConfig = {
     // Keep the element's own style. `visibility: hidden` skips the paint and
     // keeps the layout box, so replacing the whole style here would collapse
     // the box and lose every other style on the element.
-    //
-    // Hover and active go, because a hidden element must stay hidden. A hover
-    // style that sets `visibility` would otherwise paint an element React
-    // asked to hide.
-    const { hover: _hover, active: _active, ...base } = instance.props.style ?? {}
-    rendererFor(instance).setStyle(instance.id, { ...base, visibility: "hidden" })
+    stateFor(instance).hidden = true
+    rendererFor(instance).setStyle(instance.id, hiddenStyle(instance.props.style))
   },
 
   unhideInstance(instance: Instance, props: Props): void {
+    stateFor(instance).hidden = false
     rendererFor(instance).setStyle(instance.id, props.style ?? {})
   },
 

From b5789d916be2f7782c365f875d3a5ca4fe489149 Mon Sep 17 00:00:00 2001
From: Ruben Nogueira <40404708+rubnogueira@users.noreply.github.com>
Date: Sat, 10 Oct 2026 17:00:29 +0100
Subject: [PATCH 02/27] perf(react): diff event handlers over the props an
 element has

---
 .changeset/skip-unchanged-style-updates.md    |  5 +-
 packages/native/js/mutations.ts               |  7 ++
 .../src/__tests__/event-updates.test.tsx      | 86 +++++++++++++++++++
 packages/react/src/reconciler/host-config.ts  | 48 ++++++++---
 packages/solid/src/host.ts                    |  4 +-
 5 files changed, 136 insertions(+), 14 deletions(-)
 create mode 100644 packages/react/src/__tests__/event-updates.test.tsx

diff --git a/.changeset/skip-unchanged-style-updates.md b/.changeset/skip-unchanged-style-updates.md
index 2e5ae6e1d..87bd84890 100644
--- a/.changeset/skip-unchanged-style-updates.md
+++ b/.changeset/skip-unchanged-style-updates.md
@@ -1,10 +1,11 @@
 ---
 '@gpuix/react': patch
 '@gpuix/native': patch
+'@gpuix/solid': patch
 ---
 
-A re-render no longer resends styles and custom props that did not change. React calls `commitUpdate` for every element a parent re-rendered, and the reconciler used to serialize and send each one's `style` every time, which cost a JSON round trip and a style intern per element per commit. It now compares values, so `style={{ ... }}` rebuilt with the same contents sends nothing. The custom prop diff is also linear instead of quadratic in the number of props.
+A re-render no longer resends styles and custom props that did not change. React calls `commitUpdate` for every element a parent re-rendered, and the reconciler used to serialize and send each one's `style` every time, which cost a JSON round trip and a style intern per element per commit. It now compares values, so `style={{ ... }}` rebuilt with the same contents sends nothing. The custom prop diff is linear instead of quadratic in the number of props, and the event handler diff walks the props an element has instead of every event GPUIX knows.
 
 A style change on an element React has hidden (Suspense, Activity) no longer makes it visible again: it keeps `visibility: hidden` until React unhides it.
 
-`@gpuix/native/host` exports `sameMutationValue(left, right)` for adapters that diff the same payloads.
+`@gpuix/native/host` exports `sameMutationValue(left, right)` and `EVENT_TYPE_BY_PROP` for adapters that diff the same payloads.
diff --git a/packages/native/js/mutations.ts b/packages/native/js/mutations.ts
index 857eebff8..ebf06411d 100644
--- a/packages/native/js/mutations.ts
+++ b/packages/native/js/mutations.ts
@@ -103,6 +103,13 @@ export const EVENT_PROP_NAMES: ReadonlySet<string> = new Set(
   EVENT_PROPS.map(([name]) => name)
 )
 
+/**
+ * Event type for a handler prop. Adapters walk an element's own props and look
+ * each one up here, which beats testing every entry of `EVENT_PROPS` against an
+ * element that has two or three props.
+ */
+export const EVENT_TYPE_BY_PROP: ReadonlyMap<string, string> = new Map(EVENT_PROPS)
+
 export const RESERVED_PROPS: ReadonlySet<string> = new Set([
   "style",
   "className",
diff --git a/packages/react/src/__tests__/event-updates.test.tsx b/packages/react/src/__tests__/event-updates.test.tsx
new file mode 100644
index 000000000..3480fb986
--- /dev/null
+++ b/packages/react/src/__tests__/event-updates.test.tsx
@@ -0,0 +1,86 @@
+import { describe, expect, it, vi } from "vitest"
+import { createTestRoot, hasNativeTestRenderer } from "../testing.js"
+
+const describeNative = hasNativeTestRenderer ? describe : describe.skip
+
+const box = { width: 100, height: 100 }
+
+describeNative("event handler updates", () => {
+  it("wires a handler added on a later render", () => {
+    const { render, renderer, unmount } = createTestRoot()
+    const onClick = vi.fn()
+    try {
+      render(<div style={box} />)
+      renderer.nativeSimulateClick(10, 10)
+      expect(onClick).not.toHaveBeenCalled()
+
+      render(<div style={box} onClick={onClick} />)
+      renderer.nativeSimulateClick(10, 10)
+      expect(onClick).toHaveBeenCalledTimes(1)
+    } finally {
+      unmount()
+    }
+  })
+
+  it("calls only the latest handler after it is replaced", () => {
+    const { render, renderer, unmount } = createTestRoot()
+    const first = vi.fn()
+    const second = vi.fn()
+    try {
+      render(<div style={box} onClick={first} />)
+      render(<div style={box} onClick={second} />)
+      renderer.nativeSimulateClick(10, 10)
+
+      expect(first).not.toHaveBeenCalled()
+      expect(second).toHaveBeenCalledTimes(1)
+    } finally {
+      unmount()
+    }
+  })
+
+  it("stops calling a handler whose prop is no longer passed", () => {
+    const { render, renderer, unmount } = createTestRoot()
+    const onClick = vi.fn()
+    try {
+      render(<div style={box} onClick={onClick} />)
+      render(<div style={box} />)
+      renderer.nativeSimulateClick(10, 10)
+
+      expect(onClick).not.toHaveBeenCalled()
+      expect(renderer.findByType("div")[0]!.events.has("click")).toBe(false)
+    } finally {
+      unmount()
+    }
+  })
+
+  it("stops calling a handler that is set to undefined", () => {
+    const { render, renderer, unmount } = createTestRoot()
+    const onClick = vi.fn()
+    try {
+      render(<div style={box} onClick={onClick} />)
+      render(<div style={box} onClick={undefined} />)
+      renderer.nativeSimulateClick(10, 10)
+
+      expect(onClick).not.toHaveBeenCalled()
+      expect(renderer.findByType("div")[0]!.events.has("click")).toBe(false)
+    } finally {
+      unmount()
+    }
+  })
+
+  it("keeps handlers for other events when one is removed", () => {
+    const { render, renderer, unmount } = createTestRoot()
+    const onClick = vi.fn()
+    const onMouseDown = vi.fn()
+    try {
+      render(<div style={box} onClick={onClick} onMouseDown={onMouseDown} />)
+      render(<div style={box} onMouseDown={onMouseDown} />)
+
+      const events = renderer.findByType("div")[0]!.events
+      expect(events.has("click")).toBe(false)
+      expect(events.has("mouseDown")).toBe(true)
+    } finally {
+      unmount()
+    }
+  })
+})
diff --git a/packages/react/src/reconciler/host-config.ts b/packages/react/src/reconciler/host-config.ts
index 8c875c430..5a5a21ce8 100644
--- a/packages/react/src/reconciler/host-config.ts
+++ b/packages/react/src/reconciler/host-config.ts
@@ -6,9 +6,10 @@
 
 import { createContext } from "react"
 import { DefaultEventPriority } from "react-reconciler/constants.js"
+import type { HostEventHandler } from "@gpuix/native/host"
 import {
   BUILT_IN_TYPES,
-  EVENT_PROPS,
+  EVENT_TYPE_BY_PROP,
   isReservedProp,
   sameMutationValue,
   serializeCustomProp,
@@ -97,35 +98,62 @@ function nextId(container: Container): number {
 // ── Event wiring helpers ─────────────────────────────────────────────
 
 function syncEventListeners(container: Container, id: number, props: Props): void {
-  for (const [propName, eventType] of EVENT_PROPS) {
-    const handler = props[propName]
-    if (handler) {
-      registerEventHandler(container.eventHandlers, id, eventType, handler)
+  const record = props as Record<string, unknown>
+  for (const propName in record) {
+    const eventType = EVENT_TYPE_BY_PROP.get(propName)
+    const handler = record[propName]
+    if (eventType && handler) {
+      registerEventHandler(
+        container.eventHandlers,
+        id,
+        eventType,
+        handler as HostEventHandler
+      )
       container.renderer.setEventListener(id, eventType, true)
     }
   }
 }
 
+/**
+ * Walks the props an element has, not every event GPUIX knows: this runs for
+ * each re-rendered host element, and most have a few props and no handlers.
+ */
 function diffEventListeners(
   container: Container,
   id: number,
   oldProps: Props,
   newProps: Props
 ): void {
-  for (const [propName, eventType] of EVENT_PROPS) {
-    const oldHandler = oldProps[propName]
-    const newHandler = newProps[propName]
-
+  const previous = oldProps as Record<string, unknown>
+  const next = newProps as Record<string, unknown>
+  for (const propName in next) {
+    const eventType = EVENT_TYPE_BY_PROP.get(propName)
+    if (!eventType) continue
+    const oldHandler = previous[propName]
+    const newHandler = next[propName]
     if (oldHandler && !newHandler) {
       unregisterEventHandler(container.eventHandlers, id, eventType)
       container.renderer.setEventListener(id, eventType, false)
     } else if (newHandler && newHandler !== oldHandler) {
-      registerEventHandler(container.eventHandlers, id, eventType, newHandler)
+      registerEventHandler(
+        container.eventHandlers,
+        id,
+        eventType,
+        newHandler as HostEventHandler
+      )
       if (!oldHandler) {
         container.renderer.setEventListener(id, eventType, true)
       }
     }
   }
+  for (const propName in previous) {
+    if (propName in next) continue
+    const eventType = EVENT_TYPE_BY_PROP.get(propName)
+    if (eventType && previous[propName]) {
+      unregisterEventHandler(container.eventHandlers, id, eventType)
+      container.renderer.setEventListener(id, eventType, false)
+    }
+  }
 }
 
 // ── Style helper ─────────────────────────────────────────────────────
diff --git a/packages/solid/src/host.ts b/packages/solid/src/host.ts
index 36b12a876..32d690a42 100644
--- a/packages/solid/src/host.ts
+++ b/packages/solid/src/host.ts
@@ -2,8 +2,8 @@
 // native elements and event contract.
 import {
   BUILT_IN_TYPES,
-  EVENT_PROPS,
   EVENT_PROP_NAMES,
+  EVENT_TYPE_BY_PROP,
   UNIVERSAL_PROPS,
   registerEventHandler,
   serializeCustomProp,
@@ -146,7 +146,7 @@ export function replaceHostText(node: HostText, value: string): void {
 }
 
 function eventTypeFor(name: string): string | undefined {
-  return EVENT_PROPS.find(([prop]) => prop === name)?.[1]
+  return EVENT_TYPE_BY_PROP.get(name)
 }
 
 function customPropAllowed(node: HostElement, name: string): boolean {

From d47fb1d23363505ee16bb399432c5a4d49c87fff Mon Sep 17 00:00:00 2001
From: Ruben Nogueira <40404708+rubnogueira@users.noreply.github.com>
Date: Sat, 10 Oct 2026 17:00:37 +0100
Subject: [PATCH 03/27] feat(react): createPortal mounts children into an
 element

---
 .changeset/create-portal.md                  |   5 +
 README.md                                    |  32 ++++++
 packages/react/src/__tests__/portal.test.tsx | 102 +++++++++++++++++++
 packages/react/src/index.ts                  |   1 +
 packages/react/src/reconciler/host-config.ts |  44 +++++++-
 packages/react/src/reconciler/portal.ts      |  39 +++++++
 packages/react/src/types/host.ts             |   7 ++
 7 files changed, 225 insertions(+), 5 deletions(-)
 create mode 100644 .changeset/create-portal.md
 create mode 100644 packages/react/src/__tests__/portal.test.tsx
 create mode 100644 packages/react/src/reconciler/portal.ts

diff --git a/.changeset/create-portal.md b/.changeset/create-portal.md
new file mode 100644
index 000000000..c9cc5e39e
--- /dev/null
+++ b/.changeset/create-portal.md
@@ -0,0 +1,5 @@
+---
+'@gpuix/react': minor
+---
+
+Added `createPortal(children, target)`, which mounts children into an element that is already mounted. Take `target` from a `ref`. The portal's children are appended to the target and kept in key order, so a toast layer, a drag preview or an overlay root no longer needs a patched host config. See "Portals" in the README.
diff --git a/README.md b/README.md
index ac02e031e..67140175b 100644
--- a/README.md
+++ b/README.md
@@ -2209,6 +2209,38 @@ A filled child of a click target (switch thumb, radio dot, check icon) needs
 **`pointerEvents: "none"`**, or it eats the parent's click. For Select and
 Combobox rows, use the item primitive's `asChild` prop instead.
 
+### Portals
+
+`createPortal(children, target)` mounts `children` as the children of an element
+that is already mounted, wherever the calling component sits in the tree. Use it
+for a toast layer, a drag preview, or any content that belongs to another part of
+the window. Context still flows from the caller, as in React DOM.
+
+Take `target` from a `ref` and render the portal once it is set. A portal into an
+element that has not mounted has nowhere to attach.
+
+```tsx
+import { createPortal, type PublicInstance } from '@gpuix/react'
+
+function Screen() {
+  const [layer, setLayer] = useState<PublicInstance | null>(null)
+  return (
+    <>
+      <div ref={setLayer} style={{ position: 'absolute', top: 0, right: 0, bottom: 0, left: 0 }} />
+      <Sidebar>{layer && createPortal(<Toast />, layer)}</Sidebar>
+    </>
+  )
+}
+```
+
+The portal's children are appended after whatever the target already holds, and
+React keeps them in key order among themselves. `target` must belong to the same
+root as the component that calls `createPortal`.
+
+For floating menus that must paint above a `<virtual-list>`, use
+[`<anchored>`](#overlay-menus) rather than a portal: a portal changes where
+elements live in the tree, not the order gpui paints them in.
+
 ### Measure an element
 
 `getElementBounds(id)` returns the last painted box, or `null` if that node did
diff --git a/packages/react/src/__tests__/portal.test.tsx b/packages/react/src/__tests__/portal.test.tsx
new file mode 100644
index 000000000..22eb59599
--- /dev/null
+++ b/packages/react/src/__tests__/portal.test.tsx
@@ -0,0 +1,102 @@
+import { useState } from "react"
+import { describe, expect, it } from "vitest"
+import { createPortal } from "../reconciler/portal.js"
+import { createTestRoot, hasNativeTestRenderer } from "../testing.js"
+import type { PublicInstance } from "../types/host.js"
+
+const describeNative = hasNativeTestRenderer ? describe : describe.skip
+
+function Screen({ items, mounted = true }: { items: string[]; mounted?: boolean }) {
+  const [layer, setLayer] = useState<PublicInstance | null>(null)
+  return (
+    <div style={{ width: 200, height: 200 }}>
+      <div testId="layer" ref={setLayer} style={{ width: 100, height: 100 }} />
+      <div testId="lexical-parent" style={{ width: 100, height: 20 }}>
+        {mounted &&
+          layer &&
+          createPortal(
+            items.map((item) => (
+              <text key={item} testId={`item-${item}`}>
+                {item}
+              </text>
+            )),
+            layer
+          )}
+      </div>
+    </div>
+  )
+}
+
+describeNative("createPortal", () => {
+  it("mounts its children under the target element, not the lexical parent", () => {
+    const { render, renderer, unmount } = createTestRoot()
+    try {
+      render(<Screen items={["a", "b"]} />)
+
+      const layer = renderer.findByTestId("layer")!
+      const a = renderer.findByTestId("item-a")!
+      const b = renderer.findByTestId("item-b")!
+
+      expect(layer.children).toEqual([a.id, b.id])
+      expect(a.parentId).toBe(layer.id)
+      expect(renderer.findByTestId("lexical-parent")!.children).toEqual([])
+      expect(renderer.getPaintedText()).toEqual(["a", "b"])
+    } finally {
+      unmount()
+    }
+  })
+
+  it("places a child React inserts before another one in that order", () => {
+    const { render, renderer, unmount } = createTestRoot()
+    try {
+      render(<Screen items={["b", "c"]} />)
+      const b = renderer.findByTestId("item-b")!
+      const c = renderer.findByTestId("item-c")!
+
+      render(<Screen items={["a", "b", "c"]} />)
+      render(<Screen items={["a", "b", "x", "c"]} />)
+
+      const layer = renderer.findByTestId("layer")!
+      const ids = (names: string[]) => names.map((name) => renderer.findByTestId(`item-${name}`)!.id)
+      expect(layer.children).toEqual(ids(["a", "b", "x", "c"]))
+      // Neighbours are updated in place, not remounted.
+      expect(renderer.findByTestId("item-b")!.id).toBe(b.id)
+      expect(renderer.findByTestId("item-c")!.id).toBe(c.id)
+    } finally {
+      unmount()
+    }
+  })
+
+  it("keeps the portal mounted across re-renders", () => {
+    const { render, renderer, unmount } = createTestRoot()
+    try {
+      render(<Screen items={["a"]} />)
+      const first = renderer.findByTestId("item-a")!.id
+
+      render(<Screen items={["a"]} />)
+      render(<Screen items={["a"]} />)
+
+      expect(renderer.findByTestId("item-a")!.id).toBe(first)
+    } finally {
+      unmount()
+    }
+  })
+
+  it("frees the portal's elements when it unmounts", () => {
+    const { render, renderer, unmount } = createTestRoot()
+    try {
+      render(<Screen items={["a", "b"]} mounted={false} />)
+      const without = renderer.getRetainedElementCount()
+
+      render(<Screen items={["a", "b"]} />)
+      expect(renderer.getRetainedElementCount()).toBeGreaterThan(without)
+
+      render(<Screen items={["a", "b"]} mounted={false} />)
+      expect(renderer.findByTestId("item-a")).toBeUndefined()
+      expect(renderer.findByTestId("layer")!.children).toEqual([])
+      expect(renderer.getRetainedElementCount()).toBe(without)
+    } finally {
+      unmount()
+    }
+  })
+})
diff --git a/packages/react/src/index.ts b/packages/react/src/index.ts
index 9b0111a73..5fd01b6e4 100644
--- a/packages/react/src/index.ts
+++ b/packages/react/src/index.ts
@@ -1,5 +1,6 @@
 // GPUIX React - React bindings for GPUI
 export { createRoot, flushSync } from "./reconciler/index.js"
+export { createPortal } from "./reconciler/portal.js"
 export {
   createRenderer,
   enableAutomation,
diff --git a/packages/react/src/reconciler/host-config.ts b/packages/react/src/reconciler/host-config.ts
index 5a5a21ce8..5aa765188 100644
--- a/packages/react/src/reconciler/host-config.ts
+++ b/packages/react/src/reconciler/host-config.ts
@@ -280,6 +280,26 @@ function materialize(node: HostNode): HostNodeState {
   return state
 }
 
+const portalContainers = new WeakMap<Instance, Container>()
+
+/**
+ * The container a portal into `target` mounts through.
+ *
+ * Cached per target because React compares a portal's `containerInfo` by
+ * identity, and a new object on every render would unmount and remount the
+ * portal's whole subtree.
+ */
+export function portalContainerFor(target: Instance): Container {
+  let container = portalContainers.get(target)
+  if (!container) {
+    container = Object.assign(Object.create(stateFor(target).container) as Container, {
+      portalTarget: target,
+    })
+    portalContainers.set(target, container)
+  }
+  return container
+}
+
 // ── Host config ──────────────────────────────────────────────────────
 
 export const hostConfig = {
@@ -338,11 +358,19 @@ export const hostConfig = {
     parentState.container.renderer.insertBefore(parent.id, child.id, beforeChild.id)
   },
 
+  // A window's root has one child, so there is nothing to order. A portal's
+  // children share their target with whatever else it holds, and React places
+  // one before another whenever their keys reorder.
   insertInContainerBefore(
-    _parent: Container,
-    _child: Instance,
-    _beforeChild: Instance
-  ): void {},
+    container: Container,
+    child: Instance,
+    beforeChild: Instance
+  ): void {
+    const target = container.portalTarget
+    if (!target) return
+    materialize(child)
+    container.renderer.insertBefore(target.id, child.id, beforeChild.id)
+  },
 
   removeChildFromContainer(parent: Container, child: Instance): void {
     const destroyed = parent.renderer.destroyElement(child.id)
@@ -458,7 +486,13 @@ export const hostConfig = {
 
   appendChildToContainer(container: Container, child: Instance): void {
     materialize(child)
-    container.renderer.setRoot(child.id)
+    const target = container.portalTarget
+    if (target) {
+      materialize(target)
+      container.renderer.appendChild(target.id, child.id)
+    } else {
+      container.renderer.setRoot(child.id)
+    }
   },
 
   appendInitialChild(parent: Instance, child: Instance | TextInstance): void {
diff --git a/packages/react/src/reconciler/portal.ts b/packages/react/src/reconciler/portal.ts
new file mode 100644
index 000000000..881e652e0
--- /dev/null
+++ b/packages/react/src/reconciler/portal.ts
@@ -0,0 +1,39 @@
+import type { ReactNode } from "react"
+import type { PublicInstance } from "../types/host.js"
+import { portalContainerFor } from "./host-config.js"
+
+const REACT_PORTAL_TYPE = Symbol.for("react.portal")
+
+/**
+ * Render `children` as children of `target`, an element that is already
+ * mounted, in the order React places them. The content keeps the context of the
+ * component that called `createPortal`, as in React DOM.
+ *
+ * Take `target` from a `ref` and render the portal once it is set: a portal
+ * into an element that is not mounted yet has nowhere to attach.
+ *
+ * ```tsx
+ * const [layer, setLayer] = useState<PublicInstance | null>(null)
+ * return (
+ *   <>
+ *     <div ref={setLayer} style={{ position: "absolute", inset: 0 }} />
+ *     {layer && createPortal(<Toast />, layer)}
+ *   </>
+ * )
+ * ```
+ *
+ * `target` must belong to the same root as the caller.
+ */
+export function createPortal(
+  children: ReactNode,
+  target: PublicInstance,
+  key?: string | null
+): ReactNode {
+  return {
+    $$typeof: REACT_PORTAL_TYPE,
+    key: key == null ? null : String(key),
+    children,
+    containerInfo: portalContainerFor(target),
+    implementation: null,
+  } as unknown as ReactNode
+}
diff --git a/packages/react/src/types/host.ts b/packages/react/src/types/host.ts
index c97af5679..57d5c6275 100644
--- a/packages/react/src/types/host.ts
+++ b/packages/react/src/types/host.ts
@@ -91,6 +91,13 @@ export interface Container {
   windowKeyEventId: number
   windowSelectionEventId: number
   onEvent?: (event: EventPayload) => void
+  /**
+   * Set on a portal's container. Its children mount under this element instead
+   * of becoming the window's root. The container inherits everything else from
+   * the root container it was made from, so both share one mutation queue and
+   * one event map.
+   */
+  portalTarget?: Instance
 }
 
 export interface Instance {

From 782607bf219713b448b743b03e03fa969e2dbf41 Mon Sep 17 00:00:00 2001
From: Ruben Nogueira <40404708+rubnogueira@users.noreply.github.com>
Date: Sat, 10 Oct 2026 17:00:59 +0100
Subject: [PATCH 04/27] perf(native): repaint only when a batch changed
 something

---
 .changeset/invalidate-only-on-change.md |   5 ++
 packages/native/src/renderer.rs         | 109 ++++++++++++++++++++++--
 packages/native/src/retained_tree.rs    |  58 +++++++++++--
 3 files changed, 159 insertions(+), 13 deletions(-)
 create mode 100644 .changeset/invalidate-only-on-change.md

diff --git a/.changeset/invalidate-only-on-change.md b/.changeset/invalidate-only-on-change.md
new file mode 100644
index 000000000..a70c3ce09
--- /dev/null
+++ b/.changeset/invalidate-only-on-change.md
@@ -0,0 +1,5 @@
+---
+'@gpuix/native': patch
+---
+
+`applyBatch` asks the window to repaint only when the batch changed something a frame would draw. A batch that only resends the style, text, listeners or custom props an element already has no longer rebuilds and re-lays-out the whole element tree for a frame that comes out identical.
diff --git a/packages/native/src/renderer.rs b/packages/native/src/renderer.rs
index 3707b907e..6a885c533 100644
--- a/packages/native/src/renderer.rs
+++ b/packages/native/src/renderer.rs
@@ -1385,8 +1385,14 @@ impl GpuixRenderer {
         let mut tree = self.tree.lock().unwrap();
         let destroyed =
             apply_batch_to_tree(&mut tree, json.as_bytes()).map_err(Error::from_reason)?;
+        let dirty = tree.take_dirty();
         drop(tree);
-        self.request_invalidate()?;
+        // A re-render that changed nothing sends a batch of identical resends.
+        // Waking the window for it makes it rebuild and diff the whole element
+        // tree to draw the frame it already has.
+        if dirty {
+            self.request_invalidate()?;
+        }
         Ok(destroyed)
     }
 
@@ -2881,9 +2887,14 @@ impl WebGpuixRenderer {
         &self,
         json: String,
     ) -> Result<wasm_bindgen::JsValue, wasm_bindgen::JsValue> {
-        let destroyed = apply_batch_to_tree(&mut self.tree.lock().unwrap(), json.as_bytes())
+        let mut tree = self.tree.lock().unwrap();
+        let destroyed = apply_batch_to_tree(&mut tree, json.as_bytes())
             .map_err(|error| wasm_bindgen::JsValue::from_str(&error))?;
-        notify_web();
+        let dirty = tree.take_dirty();
+        drop(tree);
+        if dirty {
+            notify_web();
+        }
         Ok(web_number_array(destroyed))
     }
 
@@ -4665,7 +4676,7 @@ impl GpuixView {
         window: &gpui::Window,
         cx: &gpui::App,
     ) -> Option<Arc<[u64]>> {
-        if !tree.keyboard_focus_dim || !window.last_input_was_keyboard() {
+        if !tree.keyboard_focus_dim() || !window.last_input_was_keyboard() {
             return None;
         }
         let focused = window.focused(cx)?.id();
@@ -6448,10 +6459,10 @@ pub fn apply_batch_to_tree(tree: &mut RetainedTree, bytes: &[u8]) -> BatchResult
                 tree.set_event_listener(id, event_type, has_handler);
             }
             BatchOp::SetRoot { id } => {
-                tree.root_id = Some(id);
+                tree.set_root(id);
             }
             BatchOp::SetKeyboardFocusDim { enabled } => {
-                tree.keyboard_focus_dim = enabled;
+                tree.set_keyboard_focus_dim(enabled);
             }
             BatchOp::SetCustomProp { id, key, value } => {
                 tree.set_custom_prop(id, key, value);
@@ -7087,6 +7098,92 @@ mod batch_tests {
         out
     }
 
+    /// Whether the batch left something a frame would draw differently. The
+    /// window is only woken for these, so a wrong `false` is a stale screen and
+    /// a wrong `true` is a wasted frame.
+    fn dirty_after(tree: &mut RetainedTree, json: &str) -> bool {
+        apply(tree, json).expect("valid batch");
+        tree.take_dirty()
+    }
+
+    const MOUNT: &str = r##"[
+        ["createElement",1,"div"],["createElement",2,"text"],["createElement",3,"div"],
+        ["appendChild",1,2],["appendChild",1,3],["setRoot",1],
+        ["setStyle",1,{"width":100,"backgroundColor":"#112233"}],
+        ["setStyle",3,{"height":10}],
+        ["setText",2,"hello"],
+        ["setEventListener",3,"click",true],
+        ["setCustomProp",3,"aria-label","row"],
+        ["setCustomProp",3,"testId","row"],
+        ["setCustomProp",3,"autoFocus",true]
+    ]"##;
+
+    #[test]
+    fn mounting_marks_the_tree_dirty() {
+        let mut tree = RetainedTree::new();
+        assert!(dirty_after(&mut tree, MOUNT));
+    }
+
+    #[test]
+    fn resending_everything_unchanged_is_not_dirty() {
+        let mut tree = RetainedTree::new();
+        apply(&mut tree, MOUNT).expect("valid batch");
+        tree.take_dirty();
+
+        // The same ops again, with the style keys reordered: interning keys on
+        // raw bytes, so this reaches `set_style` as a different `Arc`.
+        let resend = r##"[
+            ["setRoot",1],
+            ["setStyle",1,{"backgroundColor":"#112233","width":100}],
+            ["setStyle",3,{"height":10}],
+            ["setText",2,"hello"],
+            ["setEventListener",3,"click",true],
+            ["setCustomProp",3,"aria-label","row"],
+            ["setCustomProp",3,"testId","row"],
+            ["setCustomProp",3,"autoFocus",true],
+            ["setKeyboardFocusDim",true],
+            ["setCustomProp",3,"missing",null]
+        ]"##;
+        assert!(!dirty_after(&mut tree, resend));
+    }
+
+    #[test]
+    fn each_kind_of_change_is_dirty() {
+        let changes = [
+            r#"[["setStyle",3,{"height":11}]]"#,
+            r#"[["setText",2,"changed"]]"#,
+            r#"[["setEventListener",3,"click",false]]"#,
+            r#"[["setEventListener",3,"mouseDown",true]]"#,
+            r#"[["setCustomProp",3,"aria-label","other"]]"#,
+            r#"[["setCustomProp",3,"aria-label",null]]"#,
+            r#"[["setCustomProp",3,"testId","other"]]"#,
+            r#"[["setCustomProp",3,"autoFocus",false]]"#,
+            r#"[["setKeyboardFocusDim",false]]"#,
+            r#"[["createElement",4,"div"]]"#,
+            r#"[["destroyElement",3]]"#,
+            r#"[["insertBefore",1,3,2]]"#,
+            r#"[["setRoot",3]]"#,
+        ];
+        for change in changes {
+            let mut tree = RetainedTree::new();
+            apply(&mut tree, MOUNT).expect("valid batch");
+            tree.take_dirty();
+            assert!(dirty_after(&mut tree, change), "{change} must repaint");
+        }
+    }
+
+    #[test]
+    fn a_rejected_batch_does_not_leave_the_tree_dirty() {
+        let mut tree = RetainedTree::new();
+        apply(&mut tree, MOUNT).expect("valid batch");
+        tree.take_dirty();
+
+        apply(&mut tree, r#"[["setText",2,"changed"],["setStyle",2,123]]"#)
+            .expect_err("malformed style");
+
+        assert!(!tree.take_dirty());
+    }
+
     /// The regression test for batch atomicity. `intern_style_payload` used to
     /// run inside the apply loop, so this batch created the element, set its
     /// text, and only then threw — leaving JS to retry against a tree that had
diff --git a/packages/native/src/retained_tree.rs b/packages/native/src/retained_tree.rs
index cbc68c99d..045b894fb 100644
--- a/packages/native/src/retained_tree.rs
+++ b/packages/native/src/retained_tree.rs
@@ -189,8 +189,13 @@ pub struct RetainedTree {
     /// The root element ID set by appendChildToContainer.
     pub root_id: Option<u64>,
     /// Dim other focusables while a control has keyboard focus. Set per root.
-    pub keyboard_focus_dim: bool,
+    keyboard_focus_dim: bool,
     next_revision: u64,
+    /// Something a frame would draw changed since the last `take_dirty`. A batch
+    /// of resends, which is what a re-render with unchanged props produces,
+    /// leaves it false, so the window is not asked to rebuild its element tree
+    /// for a frame that would come out identical.
+    dirty: bool,
 }
 
 impl RetainedTree {
@@ -202,16 +207,45 @@ impl RetainedTree {
             root_id: None,
             keyboard_focus_dim: true,
             next_revision: 1,
+            dirty: false,
+        }
+    }
+
+    /// Whether a frame drawn now would differ from the last one, clearing the
+    /// answer. Call once per applied batch.
+    pub fn take_dirty(&mut self) -> bool {
+        std::mem::take(&mut self.dirty)
+    }
+
+    pub fn keyboard_focus_dim(&self) -> bool {
+        self.keyboard_focus_dim
+    }
+
+    pub fn set_keyboard_focus_dim(&mut self, enabled: bool) {
+        if self.keyboard_focus_dim != enabled {
+            self.keyboard_focus_dim = enabled;
+            self.dirty = true;
+        }
+    }
+
+    pub fn set_root(&mut self, id: u64) {
+        if self.root_id != Some(id) {
+            self.root_id = Some(id);
+            self.dirty = true;
         }
     }
 
     pub fn create_element(&mut self, id: u64, element_type: String) {
+        self.dirty = true;
         let revision = self.take_revision();
         self.elements
             .insert(id, RetainedElement::new(id, element_type, revision));
     }
 
     fn take_revision(&mut self) -> u64 {
+        // Every content change takes a revision to invalidate caches, so this is
+        // the one place that covers style, text, structure and custom props.
+        self.dirty = true;
         let revision = self.next_revision;
         self.next_revision = self.next_revision.wrapping_add(1).max(1);
         revision
@@ -258,6 +292,9 @@ impl RetainedTree {
         }
         let mut destroyed = Vec::new();
         self.destroy_element_recursive(id, &mut destroyed);
+        if !destroyed.is_empty() {
+            self.dirty = true;
+        }
         if self.root_id == Some(id) {
             self.root_id = None;
         }
@@ -364,11 +401,14 @@ impl RetainedTree {
 
     pub fn set_event_listener(&mut self, id: u64, event_type: String, has_handler: bool) {
         if let Some(element) = self.elements.get_mut(&id) {
-            if has_handler {
-                element.events.insert(event_type);
+            let changed = if has_handler {
+                element.events.insert(event_type)
             } else {
-                element.events.remove(&event_type);
-            }
+                element.events.remove(&event_type)
+            };
+            // Which listeners exist decides how the element is built, though it
+            // does not touch any cached text.
+            self.dirty |= changed;
         }
     }
 
@@ -390,11 +430,15 @@ impl RetainedTree {
             // `autoFocus` applies to every element type, so it is lifted out of
             // the custom-prop map that only custom elements read.
             if key == "autoFocus" {
-                element.auto_focus = value.as_bool().unwrap_or(false);
+                let auto_focus = value.as_bool().unwrap_or(false);
+                self.dirty |= element.auto_focus != auto_focus;
+                element.auto_focus = auto_focus;
                 return;
             }
             if key == "testId" {
-                element.test_id = value.as_str().map(str::to_string);
+                let test_id = value.as_str().map(str::to_string);
+                self.dirty |= element.test_id != test_id;
+                element.test_id = test_id;
                 return;
             }
             if value.is_null() {

From d8cf51ac86fd6fd1ac6cfcf48a4a7b383296113f Mon Sep 17 00:00:00 2001
From: Ruben Nogueira <40404708+rubnogueira@users.noreply.github.com>
Date: Sat, 10 Oct 2026 17:01:00 +0100
Subject: [PATCH 05/27] perf(native): track host bounds from paint, not an
 extra child node

---
 .changeset/track-bounds-without-a-child.md |  7 +++++
 README.md                                  |  3 ++-
 packages/native/src/automation.rs          | 31 ++++++++++++++++++++++
 packages/native/src/custom_elements/mod.rs |  8 +++++-
 packages/native/src/renderer.rs            | 23 ++++++++++------
 packages/native/src/text/paint.rs          |  4 +--
 6 files changed, 64 insertions(+), 12 deletions(-)
 create mode 100644 .changeset/track-bounds-without-a-child.md

diff --git a/.changeset/track-bounds-without-a-child.md b/.changeset/track-bounds-without-a-child.md
new file mode 100644
index 000000000..f4789738a
--- /dev/null
+++ b/.changeset/track-bounds-without-a-child.md
@@ -0,0 +1,7 @@
+---
+'@gpuix/native': patch
+---
+
+`<div>` and `<text>` no longer add a hidden child element to record their bounds. Each host element used to carry an extra `canvas` node, which doubled the nodes gpui laid out, prepainted and painted every frame. The bounds now come from the element's own paint, so a frame over the same tree is about 15% cheaper. An element with `visibility: hidden` keeps the child, because gpui does not paint a hidden element and its layout box must stay readable.
+
+`getElementBounds()`, automation locators and text selection regions now use the element's border box. They used the padding box before, which was narrower by the border width on an element with a `borderWidth`.
diff --git a/README.md b/README.md
index 67140175b..0cd2330ad 100644
--- a/README.md
+++ b/README.md
@@ -2246,7 +2246,8 @@ elements live in the tree, not the order gpui paints them in.
 `getElementBounds(id)` returns the last painted box, or `null` if that node did
 not paint. It works on the live `GpuixRenderer` and on the test renderer.
 Bounds are recorded during **paint**, so read them after a frame, not in the
-same commit as mount.
+same commit as mount. The box is the element's border box, like a DOM
+`getBoundingClientRect`.
 
 ```tsx
 const box = renderer.getElementBounds?.(ref.current.id)
diff --git a/packages/native/src/automation.rs b/packages/native/src/automation.rs
index 41ab83cbb..c9ed5ec4c 100644
--- a/packages/native/src/automation.rs
+++ b/packages/native/src/automation.rs
@@ -69,6 +69,37 @@ pub fn track_own_bounds<E: gpui::InteractiveElement>(el: E, id: u64) -> E {
     el.on_painted(move |bounds, _, _| record_bounds(id, bounds))
 }
 
+/// Record a host element's painted box, and its selection-start region, for
+/// automation and text selection.
+///
+/// A visible element reports its own box through `on_painted`, so tracking it
+/// adds nothing to the tree. The previous `bounds_tracker` child doubled the
+/// number of nodes gpui laid out, prepainted and painted for every `<div>` and
+/// `<text>`.
+///
+/// gpui does not call `on_painted` for `visibility: hidden`, and a hidden
+/// element still has a layout box that a locator or a measurement is entitled
+/// to read. `hidden` keeps the canvas for exactly those elements. The canvas is
+/// `absolute`, so the element must be a positioned parent.
+///
+/// The two paths differ by an element's border: the canvas fills the padding
+/// box, and `on_painted` reports the border box, which is what a DOM
+/// `getBoundingClientRect` reports.
+pub fn track_host_bounds<E>(el: E, id: u64, selection_start: Option<bool>, hidden: bool) -> E
+where
+    E: gpui::InteractiveElement + gpui::ParentElement,
+{
+    if hidden {
+        return el.child(bounds_tracker(id, selection_start));
+    }
+    el.on_painted(move |bounds, _, _| {
+        record_bounds(id, bounds);
+        if let Some(selectable) = selection_start {
+            crate::text::record_start_region(bounds, selectable);
+        }
+    })
+}
+
 pub fn record_bounds(id: u64, bounds: Bounds<Pixels>) {
     BOUNDS.with(|cell| {
         cell.borrow_mut()
diff --git a/packages/native/src/custom_elements/mod.rs b/packages/native/src/custom_elements/mod.rs
index 559656412..e861fe0c5 100644
--- a/packages/native/src/custom_elements/mod.rs
+++ b/packages/native/src/custom_elements/mod.rs
@@ -128,7 +128,13 @@ pub(crate) fn custom_surface(
     {
         el = el.relative();
     }
-    el = el.child(crate::automation::bounds_tracker(ctx.id, None));
+    el = crate::automation::track_host_bounds(
+        el,
+        ctx.id,
+        None,
+        ctx.style
+            .is_some_and(|style| style.visibility.as_deref() == Some("hidden")),
+    );
     el = crate::accessibility::apply_accessibility(el, ctx.props, None);
     wire_standard_events(el, ctx)
 }
diff --git a/packages/native/src/renderer.rs b/packages/native/src/renderer.rs
index 6a885c533..654f8413d 100644
--- a/packages/native/src/renderer.rs
+++ b/packages/native/src/renderer.rs
@@ -4974,7 +4974,10 @@ pub(crate) fn build_element(
 ) -> gpui::AnyElement {
     use gpui::IntoElement;
 
-    let Some(element) = ctx.tree.elements.get(&id) else {
+    // Copy the tree reference out of `ctx`, so `element` borrows the tree and
+    // not the build context, which the children below need mutably.
+    let tree = ctx.tree;
+    let Some(element) = tree.elements.get(&id) else {
         return gpui::Empty.into_any_element();
     };
 
@@ -5233,18 +5236,17 @@ fn joined_text_content(
     if let Some(content) = element.content.as_deref().filter(|value| !value.is_empty()) {
         return Some(content.to_string());
     }
-    let mut parts = Vec::new();
+    let mut joined = String::new();
     for child_id in &element.children {
         let Some(child) = tree.elements.get(child_id) else {
             continue;
         };
         if child.element_type == "text" {
             if let Some(content) = child.content.as_deref() {
-                parts.push(content);
+                joined.push_str(content);
             }
         }
     }
-    let joined = parts.concat();
     (!joined.is_empty()).then_some(joined)
 }
 
@@ -5352,10 +5354,12 @@ pub(crate) fn build_host_container(
     if style.and_then(|style| style.position.as_deref()).is_none() {
         el = el.relative();
     }
-    el = el.child(crate::automation::bounds_tracker(
+    el = crate::automation::track_host_bounds(
+        el,
         element.id,
         selection_start_flag(style),
-    ));
+        is_hidden(style),
+    );
 
     if let Some(handle) = ctx.focus_handles.get(&element.id) {
         el = el.track_focus(handle);
@@ -5611,8 +5615,7 @@ pub(crate) fn build_host_container(
     }
 
     // Children
-    let child_ids: Vec<u64> = element.children.clone();
-    for child_id in child_ids {
+    for &child_id in &element.children {
         let child = build_element(child_id, ctx, window, cx);
         el = if overflow_x_only {
             el.child(gpui::div().flex_none().child(child))
@@ -5657,6 +5660,10 @@ fn text_content(
     })
 }
 
+fn is_hidden(style: Option<&StyleDesc>) -> bool {
+    style.is_some_and(|style| style.visibility.as_deref() == Some("hidden"))
+}
+
 /// Explicit `userSelect` on this node. `None` means inherit; the ancestor
 /// that set the value already owns the start region.
 fn selection_start_flag(style: Option<&StyleDesc>) -> Option<bool> {
diff --git a/packages/native/src/text/paint.rs b/packages/native/src/text/paint.rs
index 9af978ecb..23005b0cc 100644
--- a/packages/native/src/text/paint.rs
+++ b/packages/native/src/text/paint.rs
@@ -114,8 +114,8 @@ pub fn selection_frame_reset(
 
 /// Record a selection-start region from an element's painted box.
 ///
-/// Only `bounds_tracker` calls this, so a start region is always the same box
-/// automation already uses. Last painted region that contains the point wins.
+/// Only `track_host_bounds` and `bounds_tracker` call this, so a start region is
+/// always the same box automation already uses. Last painted region that contains the point wins.
 pub fn record_start_region(bounds: Bounds<gpui::Pixels>, selectable: bool) {
     START_REGIONS.with(|r| r.borrow_mut().push(StartRegion { bounds, selectable }));
 }

From ef1433952d65a0814338ad24dc6ca08d40d6b1b8 Mon Sep 17 00:00:00 2001
From: Ruben Nogueira <40404708+rubnogueira@users.noreply.github.com>
Date: Sat, 10 Oct 2026 17:01:08 +0100
Subject: [PATCH 06/27] test: benchmark a list that re-renders with nothing
 visibly changed

---
 examples/package.json           |  2 +-
 examples/profile-rerender.tsx   | 39 +++++++++++++
 examples/rerender-fixture.tsx   | 62 +++++++++++++++++++++
 examples/rerender.perf.test.tsx | 99 +++++++++++++++++++++++++++++++++
 4 files changed, 201 insertions(+), 1 deletion(-)
 create mode 100644 examples/profile-rerender.tsx
 create mode 100644 examples/rerender-fixture.tsx
 create mode 100644 examples/rerender.perf.test.tsx

diff --git a/examples/package.json b/examples/package.json
index 2c6d4ab6d..4896a652e 100644
--- a/examples/package.json
+++ b/examples/package.json
@@ -7,7 +7,7 @@
     "counter": "bun --hot counter.tsx",
     "diff": "bun --hot diff.tsx",
     "test": "vitest run --exclude '**/*.perf.test.tsx'",
-    "test:perf": "vitest run chat.perf.test.tsx timeline.perf.test.tsx",
+    "test:perf": "vitest run chat.perf.test.tsx timeline.perf.test.tsx rerender.perf.test.tsx",
     "native-text": "bun --hot native-text.tsx",
     "chat": "bun --hot chat.tsx",
     "chat-solid": "bun --hot solid/chat.tsx",
diff --git a/examples/profile-rerender.tsx b/examples/profile-rerender.tsx
new file mode 100644
index 000000000..c43d76c0b
--- /dev/null
+++ b/examples/profile-rerender.tsx
@@ -0,0 +1,39 @@
+/**
+ * Loops the frame that follows a header-only update over the chat-shaped list,
+ * so a sampling profiler has something to look at.
+ *
+ *   bun profile-rerender.tsx &
+ *   sample $! 5 -file /tmp/rerender.txt
+ *
+ * `MODE=commit` loops React's commit instead of the native frame.
+ */
+
+import React from 'react'
+import { flushSync } from '@gpuix/react'
+import { createTestRoot } from '@gpuix/react/testing'
+import { App } from './rerender-fixture'
+
+const mode = process.env.MODE ?? 'frame'
+const seconds = Number(process.env.SECONDS ?? '12')
+const root = createTestRoot({ width: 900, height: 700 })
+root.render(<App tick={0} streaming="done" />)
+root.renderer.flush()
+
+const end = performance.now() + seconds * 1000
+let tick = 0
+let frames = 0
+let spent = 0
+while (performance.now() < end) {
+  const start = performance.now()
+  flushSync(() => root.root.render(<App tick={++tick} streaming="done" />))
+  if (mode === 'frame') {
+    const committed = performance.now()
+    root.renderer.flush()
+    spent += performance.now() - committed
+  } else {
+    spent += performance.now() - start
+  }
+  frames++
+}
+console.log(JSON.stringify({ mode, frames, avgMs: +(spent / frames).toFixed(2) }))
+process.exit(0)
diff --git a/examples/rerender-fixture.tsx b/examples/rerender-fixture.tsx
new file mode 100644
index 000000000..9197a5a03
--- /dev/null
+++ b/examples/rerender-fixture.tsx
@@ -0,0 +1,62 @@
+/**
+ * A chat-shaped list for the re-render benchmarks. Every row builds its `style`
+ * objects and handlers from scratch on each render, the way an app that does not
+ * hoist its styles does, so a parent update re-renders all of them with values
+ * that are equal but never identical.
+ */
+
+import React from 'react'
+
+export const ROWS = 1_000
+
+function Row({ index, body }: { index: number; body: string }) {
+  return (
+    <div
+      style={{
+        flexDirection: 'column',
+        gap: 6,
+        padding: 12,
+        borderRadius: 8,
+        backgroundColor: index % 2 === 0 ? '#1e1e2e' : '#181825',
+        borderWidth: 1,
+        borderColor: '#313244',
+        hover: { backgroundColor: '#313244' },
+      }}
+    >
+      <div style={{ flexDirection: 'row', gap: 8, alignItems: 'center' }}>
+        <div style={{ width: 20, height: 20, borderRadius: 10, backgroundColor: '#89b4fa' }} />
+        <text style={{ color: '#cdd6f4', fontWeight: 600, fontSize: 13 }}>user {index}</text>
+        <text style={{ color: '#6c7086', fontSize: 11 }}>12:{String(index % 60).padStart(2, '0')}</text>
+      </div>
+      <text style={{ color: '#cdd6f4', fontSize: 13, lineHeight: 20 }}>{body}</text>
+      <div style={{ flexDirection: 'row', gap: 6 }}>
+        <div
+          onClick={() => {}}
+          style={{ padding: 4, borderRadius: 4, backgroundColor: '#313244', hover: { backgroundColor: '#45475a' } }}
+        >
+          <text style={{ color: '#cdd6f4', fontSize: 11 }}>copy</text>
+        </div>
+        <div
+          onClick={() => {}}
+          style={{ padding: 4, borderRadius: 4, backgroundColor: '#313244', hover: { backgroundColor: '#45475a' } }}
+        >
+          <text style={{ color: '#cdd6f4', fontSize: 11 }}>retry</text>
+        </div>
+      </div>
+    </div>
+  )
+}
+
+/** `tick` changes on every update and reaches no style, so every row repeats itself. */
+export function App({ tick, streaming }: { tick: number; streaming: string }) {
+  return (
+    <div style={{ flexDirection: 'column', width: 900, height: 700 }}>
+      <text style={{ color: '#fff' }}>tick {tick}</text>
+      <div style={{ flexDirection: 'column', flex: 1, overflowY: 'scroll', gap: 8 }}>
+        {Array.from({ length: ROWS }, (_, index) => (
+          <Row key={index} index={index} body={index === ROWS - 1 ? streaming : `message body number ${index}`} />
+        ))}
+      </div>
+    </div>
+  )
+}
diff --git a/examples/rerender.perf.test.tsx b/examples/rerender.perf.test.tsx
new file mode 100644
index 000000000..399ccbcc2
--- /dev/null
+++ b/examples/rerender.perf.test.tsx
@@ -0,0 +1,99 @@
+/**
+ * Re-render cost when nothing visible changed. This is the shape of a chat
+ * client: a parent holds state (composer text, a streaming message, a clock),
+ * every row below it re-renders, and each row builds its `style` object and its
+ * handlers from scratch. React cannot skip them, so what matters is how cheap
+ * the renderer makes "the same thing again".
+ *
+ * Reports the mutations that cross into Rust per update next to the time, since
+ * an update that sends nothing cannot cost a frame. Skip without the native GPU
+ * test renderer. Excluded from `bun run test` by the `*.perf.test.tsx` glob.
+ */
+
+import React from 'react'
+import { describe, expect, it } from 'vitest'
+import { flushSync } from '@gpuix/react'
+import { createTestRoot, hasNativeTestRenderer, type TestRoot } from '@gpuix/react/testing'
+import { App } from './rerender-fixture'
+
+const describeNative = hasNativeTestRenderer ? describe : describe.skip
+
+const WARMUP = 5
+const SAMPLES = 30
+
+function measure(
+  root: TestRoot,
+  next: (index: number) => React.ReactNode,
+): { ms: number[]; frameMs: number[]; ops: number; bytes: number } {
+  const { renderer } = root
+  let ops = 0
+  let bytes = 0
+  const original = renderer.applyBatch.bind(renderer)
+  renderer.applyBatch = (json: string) => {
+    bytes += json.length
+    ops += (JSON.parse(json) as unknown[]).length
+    return original(json)
+  }
+  // `ms` is React rendering and committing, which includes `applyBatch`.
+  // `frameMs` is the native frame that follows. A real window only runs one when
+  // a batch left something dirty, but the test renderer always does. Not
+  // `root.render()`, which flushes a frame of its own and would count it twice.
+  const ms: number[] = []
+  const frameMs: number[] = []
+  try {
+    for (let i = 0; i < WARMUP + SAMPLES; i++) {
+      if (i === WARMUP) {
+        ops = 0
+        bytes = 0
+      }
+      const start = performance.now()
+      flushSync(() => root.root.render(next(i)))
+      const committed = performance.now()
+      renderer.flush()
+      if (i >= WARMUP) {
+        ms.push(committed - start)
+        frameMs.push(performance.now() - committed)
+      }
+    }
+  } finally {
+    renderer.applyBatch = original
+  }
+  return { ms, frameMs, ops: ops / SAMPLES, bytes: bytes / SAMPLES }
+}
+
+function p(samples: number[], q: number) {
+  const sorted = [...samples].sort((a, b) => a - b)
+  return sorted[Math.min(sorted.length - 1, Math.ceil(q * sorted.length) - 1)]!
+}
+
+function report(label: string, result: ReturnType<typeof measure>) {
+  console.log(
+    `[rerender.perf] ${label}: commit p50=${p(result.ms, 0.5).toFixed(2)}ms p95=${p(result.ms, 0.95).toFixed(2)}ms ` +
+      `frame p50=${p(result.frameMs, 0.5).toFixed(2)}ms p95=${p(result.frameMs, 0.95).toFixed(2)}ms ` +
+      `ops/update=${result.ops.toFixed(0)} bytes/update=${result.bytes.toFixed(0)}`,
+  )
+}
+
+describeNative('re-render with nothing visibly changed', () => {
+  it('sends only the streaming row when the whole list re-renders', () => {
+    const root = createTestRoot({ width: 900, height: 700 })
+    root.render(<App tick={0} streaming="" />)
+    let text = ''
+    const result = measure(root, (index) => {
+      text += 'word '
+      return <App tick={index + 1} streaming={text} />
+    })
+    report('streaming row, whole list re-renders', result)
+    // The `tick` text and the streaming row's text are the only two changes. Each
+    // costs one op; anything near the row count means rows resend what they have.
+    expect(result.ops).toBeLessThan(10)
+  }, 120_000)
+
+  it('sends one op when only a header changes', () => {
+    const root = createTestRoot({ width: 900, height: 700 })
+    root.render(<App tick={0} streaming="done" />)
+    const result = measure(root, (index) => <App tick={index + 1} streaming="done" />)
+    report('header text only, whole list re-renders', result)
+    expect(result.ops).toBeLessThan(5)
+  }, 120_000)
+})

From ab37d93962431a0bfcdeedf5f99e257d869c3b7e Mon Sep 17 00:00:00 2001
From: Ruben Nogueira <40404708+rubnogueira@users.noreply.github.com>
Date: Sat, 10 Oct 2026 17:02:33 +0100
Subject: [PATCH 07/27] build(react): move to react-reconciler 0.33 and wait on
 AnimatePresence removal

---
 .changeset/react-reconciler-0-33.md           |  5 ++++
 bun.lock                                      |  8 ++-----
 packages/react/package.json                   |  4 ++--
 .../src/__tests__/animate-presence.test.tsx   | 24 ++++++++++++-------
 4 files changed, 24 insertions(+), 17 deletions(-)
 create mode 100644 .changeset/react-reconciler-0-33.md

diff --git a/.changeset/react-reconciler-0-33.md b/.changeset/react-reconciler-0-33.md
new file mode 100644
index 000000000..10ad56717
--- /dev/null
+++ b/.changeset/react-reconciler-0-33.md
@@ -0,0 +1,5 @@
+---
+'@gpuix/react': minor
+---
+
+`@gpuix/react` now uses `react-reconciler@^0.33.0` and peers on `react@^19.2.0`. React 19.2 pairs with reconciler 0.33, and the old `^0.31.0` pin forced every app on 19.2 to override it. The `^18.0.0` half of the old peer range was never true, since reconciler 0.31 already required React 19.
diff --git a/bun.lock b/bun.lock
index 59c0297fd..5096f3020 100644
--- a/bun.lock
+++ b/bun.lock
@@ -102,7 +102,7 @@
       "version": "0.10.0",
       "dependencies": {
         "@gpuix/native": "workspace:^",
-        "react-reconciler": "^0.31.0",
+        "react-reconciler": "^0.33.0",
       },
       "devDependencies": {
         "@testing-library/react": "^16.3.2",
@@ -114,7 +114,7 @@
         "vitest": "^4.0.18",
       },
       "peerDependencies": {
-        "react": "^18.0.0 || ^19.0.0",
+        "react": "^19.2.0",
       },
     },
     "packages/solid": {
@@ -1104,8 +1104,6 @@
 
     "@babel/helper-create-class-features-plugin/semver": ["semver@6.3.1", "", { "bin": { "semver": "bin/semver.js" } }, "sha512-BR7VvDCVHO+q2xBEWskxS6DJE1qRnb7DxzUrogb71CWoSficBxYsiAGd+Kl0mmq/MprG9yArRkyrQxTO6XjMzA=="],
 
-    "@gpuix/react/react-reconciler": ["react-reconciler@0.31.0", "", { "dependencies": { "scheduler": "^0.25.0" }, "peerDependencies": { "react": "^19.0.0" } }, "sha512-7Ob7Z+URmesIsIVRjnLoDGwBEG/tVitidU0nMsqX/eeJaLY89RISO/10ERe0MqmzuKUUB1rmY+h1itMbUHg9BQ=="],
-
     "@isaacs/fs-minipass/minipass": ["minipass@7.1.2", "", {}, "sha512-qOOzS1cBTWYF4BH8fVePDBOO9iptMnGUEZwNc/cMWnTV2nVLZ7VoNWEPHkYczZA0pdoA7dl6e7FL659nX9S2aw=="],
 
     "@napi-rs/cli/obug": ["obug@3.0.0", "", {}, "sha512-5vvB5+W7ePv+p3uqxi+RcW1XAzLW0/hxt3/4X4Lc4qHudzOhmBiBwOY6DRob4WnanAEGvNcLjF+KNOufrUoEQw=="],
@@ -1146,8 +1144,6 @@
 
     "tar/minipass": ["minipass@7.1.2", "", {}, "sha512-qOOzS1cBTWYF4BH8fVePDBOO9iptMnGUEZwNc/cMWnTV2nVLZ7VoNWEPHkYczZA0pdoA7dl6e7FL659nX9S2aw=="],
 
-    "@gpuix/react/react-reconciler/scheduler": ["scheduler@0.25.0", "", {}, "sha512-xFVuu11jh+xcO7JOAGJNOXld8/TcEHK/4CituBUeUb5hqxJLj9YuemAEuvm9gQ/+pgXYfbQuqAkiYu+u7YEsNA=="],
-
     "@napi-rs/lzma-wasm32-wasi/@napi-rs/wasm-runtime/@emnapi/core": ["@emnapi/core@1.8.1", "", { "dependencies": { "@emnapi/wasi-threads": "1.1.0", "tslib": "^2.4.0" } }, "sha512-AvT9QFpxK0Zd8J0jopedNm+w/2fIzvtPKPjqyw9jwvBaReTTqPBk9Hixaz7KbjimP+QNz605/XnjFcDAL2pqBg=="],
 
     "@napi-rs/lzma-wasm32-wasi/@napi-rs/wasm-runtime/@emnapi/runtime": ["@emnapi/runtime@1.8.1", "", { "dependencies": { "tslib": "^2.4.0" } }, "sha512-mehfKSMWjjNol8659Z8KxEMrdSJDDot5SXMq00dM8BN4o+CLNXQ0xH2V7EchNHV4RmbZLmmPdEaXZc5H2FXmDg=="],
diff --git a/packages/react/package.json b/packages/react/package.json
index cf2a94808..62cedd59c 100644
--- a/packages/react/package.json
+++ b/packages/react/package.json
@@ -88,10 +88,10 @@
   },
   "dependencies": {
     "@gpuix/native": "workspace:^",
-    "react-reconciler": "^0.31.0"
+    "react-reconciler": "^0.33.0"
   },
   "peerDependencies": {
-    "react": "^18.0.0 || ^19.0.0"
+    "react": "^19.2.0"
   },
   "devDependencies": {
     "@testing-library/react": "^16.3.2",
diff --git a/packages/react/src/__tests__/animate-presence.test.tsx b/packages/react/src/__tests__/animate-presence.test.tsx
index 18465dd9a..6a771dc8b 100644
--- a/packages/react/src/__tests__/animate-presence.test.tsx
+++ b/packages/react/src/__tests__/animate-presence.test.tsx
@@ -1,11 +1,23 @@
 import { useLayoutEffect } from "react"
-import { describe, expect, it } from "vitest"
+import { describe, expect, it, vi } from "vitest"
 import { AnimatePresence, motion, usePresence } from "../index"
 import { flushSync } from "../reconciler/reconciler"
 import { createTestRoot, hasNativeTestRenderer } from "../testing"
 
 const describeNative = hasNativeTestRenderer ? describe : describe.skip
 
+/**
+ * Waits for AnimatePresence to drop a child that has nothing to animate. The
+ * removal is a state update from a passive effect, which React's scheduler runs
+ * on its own clock, so a fixed sleep races it. Poll for the outcome instead.
+ */
+async function expectRemoved(renderer: ReturnType<typeof createTestRoot>["renderer"]) {
+  await vi.waitFor(() => {
+    renderer.flush()
+    expect(renderer.getAllText()).toEqual([])
+  })
+}
+
 describeNative("AnimatePresence", () => {
   it("keeps an exiting motion.div until the exit target finishes", () => {
     const { render, renderer } = createTestRoot()
@@ -85,10 +97,7 @@ describeNative("AnimatePresence", () => {
 
     render(<App show />)
     render(<App show={false} />)
-    await new Promise((resolve) => setTimeout(resolve, 0))
-    renderer.flush()
-
-    expect(renderer.getAllText()).toEqual([])
+    await expectRemoved(renderer)
   })
 
   it("exits with the latest props for a stable key", () => {
@@ -467,10 +476,7 @@ describeNative("AnimatePresence", () => {
     render(<App show replace />)
     staleRemove?.()
     render(<App show={false} replace />)
-    await new Promise((resolve) => setTimeout(resolve, 0))
-    renderer.flush()
-
-    expect(renderer.getAllText()).toEqual([])
+    await expectRemoved(renderer)
   })
 })
 

From a6506818548b74d1640fd224df73f1fbeddc8a7f Mon Sep 17 00:00:00 2001
From: Ruben Nogueira <40404708+rubnogueira@users.noreply.github.com>
Date: Sat, 10 Oct 2026 17:10:47 +0100
Subject: [PATCH 08/27] feat(native): aspectRatio, dashed borders, shadow
 lists, inset shadows and more alignment values

---
 .changeset/more-css-layout-styles.md          |  13 ++
 README.md                                     |  20 +-
 packages/native/js/host.ts                    |   9 +-
 packages/native/src/renderer.rs               |  43 +++-
 packages/native/src/style.rs                  |  52 ++++-
 .../react/src/__tests__/styles-css.test.tsx   | 184 ++++++++++++++++++
 6 files changed, 304 insertions(+), 17 deletions(-)
 create mode 100644 .changeset/more-css-layout-styles.md
 create mode 100644 packages/react/src/__tests__/styles-css.test.tsx

diff --git a/.changeset/more-css-layout-styles.md b/.changeset/more-css-layout-styles.md
new file mode 100644
index 000000000..5e645f1df
--- /dev/null
+++ b/.changeset/more-css-layout-styles.md
@@ -0,0 +1,13 @@
+---
+'@gpuix/native': minor
+'@gpuix/react': minor
+'@gpuix/solid': minor
+---
+
+New styles for what gpui already draws and GPUIX did not expose:
+
+- `aspectRatio` sizes the axis that has no definite size.
+- `borderStyle: "dashed"` draws every border side dashed.
+- `boxShadow` accepts an array of shadows, and each shadow takes `inset: true`.
+- `alignItems` accepts `"stretch"` and `"baseline"`, which `alignSelf` already did.
+- `justifyContent` accepts `"space-evenly"`, which `alignContent` already did.
diff --git a/README.md b/README.md
index 0cd2330ad..be1e05eb0 100644
--- a/README.md
+++ b/README.md
@@ -3060,15 +3060,15 @@ CSS-like styling via the `style` prop:
 >   style, or pad the parent wrapper. The input clips to its own
 >   `borderRadius` automatically.
 
-**Layout:** `display` (`"flex"` | `"grid"`), `flexDirection`, `flexWrap`, `flexGrow`, `flexShrink`, `flexBasis`, `alignItems`, `alignSelf`, `alignContent`, `justifyContent`, `gap`, `rowGap`, `columnGap`, `gridTemplateColumns`, `gridTemplateRows`, `gridColumnMin`, `gridRowMin`
+**Layout:** `display` (`"flex"` | `"grid"`), `flexDirection`, `flexWrap`, `flexGrow`, `flexShrink`, `flexBasis`, `alignItems` (`"start"` | `"center"` | `"end"` | `"stretch"` | `"baseline"`), `alignSelf`, `alignContent`, `justifyContent` (adds `"space-between"`, `"space-around"` and `"space-evenly"`), `gap`, `rowGap`, `columnGap`, `gridTemplateColumns`, `gridTemplateRows`, `gridColumnMin`, `gridRowMin`
 
-**Sizing:** `width`, `height`, `minWidth`, `minHeight`, `maxWidth`, `maxHeight` — accepts pixels (number) or percentages (string like `"100%"`)
+**Sizing:** `width`, `height`, `minWidth`, `minHeight`, `maxWidth`, `maxHeight` — accepts pixels (number) or percentages (string like `"100%"`). `aspectRatio` (width divided by height) sizes whichever axis has no definite size
 
 **Spacing:** `padding`, `paddingTop/Right/Bottom/Left`, `margin`, `marginTop/Right/Bottom/Left`
 
 **Position:** `position` (`"relative"` | `"absolute"` | `"fixed"`), `top`, `right`, `bottom`, `left` — `"fixed"` lays out like `"absolute"`, because GPUI has no scrolling document to be fixed against
 
-**Visual:** `background`, `backgroundColor`, `color`, `opacity`, `cursor`, `pointerEvents`, `borderRadius`, `borderTopLeftRadius`, `borderTopRightRadius`, `borderBottomLeftRadius`, `borderBottomRightRadius`, `borderWidth`, `borderTopWidth`, `borderRightWidth`, `borderBottomWidth`, `borderLeftWidth`, `borderColor`, `boxShadow`, `outlineWidth`, `outlineColor`, `outlineOffset`
+**Visual:** `background`, `backgroundColor`, `color`, `opacity`, `cursor`, `pointerEvents`, `borderRadius`, `borderTopLeftRadius`, `borderTopRightRadius`, `borderBottomLeftRadius`, `borderBottomRightRadius`, `borderWidth`, `borderTopWidth`, `borderRightWidth`, `borderBottomWidth`, `borderLeftWidth`, `borderColor`, `borderStyle` (`"solid"` | `"dashed"`), `boxShadow`, `outlineWidth`, `outlineColor`, `outlineOffset`
 
 ### Cursors
 
@@ -3159,8 +3159,9 @@ Limited relative-color forms can derive a new color from a base value:
 />
 ```
 
-`boxShadow` accepts one structured shadow. Its fields are `offsetX`, `offsetY`,
-`blurRadius`, `spreadRadius`, and `color`:
+`boxShadow` accepts one structured shadow or an array of them, painted in the
+order given. Its fields are `offsetX`, `offsetY`, `blurRadius`, `spreadRadius`,
+`color`, and `inset`, which draws inside the border box:
 
 ```tsx
 <div
@@ -3174,6 +3175,15 @@ Limited relative-color forms can derive a new color from a base value:
     },
   }}
 />
+
+<div
+  style={{
+    boxShadow: [
+      { offsetX: 0, offsetY: 1, blurRadius: 2, spreadRadius: 0, color: '#0000004d' },
+      { offsetX: 0, offsetY: 0, blurRadius: 0, spreadRadius: 1, color: '#ffffff1a', inset: true },
+    ],
+  }}
+/>
 ```
 
 **Overflow:** `overflow`, `overflowX`, `overflowY` — `"hidden"` clips content, `"scroll"` creates a native scrollable container with persistent scroll state
diff --git a/packages/native/js/host.ts b/packages/native/js/host.ts
index 04e6143c0..f813d2bdd 100644
--- a/packages/native/js/host.ts
+++ b/packages/native/js/host.ts
@@ -100,6 +100,8 @@ export interface BoxShadow {
   blurRadius: number
   spreadRadius: number
   color: string
+  /** Draw inside the border box, like CSS `inset`. */
+  inset?: boolean
 }
 
 export interface LinearGradientStop {
@@ -177,7 +179,12 @@ export interface StyleDesc {
   borderTopRightRadius?: number
   borderBottomLeftRadius?: number
   borderBottomRightRadius?: number
-  boxShadow?: BoxShadow
+  /** One shadow, or a list painted in the order given. */
+  boxShadow?: BoxShadow | BoxShadow[]
+  /** Applies to every side. */
+  borderStyle?: "solid" | "dashed"
+  /** Width divided by height. Fills in whichever axis has no definite size. */
+  aspectRatio?: number
   /** CSS `outline`: a line outside the border box. Takes no layout space, so it
    *  can appear on focus without moving anything. Width defaults to 1. */
   outlineWidth?: number
diff --git a/packages/native/src/renderer.rs b/packages/native/src/renderer.rs
index 654f8413d..442054b76 100644
--- a/packages/native/src/renderer.rs
+++ b/packages/native/src/renderer.rs
@@ -5764,6 +5764,8 @@ pub(crate) fn apply_styles<E: gpui::Styled>(mut el: E, style: &StyleDesc) -> E {
         Some("center") => el = el.items_center(),
         Some("start") | Some("flex-start") => el = el.items_start(),
         Some("end") | Some("flex-end") => el = el.items_end(),
+        Some("stretch") => el = el.items_stretch(),
+        Some("baseline") => el = el.items_baseline(),
         _ => {}
     }
     match style.align_content.as_deref() {
@@ -5783,6 +5785,7 @@ pub(crate) fn apply_styles<E: gpui::Styled>(mut el: E, style: &StyleDesc) -> E {
         Some("end") | Some("flex-end") => el = el.justify_end(),
         Some("between") | Some("space-between") => el = el.justify_between(),
         Some("around") | Some("space-around") => el = el.justify_around(),
+        Some("evenly") | Some("space-evenly") => el = el.justify_evenly(),
         _ => {}
     }
     match style.align_self.as_deref() {
@@ -5898,6 +5901,11 @@ pub(crate) fn apply_styles<E: gpui::Styled>(mut el: E, style: &StyleDesc) -> E {
     if let Some(left) = style.left {
         el = el.left(gpui::px(left as f32));
     }
+    if let Some(ratio) = style.aspect_ratio {
+        if ratio > 0.0 && ratio.is_finite() {
+            el = el.aspect_ratio(ratio as f32);
+        }
+    }
     if let Some(background) = style.resolved_background() {
         el = el.bg(background);
     }
@@ -5988,16 +5996,31 @@ pub(crate) fn apply_styles<E: gpui::Styled>(mut el: E, style: &StyleDesc) -> E {
             el = el.border_color(color);
         }
     }
-    if let Some(ref shadow) = style.box_shadow {
-        if let Some(color) = crate::color::parse_color_rgba(&shadow.color) {
-            let shadow = gpui::BoxShadow::new(
-                gpui::px(shadow.offset_x as f32),
-                gpui::px(shadow.offset_y as f32),
-                color.into(),
-            )
-            .blur_radius(gpui::px(shadow.blur_radius.max(0.0) as f32))
-            .spread_radius(gpui::px(shadow.spread_radius as f32));
-            el = el.shadow(vec![shadow]);
+    match style.border_style.as_deref() {
+        Some("dashed") => el = el.border_dashed(),
+        Some("solid") => el.style().border_style = Some(gpui::BorderStyle::Solid),
+        _ => {}
+    }
+    if let Some(ref shadows) = style.box_shadow {
+        // A shadow whose colour does not parse is dropped on its own, so one
+        // bad entry does not take the rest of a list with it.
+        let shadows: Vec<gpui::BoxShadow> = shadows
+            .as_slice()
+            .iter()
+            .filter_map(|shadow| {
+                let color = crate::color::parse_color_rgba(&shadow.color)?;
+                let built = gpui::BoxShadow::new(
+                    gpui::px(shadow.offset_x as f32),
+                    gpui::px(shadow.offset_y as f32),
+                    color.into(),
+                )
+                .blur_radius(gpui::px(shadow.blur_radius.max(0.0) as f32))
+                .spread_radius(gpui::px(shadow.spread_radius as f32));
+                Some(if shadow.inset { built.inset() } else { built })
+            })
+            .collect();
+        if !shadows.is_empty() {
+            el = el.shadow(shadows);
         }
     }
     if style.outline_width.is_some() || style.outline_color.is_some() {
diff --git a/packages/native/src/style.rs b/packages/native/src/style.rs
index e564b8281..8c1745778 100644
--- a/packages/native/src/style.rs
+++ b/packages/native/src/style.rs
@@ -17,6 +17,26 @@ pub struct BoxShadowValue {
     pub blur_radius: f64,
     pub spread_radius: f64,
     pub color: String,
+    /// Draws inside the border box instead of around it, like CSS `inset`.
+    #[serde(default)]
+    pub inset: bool,
+}
+
+/// `boxShadow` is one shadow or a list of them, painted in the order given.
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+#[serde(untagged)]
+pub enum BoxShadowValues {
+    Many(Vec<BoxShadowValue>),
+    One(BoxShadowValue),
+}
+
+impl BoxShadowValues {
+    pub fn as_slice(&self) -> &[BoxShadowValue] {
+        match self {
+            Self::Many(shadows) => shadows,
+            Self::One(shadow) => std::slice::from_ref(shadow),
+        }
+    }
 }
 
 #[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
@@ -197,7 +217,11 @@ pub struct StyleDesc {
     pub border_top_right_radius: Option<f64>,
     pub border_bottom_left_radius: Option<f64>,
     pub border_bottom_right_radius: Option<f64>,
-    pub box_shadow: Option<BoxShadowValue>,
+    pub box_shadow: Option<BoxShadowValues>,
+    /// `"solid"` or `"dashed"`, for every side.
+    pub border_style: Option<String>,
+    /// Width divided by height, applied to whichever axis is not definite.
+    pub aspect_ratio: Option<f64>,
     /// CSS `outline`: a line outside the border box that takes no layout
     /// space, so it can appear on focus without moving anything.
     pub outline_width: Option<f64>,
@@ -415,6 +439,32 @@ mod tests {
         assert!(!should_occlude(&style));
     }
 
+    #[test]
+    fn box_shadow_takes_one_shadow_or_a_list() {
+        let one: StyleDesc = serde_json::from_str(
+            r##"{"boxShadow":{"offsetX":0,"offsetY":4,"blurRadius":12,"spreadRadius":0,"color":"#00000033"}}"##,
+        )
+        .unwrap();
+        let shadows = one.box_shadow.as_ref().unwrap().as_slice();
+        assert_eq!(shadows.len(), 1);
+        assert!(
+            !shadows[0].inset,
+            "a shadow is outside unless it says otherwise"
+        );
+
+        let many: StyleDesc = serde_json::from_str(
+            r##"{"boxShadow":[
+                {"offsetX":0,"offsetY":1,"blurRadius":2,"spreadRadius":0,"color":"#0003"},
+                {"offsetX":0,"offsetY":0,"blurRadius":0,"spreadRadius":1,"color":"#fff1","inset":true}
+            ]}"##,
+        )
+        .unwrap();
+        let shadows = many.box_shadow.as_ref().unwrap().as_slice();
+        assert_eq!(shadows.len(), 2);
+        assert!(shadows[1].inset);
+        assert_eq!(shadows[1].spread_radius, 1.0);
+    }
+
     #[test]
     fn maps_the_timeline_cursors() {
         assert_eq!(
diff --git a/packages/react/src/__tests__/styles-css.test.tsx b/packages/react/src/__tests__/styles-css.test.tsx
new file mode 100644
index 000000000..882528843
--- /dev/null
+++ b/packages/react/src/__tests__/styles-css.test.tsx
@@ -0,0 +1,184 @@
+import fs from "fs"
+import { describe, expect, it } from "vitest"
+import { createTestRoot, hasNativeTestRenderer } from "../testing.js"
+import { expectScreenshotsDiffer, SHOTS_DIR } from "./test-utils.js"
+
+const describeNative = hasNativeTestRenderer ? describe : describe.skip
+
+type TestRenderer = ReturnType<typeof createTestRoot>["renderer"]
+
+function rect(renderer: TestRenderer, testId: string) {
+  const element = renderer.findByTestId(testId)
+  expect(element, `missing testId ${testId}`).toBeDefined()
+  const bounds = renderer.getElementBounds(element!.id)
+  expect(bounds, `no painted bounds for ${testId}`).toBeTruthy()
+  return bounds!
+}
+
+function screenshot(renderer: TestRenderer, name: string): string {
+  const path = `${SHOTS_DIR}/gpuix-css-${name}.png`
+  if (fs.existsSync(path)) fs.unlinkSync(path)
+  renderer.captureScreenshot(path)
+  return path
+}
+
+describeNative("aspectRatio", () => {
+  it("derives the height from the width", () => {
+    const { render, renderer, unmount } = createTestRoot()
+    try {
+      render(<div testId="box" style={{ width: 200, aspectRatio: 2 }} />)
+      expect(rect(renderer, "box")).toMatchObject({ width: 200, height: 100 })
+    } finally {
+      unmount()
+    }
+  })
+
+  it("derives the width from the height", () => {
+    const { render, renderer, unmount } = createTestRoot()
+    try {
+      render(<div testId="box" style={{ height: 60, aspectRatio: 3 }} />)
+      expect(rect(renderer, "box")).toMatchObject({ width: 180, height: 60 })
+    } finally {
+      unmount()
+    }
+  })
+
+  it("ignores a ratio that is not positive", () => {
+    const { render, renderer, unmount } = createTestRoot()
+    try {
+      render(<div testId="box" style={{ width: 200, height: 50, aspectRatio: 0 }} />)
+      expect(rect(renderer, "box")).toMatchObject({ width: 200, height: 50 })
+    } finally {
+      unmount()
+    }
+  })
+})
+
+describeNative("justifyContent: space-evenly", () => {
+  it("puts equal space before, between and after the children", () => {
+    const { render, renderer, unmount } = createTestRoot()
+    try {
+      render(
+        <div style={{ display: "flex", flexDirection: "row", width: 300, justifyContent: "space-evenly" }}>
+          {["a", "b", "c"].map((id) => (
+            <div key={id} testId={id} style={{ width: 30, height: 10 }} />
+          ))}
+        </div>
+      )
+      // 300 - 90 = 210 free, in 4 equal gaps of 52.5. Layout rounds to whole pixels.
+      const [a, b, c] = ["a", "b", "c"].map((id) => rect(renderer, id).x) as [number, number, number]
+      expect(Math.abs(a - 52.5)).toBeLessThanOrEqual(1)
+      expect(Math.abs(b - a - 82.5)).toBeLessThanOrEqual(1)
+      expect(Math.abs(c - b - 82.5)).toBeLessThanOrEqual(1)
+    } finally {
+      unmount()
+    }
+  })
+})
+
+describeNative("alignItems", () => {
+  const row = (alignItems: string) => (
+    <div style={{ display: "flex", flexDirection: "row", width: 200, height: 100, alignItems }}>
+      <div testId="child" style={{ width: 20 }} />
+    </div>
+  )
+
+  it("stretch fills the cross axis, which center does not", () => {
+    const { render, renderer, unmount } = createTestRoot()
+    try {
+      render(row("stretch"))
+      expect(rect(renderer, "child").height).toBe(100)
+      render(row("center"))
+      expect(rect(renderer, "child").height).toBeLessThan(100)
+    } finally {
+      unmount()
+    }
+  })
+})
+
+describeNative("alignItems: baseline", () => {
+  it("lines up the text of different sizes on one baseline", () => {
+    const { render, renderer, unmount } = createTestRoot()
+    try {
+      const row = (alignItems: string) => (
+        <div style={{ display: "flex", flexDirection: "row", width: 300, height: 100, alignItems }}>
+          <div testId="big" style={{ fontSize: 40 }}>
+            Big
+          </div>
+          <div testId="small" style={{ fontSize: 12 }}>
+            small
+          </div>
+        </div>
+      )
+      render(row("start"))
+      expect(rect(renderer, "small").y).toBe(rect(renderer, "big").y)
+
+      render(row("baseline"))
+      const big = rect(renderer, "big")
+      const small = rect(renderer, "small")
+      // The small text drops so that its bottom edge meets the big text's.
+      expect(small.y).toBeGreaterThan(big.y)
+      expect(Math.abs(small.y + small.height - (big.y + big.height))).toBeLessThanOrEqual(2)
+    } finally {
+      unmount()
+    }
+  })
+})
+
+describeNative("borderStyle and boxShadow", () => {
+  const frame = (style: object) => (
+    <div style={{ width: 300, height: 200, backgroundColor: "#11111b", padding: 40 }}>
+      <div style={{ width: 120, height: 80, borderRadius: 8, backgroundColor: "#1e1e2e", ...style }} />
+    </div>
+  )
+  const shadow = { offsetX: 0, offsetY: 6, blurRadius: 12, spreadRadius: 0, color: "#000000cc" }
+
+  it("draws a dashed border differently from a solid one", () => {
+    const { render, renderer, unmount } = createTestRoot()
+    try {
+      const border = { borderWidth: 3, borderColor: "#89b4fa" }
+      render(frame({ ...border, borderStyle: "solid" }))
+      const solid = screenshot(renderer, "border-solid")
+      render(frame({ ...border, borderStyle: "dashed" }))
+      expectScreenshotsDiffer(solid, screenshot(renderer, "border-dashed"))
+    } finally {
+      unmount()
+    }
+  })
+
+  it("paints every shadow in a list", () => {
+    const { render, renderer, unmount } = createTestRoot()
+    try {
+      render(frame({ boxShadow: shadow }))
+      const one = screenshot(renderer, "shadow-one")
+      render(frame({ boxShadow: [shadow, { ...shadow, offsetY: -12, color: "#f38ba8cc" }] }))
+      expectScreenshotsDiffer(one, screenshot(renderer, "shadow-two"))
+    } finally {
+      unmount()
+    }
+  })
+
+  it("paints an inset shadow differently from an outer one", () => {
+    const { render, renderer, unmount } = createTestRoot()
+    try {
+      render(frame({ boxShadow: shadow }))
+      const outer = screenshot(renderer, "shadow-outer")
+      render(frame({ boxShadow: { ...shadow, inset: true } }))
+      expectScreenshotsDiffer(outer, screenshot(renderer, "shadow-inset"))
+    } finally {
+      unmount()
+    }
+  })
+
+  it("keeps a valid shadow when another one in the list has a bad colour", () => {
+    const { render, renderer, unmount } = createTestRoot()
+    try {
+      render(frame({}))
+      const none = screenshot(renderer, "shadow-none")
+      render(frame({ boxShadow: [{ ...shadow, color: "not-a-colour" }, shadow] }))
+      expectScreenshotsDiffer(none, screenshot(renderer, "shadow-partly-bad"))
+    } finally {
+      unmount()
+    }
+  })
+})

From f10a6c1b35629c5deb81b8a50d20fade49d593d4 Mon Sep 17 00:00:00 2001
From: Ruben Nogueira <40404708+rubnogueira@users.noreply.github.com>
Date: Sat, 10 Oct 2026 17:49:07 +0100
Subject: [PATCH 09/27] test(examples): run perf budgets against a production
 React and add a chat profiler

---
 examples/chat.perf.test.tsx |  8 ++++
 examples/package.json       |  2 +-
 examples/profile-chat.tsx   | 86 +++++++++++++++++++++++++++++++++++++
 3 files changed, 95 insertions(+), 1 deletion(-)
 create mode 100644 examples/profile-chat.tsx

diff --git a/examples/chat.perf.test.tsx b/examples/chat.perf.test.tsx
index 61842e509..f7376d62f 100644
--- a/examples/chat.perf.test.tsx
+++ b/examples/chat.perf.test.tsx
@@ -7,6 +7,12 @@
  *
  * THROTTLE=utility|background|maintenance re-execs under taskpolicy -c.
  * A throttled run logs numbers and skips the default budgets.
+ *
+ * Run it through `bun run test:perf`: that sets NODE_ENV=production, so React
+ * is the build apps ship. React's development build measures and diffs every
+ * component it renders for its DevTools tracks, which more than doubles a
+ * commit here and says nothing about what users get. Files run one at a time,
+ * so two renderers do not compete for the same cores.
  */
 
 import React from 'react'
@@ -188,6 +194,8 @@ describeNative('chat performance', () => {
 
     // First query: collects and folds the subtree once. Not measured.
     render(app('p'))
+    // So are a few more, which the engine needs to compile the commit path.
+    for (let i = 0; i < WARMUP; i++) render(app(i % 2 === 0 ? 'pe' : 'per'))
 
     const word = 'performance of the renderer'
     const keystrokes: number[] = []
diff --git a/examples/package.json b/examples/package.json
index 4896a652e..eba48d22b 100644
--- a/examples/package.json
+++ b/examples/package.json
@@ -7,7 +7,7 @@
     "counter": "bun --hot counter.tsx",
     "diff": "bun --hot diff.tsx",
     "test": "vitest run --exclude '**/*.perf.test.tsx'",
-    "test:perf": "vitest run chat.perf.test.tsx timeline.perf.test.tsx rerender.perf.test.tsx",
+    "test:perf": "NODE_ENV=production vitest run --no-file-parallelism chat.perf.test.tsx timeline.perf.test.tsx rerender.perf.test.tsx",
     "native-text": "bun --hot native-text.tsx",
     "chat": "bun --hot chat.tsx",
     "chat-solid": "bun --hot solid/chat.tsx",
diff --git a/examples/profile-chat.tsx b/examples/profile-chat.tsx
new file mode 100644
index 000000000..8ac41b289
--- /dev/null
+++ b/examples/profile-chat.tsx
@@ -0,0 +1,86 @@
+/**
+ * Loops one chat interaction so a sampling profiler has something to look at.
+ *
+ *   MODE=highlight bun profile-chat.tsx &
+ *   sample $! 6 -file /tmp/chat.txt
+ *
+ * MODE=highlight   commit + frame for each query of a find-bar keystroke run
+ * MODE=frame       the native frame alone, with nothing changed
+ * MODE=commit      React's commit alone for each query
+ * MODE=mount       mounts the 1000-turn chat from scratch, over and over
+ * MODE=sidebar     clicks the sidebar toggle through the automation client
+ *
+ * Wall time is noisy on a busy machine, so every mode also reports the CPU time
+ * the process spent per iteration, which load on other processes does not move.
+ */
+
+import React from 'react'
+import { flushSync } from '@gpuix/react'
+import { createTestRoot } from '@gpuix/react/testing'
+import { connectTest } from '@gpuix/react/automation'
+import { ChatApp } from './chat'
+
+const mode = process.env.MODE ?? 'highlight'
+const seconds = Number(process.env.SECONDS ?? '12')
+const TURNS = 1_000
+const word = 'performance of the renderer'
+
+const app = (query: string, activeIndex = 0) => (
+  <div style={{ flex: 1 }} highlight={query ? { query, activeIndex } : null}>
+    <ChatApp turnCount={TURNS} includeSafeMdx />
+  </div>
+)
+
+function cpuMs() {
+  const usage = process.cpuUsage()
+  return (usage.user + usage.system) / 1000
+}
+
+let root = createTestRoot()
+root.render(app(''))
+for (let i = 0; i < 10; i++) root.renderer.flush()
+root.render(app('p'))
+
+const automation = mode === 'sidebar' ? await connectTest(root.renderer) : undefined
+if (automation) {
+  await automation.getByTestId('sidebar-collapse').waitFor()
+  await automation.clock.pause()
+}
+
+const end = performance.now() + seconds * 1000
+let iterations = 0
+let wall = 0
+let cpu = 0
+let step = 2
+while (performance.now() < end) {
+  const wallStart = performance.now()
+  const cpuStart = cpuMs()
+  if (automation) {
+    const testId = iterations % 2 === 0 ? 'sidebar-collapse' : 'sidebar-expand'
+    await automation.getByTestId(testId).click()
+    await automation.clock.fastForward(200)
+  } else if (mode === 'mount') {
+    root.unmount()
+    root = createTestRoot()
+    root.render(app(''))
+  } else if (mode === 'frame') {
+    root.renderer.flush()
+  } else {
+    const query = word.slice(0, step)
+    step = step >= word.length ? 2 : step + 1
+    if (mode === 'commit') flushSync(() => root.root.render(app(query)))
+    else root.render(app(query))
+  }
+  wall += performance.now() - wallStart
+  cpu += cpuMs() - cpuStart
+  iterations++
+}
+console.log(
+  JSON.stringify({
+    mode,
+    iterations,
+    wallMs: +(wall / iterations).toFixed(2),
+    cpuMs: +(cpu / iterations).toFixed(2),
+  }),
+)
+process.exit(0)

From f3eede6b3e0e9865d7ca9ce5ad3e943f7f49225b Mon Sep 17 00:00:00 2001
From: Ruben Nogueira <40404708+rubnogueira@users.noreply.github.com>
Date: Sat, 10 Oct 2026 17:58:28 +0100
Subject: [PATCH 10/27] feat(native): registerFont loads a font that fontFamily
 can name

---
 .changeset/register-font.md                   |   7 ++
 README.md                                     |  31 +++++++
 packages/native/Cargo.lock                    |   1 +
 packages/native/Cargo.toml                    |   2 +
 packages/native/index.d.ts                    |   9 ++
 packages/native/js/host.ts                    |   1 +
 packages/native/js/testing.ts                 |   7 ++
 packages/native/src/renderer.rs               |  84 ++++++++++++++++++
 packages/native/src/test_renderer.rs          |  14 +++
 .../fixtures/gpuix-test-nameless.ttf          | Bin 0 -> 748 bytes
 .../__tests__/fixtures/gpuix-test-square.ttf  | Bin 0 -> 1008 bytes
 .../__tests__/fixtures/make-square-font.py    |  52 +++++++++++
 packages/react/src/__tests__/fonts.test.tsx   |  84 ++++++++++++++++++
 zed                                           |   2 +-
 14 files changed, 293 insertions(+), 1 deletion(-)
 create mode 100644 .changeset/register-font.md
 create mode 100644 packages/react/src/__tests__/fixtures/gpuix-test-nameless.ttf
 create mode 100644 packages/react/src/__tests__/fixtures/gpuix-test-square.ttf
 create mode 100644 packages/react/src/__tests__/fixtures/make-square-font.py
 create mode 100644 packages/react/src/__tests__/fonts.test.tsx

diff --git a/.changeset/register-font.md b/.changeset/register-font.md
new file mode 100644
index 000000000..18b45e5b7
--- /dev/null
+++ b/.changeset/register-font.md
@@ -0,0 +1,7 @@
+---
+'@gpuix/native': minor
+'@gpuix/react': minor
+'@gpuix/solid': minor
+---
+
+`registerFont(bytes)` loads a TrueType or OpenType font so `fontFamily` can name it. Text that asked for the family before it was registered picks the font up on the next frame. Fonts GPUI would abort on, or cannot use, are rejected with an error instead.
diff --git a/README.md b/README.md
index be1e05eb0..469dce21c 100644
--- a/README.md
+++ b/README.md
@@ -830,6 +830,37 @@ activation policy, so there is no menu-bar-agent mode yet. For a real
 background daemon, run the app from a `launchd` agent in
 `~/Library/LaunchAgents/`; launchd never activates the process.
 
+### Custom fonts
+
+`registerFont()` makes a font that is not installed on the machine available to
+`fontFamily`. It takes the bytes of a **TrueType or OpenType** file (`.ttf` or
+`.otf`).
+
+```tsx
+import { readFileSync } from 'node:fs'
+import { useGpuixRequired } from '@gpuix/react'
+
+function LoadFonts() {
+  const renderer = useGpuixRequired()
+  useEffect(() => {
+    renderer.registerFont?.(readFileSync('./Inter-Regular.ttf'))
+  }, [renderer])
+  return <div style={{ fontFamily: 'Inter' }}>Hello</div>
+}
+```
+
+Text that already named the family repaints with the font once it is
+registered, so there is no need to register before the first render. Register
+every weight and style of a family you use; text picks the closest one.
+
+The font must have family, full and PostScript names and a glyph for `"m"`.
+GPUI aborts the process on a font without the names, and silently drops a font
+without the glyph, so `registerFont()` throws for both and for bytes that are
+not a font. Fonts load into the process and last until it exits.
+
+WOFF and WOFF2 are not supported; convert them to TrueType first. The browser
+renderer does not have this method, use `FontFace` there.
+
 ### Let an agent drive the app
 
 Make focus opt-in through the environment, so a human run behaves normally and
diff --git a/packages/native/Cargo.lock b/packages/native/Cargo.lock
index 916fc1f32..0015c1716 100644
--- a/packages/native/Cargo.lock
+++ b/packages/native/Cargo.lock
@@ -2622,6 +2622,7 @@ dependencies = [
  "tempfile",
  "thiserror 2.0.18",
  "time",
+ "ttf-parser",
  "two-face",
  "unicode-segmentation",
  "url",
diff --git a/packages/native/Cargo.toml b/packages/native/Cargo.toml
index d3332cdd3..666c39d49 100644
--- a/packages/native/Cargo.toml
+++ b/packages/native/Cargo.toml
@@ -31,6 +31,8 @@ thiserror = "2"
 pulldown-cmark = { version = "0.12", default-features = false }
 unicode-segmentation = "1"
 web-time = "1"
+# Checks fonts handed to `registerFont`; GPUI's text system aborts on malformed ones.
+ttf-parser = { version = "0.25", default-features = false, features = ["std"] }
 
 # Syntect compiles a grammar's TextMate regexes lazily, on the FIRST highlight
 # of that language, on the frame thread, inside a paint. fancy-regex takes
diff --git a/packages/native/index.d.ts b/packages/native/index.d.ts
index 703b58e2b..e87492687 100644
--- a/packages/native/index.d.ts
+++ b/packages/native/index.d.ts
@@ -162,6 +162,13 @@ export declare class GpuixRenderer {
    * an `<img>` host node. Prefer `setImagePixels` for live waveforms.
    */
   setImage(elementId: number, bytes: Buffer): void
+  /**
+   * Make the fonts in a TrueType or OpenType file (or a collection) usable by
+   * `fontFamily`, under the family names the file declares. Call it before
+   * the text that names the family is first laid out: a family that did not
+   * exist then has already fallen back to another font.
+   */
+  registerFont(data: Buffer): void
   getAutomationTree(): string
   getElementBounds(id: number): ElementBounds | null
   getAllText(): Array<string>
@@ -356,6 +363,8 @@ export declare class TestGpuixRenderer {
   setImagePixels(elementId: number, width: number, height: number, pixels: Buffer, format?: string | undefined | null): void
   /** Encoded image bytes onto an `<img>` host node. */
   setImage(elementId: number, bytes: Buffer): void
+  /** Make the fonts in a TrueType or OpenType file usable by `fontFamily`. */
+  registerFont(data: Buffer): void
   /**
    * The logical scroll anchor of a `<virtual-list>`:
    * `[itemIndex, offsetInItemPx, viewportHeightPx]`, or null for anything
diff --git a/packages/native/js/host.ts b/packages/native/js/host.ts
index f813d2bdd..9585d9313 100644
--- a/packages/native/js/host.ts
+++ b/packages/native/js/host.ts
@@ -675,6 +675,7 @@ export type NativeRenderer = MutationHost &
       | "getWindowSize"
       | "getWindowInsets"
       | "setWindowTitle"
+      | "registerFont"
       | "promptForPaths"
       | "activateWindow"
       | "minimizeWindow"
diff --git a/packages/native/js/testing.ts b/packages/native/js/testing.ts
index 0c1ae5635..ecbb5a578 100644
--- a/packages/native/js/testing.ts
+++ b/packages/native/js/testing.ts
@@ -81,6 +81,8 @@ interface NativeTestRendererApi extends NativeRenderer {
   scrollToItem(elementId: number, index: number, offsetInItem?: number): void
   scrollIntoView(elementId: number): void
   setImage(elementId: number, bytes: Buffer | Uint8Array): void
+  /** Make a TrueType or OpenType font usable by `fontFamily`. */
+  registerFont(bytes: Buffer | Uint8Array): void
   setImagePixels(
     elementId: number,
     width: number,
@@ -567,6 +569,11 @@ export class TestRenderer implements NativeRenderer {
     this.native.flush()
   }
 
+  registerFont(bytes: Buffer | Uint8Array): void {
+    this.native.registerFont(bytes as Buffer)
+    this.native.flush()
+  }
+
   setImagePixels(
     elementId: number,
     width: number,
diff --git a/packages/native/src/renderer.rs b/packages/native/src/renderer.rs
index 442054b76..3a788a72c 100644
--- a/packages/native/src/renderer.rs
+++ b/packages/native/src/renderer.rs
@@ -439,6 +439,10 @@ enum UiCommand {
         bytes: Vec<u8>,
         response: SyncSender<std::result::Result<(), String>>,
     },
+    RegisterFont {
+        bytes: Vec<u8>,
+        response: SyncSender<std::result::Result<(), String>>,
+    },
     GetScrollOffset {
         id: u64,
         response: SyncSender<Option<[f64; 2]>>,
@@ -632,6 +636,11 @@ async fn run_ui_commands(
                     .send(view.set_encoded_image(id, bytes, window, cx))
                     .ok();
             }),
+            UiCommand::RegisterFont { bytes, response } => {
+                window.update(cx, move |view, window, cx| {
+                    response.send(view.register_font(bytes, window, cx)).ok();
+                })
+            }
             UiCommand::GetScrollOffset { id, response } => {
                 let offset = VIRTUAL_LIST_STATES
                     .with(|cell| {
@@ -2254,6 +2263,36 @@ impl GpuixRenderer {
         Err(Error::from_reason("Unsupported operating system"))
     }
 
+    /// Make the fonts in a TrueType or OpenType file (or a collection) usable by
+    /// `fontFamily`, under the family names the file declares. Call it before
+    /// the text that names the family is first laid out: a family that did not
+    /// exist then has already fallen back to another font.
+    #[napi]
+    pub fn register_font(&self, data: Buffer) -> Result<()> {
+        let bytes = data.to_vec();
+        #[cfg(target_os = "macos")]
+        {
+            return update_window(move |view, window, cx| view.register_font(bytes, window, cx))?
+                .map_err(Error::from_reason);
+        }
+
+        #[cfg(any(target_os = "windows", target_os = "linux", target_os = "freebsd"))]
+        {
+            let (response, receiver) = sync_channel(1);
+            self.send_ui_command(UiCommand::RegisterFont { bytes, response })?;
+            return recv_ui_response(receiver, "the font registration")?
+                .map_err(Error::from_reason);
+        }
+
+        #[cfg(not(any(
+            target_os = "macos",
+            target_os = "windows",
+            target_os = "linux",
+            target_os = "freebsd"
+        )))]
+        Err(Error::from_reason("Unsupported operating system"))
+    }
+
     #[napi]
     pub fn get_automation_tree(&self) -> Result<String> {
         self.request_invalidate()?;
@@ -3796,6 +3835,24 @@ impl GpuixView {
         self.set_live_image(id, image, window, cx)
     }
 
+    /// Adds the fonts in `bytes` to the text system and repaints, so text that
+    /// names one of them picks it up.
+    pub(crate) fn register_font(
+        &mut self,
+        bytes: Vec<u8>,
+        window: &mut gpui::Window,
+        cx: &mut gpui::Context<Self>,
+    ) -> std::result::Result<(), String> {
+        check_font(&bytes)?;
+        window
+            .text_system()
+            .add_fonts(vec![std::borrow::Cow::Owned(bytes)])
+            .map_err(|error| error.to_string())?;
+        cx.notify();
+        window.refresh();
+        Ok(())
+    }
+
     pub(crate) fn scroll_element_into_view(&self, id: u64) -> bool {
         let Some((scroller_id, child_index)) = self.scroll_target(id) else {
             return false;
@@ -7610,3 +7667,30 @@ mod window_options_tests {
         }
     }
 }
+
+/// Rejects fonts GPUI's text system cannot load. It unwraps the family, full and
+/// PostScript name records and aborts the whole process when one is missing, and
+/// skips a font without an "m" glyph, which would leave the family unresolvable.
+fn check_font(bytes: &[u8]) -> std::result::Result<(), String> {
+    use ttf_parser::name_id::{FAMILY, FULL_NAME, POST_SCRIPT_NAME};
+
+    let face = ttf_parser::Face::parse(bytes, 0)
+        .map_err(|error| format!("not a TrueType or OpenType font: {error}"))?;
+    for (id, what) in [
+        (FAMILY, "family"),
+        (FULL_NAME, "full"),
+        (POST_SCRIPT_NAME, "PostScript"),
+    ] {
+        let named = face
+            .names()
+            .into_iter()
+            .any(|name| name.name_id == id && name.to_string().is_some());
+        if !named {
+            return Err(format!("font has no {what} name"));
+        }
+    }
+    if face.glyph_index('m').is_none() {
+        return Err("font has no glyph for \"m\"".to_string());
+    }
+    Ok(())
+}
diff --git a/packages/native/src/test_renderer.rs b/packages/native/src/test_renderer.rs
index e1cffc202..1f8383b4f 100644
--- a/packages/native/src/test_renderer.rs
+++ b/packages/native/src/test_renderer.rs
@@ -884,6 +884,20 @@ impl TestGpuixRenderer {
         })
     }
 
+    /// Make the fonts in a TrueType or OpenType file usable by `fontFamily`.
+    #[napi]
+    pub fn register_font(&self, data: Buffer) -> Result<()> {
+        let bytes = data.to_vec();
+        with_test_state(|cx, window, view| {
+            let view = view.clone();
+            cx.update_window(window, |_, window, app| {
+                view.update(app, |view, cx| view.register_font(bytes, window, cx))
+            })
+            .map_err(|e| Error::from_reason(e.to_string()))?
+            .map_err(Error::from_reason)
+        })
+    }
+
     /// The logical scroll anchor of a `<virtual-list>`:
     /// `[itemIndex, offsetInItemPx, viewportHeightPx]`, or null for anything
     /// else. `itemIndex == item count` is gpui's at-end sentinel.
diff --git a/packages/react/src/__tests__/fixtures/gpuix-test-nameless.ttf b/packages/react/src/__tests__/fixtures/gpuix-test-nameless.ttf
new file mode 100644
index 0000000000000000000000000000000000000000..a30d67dcc774ed654af03072eade563db610c89c
GIT binary patch
literal 748
zcmah{Jxjw-6g_ETYpbZm4xO}0h2r7|QcwzhfV7KMYIhAawuPh(O$${)baN1N5_d=a
z18$w1JLu#hBGS>tO^D|u6(T~t;k|p$x%b_7^4^04AcPahh;44q%&*5XM}U+dyIU|+
z6St@nUlXT_`oaFq`E!f-MdVAGy0`FfddFCdWQoMUec*}l8%Mlk)SIJcj39}5M6VW9
zWH3woNE|ZMrU^ekNd3gIifU+;;00@aE5yfU)vDtVQ^YOeX$Y+x8_Ds-o#E6cWVu5I
z?;m3|uMe~xUWQMwG_G+g18o60i%wos97cibxuG}d#Io`#U80W_|J$$b%QP-oh2d&&
z=U+`?u0D|w3cD3TgUk`(EILNGcY@yUsPthChHVqGvu)cg`^xiIgNPz7PTJ+<4tuiK
zTzDcZ;;(3L-Z{Z;y@-3%gKCo9oh5{ScH{{Lh^Sl%GCN5<ZtTMlmeOXU+{|lMJ<BWC
zHOtCr#fGldkcNo{%4i}F4Hn;C7Ag$Jx`Qp`=!>k;$%|Y6ds8GmChjZFH?#$O1E9lg
AYybcN

literal 0
HcmV?d00001

diff --git a/packages/react/src/__tests__/fixtures/gpuix-test-square.ttf b/packages/react/src/__tests__/fixtures/gpuix-test-square.ttf
new file mode 100644
index 0000000000000000000000000000000000000000..5f716cf9a045aa8fa291e17d7347e7e6e076f6df
GIT binary patch
literal 1008
zcmb7Dze^lJ6#n*R?=JozMwDoEY~Tb5obf`m5|W5PJH->*xR}k|!tLF<cL%37N}3cF
zRv~>V(SN|sB3N6PSO_8#f@PX?fz9`JM_5g`khi><@B8NMdv9iTVF2jH78I=c(vzpJ
zthr6V7^S+h>e)W_(Io#!K2@%+zx}jxenfsL>lMd-^Xz#0fLMI8LZRm{`-S)$Jzw#f
z?Sc11Fl2mCt*_dc!#MdVdADb`ePsB+xJPc)Y|lwgxD!C?1+{m6z0t%5MgaAh>yIJ5
z(sLK?*VlbhKcUn$6@34Z3zBp8B+?a9qSE+I9GN{4%26^U&5RTi@yrI2ixF1lm9dL7
zBmQl-vOlNsm6!119^&y<5-aXcR-{86Aw4MiAV<kK$l9ZvGf|f*Ov4L9a%K+0@F@I{
z*i|ovk(ZN>HFeFL%vJ1v)GzqgaA!R_K^-r+Lp;!no5}|IZYuHwvt;o}C=B7D#wKw=
z<1~6Oqj4sR;ZDsiDml!{u8C8)4^Lx-F>GpV67Ol8X7)3UGZHiFx7_xU(`c5~T6W+p
zI^|Z?4(_Ohzsr`Emz|*D)@xRAY#g)j(SnOMmf)blU!sIHDmDW0MS7X68u8Ath5w4S
i?nE!MQo#By>Zrj&k(=cu|M|7@8WJYoY@Ywo0`ME_-<?nZ

literal 0
HcmV?d00001

diff --git a/packages/react/src/__tests__/fixtures/make-square-font.py b/packages/react/src/__tests__/fixtures/make-square-font.py
new file mode 100644
index 000000000..5436501ce
--- /dev/null
+++ b/packages/react/src/__tests__/fixtures/make-square-font.py
@@ -0,0 +1,52 @@
+# Regenerates gpuix-test-square.ttf and gpuix-test-nameless.ttf (needs `pip install fonttools`).
+#
+# "A" and "m" are one em wide, "B" is two. Each is a filled square, so text
+# measured with this font has widths no system font produces.
+from fontTools.fontBuilder import FontBuilder
+from fontTools.pens.ttGlyphPen import TTGlyphPen
+
+NAME = "GpuixTestSquare"
+UPM = 1000
+
+
+def square(width):
+    pen = TTGlyphPen(None)
+    pen.moveTo((0, 0))
+    pen.lineTo((0, UPM))
+    pen.lineTo((width, UPM))
+    pen.lineTo((width, 0))
+    pen.closePath()
+    return pen.glyph()
+
+
+widths = {".notdef": UPM, "A": UPM, "B": 2 * UPM, "m": UPM}
+
+
+def build(path, names):
+    fb = FontBuilder(UPM, isTTF=True)
+    fb.setupGlyphOrder(list(widths))
+    fb.setupCharacterMap({ord("A"): "A", ord("B"): "B", ord("m"): "m"})
+    fb.setupGlyf({name: square(width) for name, width in widths.items()})
+    fb.setupHorizontalMetrics({name: (width, 0) for name, width in widths.items()})
+    fb.setupHorizontalHeader(ascent=UPM, descent=0)
+    fb.setupNameTable(names)
+    fb.setupOS2(sTypoAscender=UPM, sTypoDescender=0, usWinAscent=UPM, usWinDescent=0)
+    fb.setupPost()
+    fb.save(path)
+
+
+build(
+    "gpuix-test-square.ttf",
+    {
+        "familyName": NAME,
+        "styleName": "Regular",
+        "uniqueFontIdentifier": f"{NAME}-Regular",
+        "fullName": f"{NAME} Regular",
+        "psName": f"{NAME}-Regular",
+        "version": "Version 1.0",
+    },
+)
+
+# Valid, but without the full and PostScript names. GPUI aborts the process
+# when it loads such a font, so registerFont has to refuse it.
+build("gpuix-test-nameless.ttf", {"familyName": "GpuixTestNameless", "styleName": "Regular"})
diff --git a/packages/react/src/__tests__/fonts.test.tsx b/packages/react/src/__tests__/fonts.test.tsx
new file mode 100644
index 000000000..3daed5a76
--- /dev/null
+++ b/packages/react/src/__tests__/fonts.test.tsx
@@ -0,0 +1,84 @@
+import fs from "fs"
+import { describe, expect, it } from "vitest"
+import { createTestRoot, hasNativeTestRenderer } from "../testing.js"
+
+const describeNative = hasNativeTestRenderer ? describe : describe.skip
+
+const fixture = (name: string) => fs.readFileSync(new URL(`./fixtures/${name}`, import.meta.url))
+
+// "A" is one em wide and "B" two, both drawn as squares, so "AB" at 20px is 60
+// wide in this font (layout rounds to a whole pixel) and nowhere near that in
+// the system fonts it falls back to.
+const SQUARE_FONT = fixture("gpuix-test-square.ttf")
+
+const row = (family: string) => (
+  <div style={{ display: "flex", flexDirection: "row", width: 400 }}>
+    <div testId="word" style={{ fontFamily: family, fontSize: 20 }}>
+      AB
+    </div>
+  </div>
+)
+
+type TestRenderer = ReturnType<typeof createTestRoot>["renderer"]
+
+function expectSquareWidth(renderer: TestRenderer) {
+  expect(Math.abs(wordWidth(renderer) - 60)).toBeLessThanOrEqual(1)
+}
+
+function wordWidth(renderer: TestRenderer) {
+  const word = renderer.findByTestId("word")
+  expect(word).toBeDefined()
+  return renderer.getElementBounds(word!.id)!.width
+}
+
+describeNative("registerFont", () => {
+  it("makes a font that is not installed available to fontFamily", () => {
+    const { render, renderer, unmount } = createTestRoot()
+    try {
+      render(row("GpuixTestSquare"))
+      expect(
+        Math.abs(wordWidth(renderer) - 60),
+        "an unregistered family falls back to another font",
+      ).toBeGreaterThan(5)
+
+      renderer.registerFont(SQUARE_FONT)
+      expectSquareWidth(renderer)
+    } finally {
+      unmount()
+    }
+  })
+
+  it("uses a font registered before any text asks for it", () => {
+    const { render, renderer, unmount } = createTestRoot()
+    try {
+      renderer.registerFont(SQUARE_FONT)
+      render(row("GpuixTestSquare"))
+      expectSquareWidth(renderer)
+    } finally {
+      unmount()
+    }
+  })
+
+  it("rejects bytes that are not a font and keeps working", () => {
+    const { render, renderer, unmount } = createTestRoot()
+    try {
+      expect(() => renderer.registerFont(new Uint8Array([1, 2, 3, 4]))).toThrow(/not a TrueType/)
+      render(row("GpuixTestSquare"))
+      renderer.registerFont(SQUARE_FONT)
+      expectSquareWidth(renderer)
+    } finally {
+      unmount()
+    }
+  })
+
+  it("rejects a font GPUI would abort on instead of crashing the process", () => {
+    const { render, renderer, unmount } = createTestRoot()
+    try {
+      render(row("GpuixTestNameless"))
+      expect(() => renderer.registerFont(fixture("gpuix-test-nameless.ttf"))).toThrow(/full name/)
+      expect(wordWidth(renderer)).toBeGreaterThan(0)
+    } finally {
+      unmount()
+    }
+  })
+})
diff --git a/zed b/zed
index ea042f2f0..7bc43009e 160000
--- a/zed
+++ b/zed
@@ -1 +1 @@
-Subproject commit ea042f2f045157ada1d0ad71009520931dcace83
+Subproject commit 7bc43009e89f37e1ce765d0c2aa98e3f5c64cbeb

From c7dd862ad1c2309d79f7fe5cd6c1f64022c60ae0 Mon Sep 17 00:00:00 2001
From: Ruben Nogueira <40404708+rubnogueira@users.noreply.github.com>
Date: Sat, 10 Oct 2026 18:06:24 +0100
Subject: [PATCH 11/27] feat(native): onLayout reports an element's size when
 it changes

---
 .changeset/on-layout.md                       |   9 +
 README.md                                     |  17 ++
 packages/native/index.d.ts                    |   6 +
 packages/native/js/host.ts                    |   8 +
 packages/native/js/mutations.ts               |   1 +
 packages/native/src/automation.rs             |  43 ++--
 packages/native/src/custom_elements/mod.rs    |   8 +-
 packages/native/src/element_tree.rs           |   7 +
 packages/native/src/renderer.rs               |  76 ++++++-
 .../react/src/__tests__/layout-event.test.tsx | 188 ++++++++++++++++++
 .../solid/src/__tests__/renderer.test.tsx     |  13 ++
 11 files changed, 348 insertions(+), 28 deletions(-)
 create mode 100644 .changeset/on-layout.md
 create mode 100644 packages/react/src/__tests__/layout-event.test.tsx

diff --git a/.changeset/on-layout.md b/.changeset/on-layout.md
new file mode 100644
index 000000000..b465419d0
--- /dev/null
+++ b/.changeset/on-layout.md
@@ -0,0 +1,9 @@
+---
+'@gpuix/native': minor
+'@gpuix/react': minor
+'@gpuix/solid': minor
+---
+
+`onLayout` on `<div>` and `<text>` reports the element's border box after its first paint and each time its size changes, with no polling of `getElementBounds`. The event payload gains `width` and `height`.
+
+`visibility: "hidden"` elements have never reported bounds, because gpui paints nothing for them and nothing inside them. The canvas fallback that claimed otherwise could not run and is gone.
diff --git a/README.md b/README.md
index 469dce21c..7188ddfee 100644
--- a/README.md
+++ b/README.md
@@ -2991,6 +2991,7 @@ text imports no longer need a runtime flag.
 | Focus | `onFocus` | — |
 | Blur | `onBlur` | — |
 | Scroll | `onScroll` | `deltaX`, `deltaY`, `precise`, `touchPhase`, `modifiers` |
+| Layout | `onLayout` | `width`, `height`, `x`, `y` — `<div>` and `<text>` only |
 | File drop | `onFileDrop` | `paths`, `x`, `y` — Unicode filesystem paths from Finder or the OS |
 | Change | `onChange` | `value` — `<input>` and `<textarea>` only |
 | Submit | `onSubmit` | `value` — `<input>` always, `<textarea>` when `onSubmit` is set |
@@ -3018,6 +3019,22 @@ Put the listener on a **`div`**, **`text`**, **`img`**, **`svg`**, **`input`**,
 </div>
 ```
 
+**`onLayout`** is `ResizeObserver` for an element. It fires after the first paint
+that has the listener and again each time the element's **size** changes, with
+its border box: `width` and `height`, and `x` and `y` in window pixels. Moving
+without resizing, as a row does when a list scrolls, fires nothing. Removing the
+listener and adding it back reports the size again. An element with
+`visibility: "hidden"` is not painted, so it reports nothing until it is shown.
+
+```tsx
+<div onLayout={(event) => setWidth(event.width ?? 0)} style={{ flex: 1 }} />
+```
+
+The event arrives after the frame that laid the element out, so a handler that
+sets state paints the new size one frame later. Read it for decisions such as
+which layout to render, not to position something against the element in the
+same frame.
+
 Keyboard and focus listeners create a persistent GPUI `FocusHandle`
 automatically. A listener alone does not put a `div` in the Tab order; add
 `tabIndex={0}` for that. Inputs and textareas already use tab index `0`.
diff --git a/packages/native/index.d.ts b/packages/native/index.d.ts
index e87492687..c5df2a93a 100644
--- a/packages/native/index.d.ts
+++ b/packages/native/index.d.ts
@@ -583,6 +583,12 @@ export interface EventPayload {
   startIndex?: number
   /** Exclusive end of the visible logical range. Populated for: visibleRange. */
   endIndex?: number
+  /**
+   * Border-box size of the element, in pixels. With `x` and `y`, its position
+   * in window coordinates. Populated for: layout.
+   */
+  width?: number
+  height?: number
   /**
    * Matches found by this element's `highlight` prop. Counted once per match
    * even when it is split across several painted runs, and it counts every
diff --git a/packages/native/js/host.ts b/packages/native/js/host.ts
index 9585d9313..eae6eae10 100644
--- a/packages/native/js/host.ts
+++ b/packages/native/js/host.ts
@@ -431,6 +431,14 @@ export interface HostProps {
   // ── Scroll events ──────────────────────────────────────────────
   onScroll?: (event: EventPayload) => void
 
+  // ── Layout events ──────────────────────────────────────────────
+  /**
+   * The element's border box, reported after the first paint and each time its
+   * size changes: `width` and `height`, plus `x` and `y` in window coordinates.
+   * Moving without resizing reports nothing. Supported on `div` and `text`.
+   */
+  onLayout?: (event: EventPayload) => void
+
   // ── File drop (Finder / OS paths) ───────────────────────────────
   onFileDrop?: (event: EventPayload) => void
 
diff --git a/packages/native/js/mutations.ts b/packages/native/js/mutations.ts
index ebf06411d..c8738338c 100644
--- a/packages/native/js/mutations.ts
+++ b/packages/native/js/mutations.ts
@@ -96,6 +96,7 @@ export const EVENT_PROPS = [
   ["onFocus", "focus"],
   ["onBlur", "blur"],
   ["onScroll", "scroll"],
+  ["onLayout", "layout"],
   ["onFileDrop", "fileDrop"],
 ] as const
 
diff --git a/packages/native/src/automation.rs b/packages/native/src/automation.rs
index c9ed5ec4c..08e9fa93d 100644
--- a/packages/native/src/automation.rs
+++ b/packages/native/src/automation.rs
@@ -9,6 +9,7 @@
 
 use std::cell::RefCell;
 use std::collections::HashMap;
+use std::rc::Rc;
 use std::sync::{Arc, Mutex};
 use std::time::Duration;
 
@@ -72,34 +73,44 @@ pub fn track_own_bounds<E: gpui::InteractiveElement>(el: E, id: u64) -> E {
 /// Record a host element's painted box, and its selection-start region, for
 /// automation and text selection.
 ///
-/// A visible element reports its own box through `on_painted`, so tracking it
-/// adds nothing to the tree. The previous `bounds_tracker` child doubled the
-/// number of nodes gpui laid out, prepainted and painted for every `<div>` and
+/// The element reports its own box through `on_painted`, so tracking it adds
+/// nothing to the tree. The previous `bounds_tracker` child doubled the number
+/// of nodes gpui laid out, prepainted and painted for every `<div>` and
 /// `<text>`.
 ///
-/// gpui does not call `on_painted` for `visibility: hidden`, and a hidden
-/// element still has a layout box that a locator or a measurement is entitled
-/// to read. `hidden` keeps the canvas for exactly those elements. The canvas is
-/// `absolute`, so the element must be a positioned parent.
+/// gpui paints nothing for `visibility: hidden`, not the element and not its
+/// children, so a hidden element reports no box and fires no `onLayout`. A
+/// canvas child cannot work around that: it is never painted either.
 ///
-/// The two paths differ by an element's border: the canvas fills the padding
-/// box, and `on_painted` reports the border box, which is what a DOM
-/// `getBoundingClientRect` reports.
-pub fn track_host_bounds<E>(el: E, id: u64, selection_start: Option<bool>, hidden: bool) -> E
+/// The box is the border box, which is what a DOM `getBoundingClientRect`
+/// reports. `bounds_tracker` fills the padding box instead.
+///
+/// `layout` sees the painted box right after it is recorded, and is how
+/// `onLayout` learns the size. `on_painted` takes one listener, so it shares
+/// this one.
+pub fn track_host_bounds<E>(
+    el: E,
+    id: u64,
+    selection_start: Option<bool>,
+    layout: Option<LayoutReporter>,
+) -> E
 where
-    E: gpui::InteractiveElement + gpui::ParentElement,
+    E: gpui::InteractiveElement,
 {
-    if hidden {
-        return el.child(bounds_tracker(id, selection_start));
-    }
-    el.on_painted(move |bounds, _, _| {
+    el.on_painted(move |bounds, _, cx| {
         record_bounds(id, bounds);
         if let Some(selectable) = selection_start {
             crate::text::record_start_region(bounds, selectable);
         }
+        if let Some(layout) = &layout {
+            layout(bounds, cx);
+        }
     })
 }
 
+/// Called with an element's painted box on every paint, from inside paint.
+pub type LayoutReporter = Rc<dyn Fn(Bounds<Pixels>, &mut App)>;
+
 pub fn record_bounds(id: u64, bounds: Bounds<Pixels>) {
     BOUNDS.with(|cell| {
         cell.borrow_mut()
diff --git a/packages/native/src/custom_elements/mod.rs b/packages/native/src/custom_elements/mod.rs
index e861fe0c5..158269f17 100644
--- a/packages/native/src/custom_elements/mod.rs
+++ b/packages/native/src/custom_elements/mod.rs
@@ -128,13 +128,7 @@ pub(crate) fn custom_surface(
     {
         el = el.relative();
     }
-    el = crate::automation::track_host_bounds(
-        el,
-        ctx.id,
-        None,
-        ctx.style
-            .is_some_and(|style| style.visibility.as_deref() == Some("hidden")),
-    );
+    el = crate::automation::track_host_bounds(el, ctx.id, None, None);
     el = crate::accessibility::apply_accessibility(el, ctx.props, None);
     wire_standard_events(el, ctx)
 }
diff --git a/packages/native/src/element_tree.rs b/packages/native/src/element_tree.rs
index 887eb9100..cffa8b6b0 100644
--- a/packages/native/src/element_tree.rs
+++ b/packages/native/src/element_tree.rs
@@ -113,6 +113,11 @@ pub struct EventPayload {
     /// Exclusive end of the visible logical range. Populated for: visibleRange.
     pub end_index: Option<f64>,
 
+    /// Border-box size of the element, in pixels. With `x` and `y`, its position
+    /// in window coordinates. Populated for: layout.
+    pub width: Option<f64>,
+    pub height: Option<f64>,
+
     /// Matches found by this element's `highlight` prop. Counted once per match
     /// even when it is split across several painted runs, and it counts every
     /// retained match, not only the ones currently on screen.
@@ -156,6 +161,8 @@ impl Default for EventPayload {
             new_line: None,
             start_index: None,
             end_index: None,
+            width: None,
+            height: None,
             match_count: None,
             motion_generation: None,
             paths: None,
diff --git a/packages/native/src/renderer.rs b/packages/native/src/renderer.rs
index 3a788a72c..2d71e31d9 100644
--- a/packages/native/src/renderer.rs
+++ b/packages/native/src/renderer.rs
@@ -3486,8 +3486,14 @@ pub(crate) struct GpuixView {
     /// Resolved `highlight` state, keyed by the element that declared it.
     /// Empty in every app that does not use search.
     highlights: HashMap<u64, HighlightCacheEntry>,
+    /// Last size reported through `onLayout`, for elements that have the
+    /// listener. Shared with the paint closures that compare against it.
+    layout_sizes: LayoutSizes,
 }
 
+/// See `GpuixView::layout_sizes`.
+pub(crate) type LayoutSizes = Rc<RefCell<HashMap<u64, (f32, f32)>>>;
+
 /// Two-level cache for one element's `highlight`.
 ///
 /// The group list is keyed by `search_revision`, which a query change does NOT
@@ -3774,6 +3780,7 @@ impl GpuixView {
             selection_scroll_task: None,
             clock: crate::automation::AutomationClock::new(),
             highlights: HashMap::new(),
+            layout_sizes: LayoutSizes::default(),
         }
     }
 
@@ -4009,6 +4016,7 @@ impl GpuixView {
             selection: self.selection.clone(),
             inherited,
             highlights: &mut self.highlights,
+            layout_sizes: &self.layout_sizes,
             highlight_events: &mut highlight_events,
             keyboard_focus,
         };
@@ -4134,6 +4142,7 @@ pub(crate) struct BuildCtx<'a> {
     pub inherited: Inherited,
     /// Persistent `highlight` caches, keyed by the declaring element.
     highlights: &'a mut HashMap<u64, HighlightCacheEntry>,
+    layout_sizes: &'a LayoutSizes,
     /// `onHighlight` payloads queued during the build.
     ///
     /// Never emitted inline: a handler that calls `setState` repaints, which
@@ -4907,6 +4916,18 @@ impl gpui::Render for GpuixView {
             .retain(|id, _| tree.elements.contains_key(id));
         self.virtual_lists
             .retain(|id, _| tree.elements.contains_key(id));
+        // Pruned by listener, not existence: dropping `onLayout` and adding it
+        // back reports the size again, like a fresh observer.
+        {
+            let mut sizes = self.layout_sizes.borrow_mut();
+            if !sizes.is_empty() {
+                sizes.retain(|id, _| {
+                    tree.elements
+                        .get(id)
+                        .is_some_and(|element| element.events.contains("layout"))
+                });
+            }
+        }
         // Build the element tree. custom_registry, focus_handles, and scroll_handles
         // are different fields of self, so Rust allows borrowing all simultaneously.
         let theme = Theme::dark();
@@ -4937,6 +4958,7 @@ impl gpui::Render for GpuixView {
                     selection: self.selection.clone(),
                     inherited: Inherited::root(&theme),
                     highlights: &mut self.highlights,
+                    layout_sizes: &self.layout_sizes,
                     highlight_events: &mut highlight_events,
                     keyboard_focus,
                 };
@@ -5415,7 +5437,7 @@ pub(crate) fn build_host_container(
         el,
         element.id,
         selection_start_flag(style),
-        is_hidden(style),
+        layout_reporter(element.id, &element.events, ctx),
     );
 
     if let Some(handle) = ctx.focus_handles.get(&element.id) {
@@ -5717,10 +5739,6 @@ fn text_content(
     })
 }
 
-fn is_hidden(style: Option<&StyleDesc>) -> bool {
-    style.is_some_and(|style| style.visibility.as_deref() == Some("hidden"))
-}
-
 /// Explicit `userSelect` on this node. `None` means inherit; the ancestor
 /// that set the value already owns the start region.
 fn selection_start_flag(style: Option<&StyleDesc>) -> Option<bool> {
@@ -6168,6 +6186,54 @@ pub(crate) fn mouse_button_to_u32(button: gpui::MouseButton) -> u32 {
     }
 }
 
+/// `onLayout` for one element: its painted box after the first paint with the
+/// listener, then again each time its size changes. A move without a resize
+/// reports nothing, so scrolling a list does not queue an event per row.
+///
+/// The event is queued after the paint that saw the change, never from inside
+/// it. The browser build calls the listener synchronously, and a handler that
+/// sets state would re-enter the frame that is being painted.
+fn layout_reporter(
+    id: u64,
+    events: &HashSet<String>,
+    ctx: &BuildCtx,
+) -> Option<crate::automation::LayoutReporter> {
+    if !events.contains("layout") {
+        return None;
+    }
+    let callback = ctx.event_callback.clone()?;
+    let sizes = ctx.layout_sizes.clone();
+    Some(Rc::new(move |bounds, cx| {
+        let size = (
+            f32::from(bounds.size.width),
+            f32::from(bounds.size.height),
+        );
+        {
+            let mut sizes = sizes.borrow_mut();
+            let unchanged = sizes.get(&id).is_some_and(|last| {
+                (last.0 - size.0).abs() < LAYOUT_EPSILON && (last.1 - size.1).abs() < LAYOUT_EPSILON
+            });
+            if unchanged {
+                return;
+            }
+            sizes.insert(id, size);
+        }
+        let callback = Some(callback.clone());
+        cx.defer(move |_| {
+            emit_event_full(&callback, id, "layout", |payload| {
+                payload.x = Some(f64::from(f32::from(bounds.origin.x)));
+                payload.y = Some(f64::from(f32::from(bounds.origin.y)));
+                payload.width = Some(f64::from(size.0));
+                payload.height = Some(f64::from(size.1));
+            });
+        });
+    }))
+}
+
+/// Sizes closer than this are the same size. Layout is deterministic, so this
+/// only absorbs float noise from fractional scale factors.
+const LAYOUT_EPSILON: f32 = 0.01;
+
 /// General-purpose event emitter. Builds a default EventPayload, lets the
 /// caller customize it via a closure, then sends it through the callback.
 /// Production: queues on Node.js event loop via ThreadsafeFunction.
diff --git a/packages/react/src/__tests__/layout-event.test.tsx b/packages/react/src/__tests__/layout-event.test.tsx
new file mode 100644
index 000000000..e1a7e915f
--- /dev/null
+++ b/packages/react/src/__tests__/layout-event.test.tsx
@@ -0,0 +1,188 @@
+import { describe, expect, it } from "vitest"
+import type { EventPayload } from "@gpuix/native"
+import { createTestRoot, hasNativeTestRenderer } from "../testing.js"
+
+const describeNative = hasNativeTestRenderer ? describe : describe.skip
+
+const size = (event: EventPayload) => [event.width, event.height]
+
+describeNative("onLayout", () => {
+  it("reports the border box after the first paint", () => {
+    const { render, renderer, unmount } = createTestRoot()
+    try {
+      const events: EventPayload[] = []
+      render(
+        <div style={{ padding: 10 }}>
+          <div
+            testId="box"
+            style={{ width: 120, height: 40, borderWidth: 2, borderColor: "#fff" }}
+            onLayout={(event) => events.push(event)}
+          />
+        </div>
+      )
+      renderer.dispatchNativeEvents()
+
+      expect(events).toHaveLength(1)
+      expect(size(events[0]!)).toEqual([120, 40])
+      const bounds = renderer.getElementBounds(renderer.findByTestId("box")!.id)!
+      expect([events[0]!.x, events[0]!.y]).toEqual([bounds.x, bounds.y])
+    } finally {
+      unmount()
+    }
+  })
+
+  it("reports again only when the size changes", () => {
+    const { render, renderer, unmount } = createTestRoot()
+    try {
+      const sizes: unknown[] = []
+      const app = (width: number, label = "a") => (
+        <div style={{ flexDirection: "column" }}>
+          <div
+            style={{ width, height: 30 }}
+            onLayout={(event) => sizes.push(size(event))}
+            testId={label}
+          />
+        </div>
+      )
+
+      render(app(100))
+      renderer.dispatchNativeEvents()
+      render(app(100))
+      renderer.dispatchNativeEvents()
+      expect(sizes, "an identical frame reports nothing").toEqual([[100, 30]])
+
+      render(app(140))
+      renderer.dispatchNativeEvents()
+      expect(sizes).toEqual([
+        [100, 30],
+        [140, 30],
+      ])
+    } finally {
+      unmount()
+    }
+  })
+
+  it("stays quiet when an element moves without resizing", () => {
+    const { render, renderer, unmount } = createTestRoot()
+    try {
+      const sizes: unknown[] = []
+      const app = (above: number) => (
+        <div style={{ flexDirection: "column" }}>
+          <div style={{ height: above, width: 50 }} />
+          <div style={{ width: 80, height: 20 }} onLayout={(event) => sizes.push(size(event))} />
+        </div>
+      )
+
+      render(app(10))
+      renderer.dispatchNativeEvents()
+      render(app(60))
+      renderer.dispatchNativeEvents()
+      expect(sizes).toEqual([[80, 20]])
+    } finally {
+      unmount()
+    }
+  })
+
+  it("reports a size the element gets from its content", () => {
+    const { render, renderer, unmount } = createTestRoot()
+    try {
+      const heights: number[] = []
+      const app = (lines: number) => (
+        <div
+          style={{ width: 200, flexDirection: "column" }}
+          onLayout={(event) => heights.push(event.height ?? -1)}
+        >
+          {Array.from({ length: lines }, (_, index) => (
+            <div key={index} style={{ height: 16 }} />
+          ))}
+        </div>
+      )
+
+      render(app(1))
+      renderer.dispatchNativeEvents()
+      render(app(3))
+      renderer.dispatchNativeEvents()
+      expect(heights).toEqual([16, 48])
+    } finally {
+      unmount()
+    }
+  })
+
+  it("reports again when the listener is removed and added back", () => {
+    const { render, renderer, unmount } = createTestRoot()
+    try {
+      const sizes: unknown[] = []
+      const app = (listening: boolean) => (
+        <div
+          style={{ width: 70, height: 70 }}
+          onLayout={listening ? (event) => sizes.push(size(event)) : undefined}
+        />
+      )
+
+      render(app(true))
+      renderer.dispatchNativeEvents()
+      render(app(false))
+      renderer.dispatchNativeEvents()
+      render(app(true))
+      renderer.dispatchNativeEvents()
+      expect(sizes).toEqual([
+        [70, 70],
+        [70, 70],
+      ])
+    } finally {
+      unmount()
+    }
+  })
+
+  it("is silent while the element is hidden, and reports once it shows", () => {
+    const { render, renderer, unmount } = createTestRoot()
+    try {
+      const sizes: unknown[] = []
+      const app = (visibility: "hidden" | "visible") => (
+        <div
+          style={{ width: 64, height: 24, visibility }}
+          onLayout={(event) => sizes.push(size(event))}
+        />
+      )
+
+      render(app("hidden"))
+      renderer.dispatchNativeEvents()
+      expect(sizes, "gpui paints nothing for a hidden element").toEqual([])
+
+      render(app("visible"))
+      renderer.dispatchNativeEvents()
+      expect(sizes).toEqual([[64, 24]])
+    } finally {
+      unmount()
+    }
+  })
+
+  it("reports elements inside a virtual list as they are measured", () => {
+    const { render, renderer, unmount } = createTestRoot()
+    try {
+      const sizes: unknown[][] = []
+      render(
+        <div style={{ width: 300, height: 100 }}>
+          <virtual-list style={{ width: 300, height: 100 }} estimatedItemHeight={20}>
+            {Array.from({ length: 50 }, (_, index) => (
+              <div
+                key={index}
+                style={{ height: 20 + (index % 2) * 10 }}
+                onLayout={(event) => sizes.push([index, event.height])}
+              />
+            ))}
+          </virtual-list>
+        </div>
+      )
+      renderer.dispatchNativeEvents()
+
+      expect(sizes.length).toBeGreaterThan(0)
+      expect(sizes.length, "rows outside the window are never built").toBeLessThan(50)
+      for (const [index, height] of sizes) {
+        expect(height).toBe(20 + ((index as number) % 2) * 10)
+      }
+    } finally {
+      unmount()
+    }
+  })
+})
diff --git a/packages/solid/src/__tests__/renderer.test.tsx b/packages/solid/src/__tests__/renderer.test.tsx
index 4997345b3..381b56d80 100644
--- a/packages/solid/src/__tests__/renderer.test.tsx
+++ b/packages/solid/src/__tests__/renderer.test.tsx
@@ -193,4 +193,17 @@ describe.skipIf(!hasNativeTestRenderer)("Solid renderer", () => {
     })
     expect(completions).toBe(1)
   })
+
+  it("delivers onLayout with the painted size", () => {
+    const sizes: unknown[] = []
+    const app = createTestRoot()
+    app.render(() => (
+      <div
+        style={{ width: 90, height: 30 }}
+        onLayout={(event) => sizes.push([event.width, event.height])}
+      />
+    ))
+    app.renderer.dispatchNativeEvents()
+    expect(sizes).toEqual([[90, 30]])
+  })
 })

From 5ab017a32bbe82b27e9ee768ad5c714917b1974f Mon Sep 17 00:00:00 2001
From: Ruben Nogueira <40404708+rubnogueira@users.noreply.github.com>
Date: Sat, 10 Oct 2026 18:09:54 +0100
Subject: [PATCH 12/27] feat(native): onScrollChange reports every scroll of a
 scroll container

---
 .changeset/on-scroll-change.md                |   7 +
 README.md                                     |  17 ++
 packages/native/index.d.ts                    |   6 +
 packages/native/js/host.ts                    |  10 ++
 packages/native/js/mutations.ts               |   1 +
 packages/native/src/automation.rs             |  16 +-
 packages/native/src/element_tree.rs           |   7 +
 packages/native/src/renderer.rs               | 170 +++++++++++++-----
 .../__tests__/scroll-change-event.test.tsx    | 138 ++++++++++++++
 9 files changed, 318 insertions(+), 54 deletions(-)
 create mode 100644 .changeset/on-scroll-change.md
 create mode 100644 packages/react/src/__tests__/scroll-change-event.test.tsx

diff --git a/.changeset/on-scroll-change.md b/.changeset/on-scroll-change.md
new file mode 100644
index 000000000..98092b8e0
--- /dev/null
+++ b/.changeset/on-scroll-change.md
@@ -0,0 +1,7 @@
+---
+'@gpuix/native': minor
+'@gpuix/react': minor
+'@gpuix/solid': minor
+---
+
+`onScrollChange` reports the scroll offset of an `overflow: "scroll"` element after it moves, whatever moved it: the wheel, a scrollbar drag, `scrollTo` or `scrollIntoView`. `onScroll` still reports only wheel input. The event payload gains `scrollX` and `scrollY`.
diff --git a/README.md b/README.md
index 7188ddfee..c591d9e9a 100644
--- a/README.md
+++ b/README.md
@@ -2991,6 +2991,7 @@ text imports no longer need a runtime flag.
 | Focus | `onFocus` | — |
 | Blur | `onBlur` | — |
 | Scroll | `onScroll` | `deltaX`, `deltaY`, `precise`, `touchPhase`, `modifiers` |
+| Scroll change | `onScrollChange` | `scrollX`, `scrollY` — `overflow: "scroll"` containers, not `<virtual-list>` |
 | Layout | `onLayout` | `width`, `height`, `x`, `y` — `<div>` and `<text>` only |
 | File drop | `onFileDrop` | `paths`, `x`, `y` — Unicode filesystem paths from Finder or the OS |
 | Change | `onChange` | `value` — `<input>` and `<textarea>` only |
@@ -3019,6 +3020,22 @@ Put the listener on a **`div`**, **`text`**, **`img`**, **`svg`**, **`input`**,
 </div>
 ```
 
+**`onScroll`** reports wheel input: the delta, before GPUI has applied it.
+**`onScrollChange`** reports the result, after any cause: the wheel, a
+scrollbar drag, `scrollTo`, `scrollIntoView`, or content that shrank under the
+offset. `scrollX` and `scrollY` are the pair `getScrollOffset` returns, 0 at the
+start and negative as the content scrolls. The offset at the first paint is the
+baseline and is not reported. Use `onVisibleRange` on a `<virtual-list>`.
+
+```tsx
+<div
+  style={{ height: 300, overflow: 'scroll' }}
+  onScrollChange={(event) => setStuck((event.scrollY ?? 0) < -80)}
+>
+  {rows}
+</div>
+```
+
 **`onLayout`** is `ResizeObserver` for an element. It fires after the first paint
 that has the listener and again each time the element's **size** changes, with
 its border box: `width` and `height`, and `x` and `y` in window pixels. Moving
diff --git a/packages/native/index.d.ts b/packages/native/index.d.ts
index c5df2a93a..1163447ad 100644
--- a/packages/native/index.d.ts
+++ b/packages/native/index.d.ts
@@ -589,6 +589,12 @@ export interface EventPayload {
    */
   width?: number
   height?: number
+  /**
+   * Scroll offset of the element, the pair `getScrollOffset` returns: 0 at the
+   * start and negative as the content moves. Populated for: scrollChange.
+   */
+  scrollX?: number
+  scrollY?: number
   /**
    * Matches found by this element's `highlight` prop. Counted once per match
    * even when it is split across several painted runs, and it counts every
diff --git a/packages/native/js/host.ts b/packages/native/js/host.ts
index eae6eae10..35676e015 100644
--- a/packages/native/js/host.ts
+++ b/packages/native/js/host.ts
@@ -431,6 +431,16 @@ export interface HostProps {
   // ── Scroll events ──────────────────────────────────────────────
   onScroll?: (event: EventPayload) => void
 
+  /**
+   * The scroll offset of a `overflow: "scroll"` element changed, however it
+   * moved: wheel, scrollbar drag, `scrollTo`, `scrollIntoView`. `scrollX` and
+   * `scrollY` are the pair `getScrollOffset` returns: 0 at the start and
+   * negative as the content scrolls. The position at the first paint is not
+   * reported, only movement after it. Not for `<virtual-list>`; use
+   * `onVisibleRange`.
+   */
+  onScrollChange?: (event: EventPayload) => void
+
   // ── Layout events ──────────────────────────────────────────────
   /**
    * The element's border box, reported after the first paint and each time its
diff --git a/packages/native/js/mutations.ts b/packages/native/js/mutations.ts
index c8738338c..b613b80a2 100644
--- a/packages/native/js/mutations.ts
+++ b/packages/native/js/mutations.ts
@@ -97,6 +97,7 @@ export const EVENT_PROPS = [
   ["onBlur", "blur"],
   ["onScroll", "scroll"],
   ["onLayout", "layout"],
+  ["onScrollChange", "scrollChange"],
   ["onFileDrop", "fileDrop"],
 ] as const
 
diff --git a/packages/native/src/automation.rs b/packages/native/src/automation.rs
index 08e9fa93d..bdbf95b99 100644
--- a/packages/native/src/automation.rs
+++ b/packages/native/src/automation.rs
@@ -85,14 +85,13 @@ pub fn track_own_bounds<E: gpui::InteractiveElement>(el: E, id: u64) -> E {
 /// The box is the border box, which is what a DOM `getBoundingClientRect`
 /// reports. `bounds_tracker` fills the padding box instead.
 ///
-/// `layout` sees the painted box right after it is recorded, and is how
-/// `onLayout` learns the size. `on_painted` takes one listener, so it shares
-/// this one.
+/// `report` sees the painted box right after it is recorded. `on_painted`
+/// takes one listener, so the paint-driven events share this one.
 pub fn track_host_bounds<E>(
     el: E,
     id: u64,
     selection_start: Option<bool>,
-    layout: Option<LayoutReporter>,
+    report: Option<PaintReporter>,
 ) -> E
 where
     E: gpui::InteractiveElement,
@@ -102,14 +101,15 @@ where
         if let Some(selectable) = selection_start {
             crate::text::record_start_region(bounds, selectable);
         }
-        if let Some(layout) = &layout {
-            layout(bounds, cx);
+        if let Some(report) = &report {
+            report(bounds, cx);
         }
     })
 }
 
-/// Called with an element's painted box on every paint, from inside paint.
-pub type LayoutReporter = Rc<dyn Fn(Bounds<Pixels>, &mut App)>;
+/// Called with an element's painted box on every paint, from inside paint. It
+/// is how `onLayout` and `onScrollChange` see what the frame produced.
+pub type PaintReporter = Rc<dyn Fn(Bounds<Pixels>, &mut App)>;
 
 pub fn record_bounds(id: u64, bounds: Bounds<Pixels>) {
     BOUNDS.with(|cell| {
diff --git a/packages/native/src/element_tree.rs b/packages/native/src/element_tree.rs
index cffa8b6b0..1b0bdd2db 100644
--- a/packages/native/src/element_tree.rs
+++ b/packages/native/src/element_tree.rs
@@ -118,6 +118,11 @@ pub struct EventPayload {
     pub width: Option<f64>,
     pub height: Option<f64>,
 
+    /// Scroll offset of the element, the pair `getScrollOffset` returns: 0 at the
+    /// start and negative as the content moves. Populated for: scrollChange.
+    pub scroll_x: Option<f64>,
+    pub scroll_y: Option<f64>,
+
     /// Matches found by this element's `highlight` prop. Counted once per match
     /// even when it is split across several painted runs, and it counts every
     /// retained match, not only the ones currently on screen.
@@ -163,6 +168,8 @@ impl Default for EventPayload {
             end_index: None,
             width: None,
             height: None,
+            scroll_x: None,
+            scroll_y: None,
             match_count: None,
             motion_generation: None,
             paths: None,
diff --git a/packages/native/src/renderer.rs b/packages/native/src/renderer.rs
index 2d71e31d9..abca9af0b 100644
--- a/packages/native/src/renderer.rs
+++ b/packages/native/src/renderer.rs
@@ -3486,13 +3486,21 @@ pub(crate) struct GpuixView {
     /// Resolved `highlight` state, keyed by the element that declared it.
     /// Empty in every app that does not use search.
     highlights: HashMap<u64, HighlightCacheEntry>,
-    /// Last size reported through `onLayout`, for elements that have the
-    /// listener. Shared with the paint closures that compare against it.
-    layout_sizes: LayoutSizes,
+    /// What `onLayout` and `onScrollChange` last reported, for the elements that
+    /// have the listener. Shared with the paint closures that compare against it.
+    paint_reports: SharedPaintReports,
 }
 
-/// See `GpuixView::layout_sizes`.
-pub(crate) type LayoutSizes = Rc<RefCell<HashMap<u64, (f32, f32)>>>;
+#[derive(Default)]
+pub(crate) struct PaintReports {
+    /// Border-box size last delivered through `onLayout`.
+    sizes: HashMap<u64, (f32, f32)>,
+    /// Scroll offset last seen for `onScrollChange`. Recorded on the first paint
+    /// without an event, so only movement is reported.
+    scrolls: HashMap<u64, (f32, f32)>,
+}
+
+pub(crate) type SharedPaintReports = Rc<RefCell<PaintReports>>;
 
 /// Two-level cache for one element's `highlight`.
 ///
@@ -3780,7 +3788,7 @@ impl GpuixView {
             selection_scroll_task: None,
             clock: crate::automation::AutomationClock::new(),
             highlights: HashMap::new(),
-            layout_sizes: LayoutSizes::default(),
+            paint_reports: SharedPaintReports::default(),
         }
     }
 
@@ -4016,7 +4024,7 @@ impl GpuixView {
             selection: self.selection.clone(),
             inherited,
             highlights: &mut self.highlights,
-            layout_sizes: &self.layout_sizes,
+            paint_reports: &self.paint_reports,
             highlight_events: &mut highlight_events,
             keyboard_focus,
         };
@@ -4142,7 +4150,7 @@ pub(crate) struct BuildCtx<'a> {
     pub inherited: Inherited,
     /// Persistent `highlight` caches, keyed by the declaring element.
     highlights: &'a mut HashMap<u64, HighlightCacheEntry>,
-    layout_sizes: &'a LayoutSizes,
+    paint_reports: &'a SharedPaintReports,
     /// `onHighlight` payloads queued during the build.
     ///
     /// Never emitted inline: a handler that calls `setState` repaints, which
@@ -4919,14 +4927,21 @@ impl gpui::Render for GpuixView {
         // Pruned by listener, not existence: dropping `onLayout` and adding it
         // back reports the size again, like a fresh observer.
         {
-            let mut sizes = self.layout_sizes.borrow_mut();
-            if !sizes.is_empty() {
-                sizes.retain(|id, _| {
+            let mut reports = self.paint_reports.borrow_mut();
+            if !reports.sizes.is_empty() {
+                reports.sizes.retain(|id, _| {
                     tree.elements
                         .get(id)
                         .is_some_and(|element| element.events.contains("layout"))
                 });
             }
+            if !reports.scrolls.is_empty() {
+                reports.scrolls.retain(|id, _| {
+                    tree.elements
+                        .get(id)
+                        .is_some_and(|element| element.events.contains("scrollChange"))
+                });
+            }
         }
         // Build the element tree. custom_registry, focus_handles, and scroll_handles
         // are different fields of self, so Rust allows borrowing all simultaneously.
@@ -4958,7 +4973,7 @@ impl gpui::Render for GpuixView {
                     selection: self.selection.clone(),
                     inherited: Inherited::root(&theme),
                     highlights: &mut self.highlights,
-                    layout_sizes: &self.layout_sizes,
+                    paint_reports: &self.paint_reports,
                     highlight_events: &mut highlight_events,
                     keyboard_focus,
                 };
@@ -5437,7 +5452,7 @@ pub(crate) fn build_host_container(
         el,
         element.id,
         selection_start_flag(style),
-        layout_reporter(element.id, &element.events, ctx),
+        paint_reporter(element.id, &element.events, ctx),
     );
 
     if let Some(handle) = ctx.focus_handles.get(&element.id) {
@@ -6186,53 +6201,116 @@ pub(crate) fn mouse_button_to_u32(button: gpui::MouseButton) -> u32 {
     }
 }
 
-/// `onLayout` for one element: its painted box after the first paint with the
-/// listener, then again each time its size changes. A move without a resize
-/// reports nothing, so scrolling a list does not queue an event per row.
+/// The paint-driven events of one element, as one reporter for `on_painted`.
 ///
-/// The event is queued after the paint that saw the change, never from inside
-/// it. The browser build calls the listener synchronously, and a handler that
-/// sets state would re-enter the frame that is being painted.
-fn layout_reporter(
+/// `onLayout`: its border box after the first paint with the listener, then again
+/// each time its size changes. A move without a resize reports nothing, so
+/// scrolling a list does not queue an event per row.
+///
+/// `onScrollChange`: its scroll offset each time it differs from the last paint,
+/// whatever moved it. The wheel is only one cause; a scrollbar drag or
+/// `scrollTo` moves it too, and gpui raises no event for those.
+///
+/// Events are queued after the paint that saw the change, never from inside it.
+/// The browser build calls the listener synchronously, and a handler that sets
+/// state would re-enter the frame that is being painted.
+fn paint_reporter(
     id: u64,
     events: &HashSet<String>,
     ctx: &BuildCtx,
-) -> Option<crate::automation::LayoutReporter> {
-    if !events.contains("layout") {
+) -> Option<crate::automation::PaintReporter> {
+    let layout = events.contains("layout");
+    let scroll = events
+        .contains("scrollChange")
+        .then(|| ctx.scroll_handles.get(&id).cloned())
+        .flatten();
+    if !layout && scroll.is_none() {
         return None;
     }
     let callback = ctx.event_callback.clone()?;
-    let sizes = ctx.layout_sizes.clone();
+    let reports = ctx.paint_reports.clone();
     Some(Rc::new(move |bounds, cx| {
-        let size = (
-            f32::from(bounds.size.width),
-            f32::from(bounds.size.height),
-        );
-        {
-            let mut sizes = sizes.borrow_mut();
-            let unchanged = sizes.get(&id).is_some_and(|last| {
-                (last.0 - size.0).abs() < LAYOUT_EPSILON && (last.1 - size.1).abs() < LAYOUT_EPSILON
-            });
-            if unchanged {
+        if layout {
+            report_layout(id, bounds, &reports, &callback, cx);
+        }
+        if let Some(handle) = &scroll {
+            report_scroll(id, handle.offset(), &reports, &callback, cx);
+        }
+    }))
+}
+
+fn report_layout(
+    id: u64,
+    bounds: gpui::Bounds<gpui::Pixels>,
+    reports: &SharedPaintReports,
+    callback: &EventCallback,
+    cx: &mut gpui::App,
+) {
+    let size = (
+        f32::from(bounds.size.width),
+        f32::from(bounds.size.height),
+    );
+    {
+        let mut reports = reports.borrow_mut();
+        let unchanged = reports.sizes.get(&id).is_some_and(|last| {
+            (last.0 - size.0).abs() < PAINT_REPORT_EPSILON
+                && (last.1 - size.1).abs() < PAINT_REPORT_EPSILON
+        });
+        if unchanged {
+            return;
+        }
+        reports.sizes.insert(id, size);
+    }
+    let callback = Some(callback.clone());
+    cx.defer(move |_| {
+        emit_event_full(&callback, id, "layout", |payload| {
+            payload.x = Some(f64::from(f32::from(bounds.origin.x)));
+            payload.y = Some(f64::from(f32::from(bounds.origin.y)));
+            payload.width = Some(f64::from(size.0));
+            payload.height = Some(f64::from(size.1));
+        });
+    });
+}
+
+fn report_scroll(
+    id: u64,
+    offset: gpui::Point<gpui::Pixels>,
+    reports: &SharedPaintReports,
+    callback: &EventCallback,
+    cx: &mut gpui::App,
+) {
+    let offset = (f32::from(offset.x), f32::from(offset.y));
+    {
+        let mut reports = reports.borrow_mut();
+        match reports.scrolls.get(&id).copied() {
+            // The first paint only sets the baseline.
+            None => {
+                reports.scrolls.insert(id, offset);
                 return;
             }
-            sizes.insert(id, size);
-        }
-        let callback = Some(callback.clone());
-        cx.defer(move |_| {
-            emit_event_full(&callback, id, "layout", |payload| {
-                payload.x = Some(f64::from(f32::from(bounds.origin.x)));
-                payload.y = Some(f64::from(f32::from(bounds.origin.y)));
-                payload.width = Some(f64::from(size.0));
-                payload.height = Some(f64::from(size.1));
-            });
+            Some(last)
+                if (last.0 - offset.0).abs() < PAINT_REPORT_EPSILON
+                    && (last.1 - offset.1).abs() < PAINT_REPORT_EPSILON =>
+            {
+                return;
+            }
+            Some(_) => {
+                reports.scrolls.insert(id, offset);
+            }
+        }
+    }
+    let callback = Some(callback.clone());
+    cx.defer(move |_| {
+        emit_event_full(&callback, id, "scrollChange", |payload| {
+            payload.scroll_x = Some(f64::from(offset.0));
+            payload.scroll_y = Some(f64::from(offset.1));
         });
-    }))
+    });
 }
 
-/// Sizes closer than this are the same size. Layout is deterministic, so this
+/// Values closer than this are the same value. Layout is deterministic, so this
 /// only absorbs float noise from fractional scale factors.
-const LAYOUT_EPSILON: f32 = 0.01;
+const PAINT_REPORT_EPSILON: f32 = 0.01;
 
 /// General-purpose event emitter. Builds a default EventPayload, lets the
 /// caller customize it via a closure, then sends it through the callback.
diff --git a/packages/react/src/__tests__/scroll-change-event.test.tsx b/packages/react/src/__tests__/scroll-change-event.test.tsx
new file mode 100644
index 000000000..a5d458c30
--- /dev/null
+++ b/packages/react/src/__tests__/scroll-change-event.test.tsx
@@ -0,0 +1,138 @@
+import { describe, expect, it } from "vitest"
+import type { EventPayload } from "@gpuix/native"
+import { createTestRoot, hasNativeTestRenderer } from "../testing.js"
+
+const describeNative = hasNativeTestRenderer ? describe : describe.skip
+
+const offset = (event: EventPayload) => [event.scrollX, event.scrollY]
+
+function scroller(onScrollChange?: (event: EventPayload) => void) {
+  return (
+    <div
+      testId="scroller"
+      style={{ width: 200, height: 100, overflow: "scroll" }}
+      onScrollChange={onScrollChange}
+    >
+      <div style={{ height: 500 }} />
+    </div>
+  )
+}
+
+describeNative("onScrollChange", () => {
+  it("reports movement, not the position it starts at", () => {
+    const { render, renderer, unmount } = createTestRoot()
+    try {
+      const offsets: unknown[] = []
+      render(scroller((event) => offsets.push(offset(event))))
+      renderer.dispatchNativeEvents()
+      expect(offsets, "a first paint is not a scroll").toEqual([])
+
+      const id = renderer.findByTestId("scroller")!.id
+      renderer.scrollTo(id, 0, -100)
+      renderer.dispatchNativeEvents()
+      expect(offsets).toEqual([[0, -100]])
+      expect(renderer.getScrollOffset(id)).toEqual([0, -100])
+    } finally {
+      unmount()
+    }
+  })
+
+  it("reports a wheel scroll with the offset it leaves", () => {
+    const { render, renderer, unmount } = createTestRoot()
+    try {
+      const offsets: number[][] = []
+      render(scroller((event) => offsets.push(offset(event) as number[])))
+      renderer.nativeSimulateScrollWheel(100, 50, 0, -40)
+
+      expect(offsets).toHaveLength(1)
+      const id = renderer.findByTestId("scroller")!.id
+      expect(offsets[0]).toEqual(renderer.getScrollOffset(id))
+      expect(offsets[0]![1]).toBeLessThan(0)
+    } finally {
+      unmount()
+    }
+  })
+
+  it("stays quiet while the offset holds, and for sub-pixel noise", () => {
+    const { render, renderer, unmount } = createTestRoot()
+    try {
+      const offsets: unknown[] = []
+      const app = () => scroller((event) => offsets.push(offset(event)))
+      render(app())
+      const id = renderer.findByTestId("scroller")!.id
+      renderer.scrollTo(id, 0, -30)
+      renderer.dispatchNativeEvents()
+      expect(offsets).toHaveLength(1)
+
+      render(app())
+      renderer.scrollTo(id, 0, -30.004)
+      renderer.dispatchNativeEvents()
+      expect(offsets).toHaveLength(1)
+    } finally {
+      unmount()
+    }
+  })
+
+  it("starts from where the element already is when the listener arrives late", () => {
+    const { render, renderer, unmount } = createTestRoot()
+    try {
+      const offsets: unknown[] = []
+      render(scroller())
+      const id = renderer.findByTestId("scroller")!.id
+      renderer.scrollTo(id, 0, -80)
+
+      render(scroller((event) => offsets.push(offset(event))))
+      renderer.dispatchNativeEvents()
+      expect(offsets).toEqual([])
+
+      renderer.scrollTo(id, 0, -120)
+      renderer.dispatchNativeEvents()
+      expect(offsets).toEqual([[0, -120]])
+    } finally {
+      unmount()
+    }
+  })
+
+  it("reports a scroll that follows scrollIntoView", () => {
+    const { render, renderer, unmount } = createTestRoot()
+    try {
+      const offsets: unknown[] = []
+      render(
+        <div
+          testId="scroller"
+          style={{ width: 200, height: 100, overflow: "scroll" }}
+          onScrollChange={(event) => offsets.push(offset(event))}
+        >
+          <div style={{ height: 400 }} />
+          <div testId="target" style={{ height: 20 }} />
+        </div>
+      )
+      renderer.dispatchNativeEvents()
+      expect(offsets).toEqual([])
+
+      renderer.scrollIntoView(renderer.findByTestId("target")!.id)
+      renderer.dispatchNativeEvents()
+      expect(offsets).toHaveLength(1)
+      expect((offsets[0] as number[])[1]).toBeLessThan(0)
+    } finally {
+      unmount()
+    }
+  })
+
+  it("ignores an element that does not scroll", () => {
+    const { render, renderer, unmount } = createTestRoot()
+    try {
+      const offsets: unknown[] = []
+      render(
+        <div
+          style={{ width: 200, height: 100 }}
+          onScrollChange={(event) => offsets.push(offset(event))}
+        />
+      )
+      renderer.dispatchNativeEvents()
+      expect(offsets).toEqual([])
+    } finally {
+      unmount()
+    }
+  })
+})

From d8fd814ed0047f0ba5e1bf8debf476039d3f5900 Mon Sep 17 00:00:00 2001
From: Ruben Nogueira <40404708+rubnogueira@users.noreply.github.com>
Date: Sat, 10 Oct 2026 18:23:32 +0100
Subject: [PATCH 13/27] fix(native): hover ends when the pointer leaves the
 window

---
 .changeset/hover-ends-at-window-edge.md      |  5 ++
 README.md                                    |  3 ++
 packages/native/index.d.ts                   |  5 ++
 packages/native/js/testing.ts                | 10 ++++
 packages/native/src/test_renderer.rs         | 18 +++++++
 packages/react/src/__tests__/events.test.tsx | 55 +++++++++++++++++++-
 zed                                          |  2 +-
 7 files changed, 96 insertions(+), 2 deletions(-)
 create mode 100644 .changeset/hover-ends-at-window-edge.md

diff --git a/.changeset/hover-ends-at-window-edge.md b/.changeset/hover-ends-at-window-edge.md
new file mode 100644
index 000000000..716a6f933
--- /dev/null
+++ b/.changeset/hover-ends-at-window-edge.md
@@ -0,0 +1,5 @@
+---
+'@gpuix/native': patch
+---
+
+Leaving the window ends hover. The `hover` style of the element the pointer last touched used to stay painted, and the cursor and tooltips stayed with it, until the pointer came back. `onMouseLeave` already fired. The test renderer gains `simulateMouseExit` and `nativeSimulateMouseExit`.
diff --git a/README.md b/README.md
index c591d9e9a..7c308b49a 100644
--- a/README.md
+++ b/README.md
@@ -3056,6 +3056,9 @@ Keyboard and focus listeners create a persistent GPUI `FocusHandle`
 automatically. A listener alone does not put a `div` in the Tab order; add
 `tabIndex={0}` for that. Inputs and textareas already use tab index `0`.
 
+`onMouseLeave` also fires when the pointer leaves the **window** without a final
+move over the element, and the element's `hover` style ends with it.
+
 A node that listens for both `onMouseDown` and `onMouseMove` **captures the
 pointer**, like HTML [`setPointerCapture`](https://developer.mozilla.org/en-US/docs/Web/API/Element/setPointerCapture).
 `onMouseMove` and `onMouseUp` keep firing after the pointer leaves the hitbox,
diff --git a/packages/native/index.d.ts b/packages/native/index.d.ts
index 1163447ad..814af91ca 100644
--- a/packages/native/index.d.ts
+++ b/packages/native/index.d.ts
@@ -271,6 +271,11 @@ export declare class TestGpuixRenderer {
    * Used to simulate drag events.
    */
   simulateMouseMove(x: number, y: number, pressedButton?: number | undefined | null, modifiers?: string | undefined | null): void
+  /**
+   * Simulate the pointer leaving the window, as the platform reports it when
+   * the cursor crosses the window edge: there is no final mouse move.
+   */
+  simulateMouseExit(x: number, y: number): void
   /**
    * Focus an element by its numeric ID.
    * The element must have a FocusHandle (created by sync_focus_handles when
diff --git a/packages/native/js/testing.ts b/packages/native/js/testing.ts
index ecbb5a578..1973fd049 100644
--- a/packages/native/js/testing.ts
+++ b/packages/native/js/testing.ts
@@ -61,6 +61,7 @@ interface NativeTestRendererApi extends NativeRenderer {
     pressedButton?: number,
     modifiers?: string
   ): void
+  simulateMouseExit(x: number, y: number): void
   simulateMouseDown(x: number, y: number, button: number, modifiers?: string): void
   simulateMouseUp(x: number, y: number, button: number, modifiers?: string): void
   simulateFileDrop(x: number, y: number, paths: string[]): void
@@ -357,6 +358,15 @@ export class TestRenderer implements NativeRenderer {
     this.native.flush()
   }
 
+  /** End-to-end: the pointer leaves the window at (x, y), the way the platform
+   *  reports it, with no mouse move after the last position inside. */
+  nativeSimulateMouseExit(x: number, y: number): void {
+    this.native.flush()
+    this.native.simulateMouseExit(x, y)
+    this.dispatchNativeEvents()
+    this.native.flush()
+  }
+
   /** End-to-end: simulate mouse down through GPUI hit testing →
    *  dispatch resulting events to the framework.
    *  @param button - 0=left (default), 1=middle, 2=right */
diff --git a/packages/native/src/test_renderer.rs b/packages/native/src/test_renderer.rs
index 1f8383b4f..1ee35f3fc 100644
--- a/packages/native/src/test_renderer.rs
+++ b/packages/native/src/test_renderer.rs
@@ -455,6 +455,24 @@ impl TestGpuixRenderer {
         })
     }
 
+    /// Simulate the pointer leaving the window, as the platform reports it when
+    /// the cursor crosses the window edge: there is no final mouse move.
+    #[napi]
+    pub fn simulate_mouse_exit(&self, x: f64, y: f64) -> Result<()> {
+        with_test_state(|cx, window, _view| {
+            simulate_event_with_view_lease(
+                cx,
+                window,
+                gpui::MouseExitEvent {
+                    position: gpui::point(gpui::px(x as f32), gpui::px(y as f32)),
+                    pressed_button: None,
+                    modifiers: Default::default(),
+                },
+            );
+            Ok(())
+        })
+    }
+
     /// Focus an element by its numeric ID.
     /// The element must have a FocusHandle (created by sync_focus_handles when
     /// the element has keyDown, keyUp, focus, or blur listeners).
diff --git a/packages/react/src/__tests__/events.test.tsx b/packages/react/src/__tests__/events.test.tsx
index fee90f590..7457fbcb6 100644
--- a/packages/react/src/__tests__/events.test.tsx
+++ b/packages/react/src/__tests__/events.test.tsx
@@ -19,7 +19,7 @@ import { createTestRoot, hasNativeTestRenderer } from "../testing"
 import { startFrameLoop } from "../reconciler/renderer.js"
 import { motion } from "../index"
 import type { EventPayload } from "@gpuix/native"
-import { expectScreenshotsDiffer, SHOTS_DIR } from "./test-utils"
+import { expectScreenshotsDiffer, expectScreenshotsEqual, SHOTS_DIR } from "./test-utils"
 
 // All tests require the native GPUI test renderer (cargo build with test-support).
 const describeNative = hasNativeTestRenderer ? describe : describe.skip
@@ -433,6 +433,59 @@ describeNative("events", () => {
     })
   })
 
+  describe("pointer leaving the window", () => {
+    it("fires mouseLeave without a final mouse move", () => {
+      const log: string[] = []
+      testRoot.render(
+        <div
+          style={{ width: 200, height: 100 }}
+          onMouseEnter={() => log.push("enter")}
+          onMouseLeave={() => log.push("leave")}
+        />
+      )
+
+      testRoot.renderer.nativeSimulateMouseMove(50, 50)
+      expect(log).toEqual(["enter"])
+
+      // The platform reports the exit at the window edge, not a move outside.
+      testRoot.renderer.nativeSimulateMouseExit(199, 50)
+      expect(log).toEqual(["enter", "leave"])
+
+      testRoot.renderer.nativeSimulateMouseMove(60, 50)
+      expect(log).toEqual(["enter", "leave", "enter"])
+    })
+
+    it("drops the hover style too", () => {
+      testRoot.render(
+        <div style={{ width: "100%", height: "100%", backgroundColor: "#11111b" }}>
+          <div
+            style={{
+              width: 200,
+              height: 100,
+              backgroundColor: "#1e1e2e",
+              hover: { backgroundColor: "#f38ba8" },
+            }}
+          />
+        </div>
+      )
+      fs.mkdirSync(SHOTS_DIR, { recursive: true })
+      const idle = `${SHOTS_DIR}/pointer-exit-idle.png`
+      const hovered = `${SHOTS_DIR}/pointer-exit-hovered.png`
+      const exited = `${SHOTS_DIR}/pointer-exit-exited.png`
+      for (const file of [idle, hovered, exited]) fs.rmSync(file, { force: true })
+
+      testRoot.renderer.nativeSimulateMouseMove(1200, 700)
+      testRoot.renderer.captureScreenshot(idle)
+      testRoot.renderer.nativeSimulateMouseMove(100, 50)
+      testRoot.renderer.captureScreenshot(hovered)
+      expectScreenshotsDiffer(idle, hovered)
+
+      testRoot.renderer.nativeSimulateMouseExit(199, 50)
+      testRoot.renderer.captureScreenshot(exited)
+      expectScreenshotsEqual(idle, exited)
+    })
+  })
+
   describe("mouseDownOutside", () => {
     it("should handle click outside to close pattern", () => {
       function Dropdown() {
diff --git a/zed b/zed
index 7bc43009e..74a3f0ff8 160000
--- a/zed
+++ b/zed
@@ -1 +1 @@
-Subproject commit 7bc43009e89f37e1ce765d0c2aa98e3f5c64cbeb
+Subproject commit 74a3f0ff867ef2b1f875d0317a192209baf79fb2

From 720e975ca986c82e17e4ccf4b6918a88b7e35c4c Mon Sep 17 00:00:00 2001
From: Ruben Nogueira <40404708+rubnogueira@users.noreply.github.com>
Date: Sat, 10 Oct 2026 18:35:15 +0100
Subject: [PATCH 14/27] perf(native): focus sync visits only the focusable
 elements

---
 .changeset/focusable-ids.md          |  5 ++
 packages/native/src/renderer.rs      | 35 +++++------
 packages/native/src/retained_tree.rs | 88 ++++++++++++++++++++++++++++
 3 files changed, 107 insertions(+), 21 deletions(-)
 create mode 100644 .changeset/focusable-ids.md

diff --git a/.changeset/focusable-ids.md b/.changeset/focusable-ids.md
new file mode 100644
index 000000000..2fb7b9404
--- /dev/null
+++ b/.changeset/focusable-ids.md
@@ -0,0 +1,5 @@
+---
+'@gpuix/native': patch
+---
+
+Every frame no longer walks every element to find the ones that take focus. The tree now keeps that set up to date as props and listeners change, so an idle frame of a long chat costs about a third less CPU. Focus, tab order, `autoFocus`, and `onKeyDown`/`onFocus`/`onBlur` behave as before.
diff --git a/packages/native/src/renderer.rs b/packages/native/src/renderer.rs
index abca9af0b..5c59fcbbb 100644
--- a/packages/native/src/renderer.rs
+++ b/packages/native/src/renderer.rs
@@ -4783,28 +4783,19 @@ impl GpuixView {
         }) {
             self.pending_focus_element = None;
         }
-        let tab_index = |element: &crate::retained_tree::RetainedElement| {
-            element
-                .custom_props
-                .get("tabIndex")
-                .and_then(|value| value.as_i64())
-                .and_then(|index| isize::try_from(index).ok())
-        };
-        let needs_focus = |element: &crate::retained_tree::RetainedElement| {
-            matches!(element.element_type.as_str(), "input" | "textarea")
-                || tab_index(element).is_some()
-                || element.events.contains("keyDown")
-                || element.events.contains("keyUp")
-                || element.events.contains("focus")
-                || element.events.contains("blur")
-        };
+        // Only the focusable elements are visited. This runs every frame, and
+        // the rest of the tree is orders of magnitude larger.
+        //
         // Create handles for elements that need focus but don't have one yet.
-        for (&id, element) in &tree.elements {
-            let tab_index = tab_index(element).or_else(|| {
+        for &id in &tree.focusable_ids {
+            let Some(element) = tree.elements.get(&id) else {
+                continue;
+            };
+            let tab_index = element.tab_index().or_else(|| {
                 matches!(element.element_type.as_str(), "input" | "textarea").then_some(0)
             });
 
-            if needs_focus(element) && !self.focus_handles.contains_key(&id) {
+            if !self.focus_handles.contains_key(&id) {
                 let handle = match tab_index {
                     Some(index) => cx.focus_handle().tab_index(index).tab_stop(index >= 0),
                     None => cx.focus_handle(),
@@ -4841,8 +4832,10 @@ impl GpuixView {
                 .get(id)
                 .is_some_and(|element| element.events.contains(event))
         });
-        for (&id, element) in &tree.elements {
-            let Some(handle) = self.focus_handles.get(&id).cloned() else {
+        for &id in &tree.focusable_ids {
+            let (Some(element), Some(handle)) =
+                (tree.elements.get(&id), self.focus_handles.get(&id).cloned())
+            else {
                 continue;
             };
             let focus_key = (id, "focus".to_string());
@@ -4868,7 +4861,7 @@ impl GpuixView {
 
         // Clean up handles for elements that no longer exist.
         self.focus_handles
-            .retain(|id, _| tree.elements.get(id).is_some_and(&needs_focus));
+            .retain(|id, _| tree.focusable_ids.contains(id));
     }
 }
 
diff --git a/packages/native/src/retained_tree.rs b/packages/native/src/retained_tree.rs
index 045b894fb..e1a4a8cff 100644
--- a/packages/native/src/retained_tree.rs
+++ b/packages/native/src/retained_tree.rs
@@ -52,6 +52,25 @@ pub struct RetainedElement {
 }
 
 impl RetainedElement {
+    /// The element's `tabIndex`, when it has a usable one.
+    pub fn tab_index(&self) -> Option<isize> {
+        self.custom_props
+            .get("tabIndex")
+            .and_then(|value| value.as_i64())
+            .and_then(|index| isize::try_from(index).ok())
+    }
+
+    /// Whether the element must own a gpui focus handle: it takes text, is in the
+    /// tab order, or listens for a key or focus event.
+    pub fn needs_focus(&self) -> bool {
+        matches!(self.element_type.as_str(), "input" | "textarea")
+            || self.tab_index().is_some()
+            || self.events.contains("keyDown")
+            || self.events.contains("keyUp")
+            || self.events.contains("focus")
+            || self.events.contains("blur")
+    }
+
     pub fn new(id: u64, element_type: String, revision: u64) -> Self {
         Self {
             id,
@@ -185,6 +204,10 @@ impl StyleTable {
 pub struct RetainedTree {
     pub elements: ElementMap,
     pub motion_ids: HashSet<u64>,
+    /// Elements that `needs_focus`, in id order. Kept as mutations arrive so the
+    /// per-frame focus sync visits these few instead of every retained element:
+    /// a long chat retains thousands, and nearly none are focusable.
+    pub focusable_ids: std::collections::BTreeSet<u64>,
     pub styles: StyleTable,
     /// The root element ID set by appendChildToContainer.
     pub root_id: Option<u64>,
@@ -203,6 +226,7 @@ impl RetainedTree {
         Self {
             elements: ElementMap::default(),
             motion_ids: HashSet::new(),
+            focusable_ids: Default::default(),
             styles: StyleTable::default(),
             root_id: None,
             keyboard_focus_dim: true,
@@ -240,6 +264,21 @@ impl RetainedTree {
         let revision = self.take_revision();
         self.elements
             .insert(id, RetainedElement::new(id, element_type, revision));
+        self.track_focusable(id);
+    }
+
+    /// Bring `focusable_ids` in line with `id` after anything `needs_focus`
+    /// reads has changed.
+    fn track_focusable(&mut self, id: u64) {
+        if self
+            .elements
+            .get(&id)
+            .is_some_and(RetainedElement::needs_focus)
+        {
+            self.focusable_ids.insert(id);
+        } else {
+            self.focusable_ids.remove(&id);
+        }
     }
 
     fn take_revision(&mut self) -> u64 {
@@ -307,6 +346,7 @@ impl RetainedTree {
     fn destroy_element_recursive(&mut self, id: u64, destroyed: &mut Vec<u64>) {
         if let Some(element) = self.elements.remove(&id) {
             self.motion_ids.remove(&id);
+            self.focusable_ids.remove(&id);
             destroyed.push(id);
             for child_id in element.children {
                 self.destroy_element_recursive(child_id, destroyed);
@@ -409,6 +449,9 @@ impl RetainedTree {
             // Which listeners exist decides how the element is built, though it
             // does not touch any cached text.
             self.dirty |= changed;
+            if changed {
+                self.track_focusable(id);
+            }
         }
     }
 
@@ -422,6 +465,7 @@ impl RetainedTree {
         let mut changed = false;
         let is_highlight = key == "highlight";
         let is_motion = key == "motion";
+        let is_tab_index = key == "tabIndex";
         let was_declaration = self
             .elements
             .get(&id)
@@ -453,6 +497,9 @@ impl RetainedTree {
         if !changed {
             return;
         }
+        if is_tab_index {
+            self.track_focusable(id);
+        }
         if is_motion {
             if self
                 .elements
@@ -883,6 +930,47 @@ mod tests {
         assert!(tree.elements[&1].search_revision > after);
     }
 
+    /// `focusable_ids` stands in for a scan of every element, so it has to
+    /// agree with `needs_focus` after any mutation that can change the answer.
+    #[test]
+    fn focusable_ids_follow_what_needs_focus_reads() {
+        let mut tree = RetainedTree::new();
+        tree.create_element(1, "div".to_string());
+        tree.create_element(2, "input".to_string());
+        tree.create_element(3, "div".to_string());
+        tree.create_element(4, "div".to_string());
+        tree.append_child(1, 2);
+        tree.append_child(1, 3);
+        tree.append_child(1, 4);
+        let focusable =
+            |tree: &RetainedTree| tree.focusable_ids.iter().copied().collect::<Vec<_>>();
+        assert_eq!(focusable(&tree), vec![2], "inputs always take focus");
+
+        tree.set_event_listener(3, "keyDown".to_string(), true);
+        tree.set_custom_prop(4, "tabIndex".to_string(), serde_json::json!(0));
+        assert_eq!(focusable(&tree), vec![2, 3, 4]);
+
+        // A click listener has nothing to do with focus.
+        tree.set_event_listener(1, "click".to_string(), true);
+        assert_eq!(focusable(&tree), vec![2, 3, 4]);
+
+        // Other listeners keep an element in the set until the last one goes.
+        tree.set_event_listener(3, "blur".to_string(), true);
+        tree.set_event_listener(3, "keyDown".to_string(), false);
+        assert_eq!(focusable(&tree), vec![2, 3, 4]);
+        tree.set_event_listener(3, "blur".to_string(), false);
+        assert_eq!(focusable(&tree), vec![2, 4]);
+
+        tree.set_custom_prop(4, "tabIndex".to_string(), serde_json::Value::Null);
+        assert_eq!(focusable(&tree), vec![2]);
+
+        tree.destroy_element(1);
+        assert!(
+            tree.focusable_ids.is_empty(),
+            "destroying a subtree forgets its ids"
+        );
+    }
+
     #[test]
     fn set_text_bumps_every_ancestor() {
         let mut tree = tree_with_child();

From 82390c4e7084f96c9ff7406a7f9f83a7d8742e04 Mon Sep 17 00:00:00 2001
From: Ruben Nogueira <40404708+rubnogueira@users.noreply.github.com>
Date: Sat, 10 Oct 2026 18:35:18 +0100
Subject: [PATCH 15/27] test(examples): profile-chat takes a QUERY override

---
 examples/profile-chat.tsx | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/examples/profile-chat.tsx b/examples/profile-chat.tsx
index 8ac41b289..596e7d747 100644
--- a/examples/profile-chat.tsx
+++ b/examples/profile-chat.tsx
@@ -10,6 +10,9 @@
  * MODE=mount       mounts the 1000-turn chat from scratch, over and over
  * MODE=sidebar     clicks the sidebar toggle through the automation client
  *
+ * QUERY=...        the find query that is active before the loop starts, 'p' by
+ *                  default; set it empty to measure a chat with no search
+ *
  * Wall time is noisy on a busy machine, so every mode also reports the CPU time
  * the process spent per iteration, which load on other processes does not move.
  */
@@ -39,7 +42,7 @@ function cpuMs() {
 let root = createTestRoot()
 root.render(app(''))
 for (let i = 0; i < 10; i++) root.renderer.flush()
-root.render(app('p'))
+root.render(app(process.env.QUERY ?? 'p'))
 
 const automation = mode === 'sidebar' ? await connectTest(root.renderer) : undefined
 if (automation) {

From 5d86e4febdc663cc6dec0a47f204c4949552304c Mon Sep 17 00:00:00 2001
From: Ruben Nogueira <40404708+rubnogueira@users.noreply.github.com>
Date: Sat, 10 Oct 2026 19:26:35 +0100
Subject: [PATCH 16/27] feat(native): getElementsAt lists the elements under a
 point

---
 .changeset/elements-at.md                     |   5 +
 README.md                                     |  18 ++
 packages/native/index.d.ts                    |   9 +
 packages/native/js/host.ts                    |   1 +
 packages/native/js/testing.ts                 |   6 +
 packages/native/src/renderer.rs               |  39 +++
 packages/native/src/retained_tree.rs          | 293 ++++++++++++++++++
 packages/native/src/test_renderer.rs          |  12 +
 .../react/src/__tests__/elements-at.test.tsx  |  88 ++++++
 9 files changed, 471 insertions(+)
 create mode 100644 .changeset/elements-at.md
 create mode 100644 packages/react/src/__tests__/elements-at.test.tsx

diff --git a/.changeset/elements-at.md b/.changeset/elements-at.md
new file mode 100644
index 000000000..947ce717f
--- /dev/null
+++ b/.changeset/elements-at.md
@@ -0,0 +1,5 @@
+---
+'@gpuix/native': patch
+---
+
+`getElementsAt(x, y)` lists the elements under a window point, topmost first, like the DOM's `elementsFromPoint`. It clips at `overflow: hidden | scroll`, skips `pointer-events: none`, and puts a deferred `<anchored>` layer above the rest. The test renderer has it too.
diff --git a/README.md b/README.md
index 7c308b49a..1e310f450 100644
--- a/README.md
+++ b/README.md
@@ -2285,6 +2285,24 @@ const box = renderer.getElementBounds?.(ref.current.id)
 // { x, y, width, height }
 ```
 
+### Find what is under a point
+
+`getElementsAt(x, y)` returns the ids of the elements whose last painted box
+holds a window point, topmost first, like the DOM's `elementsFromPoint`. It
+works on the live `GpuixRenderer` and on the test renderer.
+
+```tsx
+const [topmost] = renderer.getElementsAt?.(event.x, event.y) ?? []
+```
+
+It answers from the last frame, so an element that did not paint (hidden, or
+outside a virtual list's window) is never listed. `overflow: hidden` and
+`scroll` clip what lies outside them, `pointer-events: none` is skipped (and
+inherited, until a child sets `auto`), and a deferred
+[`<anchored>`](#overlay-menus) layer comes first, ordered by `priority`,
+because gpui paints it after the tree and outside the clip of its ancestors.
+Beyond that, tree order is paint order: gpuix has no z-index.
+
 ### Button
 
 GPUIX has no native `<button>`, so a `div` with `onClick` is not reachable with
diff --git a/packages/native/index.d.ts b/packages/native/index.d.ts
index 814af91ca..2f865d1cc 100644
--- a/packages/native/index.d.ts
+++ b/packages/native/index.d.ts
@@ -171,6 +171,13 @@ export declare class GpuixRenderer {
   registerFont(data: Buffer): void
   getAutomationTree(): string
   getElementBounds(id: number): ElementBounds | null
+  /**
+   * The elements whose last painted box holds the window point `(x, y)`,
+   * topmost first, like the DOM's `elementsFromPoint`. An element that did
+   * not paint is never listed, `overflow: hidden | scroll` clips what lies
+   * outside it, and `pointer-events: none` is skipped.
+   */
+  getElementsAt(x: number, y: number): Array<number>
   getAllText(): Array<string>
   getPaintedText(): Array<string>
   /**
@@ -419,6 +426,8 @@ export declare class TestGpuixRenderer {
   getAutomationTree(): string
   /** Last painted bounds for an element, or null if it was not painted. */
   getElementBounds(id: number): ElementBounds | null
+  /** Ids under the window point, topmost first. See the live renderer. */
+  getElementsAt(x: number, y: number): Array<number>
   clockPause(): number
   clockSet(nowMs: number): number
   clockFastForward(deltaMs: number): number
diff --git a/packages/native/js/host.ts b/packages/native/js/host.ts
index 35676e015..023ca4eb2 100644
--- a/packages/native/js/host.ts
+++ b/packages/native/js/host.ts
@@ -680,6 +680,7 @@ export type NativeRenderer = MutationHost &
       | "setWindowKeyEvents"
       | "setWindowSelectionChange"
       | "getElementBounds"
+      | "getElementsAt"
       | "scrollTo"
       | "scrollToItem"
       | "scrollIntoView"
diff --git a/packages/native/js/testing.ts b/packages/native/js/testing.ts
index 1973fd049..b39de9beb 100644
--- a/packages/native/js/testing.ts
+++ b/packages/native/js/testing.ts
@@ -70,6 +70,7 @@ interface NativeTestRendererApi extends NativeRenderer {
   getAutomationTree(): string
   getRetainedElementCount(): number
   getElementBounds(elementId: number): ElementBounds | null
+  getElementsAt(x: number, y: number): number[]
   clockPause(): number
   clockSet(nowMs: number): number
   clockFastForward(deltaMs: number): number
@@ -490,6 +491,11 @@ export class TestRenderer implements NativeRenderer {
     return this.native.getElementBounds(elementId)
   }
 
+  /** Ids of the elements under the window point, topmost first. */
+  getElementsAt(x: number, y: number): number[] {
+    return this.native.getElementsAt(x, y)
+  }
+
   clockPause(): number {
     return this.native.clockPause()
   }
diff --git a/packages/native/src/renderer.rs b/packages/native/src/renderer.rs
index 5c59fcbbb..dddbcc78e 100644
--- a/packages/native/src/renderer.rs
+++ b/packages/native/src/renderer.rs
@@ -1041,6 +1041,32 @@ impl GpuixRenderer {
         Err(Error::from_reason("Unsupported operating system"))
     }
 
+    fn elements_at(&self, x: f64, y: f64) -> Result<Vec<u64>> {
+        #[cfg(target_os = "macos")]
+        {
+            let tree = self.tree.lock().unwrap();
+            return Ok(tree.elements_at(x, y, &crate::automation::get_bounds));
+        }
+
+        #[cfg(any(target_os = "windows", target_os = "linux", target_os = "freebsd"))]
+        {
+            let bounds = self.automation_bounds()?;
+            let tree = self.tree.lock().unwrap();
+            return Ok(tree.elements_at(x, y, &|id| bounds.get(&id).copied()));
+        }
+
+        #[cfg(not(any(
+            target_os = "macos",
+            target_os = "windows",
+            target_os = "linux",
+            target_os = "freebsd"
+        )))]
+        {
+            let _ = (x, y);
+            Err(Error::from_reason("Unsupported operating system"))
+        }
+    }
+
     fn element_bounds(&self, id: u64) -> Result<Option<crate::automation::ElementBounds>> {
         #[cfg(target_os = "macos")]
         return Ok(crate::automation::get_bounds(id));
@@ -2309,6 +2335,19 @@ impl GpuixRenderer {
         Ok(self.element_bounds(id)?.map(ElementBounds::from_painted))
     }
 
+    /// The elements whose last painted box holds the window point `(x, y)`,
+    /// topmost first, like the DOM's `elementsFromPoint`. An element that did
+    /// not paint is never listed, `overflow: hidden | scroll` clips what lies
+    /// outside it, and `pointer-events: none` is skipped.
+    #[napi]
+    pub fn get_elements_at(&self, x: f64, y: f64) -> Result<Vec<f64>> {
+        Ok(self
+            .elements_at(x, y)?
+            .into_iter()
+            .map(|id| id as f64)
+            .collect())
+    }
+
     #[napi]
     pub fn get_all_text(&self) -> Vec<String> {
         let tree = self.tree.lock().unwrap();
diff --git a/packages/native/src/retained_tree.rs b/packages/native/src/retained_tree.rs
index e1a4a8cff..5a2ef8c14 100644
--- a/packages/native/src/retained_tree.rs
+++ b/packages/native/src/retained_tree.rs
@@ -12,6 +12,15 @@ use std::sync::Arc;
 
 use crate::style::StyleDesc;
 
+/// What one `elements_at` walk carries along.
+struct HitWalk<'a> {
+    x: f64,
+    y: f64,
+    painted_box: &'a dyn Fn(u64) -> Option<crate::automation::ElementBounds>,
+    /// Deferred `anchored` layers met so far, each with its priority and hits.
+    layers: Vec<(u64, Vec<u64>)>,
+}
+
 pub struct RetainedElement {
     pub id: u64,
     pub element_type: String,
@@ -208,6 +217,9 @@ pub struct RetainedTree {
     /// per-frame focus sync visits these few instead of every retained element:
     /// a long chat retains thousands, and nearly none are focusable.
     pub focusable_ids: std::collections::BTreeSet<u64>,
+    /// How many `anchored` elements exist. Without any, an `elements_at` walk
+    /// can drop a clipped subtree whole.
+    anchored_count: usize,
     pub styles: StyleTable,
     /// The root element ID set by appendChildToContainer.
     pub root_id: Option<u64>,
@@ -227,6 +239,7 @@ impl RetainedTree {
             elements: ElementMap::default(),
             motion_ids: HashSet::new(),
             focusable_ids: Default::default(),
+            anchored_count: 0,
             styles: StyleTable::default(),
             root_id: None,
             keyboard_focus_dim: true,
@@ -260,6 +273,7 @@ impl RetainedTree {
     }
 
     pub fn create_element(&mut self, id: u64, element_type: String) {
+        self.anchored_count += usize::from(element_type == "anchored");
         self.dirty = true;
         let revision = self.take_revision();
         self.elements
@@ -347,6 +361,7 @@ impl RetainedTree {
         if let Some(element) = self.elements.remove(&id) {
             self.motion_ids.remove(&id);
             self.focusable_ids.remove(&id);
+            self.anchored_count -= usize::from(element.element_type == "anchored");
             destroyed.push(id);
             for child_id in element.children {
                 self.destroy_element_recursive(child_id, destroyed);
@@ -546,6 +561,114 @@ impl RetainedTree {
         self.to_json_detail(bounds, false)
     }
 
+    /// The elements whose painted box holds the point, topmost first: the DOM's
+    /// `elementsFromPoint`.
+    ///
+    /// There is no z-index, so tree order is paint order. Walking each
+    /// element's children last to first, and the element after them, yields
+    /// the topmost element first. The exception is a deferred `anchored`
+    /// layer, which gpui paints after the tree by `priority` and without the
+    /// clip of the elements around it: its hits come first.
+    ///
+    /// `painted_box` is the last frame's box. An element that was not painted
+    /// (hidden, or outside a virtual list's window) has none and is never hit,
+    /// though its descendants are still visited. What clips matches what is
+    /// drawn: `overflow` of `hidden` or `scroll`, per axis, hides whatever lies
+    /// outside the clipping box. `pointer-events: none` is inherited, like in
+    /// CSS, and `auto` restores it.
+    pub fn elements_at(
+        &self,
+        x: f64,
+        y: f64,
+        painted_box: &dyn Fn(u64) -> Option<crate::automation::ElementBounds>,
+    ) -> Vec<u64> {
+        let mut walk = HitWalk {
+            x,
+            y,
+            painted_box,
+            layers: Vec::new(),
+        };
+        let mut hits = Vec::new();
+        if let Some(root_id) = self.root_id {
+            self.collect_hits(root_id, false, false, &mut walk, &mut hits);
+        }
+        // Stable, so layers of one priority stay topmost first.
+        walk.layers.sort_by(|a, b| b.0.cmp(&a.0));
+        let mut ordered: Vec<u64> = walk.layers.into_iter().flat_map(|(_, layer)| layer).collect();
+        ordered.extend(hits);
+        ordered
+    }
+
+    /// `none` is the inherited `pointer-events: none`. `clipped` means an
+    /// ancestor's clip excludes the point, so only deferred layers below can
+    /// still be hit.
+    fn collect_hits(
+        &self,
+        id: u64,
+        none: bool,
+        clipped: bool,
+        walk: &mut HitWalk,
+        hits: &mut Vec<u64>,
+    ) {
+        let Some(element) = self.elements.get(&id) else {
+            return;
+        };
+        let style = element.style.as_deref();
+        let own_box = (walk.painted_box)(id);
+        let (x, y) = (walk.x, walk.y);
+        let inside = |bounds: &crate::automation::ElementBounds, horizontal: bool, vertical: bool| {
+            (!horizontal || (x >= bounds.x && x < bounds.x + bounds.width))
+                && (!vertical || (y >= bounds.y && y < bounds.y + bounds.height))
+        };
+
+        let mut clipped = clipped;
+        if let (Some(style), Some(bounds)) = (style, &own_box) {
+            let clips = |axis: Option<&str>| matches!(axis, Some("hidden" | "scroll"));
+            let clip_x = clips(style.overflow_x.as_deref().or(style.overflow.as_deref()));
+            let clip_y = clips(style.overflow_y.as_deref().or(style.overflow.as_deref()));
+            if (clip_x || clip_y) && !inside(bounds, clip_x, clip_y) {
+                if self.anchored_count == 0 {
+                    return;
+                }
+                clipped = true;
+            }
+        }
+
+        let none = match style.and_then(|style| style.pointer_events.as_deref()) {
+            Some("none") => true,
+            Some("auto") => false,
+            _ => none,
+        };
+
+        if element.element_type == "anchored" {
+            let deferred = element
+                .custom_props
+                .get("deferred")
+                .and_then(|value| value.as_bool())
+                .unwrap_or(true);
+            if deferred {
+                let priority = element
+                    .custom_props
+                    .get("priority")
+                    .and_then(|value| value.as_u64())
+                    .unwrap_or(1);
+                let mut layer = Vec::new();
+                for &child in element.children.iter().rev() {
+                    self.collect_hits(child, none, false, walk, &mut layer);
+                }
+                walk.layers.push((priority, layer));
+                return;
+            }
+        }
+
+        for &child in element.children.iter().rev() {
+            self.collect_hits(child, none, clipped, walk, hits);
+        }
+        if !clipped && !none && own_box.is_some_and(|bounds| inside(&bounds, true, true)) {
+            hits.push(id);
+        }
+    }
+
     fn to_json_detail(
         &self,
         bounds: &std::collections::HashMap<u64, crate::automation::ElementBounds>,
@@ -971,6 +1094,176 @@ mod tests {
         );
     }
 
+    /// A page with a clipping scroller, overlapping siblings, and an overlay that
+    /// does not take the pointer:
+    ///
+    /// ```text
+    /// 1 root      0,0   100x100
+    ///   2 scroller  0,0   50x50   overflow: hidden
+    ///     3 row       0,40  50x30   (sticks out of the scroller's bottom)
+    ///   4 sibling   40,0  50x50   (paints over the scroller)
+    ///   5 overlay   0,0   100x100 pointer-events: none
+    ///     6 button    60,60 20x20   pointer-events: auto
+    /// ```
+    fn hit_test_tree() -> (RetainedTree, impl Fn(u64) -> Option<crate::automation::ElementBounds>) {
+        let mut tree = RetainedTree::new();
+        for id in 1..=6 {
+            tree.create_element(id, "div".to_string());
+        }
+        tree.set_root(1);
+        for (parent, child) in [(1, 2), (2, 3), (1, 4), (1, 5), (5, 6)] {
+            tree.append_child(parent, child);
+        }
+        let styled = |overflow: Option<&str>, pointer_events: Option<&str>| {
+            Arc::new(StyleDesc {
+                overflow: overflow.map(str::to_string),
+                pointer_events: pointer_events.map(str::to_string),
+                ..Default::default()
+            })
+        };
+        tree.set_style(2, styled(Some("hidden"), None));
+        tree.set_style(5, styled(None, Some("none")));
+        tree.set_style(6, styled(None, Some("auto")));
+        let boxes = [
+            (1, (0.0, 0.0, 100.0, 100.0)),
+            (2, (0.0, 0.0, 50.0, 50.0)),
+            (3, (0.0, 40.0, 50.0, 30.0)),
+            (4, (40.0, 0.0, 50.0, 50.0)),
+            (5, (0.0, 0.0, 100.0, 100.0)),
+            (6, (60.0, 60.0, 20.0, 20.0)),
+        ];
+        let lookup = move |id: u64| {
+            boxes
+                .iter()
+                .find(|(candidate, _)| *candidate == id)
+                .map(|(_, (x, y, width, height))| crate::automation::ElementBounds {
+                    x: *x,
+                    y: *y,
+                    width: *width,
+                    height: *height,
+                })
+        };
+        (tree, lookup)
+    }
+
+    #[test]
+    fn elements_at_lists_what_is_under_the_point_topmost_first() {
+        let (tree, painted) = hit_test_tree();
+        // The later sibling paints over the scroller, and both sit in the root.
+        assert_eq!(tree.elements_at(45.0, 10.0, &painted), vec![4, 2, 1]);
+        // A descendant is above its ancestor.
+        assert_eq!(tree.elements_at(10.0, 45.0, &painted), vec![3, 2, 1]);
+        assert_eq!(tree.elements_at(500.0, 500.0, &painted), Vec::<u64>::new());
+    }
+
+    #[test]
+    fn elements_at_stops_at_the_clip_edge() {
+        let (tree, painted) = hit_test_tree();
+        // y 60 is inside the row but below the scroller that clips it.
+        assert_eq!(tree.elements_at(10.0, 60.0, &painted), vec![1]);
+    }
+
+    #[test]
+    fn elements_at_skips_what_does_not_take_the_pointer() {
+        let (tree, painted) = hit_test_tree();
+        // The overlay covers everything yet is never hit...
+        assert_eq!(tree.elements_at(10.0, 90.0, &painted), vec![1]);
+        // ...while its child opts back in.
+        assert_eq!(tree.elements_at(70.0, 70.0, &painted), vec![6, 1]);
+    }
+
+    #[test]
+    fn elements_at_never_hits_what_was_not_painted() {
+        let (tree, painted) = hit_test_tree();
+        let without_the_sibling = |id: u64| if id == 4 { None } else { painted(id) };
+        assert_eq!(tree.elements_at(45.0, 10.0, &without_the_sibling), vec![2, 1]);
+    }
+
+    fn boxed(
+        boxes: &[(u64, (f64, f64, f64, f64))],
+    ) -> impl Fn(u64) -> Option<crate::automation::ElementBounds> + '_ {
+        move |id| {
+            boxes
+                .iter()
+                .find(|(candidate, _)| *candidate == id)
+                .map(|(_, (x, y, width, height))| crate::automation::ElementBounds {
+                    x: *x,
+                    y: *y,
+                    width: *width,
+                    height: *height,
+                })
+        }
+    }
+
+    /// A popover lives inside a clipping scroller, early in the tree, yet gpui
+    /// paints it after everything else and outside that clip.
+    #[test]
+    fn elements_at_puts_a_deferred_layer_above_the_tree_and_outside_its_clip() {
+        let mut tree = RetainedTree::new();
+        for (id, kind) in [
+            (1, "div"),
+            (2, "div"),
+            (3, "anchored"),
+            (4, "div"),
+            (5, "div"),
+        ] {
+            tree.create_element(id, kind.to_string());
+        }
+        tree.set_root(1);
+        for (parent, child) in [(1, 2), (2, 3), (3, 4), (1, 5)] {
+            tree.append_child(parent, child);
+        }
+        tree.set_style(
+            2,
+            Arc::new(StyleDesc {
+                overflow: Some("hidden".to_string()),
+                ..Default::default()
+            }),
+        );
+        let boxes = [
+            (1, (0.0, 0.0, 100.0, 100.0)),
+            (2, (0.0, 0.0, 20.0, 20.0)),
+            (4, (50.0, 50.0, 30.0, 30.0)),
+            (5, (40.0, 40.0, 60.0, 60.0)),
+        ];
+        // The popover content is outside its scroller's clip and under a later
+        // sibling, and is still what the point lands on.
+        assert_eq!(tree.elements_at(60.0, 60.0, &boxed(&boxes)), vec![4, 5, 1]);
+
+        // Ordinary clipping is untouched.
+        tree.destroy_element(3);
+        tree.create_element(6, "div".to_string());
+        tree.append_child(2, 6);
+        let with_clipped_child = [(1, (0.0, 0.0, 100.0, 100.0)), (2, (0.0, 0.0, 20.0, 20.0)), (6, (0.0, 0.0, 90.0, 90.0))];
+        assert_eq!(tree.elements_at(60.0, 60.0, &boxed(&with_clipped_child)), vec![1]);
+    }
+
+    #[test]
+    fn elements_at_orders_deferred_layers_by_priority() {
+        let mut tree = RetainedTree::new();
+        for (id, kind) in [(1, "div"), (2, "anchored"), (3, "div"), (4, "anchored"), (5, "div")] {
+            tree.create_element(id, kind.to_string());
+        }
+        tree.set_root(1);
+        for (parent, child) in [(1, 2), (2, 3), (1, 4), (4, 5)] {
+            tree.append_child(parent, child);
+        }
+        let boxes = [
+            (1, (0.0, 0.0, 100.0, 100.0)),
+            (3, (0.0, 0.0, 100.0, 100.0)),
+            (5, (0.0, 0.0, 100.0, 100.0)),
+        ];
+        // Equal priority: the layer later in the tree paints over the earlier.
+        assert_eq!(tree.elements_at(10.0, 10.0, &boxed(&boxes)), vec![5, 3, 1]);
+
+        tree.set_custom_prop(2, "priority".to_string(), serde_json::json!(5));
+        assert_eq!(tree.elements_at(10.0, 10.0, &boxed(&boxes)), vec![3, 5, 1]);
+
+        // Not deferred: painted in place, in tree order, under the clip.
+        tree.set_custom_prop(2, "deferred".to_string(), serde_json::json!(false));
+        assert_eq!(tree.elements_at(10.0, 10.0, &boxed(&boxes)), vec![5, 3, 1]);
+    }
+
     #[test]
     fn set_text_bumps_every_ancestor() {
         let mut tree = tree_with_child();
diff --git a/packages/native/src/test_renderer.rs b/packages/native/src/test_renderer.rs
index 1ee35f3fc..4e2718d4d 100644
--- a/packages/native/src/test_renderer.rs
+++ b/packages/native/src/test_renderer.rs
@@ -1152,6 +1152,18 @@ impl TestGpuixRenderer {
         Ok(crate::automation::get_bounds(id).map(crate::renderer::ElementBounds::from_painted))
     }
 
+    /// Ids under the window point, topmost first. See the live renderer.
+    #[napi]
+    pub fn get_elements_at(&self, x: f64, y: f64) -> Result<Vec<f64>> {
+        self.flush()?;
+        let tree = self.tree.lock().unwrap();
+        Ok(tree
+            .elements_at(x, y, &crate::automation::get_bounds)
+            .into_iter()
+            .map(|id| id as f64)
+            .collect())
+    }
+
     #[napi]
     pub fn clock_pause(&self) -> Result<f64> {
         with_test_state(|cx, window, view| {
diff --git a/packages/react/src/__tests__/elements-at.test.tsx b/packages/react/src/__tests__/elements-at.test.tsx
new file mode 100644
index 000000000..ea882a725
--- /dev/null
+++ b/packages/react/src/__tests__/elements-at.test.tsx
@@ -0,0 +1,88 @@
+import { describe, expect, it } from "vitest"
+import { createTestRoot, hasNativeTestRenderer } from "../testing.js"
+
+const describeNative = hasNativeTestRenderer ? describe : describe.skip
+
+describeNative("getElementsAt", () => {
+  const idsAt = (
+    renderer: ReturnType<typeof createTestRoot>["renderer"],
+    x: number,
+    y: number
+  ) => renderer.getElementsAt(x, y)
+
+  it("lists the elements under a point, topmost first, and honors clipping", () => {
+    const { render, renderer, unmount } = createTestRoot()
+    try {
+      render(
+        <div style={{ display: "flex", flexDirection: "row", width: 400, height: 300 }}>
+          <div
+            testId="scroller"
+            style={{ width: 100, height: 100, overflow: "hidden", flexDirection: "column" }}
+          >
+            <div testId="row" style={{ width: 100, height: 160, flexShrink: 0 }} />
+          </div>
+          <div testId="beside" style={{ width: 80, height: 80 }} />
+        </div>
+      )
+      renderer.dispatchNativeEvents()
+      const id = (testId: string) => renderer.findByTestId(testId)!.id
+
+      expect(idsAt(renderer, 50, 50).slice(0, 2)).toEqual([id("row"), id("scroller")])
+      expect(
+        idsAt(renderer, 50, 130),
+        "the row extends below the scroller, which clips it"
+      ).not.toContain(id("row"))
+      expect(idsAt(renderer, 150, 50)).toContain(id("beside"))
+      expect(idsAt(renderer, 5000, 5000)).toEqual([])
+    } finally {
+      unmount()
+    }
+  })
+
+  it("puts an <anchored> popover above what follows it in the tree", () => {
+    const { render, renderer, unmount } = createTestRoot()
+    try {
+      render(
+        <div style={{ width: 400, height: 300 }}>
+          <div testId="trigger" style={{ width: 60, height: 30 }}>
+            <anchored position={{ x: 20, y: 20 }} anchor="topLeft" deferred priority={1}>
+              <div testId="popover" style={{ width: 100, height: 100 }} />
+            </anchored>
+          </div>
+          <div testId="later" style={{ position: "absolute", left: 0, top: 0, width: 200, height: 200 }} />
+        </div>
+      )
+      renderer.dispatchNativeEvents()
+      const id = (testId: string) => renderer.findByTestId(testId)!.id
+
+      const hits = idsAt(renderer, 40, 40)
+      expect(hits.indexOf(id("popover")), "the popover is hit").toBeGreaterThanOrEqual(0)
+      expect(hits.indexOf(id("popover"))).toBeLessThan(hits.indexOf(id("later")))
+    } finally {
+      unmount()
+    }
+  })
+
+  it("skips pointer-events: none and lets a child opt back in", () => {
+    const { render, renderer, unmount } = createTestRoot()
+    try {
+      render(
+        <div style={{ width: 200, height: 200 }}>
+          <div
+            testId="overlay"
+            style={{ position: "absolute", left: 0, top: 0, width: 200, height: 200, pointerEvents: "none" }}
+          >
+            <div testId="button" style={{ width: 40, height: 40, pointerEvents: "auto" }} />
+          </div>
+        </div>
+      )
+      renderer.dispatchNativeEvents()
+      const hits = idsAt(renderer, 10, 10)
+      expect(hits).toContain(renderer.findByTestId("button")!.id)
+      expect(hits).not.toContain(renderer.findByTestId("overlay")!.id)
+      expect(idsAt(renderer, 100, 100)).not.toContain(renderer.findByTestId("overlay")!.id)
+    } finally {
+      unmount()
+    }
+  })
+})

From 4f622483b65fa8f1f8bf6e917b8afb37143330bb Mon Sep 17 00:00:00 2001
From: Ruben Nogueira <40404708+rubnogueira@users.noreply.github.com>
Date: Sat, 10 Oct 2026 19:29:00 +0100
Subject: [PATCH 17/27] feat(native): collectGarbageWhenIdle collects once the
 app has stopped committing

---
 .changeset/collect-garbage-when-idle.md      |  6 ++
 README.md                                    | 20 +++++
 packages/native/js/__tests__/idle-gc.test.ts | 69 +++++++++++++++
 packages/native/js/idle-gc.ts                | 91 ++++++++++++++++++++
 packages/native/js/mutations.ts              | 12 +++
 packages/native/package.json                 |  5 ++
 packages/react/src/idle-gc.ts                |  2 +
 packages/react/src/index.ts                  |  2 +
 8 files changed, 207 insertions(+)
 create mode 100644 .changeset/collect-garbage-when-idle.md
 create mode 100644 packages/native/js/__tests__/idle-gc.test.ts
 create mode 100644 packages/native/js/idle-gc.ts
 create mode 100644 packages/react/src/idle-gc.ts

diff --git a/.changeset/collect-garbage-when-idle.md b/.changeset/collect-garbage-when-idle.md
new file mode 100644
index 000000000..af8758dfe
--- /dev/null
+++ b/.changeset/collect-garbage-when-idle.md
@@ -0,0 +1,6 @@
+---
+'@gpuix/native': patch
+'@gpuix/react': patch
+---
+
+`collectGarbageWhenIdle()` runs one full garbage collection once the app has stopped committing for a while, so the heap of a long session comes back down after a burst of work. It watches the new `appliedBatchCount()` and the process's CPU, and returns a function that stops it.
diff --git a/README.md b/README.md
index 1e310f450..cc7c5dded 100644
--- a/README.md
+++ b/README.md
@@ -1744,6 +1744,26 @@ that height. An explicit `height` still overrides both.
 />
 ```
 
+### Give memory back when idle
+
+A JavaScript engine collects on allocation pressure, so after a burst of work
+(the first mount, opening a long thread) the heap stays at its peak until the
+next burst. `collectGarbageWhenIdle()` runs one full collection once the app has
+stopped committing for a while, then waits for the next burst.
+
+```tsx
+import { collectGarbageWhenIdle } from '@gpuix/react'
+
+const stop = collectGarbageWhenIdle() // checks every 5s, collects after two quiet checks
+```
+
+It uses `Bun.gc(true)`, or `gc()` where Node runs with `--expose-gc`, and does
+nothing in a runtime that has neither. Quiet means no mutation batch reached a
+renderer and the process is under half a core. The batch count decides, not CPU
+alone, because a focused text field blinks its caret in native code and redraws
+twice a second. Pass `activity`, `collect`, `checkMs`, `quietChecks` or
+`busyCpu` to change what it watches or how often.
+
 ### Input in a search pill
 
 `<input>` has **no default inner padding** and paints text at the top of its
diff --git a/packages/native/js/__tests__/idle-gc.test.ts b/packages/native/js/__tests__/idle-gc.test.ts
new file mode 100644
index 000000000..5b80d5383
--- /dev/null
+++ b/packages/native/js/__tests__/idle-gc.test.ts
@@ -0,0 +1,69 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"
+import { collectGarbageWhenIdle } from "../idle-gc.js"
+import { appliedBatchCount, createMutationQueue } from "../host.js"
+
+describe("collectGarbageWhenIdle", () => {
+  beforeEach(() => {
+    vi.useFakeTimers()
+  })
+  afterEach(() => {
+    vi.useRealTimers()
+  })
+
+  const setup = () => {
+    let activity = 0
+    const collect = vi.fn()
+    const stop = collectGarbageWhenIdle({ activity: () => activity, collect, checkMs: 1000, quietChecks: 2 })
+    return {
+      collect,
+      stop,
+      work: () => void activity++,
+      wait: (checks: number) => vi.advanceTimersByTime(checks * 1000),
+    }
+  }
+
+  it("collects once after the app has been quiet, then waits for the next burst", () => {
+    const { collect, work, wait } = setup()
+    wait(1)
+    expect(collect, "one quiet look is not enough").not.toHaveBeenCalled()
+    wait(1)
+    expect(collect).toHaveBeenCalledTimes(1)
+    wait(10)
+    expect(collect, "nothing new to collect").toHaveBeenCalledTimes(1)
+
+    work()
+    wait(1)
+    expect(collect, "the burst itself is not quiet").toHaveBeenCalledTimes(1)
+    wait(2)
+    expect(collect).toHaveBeenCalledTimes(2)
+  })
+
+  it("starts counting again whenever work shows up", () => {
+    const { collect, work, wait } = setup()
+    wait(1)
+    work()
+    wait(1)
+    wait(1)
+    expect(collect).not.toHaveBeenCalled()
+    wait(1)
+    expect(collect).toHaveBeenCalledTimes(1)
+  })
+
+  it("stops when asked", () => {
+    const { collect, stop, wait } = setup()
+    stop()
+    wait(10)
+    expect(collect).not.toHaveBeenCalled()
+  })
+
+  it("counts applied mutation batches by default", () => {
+    const renderer = { applyBatch: () => [] as number[] }
+    const queue = createMutationQueue(renderer)
+    const before = appliedBatchCount()
+    queue.flushMutations()
+    expect(appliedBatchCount(), "an empty queue applies nothing").toBe(before)
+    queue.createElement(1, "div")
+    queue.flushMutations()
+    expect(appliedBatchCount()).toBe(before + 1)
+  })
+})
diff --git a/packages/native/js/idle-gc.ts b/packages/native/js/idle-gc.ts
new file mode 100644
index 000000000..68566837d
--- /dev/null
+++ b/packages/native/js/idle-gc.ts
@@ -0,0 +1,91 @@
+import { appliedBatchCount } from "./mutations.js"
+
+export interface IdleGcOptions {
+  /**
+   * A number that changes whenever the app is doing work worth waiting out.
+   * Defaults to the count of mutation batches applied to any renderer, which
+   * moves on every commit, scroll-driven render and typed character.
+   */
+  activity?: () => number
+  /** Runs the collection. Defaults to `Bun.gc(true)`, then `globalThis.gc` (Node's `--expose-gc`). */
+  collect?: () => void
+  /** How often to look, in ms. Default 5000. */
+  checkMs?: number
+  /** Quiet looks in a row before collecting. Default 2. */
+  quietChecks?: number
+  /** Fraction of one core above which work that commits nothing (parsing, decoding) is running. Default 0.5. */
+  busyCpu?: number
+}
+
+type Collector = () => void
+
+/** CPU time this process has used, in ms; 0 where the runtime cannot say (a browser). */
+function cpuMs(): number {
+  if (typeof process === "undefined" || typeof process.cpuUsage !== "function") return 0
+  const { user, system } = process.cpuUsage()
+  return (user + system) / 1000
+}
+
+function defaultCollector(): Collector | undefined {
+  const runtime = globalThis as unknown as {
+    Bun?: { gc(force: boolean): void }
+    gc?: () => void
+  }
+  if (runtime.Bun) return () => runtime.Bun!.gc(true)
+  if (runtime.gc) return () => runtime.gc!()
+  return undefined
+}
+
+/**
+ * Run one full garbage collection once the app has been quiet for a while.
+ *
+ * A JavaScript engine collects on allocation pressure, so after a burst of work
+ * (the first mount, opening a long thread) the heap and the pages behind it stay
+ * at their peak until the next burst. This waits for `activity` to hold still
+ * for `quietChecks` looks and the process to be under `busyCpu`, collects once,
+ * then waits for the next busy period.
+ *
+ * CPU alone cannot stand for "quiet": a focused text field blinks its caret in
+ * native code and redraws the window twice a second, which on a long thread
+ * exceeds any threshold that would still tell a busy period apart. Commits do
+ * not move for that, so they decide, and CPU only covers work that commits
+ * nothing.
+ *
+ * Returns a function that stops it. Does nothing, and returns a no-op, where
+ * the runtime has no way to force a collection.
+ */
+export function collectGarbageWhenIdle(options: IdleGcOptions = {}): () => void {
+  const collect = options.collect ?? defaultCollector()
+  if (!collect) return () => {}
+  const activity = options.activity ?? appliedBatchCount
+  const checkMs = options.checkMs ?? 5_000
+  const quietChecks = options.quietChecks ?? 2
+  const busyCpu = options.busyCpu ?? 0.5
+
+  let lastCpu = cpuMs()
+  let lastWall = performance.now()
+  let lastActivity = activity()
+  let quiet = 0
+  let collected = false
+  const timer = setInterval(() => {
+    const cpu = cpuMs()
+    const wall = performance.now()
+    const busy = (cpu - lastCpu) / (wall - lastWall)
+    const current = activity()
+    const active = current !== lastActivity || busy >= busyCpu
+    lastCpu = cpu
+    lastWall = wall
+    lastActivity = current
+    if (active) {
+      quiet = 0
+      collected = false
+      return
+    }
+    if (collected || ++quiet < quietChecks) return
+    collected = true
+    collect()
+  }, checkMs)
+  // A background check must not keep a process alive that has nothing else to do.
+  ;(timer as { unref?: () => void }).unref?.()
+  return () => clearInterval(timer)
+}
diff --git a/packages/native/js/mutations.ts b/packages/native/js/mutations.ts
index b613b80a2..9a72394fd 100644
--- a/packages/native/js/mutations.ts
+++ b/packages/native/js/mutations.ts
@@ -3,6 +3,17 @@ import type { MutationHost, MutationRenderer } from "./host.js"
 export type MutationValue = number | string | boolean | object | null
 export type MutationTuple = [string, ...MutationValue[]]
 
+let appliedBatches = 0
+
+/**
+ * How many batches of mutations have reached a renderer, across every queue.
+ * It moves whenever the tree changes, which makes it the signal that an app is
+ * still working: `collectGarbageWhenIdle` waits for it to hold still.
+ */
+export function appliedBatchCount(): number {
+  return appliedBatches
+}
+
 /** Atomic mutation queue shared by all framework adapters. */
 export interface MutationQueue extends MutationRenderer {
   readonly pending: number
@@ -65,6 +76,7 @@ export function createMutationQueue(
     flushMutations() {
       flushScheduled = false
       if (queue.length === 0) return
+      appliedBatches++
       const destroyed = renderer.applyBatch(JSON.stringify(queue))
       onDestroyed(destroyed)
       queue = []
diff --git a/packages/native/package.json b/packages/native/package.json
index 4b9d3aa36..85fd23fd1 100644
--- a/packages/native/package.json
+++ b/packages/native/package.json
@@ -34,6 +34,11 @@
       "import": "./dist/cpu-throttle.js",
       "default": "./dist/cpu-throttle.js"
     },
+    "./idle-gc": {
+      "types": "./dist/idle-gc.d.ts",
+      "import": "./dist/idle-gc.js",
+      "default": "./dist/idle-gc.js"
+    },
     "./runtime": {
       "types": "./dist/runtime.d.ts",
       "import": "./dist/runtime.js",
diff --git a/packages/react/src/idle-gc.ts b/packages/react/src/idle-gc.ts
new file mode 100644
index 000000000..fcb7391de
--- /dev/null
+++ b/packages/react/src/idle-gc.ts
@@ -0,0 +1,2 @@
+export { collectGarbageWhenIdle } from "@gpuix/native/idle-gc"
+export type { IdleGcOptions } from "@gpuix/native/idle-gc"
diff --git a/packages/react/src/index.ts b/packages/react/src/index.ts
index 5fd01b6e4..0cbb65ebf 100644
--- a/packages/react/src/index.ts
+++ b/packages/react/src/index.ts
@@ -166,6 +166,8 @@ export {
   readMacCpuThrottle,
 } from "./cpu-throttle.js"
 export type { MacCpuThrottle } from "./cpu-throttle.js"
+export { collectGarbageWhenIdle } from "./idle-gc.js"
+export type { IdleGcOptions } from "./idle-gc.js"
 export type {
   EventPayload,
   EventModifiers,

From d789ba4b9b2d2ecb89dab12aea35fdaef658d5a3 Mon Sep 17 00:00:00 2001
From: Ruben Nogueira <40404708+rubnogueira@users.noreply.github.com>
Date: Sat, 10 Oct 2026 19:34:39 +0100
Subject: [PATCH 18/27] feat(native): scrollbarColor paints a native scrollbar
 thumb

---
 .changeset/native-scrollbars.md               |   5 +
 README.md                                     |  20 +++
 packages/native/js/host.ts                    |   6 +
 packages/native/src/renderer.rs               | 145 ++++++++++++++++++
 packages/native/src/style.rs                  |   5 +
 .../react/src/__tests__/scrollbar.test.tsx    | 121 +++++++++++++++
 packages/react/src/__tests__/test-utils.ts    |  57 +++++++
 7 files changed, 359 insertions(+)
 create mode 100644 .changeset/native-scrollbars.md
 create mode 100644 packages/react/src/__tests__/scrollbar.test.tsx

diff --git a/.changeset/native-scrollbars.md b/.changeset/native-scrollbars.md
new file mode 100644
index 000000000..25d715b7a
--- /dev/null
+++ b/.changeset/native-scrollbars.md
@@ -0,0 +1,5 @@
+---
+'@gpuix/native': patch
+---
+
+`scrollbarColor` and `scrollbarWidth` paint a native scrollbar thumb over a container with `overflow: "scroll"`, on each axis that has more to show. The thumb follows the scroll offset in the frame it paints, with no JavaScript in the loop and no extra frame, and it takes no pointer input.
diff --git a/README.md b/README.md
index cc7c5dded..a3f85a4f4 100644
--- a/README.md
+++ b/README.md
@@ -1744,6 +1744,26 @@ that height. An explicit `height` still overrides both.
 />
 ```
 
+### Scrollbars
+
+A container with `overflow: 'scroll'` scrolls but draws no scrollbar. Give it a
+`scrollbarColor` and gpuix paints a thumb over its content, on each axis that has
+more to show:
+
+```tsx
+<div style={{ height: 300, overflow: 'scroll', scrollbarColor: '#8884', scrollbarWidth: 6 }}>
+  {rows}
+</div>
+```
+
+`scrollbarWidth` is the thickness in px and defaults to 6. The thumb is as long
+as the viewport is of the content (never under 20px), fully rounded, and sits
+on the right edge, or the bottom for sideways scrolling, leaving the corner free
+when both show. It is painted from the scroll offset in the frame the content
+moves, so a wheel tick costs nothing beyond that frame. It is a drawing, not a
+control: it takes no pointer input, so it cannot be dragged. It applies to
+`overflow: 'scroll'` containers, not `<virtual-list>`.
+
 ### Give memory back when idle
 
 A JavaScript engine collects on allocation pressure, so after a burst of work
diff --git a/packages/native/js/host.ts b/packages/native/js/host.ts
index 023ca4eb2..47a3faca9 100644
--- a/packages/native/js/host.ts
+++ b/packages/native/js/host.ts
@@ -205,6 +205,12 @@ export interface StyleDesc {
   overflow?: string
   overflowX?: string
   overflowY?: string
+  /** Colour of the scrollbar thumb. Setting it paints a native thumb over a container
+   *  that scrolls (`overflow: "scroll"`), on each axis that has more to show. The
+   *  thumb follows the scroll offset in the frame it paints, and takes no pointer input. */
+  scrollbarColor?: string
+  /** Thickness of that thumb in px. Defaults to 6. */
+  scrollbarWidth?: number
 
   cursor?: CursorValue
   /** `"auto"` blocks hits behind this element **and its wheel**. `"none"` never
diff --git a/packages/native/src/renderer.rs b/packages/native/src/renderer.rs
index dddbcc78e..24f32cadc 100644
--- a/packages/native/src/renderer.rs
+++ b/packages/native/src/renderer.rs
@@ -5750,9 +5750,154 @@ pub(crate) fn build_host_container(
         };
     }
 
+    // Last, so the thumb paints over the content.
+    if let (Some(style), Some(handle)) = (style, ctx.scroll_handles.get(&element.id)) {
+        if let Some(color) = style
+            .scrollbar_color
+            .as_deref()
+            .and_then(crate::color::parse_color_rgba)
+        {
+            let along = |axis: Option<&str>| axis == Some("scroll");
+            el = el.child(scrollbar_overlay(
+                handle.clone(),
+                color.into(),
+                style.scrollbar_width.unwrap_or(SCROLLBAR_WIDTH as f64) as f32,
+                along(style.overflow_x.as_deref().or(style.overflow.as_deref())),
+                along(style.overflow_y.as_deref().or(style.overflow.as_deref())),
+            ));
+        }
+    }
+
     el.into_any_element()
 }
 
+/// A classic scrollbar's default thickness.
+const SCROLLBAR_WIDTH: f32 = 6.0;
+/// The shortest a thumb gets, however long the content.
+const MIN_SCROLLBAR_THUMB: f32 = 20.0;
+
+/// Where a thumb starts and how long it is along one axis, in the track's own
+/// coordinates. `track` is the viewport's extent, `max_scroll` how far the
+/// content can move, and `offset` how far it has (zero or negative). `None`
+/// when the content fits, so there is nothing to show.
+fn scrollbar_thumb(track: f32, max_scroll: f32, offset: f32) -> Option<(f32, f32)> {
+    if track <= 0.0 || max_scroll <= 1.0 {
+        return None;
+    }
+    let length = (track * track / (track + max_scroll)).clamp(MIN_SCROLLBAR_THUMB.min(track), track);
+    let progress = (-offset / max_scroll).clamp(0.0, 1.0);
+    Some((progress * (track - length), length))
+}
+
+/// The thumbs of a scroll container, painted from its own scroll offset in the
+/// frame the content moves in, so a wheel tick costs nothing beyond that frame.
+///
+/// It is the container's last child, absolutely placed over its padding box.
+/// Children of a scroller are painted shifted by the scroll offset, so the
+/// viewport is this box moved back by it. It has no hitbox and takes no input.
+fn scrollbar_overlay(
+    handle: gpui::ScrollHandle,
+    color: gpui::Hsla,
+    thickness: f32,
+    horizontal: bool,
+    vertical: bool,
+) -> gpui::AnyElement {
+    use gpui::prelude::*;
+
+    gpui::canvas(
+        |_, _, _| (),
+        move |bounds, _, window, _| {
+            let offset = handle.offset();
+            let max = handle.max_offset();
+            let origin = bounds.origin - offset;
+            let (width, height) = (
+                f32::from(bounds.size.width),
+                f32::from(bounds.size.height),
+            );
+            let along = |show: bool, track: f32, max_scroll: gpui::Pixels, offset: gpui::Pixels| {
+                show.then(|| scrollbar_thumb(track, f32::from(max_scroll), f32::from(offset)))
+                    .flatten()
+            };
+            let mut across = along(vertical, height, max.y, offset.y);
+            let mut sideways = along(horizontal, width, max.x, offset.x);
+            if across.is_some() && sideways.is_some() {
+                // Leave the corner to whichever thumb reaches it first.
+                across = along(vertical, height - thickness, max.y, offset.y);
+                sideways = along(horizontal, width - thickness, max.x, offset.x);
+            }
+            let paint = |window: &mut gpui::Window, x: f32, y: f32, w: f32, h: f32| {
+                // Whole pixels, so a thumb is as crisp as a browser's.
+                let rect = gpui::Bounds::new(
+                    gpui::point(origin.x + gpui::px(x.round()), origin.y + gpui::px(y.round())),
+                    gpui::size(gpui::px(w.round()), gpui::px(h.round())),
+                );
+                window.paint_quad(gpui::quad(
+                    rect,
+                    gpui::px(thickness / 2.0),
+                    color,
+                    gpui::px(0.0),
+                    gpui::transparent_black(),
+                    gpui::BorderStyle::default(),
+                ));
+            };
+            if let Some((start, length)) = across {
+                paint(window, width - thickness, start, thickness, length);
+            }
+            if let Some((start, length)) = sideways {
+                paint(window, start, height - thickness, length, thickness);
+            }
+        },
+    )
+    .absolute()
+    .top_0()
+    .left_0()
+    .size_full()
+    .into_any_element()
+}
+
+#[cfg(test)]
+mod scrollbar_tests {
+    use super::scrollbar_thumb;
+
+    #[test]
+    fn a_thumb_is_the_viewports_share_of_the_content() {
+        // 100 of 300: a third of the track.
+        let (start, length) = scrollbar_thumb(100.0, 200.0, 0.0).unwrap();
+        assert_eq!(start, 0.0);
+        assert!((length - 100.0 / 3.0).abs() < 0.01);
+    }
+
+    #[test]
+    fn a_thumb_runs_the_whole_track_as_the_content_runs_its_distance() {
+        let (_, length) = scrollbar_thumb(100.0, 200.0, 0.0).unwrap();
+        let (start, same_length) = scrollbar_thumb(100.0, 200.0, -200.0).unwrap();
+        assert_eq!(length, same_length);
+        assert!((start + length - 100.0).abs() < 0.01, "ends at the end of the track");
+        let (halfway, _) = scrollbar_thumb(100.0, 200.0, -100.0).unwrap();
+        assert!((halfway - (100.0 - length) / 2.0).abs() < 0.01);
+    }
+
+    #[test]
+    fn a_thumb_stays_inside_the_track_when_the_offset_overshoots() {
+        let (start, length) = scrollbar_thumb(100.0, 200.0, -450.0).unwrap();
+        assert!((start + length - 100.0).abs() < 0.01);
+        assert_eq!(scrollbar_thumb(100.0, 200.0, 30.0).unwrap().0, 0.0);
+    }
+
+    #[test]
+    fn a_thumb_is_never_shorter_than_a_grabbable_length_nor_longer_than_the_track() {
+        assert_eq!(scrollbar_thumb(100.0, 100_000.0, 0.0).unwrap().1, 20.0);
+        assert_eq!(scrollbar_thumb(10.0, 100_000.0, 0.0).unwrap().1, 10.0);
+    }
+
+    #[test]
+    fn content_that_fits_has_no_thumb() {
+        assert_eq!(scrollbar_thumb(100.0, 0.0, 0.0), None);
+        assert_eq!(scrollbar_thumb(100.0, 0.5, 0.0), None, "a fraction of a pixel is rounding");
+        assert_eq!(scrollbar_thumb(0.0, 200.0, 0.0), None);
+    }
+}
+
 /// A selectable text run owned by `element`. Runs are left to gpui so the
 /// text keeps inheriting colour, weight and family from ancestor styles.
 ///
diff --git a/packages/native/src/style.rs b/packages/native/src/style.rs
index 8c1745778..5c2aba81b 100644
--- a/packages/native/src/style.rs
+++ b/packages/native/src/style.rs
@@ -243,6 +243,11 @@ pub struct StyleDesc {
     pub overflow: Option<String>,
     pub overflow_x: Option<String>,
     pub overflow_y: Option<String>,
+    /// Thumb colour for a container that scrolls (`overflow: "scroll"`). Setting
+    /// it is what turns the native scrollbar on.
+    pub scrollbar_color: Option<String>,
+    /// Thickness of that thumb in px. Defaults to 6.
+    pub scrollbar_width: Option<f64>,
 
     // Cursor
     pub cursor: Option<String>,
diff --git a/packages/react/src/__tests__/scrollbar.test.tsx b/packages/react/src/__tests__/scrollbar.test.tsx
new file mode 100644
index 000000000..f570f8250
--- /dev/null
+++ b/packages/react/src/__tests__/scrollbar.test.tsx
@@ -0,0 +1,121 @@
+import path from "path"
+import { describe, expect, it } from "vitest"
+import { createTestRoot, hasNativeTestRenderer } from "../testing.js"
+import { readPixels, SHOTS_DIR } from "./test-utils.js"
+
+const describeNative = hasNativeTestRenderer ? describe : describe.skip
+
+const THUMB = "#ff0000"
+
+/** Rows (within the scroller's 100px) holding thumb-coloured pixels in a column. */
+function thumbRows(pixels: ReturnType<typeof readPixels>, x: number, top = 0) {
+  const rows: number[] = []
+  for (let y = 0; y < 100; y++) {
+    const [r, g, b] = pixels.at(x, top + y)
+    if (r > 200 && g < 60 && b < 60) rows.push(y)
+  }
+  return rows
+}
+
+function shoot(
+  contentHeight: number,
+  scrollTo?: number,
+  scroller: Record<string, unknown> = {}
+) {
+  const { render, renderer, unmount } = createTestRoot()
+  try {
+    render(
+      <div
+        testId="scroller"
+        style={{
+          width: 100,
+          height: 100,
+          overflow: "scroll",
+          scrollbarColor: THUMB,
+          ...scroller,
+        }}
+      >
+        <div style={{ width: 100, height: contentHeight, backgroundColor: "#202020" }} />
+      </div>
+    )
+    renderer.dispatchNativeEvents()
+    if (scrollTo !== undefined) {
+      renderer.scrollTo(renderer.findByTestId("scroller")!.id, 0, -scrollTo)
+      renderer.flush()
+    }
+    const file = path.join(SHOTS_DIR, `scrollbar-${contentHeight}-${scrollTo ?? "top"}.png`)
+    renderer.captureScreenshot(file)
+    return readPixels(file)
+  } finally {
+    unmount()
+  }
+}
+
+describeNative("scrollbarColor", () => {
+  it("paints a thumb along the right edge, as long as the viewport is of the content", () => {
+    // 100px of a 300px content: a third of the track.
+    const rows = thumbRows(shoot(300), 97)
+    expect(rows[0]).toBe(0)
+    expect(rows.at(-1)).toBe(32)
+    expect(thumbRows(shoot(300), 80), "only along the edge").toEqual([])
+    expect(thumbRows(shoot(300), 93), "6px wide: x 94 to 99").toEqual([])
+    expect(thumbRows(shoot(300), 94).length).toBeGreaterThan(0)
+  })
+
+  it("follows the scroll offset", () => {
+    const rows = thumbRows(shoot(300, 200), 97)
+    expect(rows[0]).toBe(67)
+    expect(rows.at(-1)).toBe(99)
+    const middle = thumbRows(shoot(300, 100), 97)
+    expect(middle[0]).toBeGreaterThan(25)
+    expect(middle[0]).toBeLessThan(45)
+  })
+
+  it("paints nothing when the content fits", () => {
+    expect(thumbRows(shoot(80), 97)).toEqual([])
+  })
+
+  it("is off without a colour, and takes the thickness from scrollbarWidth", () => {
+    expect(thumbRows(shoot(300, undefined, { scrollbarColor: undefined }), 97)).toEqual([])
+    const wide = shoot(300, undefined, { scrollbarWidth: 12 })
+    expect(thumbRows(wide, 89).length, "12px wide: x 88 to 99").toBeGreaterThan(0)
+    expect(thumbRows(wide, 87)).toEqual([])
+  })
+
+  it("draws a thumb along the bottom for sideways scrolling, and leaves the corner when both show", () => {
+    const { render, renderer, unmount } = createTestRoot()
+    try {
+      render(
+        <div
+          style={{ width: 100, height: 100, overflow: "scroll", scrollbarColor: THUMB, scrollbarWidth: 6 }}
+        >
+          <div style={{ width: 300, height: 300, backgroundColor: "#202020" }} />
+        </div>
+      )
+      renderer.dispatchNativeEvents()
+      const file = path.join(SHOTS_DIR, "scrollbar-both.png")
+      renderer.captureScreenshot(file)
+      const pixels = readPixels(file)
+      const isThumb = (x: number, y: number) => {
+        const [r, g, b] = pixels.at(x, y)
+        return r > 200 && g < 60 && b < 60
+      }
+      // Vertical thumb: the right edge, from the top, stopping short of the corner.
+      const down = Array.from({ length: 100 }, (_, y) => y).filter((y) => isThumb(97, y))
+      // Horizontal thumb: the bottom edge, from the left, stopping short of the corner.
+      const across = Array.from({ length: 100 }, (_, x) => x).filter((x) => isThumb(x, 97))
+      expect(down[0]).toBe(0)
+      expect(across[0]).toBe(0)
+      expect(down.at(-1)).toBeLessThan(94)
+      expect(across.at(-1)).toBeLessThan(94)
+      expect(isThumb(97, 97), "the corner stays free").toBe(false)
+    } finally {
+      unmount()
+    }
+  })
+
+  it("never shortens a thumb below a grabbable length", () => {
+    const rows = thumbRows(shoot(5000), 97)
+    expect(rows.length).toBe(20)
+  })
+})
diff --git a/packages/react/src/__tests__/test-utils.ts b/packages/react/src/__tests__/test-utils.ts
index 7112ad550..90e60a593 100644
--- a/packages/react/src/__tests__/test-utils.ts
+++ b/packages/react/src/__tests__/test-utils.ts
@@ -1,6 +1,7 @@
 /// Test utilities shared across GPUIX test files.
 
 import fs from "fs"
+import zlib from "zlib"
 import path from "path"
 import { fileURLToPath } from "url"
 import { expect } from "vitest"
@@ -73,3 +74,59 @@ export function expectScreenshotsEqual(leftPath: string, rightPath: string) {
   const right = fs.readFileSync(rightPath)
   expect(left.equals(right)).toBe(true)
 }
+
+export interface Pixels {
+  width: number
+  height: number
+  /** The pixel at (x, y) as `[r, g, b, a]`. */
+  at(x: number, y: number): [number, number, number, number]
+}
+
+/** Decode a screenshot (8-bit RGBA, not interlaced, which is what the test
+ *  renderer writes) so a test can look at actual pixels. */
+export function readPixels(file: string): Pixels {
+  const png = fs.readFileSync(file)
+  const width = png.readUInt32BE(16)
+  const height = png.readUInt32BE(20)
+  expect([png[24], png[25], png[28]], "8-bit RGBA, not interlaced").toEqual([8, 6, 0])
+  const chunks: Buffer[] = []
+  for (let at = 8; at < png.length; ) {
+    const length = png.readUInt32BE(at)
+    if (png.toString("latin1", at + 4, at + 8) === "IDAT") {
+      chunks.push(png.subarray(at + 8, at + 8 + length))
+    }
+    at += 12 + length
+  }
+  const raw = zlib.inflateSync(Buffer.concat(chunks))
+  const stride = width * 4
+  const data = Buffer.alloc(stride * height)
+  for (let y = 0; y < height; y++) {
+    const filter = raw[y * (stride + 1)]
+    for (let x = 0; x < stride; x++) {
+      const byte = raw[y * (stride + 1) + 1 + x]!
+      const left = x >= 4 ? data[y * stride + x - 4]! : 0
+      const up = y > 0 ? data[(y - 1) * stride + x]! : 0
+      const upLeft = x >= 4 && y > 0 ? data[(y - 1) * stride + x - 4]! : 0
+      const paeth = () => {
+        const estimate = left + up - upLeft
+        const [a, b, c] = [
+          Math.abs(estimate - left),
+          Math.abs(estimate - up),
+          Math.abs(estimate - upLeft),
+        ]
+        return a <= b && a <= c ? left : b <= c ? up : upLeft
+      }
+      const predicted =
+        filter === 0 ? 0 : filter === 1 ? left : filter === 2 ? up : filter === 3 ? (left + up) >> 1 : paeth()
+      data[y * stride + x] = (byte + predicted) & 255
+    }
+  }
+  return {
+    width,
+    height,
+    at: (x, y) => {
+      const i = y * stride + x * 4
+      return [data[i]!, data[i + 1]!, data[i + 2]!, data[i + 3]!]
+    },
+  }
+}

From be82b368b976b5db4a4df09c33f08958fa664de2 Mon Sep 17 00:00:00 2001
From: Ruben Nogueira <40404708+rubnogueira@users.noreply.github.com>
Date: Sat, 10 Oct 2026 20:17:33 +0100
Subject: [PATCH 19/27] perf(native): compile the highlight query once per
 keystroke

---
 .changeset/highlight-search-needle.md |  5 ++
 packages/native/Cargo.lock            |  1 +
 packages/native/Cargo.toml            |  1 +
 packages/native/src/text/search.rs    | 93 +++++++++++++++++++++++++--
 4 files changed, 94 insertions(+), 6 deletions(-)
 create mode 100644 .changeset/highlight-search-needle.md

diff --git a/.changeset/highlight-search-needle.md b/.changeset/highlight-search-needle.md
new file mode 100644
index 000000000..71f0f68d8
--- /dev/null
+++ b/.changeset/highlight-search-needle.md
@@ -0,0 +1,5 @@
+---
+'@gpuix/native': patch
+---
+
+Typing in a find-in-page query no longer rebuilds the search for every block of text. The query is lowercased and compiled once per keystroke and shared by all the text it is matched against, so each keystroke in a long chat costs a few percent less CPU. Matches are the same as before: leftmost, non-overlapping, case-insensitive by default.
diff --git a/packages/native/Cargo.lock b/packages/native/Cargo.lock
index 0015c1716..ade6700cd 100644
--- a/packages/native/Cargo.lock
+++ b/packages/native/Cargo.lock
@@ -2604,6 +2604,7 @@ dependencies = [
  "http_client",
  "js-sys",
  "log",
+ "memchr",
  "minisign-verify",
  "napi",
  "napi-build",
diff --git a/packages/native/Cargo.toml b/packages/native/Cargo.toml
index 666c39d49..d07bff3c1 100644
--- a/packages/native/Cargo.toml
+++ b/packages/native/Cargo.toml
@@ -16,6 +16,7 @@ anyhow = "1"
 base64 = "0.22"
 csscolorparser = "0.8.3"
 log = "0.4"
+memchr = "2"
 env_logger = "0.11"
 parking_lot = "0.12"
 futures = "0.3"
diff --git a/packages/native/src/text/search.rs b/packages/native/src/text/search.rs
index 26335ff00..ebffd7f07 100644
--- a/packages/native/src/text/search.rs
+++ b/packages/native/src/text/search.rs
@@ -26,6 +26,9 @@ use crate::retained_tree::RetainedTree;
 #[derive(Clone, Debug, PartialEq)]
 pub struct HighlightSpec {
     pub query: String,
+    /// `query` as a searcher. It is shared by every text group a keystroke
+    /// visits, so it is built here and not inside the per-group search.
+    pub needle: Needle,
     pub case_sensitive: bool,
     pub whole_word: bool,
     /// `[start, end)` in UTF-16 code units, indexing the declaring subtree's
@@ -144,9 +147,11 @@ impl HighlightSpec {
         base.a = 0.30;
         let mut active = theme.accent;
         active.a = 0.65;
+        let case_sensitive = flag("caseSensitive");
         Some(Self {
+            needle: Needle::new(&query, case_sensitive),
             query,
-            case_sensitive: flag("caseSensitive"),
+            case_sensitive,
             whole_word: flag("wholeWord"),
             ranges,
             color: color("color").map(Into::into).unwrap_or(base),
@@ -165,6 +170,50 @@ impl HighlightSpec {
     }
 }
 
+/// A query ready to search with: lowercased unless the match is case
+/// sensitive, behind a `memmem` searcher that is built once. The standard
+/// library builds a fresh searcher for every `match_indices` call, and a
+/// keystroke makes one call per text group, which on a long thread cost more
+/// than scanning the text.
+#[derive(Clone)]
+pub struct Needle {
+    text: Arc<str>,
+    finder: Arc<memchr::memmem::Finder<'static>>,
+}
+
+impl Needle {
+    pub fn new(query: &str, case_sensitive: bool) -> Self {
+        let text: Arc<str> = if case_sensitive {
+            query.into()
+        } else {
+            query.to_lowercase().into()
+        };
+        let finder = Arc::new(memchr::memmem::Finder::new(text.as_bytes()).into_owned());
+        Self { text, finder }
+    }
+
+    /// Non-overlapping byte ranges of the needle in `haystack`, leftmost first.
+    /// A UTF-8 needle only matches on character boundaries of UTF-8 text.
+    fn find<'a>(&'a self, haystack: &'a str) -> impl Iterator<Item = Range<usize>> + 'a {
+        let length = self.text.len();
+        self.finder
+            .find_iter(haystack.as_bytes())
+            .map(move |start| start..start + length)
+    }
+}
+
+impl PartialEq for Needle {
+    fn eq(&self, other: &Self) -> bool {
+        self.text == other.text
+    }
+}
+
+impl std::fmt::Debug for Needle {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.debug_tuple("Needle").field(&self.text).finish()
+    }
+}
+
 // ── Lowercasing ──────────────────────────────────────────────────────
 //
 // This is Unicode default lowercasing (`str::to_lowercase`), NOT full case
@@ -396,17 +445,15 @@ fn matches_in(
     }
     let mut out = Vec::new();
     if spec.case_sensitive {
-        for (ix, hit) in text.match_indices(spec.query.as_str()) {
-            let range = ix..ix + hit.len();
+        for range in spec.needle.find(text) {
             if !spec.whole_word || is_whole_word(text, &range) {
                 out.push(range);
             }
         }
         return out;
     }
-    let needle = spec.query.to_lowercase();
-    for (ix, hit) in folded.match_indices(needle.as_str()) {
-        let (Some(&start), Some(&end)) = (fold_map.get(ix), fold_map.get(ix + hit.len())) else {
+    for hit in spec.needle.find(folded) {
+        let (Some(&start), Some(&end)) = (fold_map.get(hit.start), fold_map.get(hit.end)) else {
             continue;
         };
         let range = start as usize..end as usize;
@@ -700,6 +747,7 @@ mod tests {
     fn spec(query: &str) -> HighlightSpec {
         HighlightSpec {
             query: query.to_string(),
+            needle: Needle::new(query, false),
             case_sensitive: false,
             whole_word: false,
             ranges: Vec::new(),
@@ -711,6 +759,39 @@ mod tests {
         }
     }
 
+    /// The searcher must report what `str::match_indices` always did: leftmost,
+    /// non-overlapping, on character boundaries.
+    #[test]
+    fn a_needle_finds_what_match_indices_finds() {
+        for (haystack, query) in [
+            ("aaaa", "aa"),
+            ("aaa", "aa"),
+            ("abcabcabc", "abc"),
+            ("héllo wörld héllo", "héllo"),
+            ("日本語の日本語", "日本語"),
+            ("a😀b😀c", "😀"),
+            ("short", "much longer than the text"),
+            ("", "x"),
+        ] {
+            let expected: Vec<_> = haystack
+                .match_indices(query)
+                .map(|(start, hit)| start..start + hit.len())
+                .collect();
+            let found: Vec<_> = Needle::new(query, true).find(haystack).collect();
+            assert_eq!(found, expected, "{query:?} in {haystack:?}");
+        }
+    }
+
+    #[test]
+    fn a_case_insensitive_needle_searches_the_lowercased_text() {
+        let needle = Needle::new("FOO", false);
+        assert_eq!(needle.find("a foo and a FOO").collect::<Vec<_>>(), vec![2..5]);
+        assert_eq!(
+            needle.find(&"a foo and a FOO".to_lowercase()).collect::<Vec<_>>(),
+            vec![2..5, 12..15]
+        );
+    }
+
     fn find(text: &str, spec: &HighlightSpec) -> Vec<Range<usize>> {
         let (folded, map) = fold(text);
         matches_in(text, &folded, &map, spec)

From a0642953cfb9cb5060923367e23782821362e2e0 Mon Sep 17 00:00:00 2001
From: Ruben Nogueira <40404708+rubnogueira@users.noreply.github.com>
Date: Sat, 10 Oct 2026 20:35:08 +0100
Subject: [PATCH 20/27] feat(native): scrollbarColor draws a thumb on a virtual
 list

---
 .changeset/virtual-list-scrollbar.md          |   5 +
 README.md                                     |   5 +-
 packages/native/src/renderer.rs               | 246 +++++++++++++-----
 .../react/src/__tests__/scrollbar.test.tsx    |  65 +++++
 4 files changed, 261 insertions(+), 60 deletions(-)
 create mode 100644 .changeset/virtual-list-scrollbar.md

diff --git a/.changeset/virtual-list-scrollbar.md b/.changeset/virtual-list-scrollbar.md
new file mode 100644
index 000000000..d5c8cd8cf
--- /dev/null
+++ b/.changeset/virtual-list-scrollbar.md
@@ -0,0 +1,5 @@
+---
+'@gpuix/native': patch
+---
+
+`scrollbarColor` and `scrollbarWidth` now also draw a thumb on a `<virtual-list>`. It is painted over the list in the frame the list scrolls, from the heights the list has measured, so it never lags the scroll position and costs no frame of its own. The list's layout is unchanged.
diff --git a/README.md b/README.md
index a3f85a4f4..59c7a4313 100644
--- a/README.md
+++ b/README.md
@@ -1762,7 +1762,10 @@ on the right edge, or the bottom for sideways scrolling, leaving the corner free
 when both show. It is painted from the scroll offset in the frame the content
 moves, so a wheel tick costs nothing beyond that frame. It is a drawing, not a
 control: it takes no pointer input, so it cannot be dragged. It applies to
-`overflow: 'scroll'` containers, not `<virtual-list>`.
+`overflow: 'scroll'` containers and to `<virtual-list>`. A list's thumb comes
+from the heights the list has measured (and `estimatedItemHeight` for rows it has
+not reached), the same totals it scrolls by, so it only runs along the right edge
+and its length settles as rows are measured.
 
 ### Give memory back when idle
 
diff --git a/packages/native/src/renderer.rs b/packages/native/src/renderer.rs
index 24f32cadc..164892fed 100644
--- a/packages/native/src/renderer.rs
+++ b/packages/native/src/renderer.rs
@@ -5327,6 +5327,7 @@ fn build_virtual_list(
         };
         view.build_virtual_child(list_id, index, child_id, inherited.clone(), window, cx)
     });
+    let scroll_state = list_state.clone();
     let mut list = gpui::list(list_state, render_item)
         .with_sizing_behavior(gpui::ListSizingBehavior::Auto)
         .id(gpui::ElementId::Name(gpui::SharedString::from(format!(
@@ -5336,7 +5337,20 @@ fn build_virtual_list(
     if let Some(style) = element.style.as_deref() {
         list = apply_styles(list, style);
     }
-    apply_accessibility(list, &element.custom_props, None).into_any_element()
+    let list = apply_accessibility(list, &element.custom_props, None).into_any_element();
+    match element
+        .style
+        .as_deref()
+        .and_then(|style| ThumbStyle::of(style, false, true))
+    {
+        Some(thumbs) => ListWithScrollbar {
+            list,
+            state: scroll_state,
+            thumbs,
+        }
+        .into_any_element(),
+        None => list,
+    }
 }
 
 fn unmounted_virtual_row(height: f32) -> gpui::AnyElement {
@@ -5752,19 +5766,12 @@ pub(crate) fn build_host_container(
 
     // Last, so the thumb paints over the content.
     if let (Some(style), Some(handle)) = (style, ctx.scroll_handles.get(&element.id)) {
-        if let Some(color) = style
-            .scrollbar_color
-            .as_deref()
-            .and_then(crate::color::parse_color_rgba)
-        {
-            let along = |axis: Option<&str>| axis == Some("scroll");
-            el = el.child(scrollbar_overlay(
-                handle.clone(),
-                color.into(),
-                style.scrollbar_width.unwrap_or(SCROLLBAR_WIDTH as f64) as f32,
-                along(style.overflow_x.as_deref().or(style.overflow.as_deref())),
-                along(style.overflow_y.as_deref().or(style.overflow.as_deref())),
-            ));
+        if let Some(thumbs) = ThumbStyle::of(
+            style,
+            style.overflow_x.as_deref().or(style.overflow.as_deref()) == Some("scroll"),
+            style.overflow_y.as_deref().or(style.overflow.as_deref()) == Some("scroll"),
+        ) {
+            el = el.child(scrollbar_overlay(handle.clone(), thumbs));
         }
     }
 
@@ -5784,68 +5791,112 @@ fn scrollbar_thumb(track: f32, max_scroll: f32, offset: f32) -> Option<(f32, f32
     if track <= 0.0 || max_scroll <= 1.0 {
         return None;
     }
-    let length = (track * track / (track + max_scroll)).clamp(MIN_SCROLLBAR_THUMB.min(track), track);
+    let length =
+        (track * track / (track + max_scroll)).clamp(MIN_SCROLLBAR_THUMB.min(track), track);
     let progress = (-offset / max_scroll).clamp(0.0, 1.0);
     Some((progress * (track - length), length))
 }
 
+/// What a scroller asks its thumbs to look like, and along which axes it has any.
+#[derive(Clone, Copy)]
+struct ThumbStyle {
+    color: gpui::Hsla,
+    thickness: f32,
+    horizontal: bool,
+    vertical: bool,
+}
+
+impl ThumbStyle {
+    /// `None` unless the style names a `scrollbarColor` that parses.
+    fn of(style: &StyleDesc, horizontal: bool, vertical: bool) -> Option<Self> {
+        let color = style
+            .scrollbar_color
+            .as_deref()
+            .and_then(crate::color::parse_color_rgba)?;
+        Some(Self {
+            color: color.into(),
+            thickness: style.scrollbar_width.unwrap_or(SCROLLBAR_WIDTH as f64) as f32,
+            horizontal,
+            vertical,
+        })
+    }
+}
+
+/// Paints the thumbs of a viewport at `origin` with `size`. `max` is how far
+/// its content can move and `offset` how far it has (zero or negative).
+fn paint_scrollbars(
+    window: &mut gpui::Window,
+    origin: gpui::Point<gpui::Pixels>,
+    size: gpui::Size<gpui::Pixels>,
+    max: gpui::Point<gpui::Pixels>,
+    offset: gpui::Point<gpui::Pixels>,
+    thumbs: ThumbStyle,
+) {
+    let ThumbStyle {
+        color,
+        thickness,
+        horizontal,
+        vertical,
+    } = thumbs;
+    let (width, height) = (f32::from(size.width), f32::from(size.height));
+    let along = |show: bool, track: f32, max_scroll: gpui::Pixels, offset: gpui::Pixels| {
+        show.then(|| scrollbar_thumb(track, f32::from(max_scroll), f32::from(offset)))
+            .flatten()
+    };
+    let mut across = along(vertical, height, max.y, offset.y);
+    let mut sideways = along(horizontal, width, max.x, offset.x);
+    if across.is_some() && sideways.is_some() {
+        // Leave the corner to whichever thumb reaches it first.
+        across = along(vertical, height - thickness, max.y, offset.y);
+        sideways = along(horizontal, width - thickness, max.x, offset.x);
+    }
+    let paint = |window: &mut gpui::Window, x: f32, y: f32, w: f32, h: f32| {
+        // Whole pixels, so a thumb is as crisp as a browser's.
+        let rect = gpui::Bounds::new(
+            gpui::point(
+                origin.x + gpui::px(x.round()),
+                origin.y + gpui::px(y.round()),
+            ),
+            gpui::size(gpui::px(w.round()), gpui::px(h.round())),
+        );
+        window.paint_quad(gpui::quad(
+            rect,
+            gpui::px(thickness / 2.0),
+            color,
+            gpui::px(0.0),
+            gpui::transparent_black(),
+            gpui::BorderStyle::default(),
+        ));
+    };
+    if let Some((start, length)) = across {
+        paint(window, width - thickness, start, thickness, length);
+    }
+    if let Some((start, length)) = sideways {
+        paint(window, start, height - thickness, length, thickness);
+    }
+}
+
 /// The thumbs of a scroll container, painted from its own scroll offset in the
 /// frame the content moves in, so a wheel tick costs nothing beyond that frame.
 ///
 /// It is the container's last child, absolutely placed over its padding box.
 /// Children of a scroller are painted shifted by the scroll offset, so the
 /// viewport is this box moved back by it. It has no hitbox and takes no input.
-fn scrollbar_overlay(
-    handle: gpui::ScrollHandle,
-    color: gpui::Hsla,
-    thickness: f32,
-    horizontal: bool,
-    vertical: bool,
-) -> gpui::AnyElement {
+fn scrollbar_overlay(handle: gpui::ScrollHandle, thumbs: ThumbStyle) -> gpui::AnyElement {
     use gpui::prelude::*;
 
     gpui::canvas(
         |_, _, _| (),
         move |bounds, _, window, _| {
             let offset = handle.offset();
-            let max = handle.max_offset();
-            let origin = bounds.origin - offset;
-            let (width, height) = (
-                f32::from(bounds.size.width),
-                f32::from(bounds.size.height),
+            paint_scrollbars(
+                window,
+                bounds.origin - offset,
+                bounds.size,
+                handle.max_offset(),
+                offset,
+                thumbs,
             );
-            let along = |show: bool, track: f32, max_scroll: gpui::Pixels, offset: gpui::Pixels| {
-                show.then(|| scrollbar_thumb(track, f32::from(max_scroll), f32::from(offset)))
-                    .flatten()
-            };
-            let mut across = along(vertical, height, max.y, offset.y);
-            let mut sideways = along(horizontal, width, max.x, offset.x);
-            if across.is_some() && sideways.is_some() {
-                // Leave the corner to whichever thumb reaches it first.
-                across = along(vertical, height - thickness, max.y, offset.y);
-                sideways = along(horizontal, width - thickness, max.x, offset.x);
-            }
-            let paint = |window: &mut gpui::Window, x: f32, y: f32, w: f32, h: f32| {
-                // Whole pixels, so a thumb is as crisp as a browser's.
-                let rect = gpui::Bounds::new(
-                    gpui::point(origin.x + gpui::px(x.round()), origin.y + gpui::px(y.round())),
-                    gpui::size(gpui::px(w.round()), gpui::px(h.round())),
-                );
-                window.paint_quad(gpui::quad(
-                    rect,
-                    gpui::px(thickness / 2.0),
-                    color,
-                    gpui::px(0.0),
-                    gpui::transparent_black(),
-                    gpui::BorderStyle::default(),
-                ));
-            };
-            if let Some((start, length)) = across {
-                paint(window, width - thickness, start, thickness, length);
-            }
-            if let Some((start, length)) = sideways {
-                paint(window, start, height - thickness, length, thickness);
-            }
         },
     )
     .absolute()
@@ -5855,6 +5906,83 @@ fn scrollbar_overlay(
     .into_any_element()
 }
 
+/// A virtual list with its thumb painted over it.
+///
+/// A list element takes no children, and wrapping it in a box would change the
+/// layout its style asks for. This lays out, prepaints and paints as the list
+/// does (it answers with the list's own layout node), then draws the thumb in
+/// the list's bounds from what its `ListState` has measured: the same totals
+/// the list scrolls by, so the thumb and the scroll position cannot disagree.
+struct ListWithScrollbar {
+    list: gpui::AnyElement,
+    state: gpui::ListState,
+    thumbs: ThumbStyle,
+}
+
+impl gpui::IntoElement for ListWithScrollbar {
+    type Element = Self;
+
+    fn into_element(self) -> Self {
+        self
+    }
+}
+
+impl gpui::Element for ListWithScrollbar {
+    type RequestLayoutState = ();
+    type PrepaintState = ();
+
+    fn id(&self) -> Option<gpui::ElementId> {
+        None
+    }
+
+    fn source_location(&self) -> Option<&'static std::panic::Location<'static>> {
+        None
+    }
+
+    fn request_layout(
+        &mut self,
+        _: Option<&gpui::GlobalElementId>,
+        _: Option<&gpui::InspectorElementId>,
+        window: &mut gpui::Window,
+        cx: &mut gpui::App,
+    ) -> (gpui::LayoutId, ()) {
+        (self.list.request_layout(window, cx), ())
+    }
+
+    fn prepaint(
+        &mut self,
+        _: Option<&gpui::GlobalElementId>,
+        _: Option<&gpui::InspectorElementId>,
+        _: gpui::Bounds<gpui::Pixels>,
+        _: &mut (),
+        window: &mut gpui::Window,
+        cx: &mut gpui::App,
+    ) {
+        self.list.prepaint(window, cx);
+    }
+
+    fn paint(
+        &mut self,
+        _: Option<&gpui::GlobalElementId>,
+        _: Option<&gpui::InspectorElementId>,
+        bounds: gpui::Bounds<gpui::Pixels>,
+        _: &mut (),
+        _: &mut (),
+        window: &mut gpui::Window,
+        cx: &mut gpui::App,
+    ) {
+        self.list.paint(window, cx);
+        paint_scrollbars(
+            window,
+            bounds.origin,
+            bounds.size,
+            self.state.max_offset_for_scrollbar(),
+            self.state.scroll_px_offset_for_scrollbar(),
+            self.thumbs,
+        );
+    }
+}
+
 #[cfg(test)]
 mod scrollbar_tests {
     use super::scrollbar_thumb;
diff --git a/packages/react/src/__tests__/scrollbar.test.tsx b/packages/react/src/__tests__/scrollbar.test.tsx
index f570f8250..f1ed8d0db 100644
--- a/packages/react/src/__tests__/scrollbar.test.tsx
+++ b/packages/react/src/__tests__/scrollbar.test.tsx
@@ -119,3 +119,68 @@ describeNative("scrollbarColor", () => {
     expect(rows.length).toBe(20)
   })
 })
+
+describeNative("scrollbarColor on a <virtual-list>", () => {
+  /** 30 rows of 40px in a 160px list: 1200px of content. */
+  function shootList(scrollToRow?: number, scrollbarColor: string | null = THUMB) {
+    const { render, renderer, unmount } = createTestRoot()
+    try {
+      render(
+        <virtual-list
+          testId="list"
+          overdraw={0}
+          estimatedItemHeight={40}
+          style={{
+            width: 100,
+            height: 160,
+            backgroundColor: "#202020",
+            scrollbarColor: scrollbarColor ?? undefined,
+          }}
+        >
+          {Array.from({ length: 30 }, (_, index) => (
+            <div key={index} style={{ height: 40, flexShrink: 0 }} />
+          ))}
+        </virtual-list>
+      )
+      renderer.dispatchNativeEvents()
+      if (scrollToRow !== undefined) {
+        renderer.scrollToItem(renderer.findByTestId("list")!.id, scrollToRow)
+        renderer.flush()
+      }
+      const file = path.join(
+        SHOTS_DIR,
+        `scrollbar-list-${scrollToRow ?? "top"}-${scrollbarColor ? "on" : "off"}.png`
+      )
+      renderer.captureScreenshot(file)
+      const pixels = readPixels(file)
+      const rows: number[] = []
+      for (let y = 0; y < 160; y++) {
+        const [r, g, b] = pixels.at(97, y)
+        if (r > 200 && g < 60 && b < 60) rows.push(y)
+      }
+      return rows
+    } finally {
+      unmount()
+    }
+  }
+
+  it("paints a thumb at the top of a list that rests there", () => {
+    // 160px of 1200px is 21px of the track.
+    const rows = shootList()
+    expect(rows[0]).toBe(0)
+    expect(rows.length).toBeGreaterThanOrEqual(20)
+    expect(rows.length).toBeLessThanOrEqual(22)
+  })
+
+  it("moves the thumb down as the list scrolls", () => {
+    // 600px of the 1040px it can move: past the middle of the track.
+    const rows = shootList(15)
+    expect(rows[0]).toBeGreaterThan(70)
+    expect(rows[0]).toBeLessThan(90)
+    expect(shootList(29)[0]).toBeGreaterThan(rows[0]!)
+  })
+
+  it("paints nothing without a colour", () => {
+    expect(shootList(undefined, null)).toEqual([])
+  })
+})

From 8a751703bad2bab7111d731ce702b8c9fe263a17 Mon Sep 17 00:00:00 2001
From: Ruben Nogueira <40404708+rubnogueira@users.noreply.github.com>
Date: Sat, 10 Oct 2026 20:43:10 +0100
Subject: [PATCH 21/27] feat(native): a box around a virtual list draws the
 list's thumb at its edge

---
 .../box-around-virtual-list-scrollbar.md      |  5 ++
 README.md                                     |  4 +-
 packages/native/src/renderer.rs               | 53 ++++++++++++++++---
 .../react/src/__tests__/scrollbar.test.tsx    | 44 +++++++++++++++
 4 files changed, 98 insertions(+), 8 deletions(-)
 create mode 100644 .changeset/box-around-virtual-list-scrollbar.md

diff --git a/.changeset/box-around-virtual-list-scrollbar.md b/.changeset/box-around-virtual-list-scrollbar.md
new file mode 100644
index 000000000..6e93b6f8e
--- /dev/null
+++ b/.changeset/box-around-virtual-list-scrollbar.md
@@ -0,0 +1,5 @@
+---
+'@gpuix/native': patch
+---
+
+A box with a `scrollbarColor` and a `<virtual-list>` as a direct child draws the list's thumb at the box's own edge, past the box's padding, where a browser puts the scrollbar of a padded scroller. The list itself still draws its own thumb when it is the one that has the colour.
diff --git a/README.md b/README.md
index 59c7a4313..f04739a37 100644
--- a/README.md
+++ b/README.md
@@ -1765,7 +1765,9 @@ control: it takes no pointer input, so it cannot be dragged. It applies to
 `overflow: 'scroll'` containers and to `<virtual-list>`. A list's thumb comes
 from the heights the list has measured (and `estimatedItemHeight` for rows it has
 not reached), the same totals it scrolls by, so it only runs along the right edge
-and its length settles as rows are measured.
+and its length settles as rows are measured. To draw it at the edge of a padded
+box instead (where a browser puts a scroller's scrollbar), give `scrollbarColor`
+to the box that has the `<virtual-list>` as a direct child.
 
 ### Give memory back when idle
 
diff --git a/packages/native/src/renderer.rs b/packages/native/src/renderer.rs
index 164892fed..73c852e0b 100644
--- a/packages/native/src/renderer.rs
+++ b/packages/native/src/renderer.rs
@@ -5765,13 +5765,26 @@ pub(crate) fn build_host_container(
     }
 
     // Last, so the thumb paints over the content.
-    if let (Some(style), Some(handle)) = (style, ctx.scroll_handles.get(&element.id)) {
-        if let Some(thumbs) = ThumbStyle::of(
-            style,
-            style.overflow_x.as_deref().or(style.overflow.as_deref()) == Some("scroll"),
-            style.overflow_y.as_deref().or(style.overflow.as_deref()) == Some("scroll"),
-        ) {
-            el = el.child(scrollbar_overlay(handle.clone(), thumbs));
+    if let Some(style) = style {
+        if let Some(handle) = ctx.scroll_handles.get(&element.id) {
+            if let Some(thumbs) = ThumbStyle::of(
+                style,
+                style.overflow_x.as_deref().or(style.overflow.as_deref()) == Some("scroll"),
+                style.overflow_y.as_deref().or(style.overflow.as_deref()) == Some("scroll"),
+            ) {
+                el = el.child(scrollbar_overlay(handle.clone(), thumbs));
+            }
+        } else if let Some(thumbs) = ThumbStyle::of(style, false, true) {
+            // A box around a virtual list draws the list's thumb at the box's own
+            // edge, past any padding, as a scroller's scrollbar sits in the DOM.
+            let list = element.children.iter().find_map(|child| {
+                ctx.virtual_lists
+                    .get(child)
+                    .map(|entry| entry.state.clone())
+            });
+            if let Some(list) = list {
+                el = el.child(list_scrollbar_overlay(list, thumbs));
+            }
         }
     }
 
@@ -5906,6 +5919,32 @@ fn scrollbar_overlay(handle: gpui::ScrollHandle, thumbs: ThumbStyle) -> gpui::An
     .into_any_element()
 }
 
+/// The thumb of the virtual list inside a container, painted over the
+/// container's padding box. See `scrollbar_overlay`; a list is not shifted by
+/// its scroll offset, so the viewport is the box itself.
+fn list_scrollbar_overlay(state: gpui::ListState, thumbs: ThumbStyle) -> gpui::AnyElement {
+    use gpui::prelude::*;
+
+    gpui::canvas(
+        |_, _, _| (),
+        move |bounds, _, window, _| {
+            paint_scrollbars(
+                window,
+                bounds.origin,
+                bounds.size,
+                state.max_offset_for_scrollbar(),
+                state.scroll_px_offset_for_scrollbar(),
+                thumbs,
+            );
+        },
+    )
+    .absolute()
+    .top_0()
+    .left_0()
+    .size_full()
+    .into_any_element()
+}
+
 /// A virtual list with its thumb painted over it.
 ///
 /// A list element takes no children, and wrapping it in a box would change the
diff --git a/packages/react/src/__tests__/scrollbar.test.tsx b/packages/react/src/__tests__/scrollbar.test.tsx
index f1ed8d0db..cf914bb60 100644
--- a/packages/react/src/__tests__/scrollbar.test.tsx
+++ b/packages/react/src/__tests__/scrollbar.test.tsx
@@ -184,3 +184,47 @@ describeNative("scrollbarColor on a <virtual-list>", () => {
     expect(shootList(undefined, null)).toEqual([])
   })
 })
+
+describeNative("scrollbarColor on a box around a <virtual-list>", () => {
+  it("draws the thumb at the box's own edge, past its padding", () => {
+    const { render, renderer, unmount } = createTestRoot()
+    try {
+      render(
+        <div
+          style={{
+            display: "flex",
+            flexDirection: "column",
+            width: 100,
+            height: 160,
+            paddingRight: 20,
+            backgroundColor: "#202020",
+            scrollbarColor: THUMB,
+          }}
+        >
+          <virtual-list overdraw={0} estimatedItemHeight={40} style={{ flexGrow: 1, minHeight: 0 }}>
+            {Array.from({ length: 30 }, (_, index) => (
+              <div key={index} style={{ height: 40, flexShrink: 0 }} />
+            ))}
+          </virtual-list>
+        </div>
+      )
+      renderer.dispatchNativeEvents()
+      const file = path.join(SHOTS_DIR, "scrollbar-list-box.png")
+      renderer.captureScreenshot(file)
+      const pixels = readPixels(file)
+      const thumbAt = (x: number) => {
+        for (let y = 0; y < 160; y++) {
+          const [r, g, b] = pixels.at(x, y)
+          if (r > 200 && g < 60 && b < 60) return true
+        }
+        return false
+      }
+      expect(thumbAt(97), "6px at the box's right edge, x 94 to 99").toBe(true)
+      expect(thumbAt(93)).toBe(false)
+      expect(thumbAt(77), "not at the list's edge, 20px in").toBe(false)
+    } finally {
+      unmount()
+    }
+  })
+})
+

From 90c6ad094c26ab19e3cf8c2deff9feb8130532b1 Mon Sep 17 00:00:00 2001
From: Ruben Nogueira <40404708+rubnogueira@users.noreply.github.com>
Date: Sat, 10 Oct 2026 20:57:02 +0100
Subject: [PATCH 22/27] feat(native): a list's thumb sizes unmeasured rows from
 the measured ones

---
 .../virtual-list-thumb-averages-rows.md       |  5 ++
 packages/native/src/renderer.rs               | 50 ++++++++++++-------
 .../react/src/__tests__/scrollbar.test.tsx    | 39 +++++++++++++++
 zed                                           |  2 +-
 4 files changed, 77 insertions(+), 19 deletions(-)
 create mode 100644 .changeset/virtual-list-thumb-averages-rows.md

diff --git a/.changeset/virtual-list-thumb-averages-rows.md b/.changeset/virtual-list-thumb-averages-rows.md
new file mode 100644
index 000000000..14e77027b
--- /dev/null
+++ b/.changeset/virtual-list-thumb-averages-rows.md
@@ -0,0 +1,5 @@
+---
+'@gpuix/native': patch
+---
+
+The thumb of a `<virtual-list>` counts the rows the list has not measured yet as the average measured row, not as `estimatedItemHeight`. A thread of tall rows with a short estimate no longer draws a thumb several times too long that shrinks as rows scroll into view; the thumb is right once a few rows have been measured.
diff --git a/packages/native/src/renderer.rs b/packages/native/src/renderer.rs
index 73c852e0b..14599aa14 100644
--- a/packages/native/src/renderer.rs
+++ b/packages/native/src/renderer.rs
@@ -5919,6 +5919,25 @@ fn scrollbar_overlay(handle: gpui::ScrollHandle, thumbs: ThumbStyle) -> gpui::An
     .into_any_element()
 }
 
+/// How far a virtual list can scroll and has, for `paint_scrollbars`. Rows the
+/// list has not measured count as the average measured row, not as the single
+/// `estimatedItemHeight`, which a thread of tall rows would otherwise miss by
+/// a few times. Before any row is measured the list's own totals stand.
+fn list_scroll_extent(
+    state: &gpui::ListState,
+) -> (gpui::Point<gpui::Pixels>, gpui::Point<gpui::Pixels>) {
+    match state.averaged_scroll_extent() {
+        Some((max, offset)) => (
+            gpui::point(gpui::px(0.0), max),
+            gpui::point(gpui::px(0.0), -offset),
+        ),
+        None => (
+            state.max_offset_for_scrollbar(),
+            state.scroll_px_offset_for_scrollbar(),
+        ),
+    }
+}
+
 /// The thumb of the virtual list inside a container, painted over the
 /// container's padding box. See `scrollbar_overlay`; a list is not shifted by
 /// its scroll offset, so the viewport is the box itself.
@@ -5928,14 +5947,8 @@ fn list_scrollbar_overlay(state: gpui::ListState, thumbs: ThumbStyle) -> gpui::A
     gpui::canvas(
         |_, _, _| (),
         move |bounds, _, window, _| {
-            paint_scrollbars(
-                window,
-                bounds.origin,
-                bounds.size,
-                state.max_offset_for_scrollbar(),
-                state.scroll_px_offset_for_scrollbar(),
-                thumbs,
-            );
+            let (max, offset) = list_scroll_extent(&state);
+            paint_scrollbars(window, bounds.origin, bounds.size, max, offset, thumbs);
         },
     )
     .absolute()
@@ -6011,14 +6024,8 @@ impl gpui::Element for ListWithScrollbar {
         cx: &mut gpui::App,
     ) {
         self.list.paint(window, cx);
-        paint_scrollbars(
-            window,
-            bounds.origin,
-            bounds.size,
-            self.state.max_offset_for_scrollbar(),
-            self.state.scroll_px_offset_for_scrollbar(),
-            self.thumbs,
-        );
+        let (max, offset) = list_scroll_extent(&self.state);
+        paint_scrollbars(window, bounds.origin, bounds.size, max, offset, self.thumbs);
     }
 }
 
@@ -6039,7 +6046,10 @@ mod scrollbar_tests {
         let (_, length) = scrollbar_thumb(100.0, 200.0, 0.0).unwrap();
         let (start, same_length) = scrollbar_thumb(100.0, 200.0, -200.0).unwrap();
         assert_eq!(length, same_length);
-        assert!((start + length - 100.0).abs() < 0.01, "ends at the end of the track");
+        assert!(
+            (start + length - 100.0).abs() < 0.01,
+            "ends at the end of the track"
+        );
         let (halfway, _) = scrollbar_thumb(100.0, 200.0, -100.0).unwrap();
         assert!((halfway - (100.0 - length) / 2.0).abs() < 0.01);
     }
@@ -6060,7 +6070,11 @@ mod scrollbar_tests {
     #[test]
     fn content_that_fits_has_no_thumb() {
         assert_eq!(scrollbar_thumb(100.0, 0.0, 0.0), None);
-        assert_eq!(scrollbar_thumb(100.0, 0.5, 0.0), None, "a fraction of a pixel is rounding");
+        assert_eq!(
+            scrollbar_thumb(100.0, 0.5, 0.0),
+            None,
+            "a fraction of a pixel is rounding"
+        );
         assert_eq!(scrollbar_thumb(0.0, 200.0, 0.0), None);
     }
 }
diff --git a/packages/react/src/__tests__/scrollbar.test.tsx b/packages/react/src/__tests__/scrollbar.test.tsx
index cf914bb60..d5bc91a2c 100644
--- a/packages/react/src/__tests__/scrollbar.test.tsx
+++ b/packages/react/src/__tests__/scrollbar.test.tsx
@@ -183,6 +183,45 @@ describeNative("scrollbarColor on a <virtual-list>", () => {
   it("paints nothing without a colour", () => {
     expect(shootList(undefined, null)).toEqual([])
   })
+
+  it("sizes the rows it has not measured from the ones it has, not from the estimate", () => {
+    const { render, renderer, unmount } = createTestRoot()
+    try {
+      // 20 rows of 200px in a 400px list is 4000px, so the thumb is 40px. With only
+      // the 40px estimate for the rows out of view it would be 143px.
+      render(
+        <virtual-list
+          testId="list"
+          overdraw={0}
+          estimatedItemHeight={40}
+          style={{
+            width: 100,
+            height: 400,
+            backgroundColor: "#202020",
+            scrollbarColor: THUMB,
+          }}
+        >
+          {Array.from({ length: 20 }, (_, index) => (
+            <div key={index} style={{ height: 200, flexShrink: 0 }} />
+          ))}
+        </virtual-list>
+      )
+      renderer.dispatchNativeEvents()
+      const file = path.join(SHOTS_DIR, "scrollbar-list-tall-rows.png")
+      renderer.captureScreenshot(file)
+      const pixels = readPixels(file)
+      const rows: number[] = []
+      for (let y = 0; y < 400; y++) {
+        const [r, g, b] = pixels.at(97, y)
+        if (r > 200 && g < 60 && b < 60) rows.push(y)
+      }
+      expect(rows[0]).toBe(0)
+      expect(rows.length).toBeGreaterThanOrEqual(38)
+      expect(rows.length).toBeLessThanOrEqual(42)
+    } finally {
+      unmount()
+    }
+  })
 })
 
 describeNative("scrollbarColor on a box around a <virtual-list>", () => {
diff --git a/zed b/zed
index 74a3f0ff8..d49a77ff7 160000
--- a/zed
+++ b/zed
@@ -1 +1 @@
-Subproject commit 74a3f0ff867ef2b1f875d0317a192209baf79fb2
+Subproject commit d49a77ff76aba63ac412c0c72ccd05c090e0a9c0

From 239f16d199e15c0afd7c381bb266d4da6961b2fe Mon Sep 17 00:00:00 2001
From: Ruben Nogueira <40404708+rubnogueira@users.noreply.github.com>
Date: Sat, 10 Oct 2026 21:22:27 +0100
Subject: [PATCH 23/27] perf(react): root.render() keeps one context value so
 useGpuix consumers stop re-rendering

Each render() call wrapped the tree in a Provider whose value was a new
{ renderer } object, so every call was a context change. In the chat example
that re-rendered ChatApp, whose inline onRetry closure then busted the memo on
Transcript: 305 SafeMdxContent renders and about 9 ms per find-bar keystroke.

The example also keeps onRetry stable now, so typing in the composer no longer
re-renders every row.
---
 .changeset/root-context-stable-value.md       |  5 ++
 examples/chat.tsx                             | 52 +++++++++++--------
 .../react/src/__tests__/root-context.test.tsx | 31 +++++++++++
 packages/react/src/reconciler/reconciler.ts   |  9 +++-
 4 files changed, 73 insertions(+), 24 deletions(-)
 create mode 100644 .changeset/root-context-stable-value.md
 create mode 100644 packages/react/src/__tests__/root-context.test.tsx

diff --git a/.changeset/root-context-stable-value.md b/.changeset/root-context-stable-value.md
new file mode 100644
index 000000000..378387f2b
--- /dev/null
+++ b/.changeset/root-context-stable-value.md
@@ -0,0 +1,5 @@
+---
+'@gpuix/react': patch
+---
+
+`root.render()` no longer re-renders every `useGpuix()` consumer. The root's context value was a new object on each call, so calling `render()` again (a hot reload, a test, an app that renders the root with new props) counted as a context change and re-rendered each consumer and, through its new callbacks, every `memo` row below it. In the chat example this was 305 row renders and about 9 ms per keystroke of a find bar; it is now 0.2 ms.
diff --git a/examples/chat.tsx b/examples/chat.tsx
index 771f51c6c..f6e96e017 100644
--- a/examples/chat.tsx
+++ b/examples/chat.tsx
@@ -10,7 +10,7 @@
  * Slow CPU: THROTTLE=utility bun --hot chat.tsx
  */
 
-import React, { memo, useEffect, useMemo, useRef, useState } from 'react'
+import React, { memo, useCallback, useEffect, useMemo, useRef, useState } from 'react'
 import {
   applyMacCpuThrottleFromEnv,
   Button,
@@ -2222,6 +2222,34 @@ export function ChatApp({
     setFocusTick((value) => value + 1)
   }
 
+  const retryLastReply = () => {
+    let cut = -1
+    for (let i = turns.length - 1; i >= 0; i--) {
+      if (turns[i]?.kind === 'user') {
+        cut = i
+        break
+      }
+    }
+    const lastUser = cut >= 0 ? turns[cut] : undefined
+    if (!lastUser || lastUser.kind !== 'user') return
+    const modelLabel = MODELS.find((item) => item.id === model)?.label ?? model
+    const reply = demoReply({ text: lastUser.text, modelLabel, mode })
+    setConversations((current) =>
+      current.map((conversation) =>
+        conversation.id === activeId
+          ? { ...conversation, turns: [...conversation.turns.slice(0, cut + 1), ...reply] }
+          : conversation,
+      ),
+    )
+    setTailTick((value) => value + 1)
+  }
+  // `Transcript` is memo: a fresh closure per render would re-render every row
+  // on each keystroke in the composer. The ref keeps the callback identity
+  // stable while it always runs the latest closure.
+  const retryRef = useRef(retryLastReply)
+  retryRef.current = retryLastReply
+  const onRetry = useCallback(() => retryRef.current(), [])
+
   useEffect(() => {
     if (tailTick === 0) return
     const id = listRef.current?.id
@@ -2314,27 +2342,7 @@ export function ChatApp({
           turns={turns}
           includeSafeMdx={showSafeMdx}
           listRef={listRef}
-          onRetry={() => {
-            let cut = -1
-            for (let i = turns.length - 1; i >= 0; i--) {
-              if (turns[i]?.kind === 'user') {
-                cut = i
-                break
-              }
-            }
-            const lastUser = cut >= 0 ? turns[cut] : undefined
-            if (!lastUser || lastUser.kind !== 'user') return
-            const modelLabel = MODELS.find((item) => item.id === model)?.label ?? model
-            const reply = demoReply({ text: lastUser.text, modelLabel, mode })
-            setConversations((current) =>
-              current.map((conversation) =>
-                conversation.id === activeId
-                  ? { ...conversation, turns: [...conversation.turns.slice(0, cut + 1), ...reply] }
-                  : conversation,
-              ),
-            )
-            setTailTick((value) => value + 1)
-          }}
+          onRetry={onRetry}
         />
         <Composer
           value={draft}
diff --git a/packages/react/src/__tests__/root-context.test.tsx b/packages/react/src/__tests__/root-context.test.tsx
new file mode 100644
index 000000000..3a46d84d2
--- /dev/null
+++ b/packages/react/src/__tests__/root-context.test.tsx
@@ -0,0 +1,31 @@
+import { describe, expect, it } from "vitest"
+import { useGpuix } from "../hooks/use-gpuix.js"
+import { createTestRoot, hasNativeTestRenderer } from "../testing.js"
+
+const describeNative = hasNativeTestRenderer ? describe : describe.skip
+
+describeNative("root context", () => {
+  // An app shell reads the renderer and passes `memo` rows a fresh callback
+  // whenever it re-renders. If every `root.render()` counted as a context
+  // change, one keystroke in the shell would re-render the whole transcript.
+  it("does not re-render useGpuix consumers when the root renders again", () => {
+    const { render, unmount } = createTestRoot()
+    try {
+      let renders = 0
+      function Shell() {
+        useGpuix()
+        renders++
+        return <div />
+      }
+      const shell = <Shell />
+
+      render(shell)
+      render(shell)
+      render(shell)
+
+      expect(renders).toBe(1)
+    } finally {
+      unmount()
+    }
+  })
+})
diff --git a/packages/react/src/reconciler/reconciler.ts b/packages/react/src/reconciler/reconciler.ts
index b9ff23050..0b22148e0 100644
--- a/packages/react/src/reconciler/reconciler.ts
+++ b/packages/react/src/reconciler/reconciler.ts
@@ -4,7 +4,7 @@ import ReactReconciler from "react-reconciler"
 import type { OpaqueRoot } from "react-reconciler"
 import { ConcurrentRoot } from "react-reconciler/constants.js"
 import { createMutationQueue } from "@gpuix/native/host"
-import { GpuixContext } from "../hooks/use-gpuix.js"
+import { GpuixContext, type GpuixContextValue } from "../hooks/use-gpuix.js"
 import type {
   Container,
   NativeRenderer,
@@ -135,6 +135,11 @@ export function createRoot(
     null
   )
 
+  // One object for the life of the root. A fresh `{ renderer }` per `render()`
+  // call is a context change, which re-renders every `useGpuix()` consumer, and
+  // through them busts `memo` below it, on every re-render of the root.
+  const contextValue: GpuixContextValue = { renderer }
+
   return {
     render: (node): void => {
       const activeContainer = container
@@ -144,7 +149,7 @@ export function createRoot(
       reconciler.updateContainer(
         React.createElement(
           GpuixContext.Provider,
-          { value: { renderer } },
+          { value: contextValue },
           node
         ),
         activeContainer,

From eb4ef4a59221b0bf4cdb37020eb25a82849ef1f3 Mon Sep 17 00:00:00 2001
From: Ruben Nogueira <40404708+rubnogueira@users.noreply.github.com>
Date: Sun, 11 Oct 2026 11:48:01 +0100
Subject: [PATCH 24/27] docs: describe the new features without reference to
 any one app

---
 .changeset/create-portal.md                        | 2 +-
 .changeset/focusable-ids.md                        | 2 +-
 .changeset/highlight-search-needle.md              | 2 +-
 .changeset/virtual-list-thumb-averages-rows.md     | 2 +-
 README.md                                          | 2 +-
 packages/native/js/idle-gc.ts                      | 4 ++--
 packages/native/src/renderer.rs                    | 2 +-
 packages/native/src/retained_tree.rs               | 2 +-
 packages/native/src/text/search.rs                 | 2 +-
 packages/react/src/__tests__/root-context.test.tsx | 2 +-
 zed                                                | 2 +-
 11 files changed, 12 insertions(+), 12 deletions(-)

diff --git a/.changeset/create-portal.md b/.changeset/create-portal.md
index c9cc5e39e..8cc5d016f 100644
--- a/.changeset/create-portal.md
+++ b/.changeset/create-portal.md
@@ -2,4 +2,4 @@
 '@gpuix/react': minor
 ---
 
-Added `createPortal(children, target)`, which mounts children into an element that is already mounted. Take `target` from a `ref`. The portal's children are appended to the target and kept in key order, so a toast layer, a drag preview or an overlay root no longer needs a patched host config. See "Portals" in the README.
+Added `createPortal(children, target)`, which mounts children into an element that is already mounted. Take `target` from a `ref`. The portal's children are appended to the target and kept in key order, so a toast layer, a drag preview or an overlay root can live in another part of the tree than the component that renders it. See "Portals" in the README.
diff --git a/.changeset/focusable-ids.md b/.changeset/focusable-ids.md
index 2fb7b9404..a48312d08 100644
--- a/.changeset/focusable-ids.md
+++ b/.changeset/focusable-ids.md
@@ -2,4 +2,4 @@
 '@gpuix/native': patch
 ---
 
-Every frame no longer walks every element to find the ones that take focus. The tree now keeps that set up to date as props and listeners change, so an idle frame of a long chat costs about a third less CPU. Focus, tab order, `autoFocus`, and `onKeyDown`/`onFocus`/`onBlur` behave as before.
+Every frame no longer walks every element to find the ones that take focus. The tree now keeps that set up to date as props and listeners change, so an idle frame of a tree with thousands of elements costs about a third less CPU. Focus, tab order, `autoFocus`, and `onKeyDown`/`onFocus`/`onBlur` behave as before.
diff --git a/.changeset/highlight-search-needle.md b/.changeset/highlight-search-needle.md
index 71f0f68d8..02097a01e 100644
--- a/.changeset/highlight-search-needle.md
+++ b/.changeset/highlight-search-needle.md
@@ -2,4 +2,4 @@
 '@gpuix/native': patch
 ---
 
-Typing in a find-in-page query no longer rebuilds the search for every block of text. The query is lowercased and compiled once per keystroke and shared by all the text it is matched against, so each keystroke in a long chat costs a few percent less CPU. Matches are the same as before: leftmost, non-overlapping, case-insensitive by default.
+Typing in a find-in-page query no longer rebuilds the search for every block of text. The query is lowercased and compiled once per keystroke and shared by all the text it is matched against, so each keystroke over a long document costs a few percent less CPU. Matches are the same as before: leftmost, non-overlapping, case-insensitive by default.
diff --git a/.changeset/virtual-list-thumb-averages-rows.md b/.changeset/virtual-list-thumb-averages-rows.md
index 14e77027b..3cb35ba5b 100644
--- a/.changeset/virtual-list-thumb-averages-rows.md
+++ b/.changeset/virtual-list-thumb-averages-rows.md
@@ -2,4 +2,4 @@
 '@gpuix/native': patch
 ---
 
-The thumb of a `<virtual-list>` counts the rows the list has not measured yet as the average measured row, not as `estimatedItemHeight`. A thread of tall rows with a short estimate no longer draws a thumb several times too long that shrinks as rows scroll into view; the thumb is right once a few rows have been measured.
+The thumb of a `<virtual-list>` counts the rows the list has not measured yet as the average measured row, not as `estimatedItemHeight`. A list of tall rows with a short estimate no longer draws a thumb several times too long that shrinks as rows scroll into view; the thumb is right once a few rows have been measured.
diff --git a/README.md b/README.md
index f04739a37..caf5ba857 100644
--- a/README.md
+++ b/README.md
@@ -1772,7 +1772,7 @@ to the box that has the `<virtual-list>` as a direct child.
 ### Give memory back when idle
 
 A JavaScript engine collects on allocation pressure, so after a burst of work
-(the first mount, opening a long thread) the heap stays at its peak until the
+(the first mount, opening a large screen) the heap stays at its peak until the
 next burst. `collectGarbageWhenIdle()` runs one full collection once the app has
 stopped committing for a while, then waits for the next burst.
 
diff --git a/packages/native/js/idle-gc.ts b/packages/native/js/idle-gc.ts
index 68566837d..2fcde38b0 100644
--- a/packages/native/js/idle-gc.ts
+++ b/packages/native/js/idle-gc.ts
@@ -40,13 +40,13 @@ function defaultCollector(): Collector | undefined {
  * Run one full garbage collection once the app has been quiet for a while.
  *
  * A JavaScript engine collects on allocation pressure, so after a burst of work
- * (the first mount, opening a long thread) the heap and the pages behind it stay
+ * (the first mount, opening a large screen) the heap and the pages behind it stay
  * at their peak until the next burst. This waits for `activity` to hold still
  * for `quietChecks` looks and the process to be under `busyCpu`, collects once,
  * then waits for the next busy period.
  *
  * CPU alone cannot stand for "quiet": a focused text field blinks its caret in
- * native code and redraws the window twice a second, which on a long thread
+ * native code and redraws the window twice a second, which on a large screen
  * exceeds any threshold that would still tell a busy period apart. Commits do
  * not move for that, so they decide, and CPU only covers work that commits
  * nothing.
diff --git a/packages/native/src/renderer.rs b/packages/native/src/renderer.rs
index 14599aa14..17dde1a4c 100644
--- a/packages/native/src/renderer.rs
+++ b/packages/native/src/renderer.rs
@@ -5921,7 +5921,7 @@ fn scrollbar_overlay(handle: gpui::ScrollHandle, thumbs: ThumbStyle) -> gpui::An
 
 /// How far a virtual list can scroll and has, for `paint_scrollbars`. Rows the
 /// list has not measured count as the average measured row, not as the single
-/// `estimatedItemHeight`, which a thread of tall rows would otherwise miss by
+/// `estimatedItemHeight`, which a list of tall rows would otherwise miss by
 /// a few times. Before any row is measured the list's own totals stand.
 fn list_scroll_extent(
     state: &gpui::ListState,
diff --git a/packages/native/src/retained_tree.rs b/packages/native/src/retained_tree.rs
index 5a2ef8c14..cfd707033 100644
--- a/packages/native/src/retained_tree.rs
+++ b/packages/native/src/retained_tree.rs
@@ -215,7 +215,7 @@ pub struct RetainedTree {
     pub motion_ids: HashSet<u64>,
     /// Elements that `needs_focus`, in id order. Kept as mutations arrive so the
     /// per-frame focus sync visits these few instead of every retained element:
-    /// a long chat retains thousands, and nearly none are focusable.
+    /// a large tree retains thousands, and nearly none are focusable.
     pub focusable_ids: std::collections::BTreeSet<u64>,
     /// How many `anchored` elements exist. Without any, an `elements_at` walk
     /// can drop a clipped subtree whole.
diff --git a/packages/native/src/text/search.rs b/packages/native/src/text/search.rs
index ebffd7f07..ee52a95b5 100644
--- a/packages/native/src/text/search.rs
+++ b/packages/native/src/text/search.rs
@@ -173,7 +173,7 @@ impl HighlightSpec {
 /// A query ready to search with: lowercased unless the match is case
 /// sensitive, behind a `memmem` searcher that is built once. The standard
 /// library builds a fresh searcher for every `match_indices` call, and a
-/// keystroke makes one call per text group, which on a long thread cost more
+/// keystroke makes one call per text group, which on a long document cost more
 /// than scanning the text.
 #[derive(Clone)]
 pub struct Needle {
diff --git a/packages/react/src/__tests__/root-context.test.tsx b/packages/react/src/__tests__/root-context.test.tsx
index 3a46d84d2..38417291e 100644
--- a/packages/react/src/__tests__/root-context.test.tsx
+++ b/packages/react/src/__tests__/root-context.test.tsx
@@ -7,7 +7,7 @@ const describeNative = hasNativeTestRenderer ? describe : describe.skip
 describeNative("root context", () => {
   // An app shell reads the renderer and passes `memo` rows a fresh callback
   // whenever it re-renders. If every `root.render()` counted as a context
-  // change, one keystroke in the shell would re-render the whole transcript.
+  // change, one keystroke in the shell would re-render every row below it.
   it("does not re-render useGpuix consumers when the root renders again", () => {
     const { render, unmount } = createTestRoot()
     try {
diff --git a/zed b/zed
index d49a77ff7..a27410937 160000
--- a/zed
+++ b/zed
@@ -1 +1 @@
-Subproject commit d49a77ff76aba63ac412c0c72ccd05c090e0a9c0
+Subproject commit a27410937e4df20ba02f8a241567d159550de396

From f15c044af6676f95dde389c3f4efaf25797b0565 Mon Sep 17 00:00:00 2001
From: Ruben Nogueira <40404708+rubnogueira@users.noreply.github.com>
Date: Sun, 11 Oct 2026 11:48:02 +0100
Subject: [PATCH 25/27] test(react): read scrollbar pixels in logical units so
 they pass on a 2x display

---
 .../react/src/__tests__/scrollbar.test.tsx     | 14 +++++++-------
 packages/react/src/__tests__/test-utils.ts     | 18 ++++++++++++++++++
 2 files changed, 25 insertions(+), 7 deletions(-)

diff --git a/packages/react/src/__tests__/scrollbar.test.tsx b/packages/react/src/__tests__/scrollbar.test.tsx
index d5bc91a2c..f6aa5ee92 100644
--- a/packages/react/src/__tests__/scrollbar.test.tsx
+++ b/packages/react/src/__tests__/scrollbar.test.tsx
@@ -1,14 +1,14 @@
 import path from "path"
 import { describe, expect, it } from "vitest"
 import { createTestRoot, hasNativeTestRenderer } from "../testing.js"
-import { readPixels, SHOTS_DIR } from "./test-utils.js"
+import { readLogicalPixels, SHOTS_DIR } from "./test-utils.js"
 
 const describeNative = hasNativeTestRenderer ? describe : describe.skip
 
 const THUMB = "#ff0000"
 
 /** Rows (within the scroller's 100px) holding thumb-coloured pixels in a column. */
-function thumbRows(pixels: ReturnType<typeof readPixels>, x: number, top = 0) {
+function thumbRows(pixels: ReturnType<typeof readLogicalPixels>, x: number, top = 0) {
   const rows: number[] = []
   for (let y = 0; y < 100; y++) {
     const [r, g, b] = pixels.at(x, top + y)
@@ -45,7 +45,7 @@ function shoot(
     }
     const file = path.join(SHOTS_DIR, `scrollbar-${contentHeight}-${scrollTo ?? "top"}.png`)
     renderer.captureScreenshot(file)
-    return readPixels(file)
+    return readLogicalPixels(file)
   } finally {
     unmount()
   }
@@ -95,7 +95,7 @@ describeNative("scrollbarColor", () => {
       renderer.dispatchNativeEvents()
       const file = path.join(SHOTS_DIR, "scrollbar-both.png")
       renderer.captureScreenshot(file)
-      const pixels = readPixels(file)
+      const pixels = readLogicalPixels(file)
       const isThumb = (x: number, y: number) => {
         const [r, g, b] = pixels.at(x, y)
         return r > 200 && g < 60 && b < 60
@@ -152,7 +152,7 @@ describeNative("scrollbarColor on a <virtual-list>", () => {
         `scrollbar-list-${scrollToRow ?? "top"}-${scrollbarColor ? "on" : "off"}.png`
       )
       renderer.captureScreenshot(file)
-      const pixels = readPixels(file)
+      const pixels = readLogicalPixels(file)
       const rows: number[] = []
       for (let y = 0; y < 160; y++) {
         const [r, g, b] = pixels.at(97, y)
@@ -209,7 +209,7 @@ describeNative("scrollbarColor on a <virtual-list>", () => {
       renderer.dispatchNativeEvents()
       const file = path.join(SHOTS_DIR, "scrollbar-list-tall-rows.png")
       renderer.captureScreenshot(file)
-      const pixels = readPixels(file)
+      const pixels = readLogicalPixels(file)
       const rows: number[] = []
       for (let y = 0; y < 400; y++) {
         const [r, g, b] = pixels.at(97, y)
@@ -250,7 +250,7 @@ describeNative("scrollbarColor on a box around a <virtual-list>", () => {
       renderer.dispatchNativeEvents()
       const file = path.join(SHOTS_DIR, "scrollbar-list-box.png")
       renderer.captureScreenshot(file)
-      const pixels = readPixels(file)
+      const pixels = readLogicalPixels(file)
       const thumbAt = (x: number) => {
         for (let y = 0; y < 160; y++) {
           const [r, g, b] = pixels.at(x, y)
diff --git a/packages/react/src/__tests__/test-utils.ts b/packages/react/src/__tests__/test-utils.ts
index 90e60a593..e374f59fe 100644
--- a/packages/react/src/__tests__/test-utils.ts
+++ b/packages/react/src/__tests__/test-utils.ts
@@ -130,3 +130,21 @@ export function readPixels(file: string): Pixels {
     },
   }
 }
+
+/** The test window's width in logical pixels (`DEFAULT_WINDOW_WIDTH` in the
+ *  native test renderer). On a 2x display the window captures twice that. */
+const TEST_WINDOW_WIDTH = 1280
+
+/** `readPixels` addressed in logical pixels, the units styles are written in,
+ *  sampling the centre of each. The same geometry reads the same on a 1x and
+ *  a 2x display. */
+export function readLogicalPixels(file: string): Pixels {
+  const pixels = readPixels(file)
+  const scale = pixels.width / TEST_WINDOW_WIDTH
+  return {
+    width: pixels.width / scale,
+    height: pixels.height / scale,
+    at: (x, y) =>
+      pixels.at(Math.floor((x + 0.5) * scale), Math.floor((y + 0.5) * scale)),
+  }
+}

From 3c991f2e958a0df7ece6350f1c51b9f388d0e793 Mon Sep 17 00:00:00 2001
From: Ruben Nogueira <40404708+rubnogueira@users.noreply.github.com>
Date: Sun, 11 Oct 2026 12:28:30 +0100
Subject: [PATCH 26/27] revert(native): drop the box-around-virtual-list thumb

A padded box around a list is better served by padding on the list itself,
with the thumb at the list's own edge. The list now takes padding on all
four sides.
---
 .../box-around-virtual-list-scrollbar.md      |  5 --
 README.md                                     |  4 +-
 packages/native/src/renderer.rs               | 47 +++----------------
 .../react/src/__tests__/scrollbar.test.tsx    | 44 -----------------
 4 files changed, 8 insertions(+), 92 deletions(-)
 delete mode 100644 .changeset/box-around-virtual-list-scrollbar.md

diff --git a/.changeset/box-around-virtual-list-scrollbar.md b/.changeset/box-around-virtual-list-scrollbar.md
deleted file mode 100644
index 6e93b6f8e..000000000
--- a/.changeset/box-around-virtual-list-scrollbar.md
+++ /dev/null
@@ -1,5 +0,0 @@
----
-'@gpuix/native': patch
----
-
-A box with a `scrollbarColor` and a `<virtual-list>` as a direct child draws the list's thumb at the box's own edge, past the box's padding, where a browser puts the scrollbar of a padded scroller. The list itself still draws its own thumb when it is the one that has the colour.
diff --git a/README.md b/README.md
index caf5ba857..c280a2c85 100644
--- a/README.md
+++ b/README.md
@@ -1765,9 +1765,7 @@ control: it takes no pointer input, so it cannot be dragged. It applies to
 `overflow: 'scroll'` containers and to `<virtual-list>`. A list's thumb comes
 from the heights the list has measured (and `estimatedItemHeight` for rows it has
 not reached), the same totals it scrolls by, so it only runs along the right edge
-and its length settles as rows are measured. To draw it at the edge of a padded
-box instead (where a browser puts a scroller's scrollbar), give `scrollbarColor`
-to the box that has the `<virtual-list>` as a direct child.
+and its length settles as rows are measured.
 
 ### Give memory back when idle
 
diff --git a/packages/native/src/renderer.rs b/packages/native/src/renderer.rs
index 17dde1a4c..b2199162d 100644
--- a/packages/native/src/renderer.rs
+++ b/packages/native/src/renderer.rs
@@ -5765,26 +5765,13 @@ pub(crate) fn build_host_container(
     }
 
     // Last, so the thumb paints over the content.
-    if let Some(style) = style {
-        if let Some(handle) = ctx.scroll_handles.get(&element.id) {
-            if let Some(thumbs) = ThumbStyle::of(
-                style,
-                style.overflow_x.as_deref().or(style.overflow.as_deref()) == Some("scroll"),
-                style.overflow_y.as_deref().or(style.overflow.as_deref()) == Some("scroll"),
-            ) {
-                el = el.child(scrollbar_overlay(handle.clone(), thumbs));
-            }
-        } else if let Some(thumbs) = ThumbStyle::of(style, false, true) {
-            // A box around a virtual list draws the list's thumb at the box's own
-            // edge, past any padding, as a scroller's scrollbar sits in the DOM.
-            let list = element.children.iter().find_map(|child| {
-                ctx.virtual_lists
-                    .get(child)
-                    .map(|entry| entry.state.clone())
-            });
-            if let Some(list) = list {
-                el = el.child(list_scrollbar_overlay(list, thumbs));
-            }
+    if let (Some(style), Some(handle)) = (style, ctx.scroll_handles.get(&element.id)) {
+        if let Some(thumbs) = ThumbStyle::of(
+            style,
+            style.overflow_x.as_deref().or(style.overflow.as_deref()) == Some("scroll"),
+            style.overflow_y.as_deref().or(style.overflow.as_deref()) == Some("scroll"),
+        ) {
+            el = el.child(scrollbar_overlay(handle.clone(), thumbs));
         }
     }
 
@@ -5938,26 +5925,6 @@ fn list_scroll_extent(
     }
 }
 
-/// The thumb of the virtual list inside a container, painted over the
-/// container's padding box. See `scrollbar_overlay`; a list is not shifted by
-/// its scroll offset, so the viewport is the box itself.
-fn list_scrollbar_overlay(state: gpui::ListState, thumbs: ThumbStyle) -> gpui::AnyElement {
-    use gpui::prelude::*;
-
-    gpui::canvas(
-        |_, _, _| (),
-        move |bounds, _, window, _| {
-            let (max, offset) = list_scroll_extent(&state);
-            paint_scrollbars(window, bounds.origin, bounds.size, max, offset, thumbs);
-        },
-    )
-    .absolute()
-    .top_0()
-    .left_0()
-    .size_full()
-    .into_any_element()
-}
-
 /// A virtual list with its thumb painted over it.
 ///
 /// A list element takes no children, and wrapping it in a box would change the
diff --git a/packages/react/src/__tests__/scrollbar.test.tsx b/packages/react/src/__tests__/scrollbar.test.tsx
index f6aa5ee92..0cbc68f05 100644
--- a/packages/react/src/__tests__/scrollbar.test.tsx
+++ b/packages/react/src/__tests__/scrollbar.test.tsx
@@ -223,47 +223,3 @@ describeNative("scrollbarColor on a <virtual-list>", () => {
     }
   })
 })
-
-describeNative("scrollbarColor on a box around a <virtual-list>", () => {
-  it("draws the thumb at the box's own edge, past its padding", () => {
-    const { render, renderer, unmount } = createTestRoot()
-    try {
-      render(
-        <div
-          style={{
-            display: "flex",
-            flexDirection: "column",
-            width: 100,
-            height: 160,
-            paddingRight: 20,
-            backgroundColor: "#202020",
-            scrollbarColor: THUMB,
-          }}
-        >
-          <virtual-list overdraw={0} estimatedItemHeight={40} style={{ flexGrow: 1, minHeight: 0 }}>
-            {Array.from({ length: 30 }, (_, index) => (
-              <div key={index} style={{ height: 40, flexShrink: 0 }} />
-            ))}
-          </virtual-list>
-        </div>
-      )
-      renderer.dispatchNativeEvents()
-      const file = path.join(SHOTS_DIR, "scrollbar-list-box.png")
-      renderer.captureScreenshot(file)
-      const pixels = readLogicalPixels(file)
-      const thumbAt = (x: number) => {
-        for (let y = 0; y < 160; y++) {
-          const [r, g, b] = pixels.at(x, y)
-          if (r > 200 && g < 60 && b < 60) return true
-        }
-        return false
-      }
-      expect(thumbAt(97), "6px at the box's right edge, x 94 to 99").toBe(true)
-      expect(thumbAt(93)).toBe(false)
-      expect(thumbAt(77), "not at the list's edge, 20px in").toBe(false)
-    } finally {
-      unmount()
-    }
-  })
-})
-

From 447ade95e452a7b707b59c278deb3380b9d0e29c Mon Sep 17 00:00:00 2001
From: Ruben Nogueira <40404708+rubnogueira@users.noreply.github.com>
Date: Sun, 11 Oct 2026 12:42:10 +0100
Subject: [PATCH 27/27] feat(native): padding on a virtual list insets its rows
 on all four sides

The list ignored left and right padding, so rows spanned its full width. Rows now sit inside all four sides, and a scrollbarColor thumb stays at the list's own edge, past the padding. Moves the zed submodule to the commit that lays rows out inside horizontal padding.
---
 .changeset/virtual-list-horizontal-padding.md |  5 ++
 README.md                                     |  4 +-
 .../react/src/__tests__/scrollbar.test.tsx    | 51 +++++++++++++++++++
 zed                                           |  2 +-
 4 files changed, 60 insertions(+), 2 deletions(-)
 create mode 100644 .changeset/virtual-list-horizontal-padding.md

diff --git a/.changeset/virtual-list-horizontal-padding.md b/.changeset/virtual-list-horizontal-padding.md
new file mode 100644
index 000000000..2b1f8a28d
--- /dev/null
+++ b/.changeset/virtual-list-horizontal-padding.md
@@ -0,0 +1,5 @@
+---
+'@gpuix/native': patch
+---
+
+`padding` on a `<virtual-list>` now insets its rows on the left and right as well as the top and bottom. Rows used to span the list's full width and ignore left and right padding. A `scrollbarColor` thumb stays at the list's own edge, past the padding.
diff --git a/README.md b/README.md
index c280a2c85..745aff7e9 100644
--- a/README.md
+++ b/README.md
@@ -1765,7 +1765,9 @@ control: it takes no pointer input, so it cannot be dragged. It applies to
 `overflow: 'scroll'` containers and to `<virtual-list>`. A list's thumb comes
 from the heights the list has measured (and `estimatedItemHeight` for rows it has
 not reached), the same totals it scrolls by, so it only runs along the right edge
-and its length settles as rows are measured.
+and its length settles as rows are measured. `padding` on a `<virtual-list>` insets
+its rows on all four sides, and the thumb stays at the list's own edge, past the
+padding, where a browser puts a padded scroller's scrollbar.
 
 ### Give memory back when idle
 
diff --git a/packages/react/src/__tests__/scrollbar.test.tsx b/packages/react/src/__tests__/scrollbar.test.tsx
index 0cbc68f05..c459a4dea 100644
--- a/packages/react/src/__tests__/scrollbar.test.tsx
+++ b/packages/react/src/__tests__/scrollbar.test.tsx
@@ -223,3 +223,54 @@ describeNative("scrollbarColor on a <virtual-list>", () => {
     }
   })
 })
+
+describeNative("padding on a <virtual-list>", () => {
+  const ROW = "#00ff00"
+
+  it("insets the rows on every side and keeps the thumb at the list's own edge", () => {
+    const { render, renderer, unmount } = createTestRoot()
+    try {
+      // 30 rows of 40px in a 160px list: the rows get 60px of the 100px.
+      render(
+        <virtual-list
+          overdraw={0}
+          estimatedItemHeight={40}
+          style={{
+            width: 100,
+            height: 160,
+            paddingTop: 20,
+            paddingLeft: 10,
+            paddingRight: 30,
+            backgroundColor: "#202020",
+            scrollbarColor: THUMB,
+          }}
+        >
+          {Array.from({ length: 30 }, (_, index) => (
+            <div key={index} style={{ height: 40, flexShrink: 0, backgroundColor: ROW }} />
+          ))}
+        </virtual-list>
+      )
+      renderer.dispatchNativeEvents()
+      const file = path.join(SHOTS_DIR, "scrollbar-list-padded.png")
+      renderer.captureScreenshot(file)
+      const pixels = readLogicalPixels(file)
+      const rows = { left: Infinity, right: -Infinity, top: Infinity }
+      let thumbX = -1
+      for (let y = 0; y < 160; y++) {
+        for (let x = 0; x < 100; x++) {
+          const [r, g, b] = pixels.at(x, y)
+          if (g > 200 && r < 60 && b < 60) {
+            rows.left = Math.min(rows.left, x)
+            rows.right = Math.max(rows.right, x)
+            rows.top = Math.min(rows.top, y)
+          }
+          if (r > 200 && g < 60 && b < 60) thumbX = Math.max(thumbX, x)
+        }
+      }
+      expect(rows).toEqual({ left: 10, right: 69, top: 20 })
+      expect(thumbX, "the thumb sits in the right padding, at the list's edge").toBe(99)
+    } finally {
+      unmount()
+    }
+  })
+})
diff --git a/zed b/zed
index a27410937..c2e9f8820 160000
--- a/zed
+++ b/zed
@@ -1 +1 @@
-Subproject commit a27410937e4df20ba02f8a241567d159550de396
+Subproject commit c2e9f882030ca95cee55d206512a0a3ee6cd72b0