nomen-lang 0.7.1 → 0.9.0

package/core/System/Controls/Window.nm

@@ -8,7 +8,7 @@
  * pointer form); the constructor's `self` is the inline instance (the `.`
  * accessor).
  **/
-pub mv struct Window : Control {
+pub mv struct Window: Control {
 	var uint64 handle = 0
 
 	pub func #init = (self, string title, int width, int height) {
@@ -160,18 +160,290 @@ pub mv struct Window : Control {
 	}
 
 	// Process pending events without blocking. Returns 1 if a left-mouse-down
-	// was among the events (i.e. a click happened), 0 otherwise. This lets a
-	// manual event loop detect clicks for re-layout without target/action.
-	// Also runs the run loop briefly to process Apple Events (e.g. dock Quit).
+	// was among the events (i.e. a click happened), 2 if a right-mouse-down
+	// was, 0 otherwise. This lets a manual event loop detect clicks (and
+	// right-clicks) for hit-testing without target/action. The click's
+	// coordinates are captured here (see click_x/click_y), and the click's
+	// button kind is stamped for the drains (nomen_last_click_kind —
+	// Container.take_right_click reads it). Also runs the run
+	// loop briefly to process Apple Events (e.g. dock Quit).
 	pub func process_events = (out int) {
 		```
 		#arch: c
 		#platform: macos
+		#scope: file
+		// The most recent mouse-down (NSLeftMouseDown = 1 or NSRightMouseDown = 3)
+		// among the events the latest process_events call pumped, in the event
+		// window's content coordinates (top-left origin). Written by the pump;
+		// read by click_x/click_y. click_x/click_y deliberately do NOT read the
+		// live currentEvent: any event after the click in the same batch (a
+		// mouse-move, drag, or key) would make the coordinates stale or missing,
+		// so hit-tests would intermittently miss.
+		static int nomen_last_click_x = -1;
+		static int nomen_last_click_y = -1;
+		// The same record's button kind (0 none / 1 left / 2 right), stamped
+		// by every pump — a quiet pump stamps 0, so the edge expires with
+		// the frame. External linkage (NOT static, unlike the coordinates):
+		// Container's take_right_click drain externs it from another TU —
+		// the focus snapshot's sharing pattern (nomen_window_focus_poll).
+		int nomen_last_click_kind = 0;
+		// The full mouse-down record for THIS pump (the exhaustive input
+		// surface — every button, not just left/right): 1-based button
+		// number (0 = no mouse-down this frame), AppKit clickCount, and the
+		// device-independent modifier flags (Command = 0x100000, Option =
+		// 0x80000, Control = 0x40000, Shift = 0x20000). Zeroed by every
+		// pump, so the edge expires with the frame. External linkage:
+		// Container.take_mouse_down externs the button from another TU.
+		int nomen_last_click_button = 0;
+		int nomen_last_click_count = 0;
+		int nomen_last_click_modifiers = 0;
+		// Scroll-wheel deltas accumulated across this pump's events
+		// (trackpads emit many small events per frame; momentum counts).
+		// Zeroed by every pump. External linkage: Scrollable.take_scroll
+		// externs them from another TU.
+		double nomen_scroll_dx_acc = 0.0;
+		double nomen_scroll_dy_acc = 0.0;
+		// The keyboard record for THIS pump: the hardware keycode of the
+		// last key-down (NSEventTypeKeyDown = 10) and key-up (type 11),
+		// -1 = none this frame; the modifiers at key-down; and whether the
+		// key-down was an auto-repeat (a held key). Zeroed by every pump.
+		// External linkage: Container.take_key_down / take_key_up extern
+		// them from another TU. Text entry does NOT flow here (the field
+		// editor feeds TextBox.on_input) — this record is for shortcuts and
+		// raw key handling.
+		int nomen_last_key_code = -1;
+		int nomen_last_key_modifiers = 0;
+		int nomen_last_key_repeat = 0;
+		int nomen_last_key_up_code = -1;
+		// The pointer-MOVE record for THIS pump (NSEventTypeMouseMoved = 5,
+		// plus the dragged variants 6/7/26 while a button is held): the last
+		// seen position, -1 = no move this frame. Zeroed by every pump.
+		// External linkage: Container.take_mouse_move externs it. Requires
+		// setAcceptsMouseMovedEvents (armed by every pump below) — without
+		// it AppKit delivers no move events at all.
+		int nomen_last_mouse_move_x = -1;
+		int nomen_last_mouse_move_y = -1;
+		// Frame time: the pump's wall-clock interval, persisted across
+		// pumps (NOT zeroed — the first frame reports 0). Read by win.dt().
+		double nomen_last_pump_time = 0.0;
+		double nomen_last_dt_ms = 0.0;
+		// The window-resize record for THIS frame, stamped by Window.run's
+		// resize detection (not by the pump). External linkage:
+		// Container.take_resize externs the edge from another TU; the size
+		// getters (resize_width/resize_height) are Window methods reading
+		// these directly.
+		int nomen_last_resized = 0;
+		int nomen_last_resize_w = 0;
+		int nomen_last_resize_h = 0;
+		```
+		```
+		#arch: aarch64_use_c
+		#platform: macos
+		#scope: file
+		// The most recent mouse-down (NSLeftMouseDown = 1 or NSRightMouseDown = 3)
+		// among the events the latest process_events call pumped, in the event
+		// window's content coordinates (top-left origin). Written by the pump;
+		// read by click_x/click_y. click_x/click_y deliberately do NOT read the
+		// live currentEvent: any event after the click in the same batch (a
+		// mouse-move, drag, or key) would make the coordinates stale or missing,
+		// so hit-tests would intermittently miss.
+		static int nomen_last_click_x = -1;
+		static int nomen_last_click_y = -1;
+		// The same record's button kind (0 none / 1 left / 2 right), stamped
+		// by every pump — a quiet pump stamps 0, so the edge expires with
+		// the frame. External linkage (NOT static, unlike the coordinates):
+		// Container's take_right_click drain externs it from another TU —
+		// the focus snapshot's sharing pattern (nomen_window_focus_poll).
+		int nomen_last_click_kind = 0;
+		// The full mouse-down record for THIS pump (the exhaustive input
+		// surface — every button, not just left/right): 1-based button
+		// number (0 = no mouse-down this frame), AppKit clickCount, and the
+		// device-independent modifier flags (Command = 0x100000, Option =
+		// 0x80000, Control = 0x40000, Shift = 0x20000). Zeroed by every
+		// pump, so the edge expires with the frame. External linkage:
+		// Container.take_mouse_down externs the button from another TU.
+		int nomen_last_click_button = 0;
+		int nomen_last_click_count = 0;
+		int nomen_last_click_modifiers = 0;
+		// Scroll-wheel deltas accumulated across this pump's events
+		// (trackpads emit many small events per frame; momentum counts).
+		// Zeroed by every pump. External linkage: Scrollable.take_scroll
+		// externs them from another TU.
+		double nomen_scroll_dx_acc = 0.0;
+		double nomen_scroll_dy_acc = 0.0;
+		// The keyboard record for THIS pump: the hardware keycode of the
+		// last key-down (NSEventTypeKeyDown = 10) and key-up (type 11),
+		// -1 = none this frame; the modifiers at key-down; and whether the
+		// key-down was an auto-repeat (a held key). Zeroed by every pump.
+		// External linkage: Container.take_key_down / take_key_up extern
+		// them from another TU. Text entry does NOT flow here (the field
+		// editor feeds TextBox.on_input) — this record is for shortcuts and
+		// raw key handling.
+		int nomen_last_key_code = -1;
+		int nomen_last_key_modifiers = 0;
+		int nomen_last_key_repeat = 0;
+		int nomen_last_key_up_code = -1;
+		// The pointer-MOVE record for THIS pump (NSEventTypeMouseMoved = 5,
+		// plus the dragged variants 6/7/26 while a button is held): the last
+		// seen position, -1 = no move this frame. Zeroed by every pump.
+		// External linkage: Container.take_mouse_move externs it. Requires
+		// setAcceptsMouseMovedEvents (armed by every pump below) — without
+		// it AppKit delivers no move events at all.
+		int nomen_last_mouse_move_x = -1;
+		int nomen_last_mouse_move_y = -1;
+		// Frame time: the pump's wall-clock interval, persisted across
+		// pumps (NOT zeroed — the first frame reports 0). Read by win.dt().
+		double nomen_last_pump_time = 0.0;
+		double nomen_last_dt_ms = 0.0;
+		// The window-resize record for THIS frame, stamped by Window.run's
+		// resize detection (not by the pump). External linkage:
+		// Container.take_resize externs the edge from another TU; the size
+		// getters (resize_width/resize_height) are Window methods reading
+		// these directly.
+		int nomen_last_resized = 0;
+		int nomen_last_resize_w = 0;
+		int nomen_last_resize_h = 0;
+		```
+		```
+		#arch: c
+		#platform: macos
+		// A manual event loop has no autorelease pool of its own: AppKit
+		// autoreleases objects on every pump (events, strings, cell caches)
+		// and without a pool they accumulate for the process lifetime — the
+		// loop leaked tens of MB per second and a busy window eventually
+		// died. One pool per pump; the returned had_click is a plain int.
+		id pool = ((id(*)(id, SEL))objc_msgSend)(
+			((id(*)(id, SEL))objc_msgSend)((id)objc_getClass("NSAutoreleasePool"), sel_registerName("alloc")),
+			sel_registerName("init"));
+		id app = ((id(*)(id, SEL))objc_msgSend)((id)objc_getClass("NSApplication"), sel_registerName("sharedApplication"));
+		id distant_past = ((id(*)(id, SEL))objc_msgSend)((id)objc_getClass("NSDate"), sel_registerName("distantPast"));
+		id default_mode = ((id(*)(id, SEL, const char*))objc_msgSend)(
+			(id)objc_getClass("NSString"), sel_registerName("stringWithUTF8String:"), "kCFRunLoopDefaultMode");
+		int had_click = 0;
+		// This pump's mouse record: zeroed first, so a quiet pump expires
+		// the previous frame's edge — the getters and drains read these,
+		// and 0 means "no mouse-down / no scroll this frame".
+		nomen_last_click_button = 0;
+		nomen_last_click_count = 0;
+		nomen_last_click_modifiers = 0;
+		nomen_scroll_dx_acc = 0.0;
+		nomen_scroll_dy_acc = 0.0;
+		nomen_last_key_code = -1;
+		nomen_last_key_modifiers = 0;
+		nomen_last_key_repeat = 0;
+		nomen_last_key_up_code = -1;
+		nomen_last_mouse_move_x = -1;
+		nomen_last_mouse_move_y = -1;
+		while (1) {
+			id event = ((id(*)(id, SEL, unsigned long long, id, id, BOOL))objc_msgSend)(
+				app, sel_registerName("nextEventMatchingMask:untilDate:inMode:dequeue:"),
+				0xFFFFFFFFFFFFFFFFULL, // NSEventMaskAny
+				distant_past,          // untilDate — returns immediately if no events
+				default_mode,          // inMode
+				1);                    // dequeue
+			if (!event) break;
+			((void(*)(id, SEL, id))objc_msgSend)(app, sel_registerName("sendEvent:"), event);
+			long type = ((long(*)(id, SEL))objc_msgSend)(event, sel_registerName("type"));
+			// A mouse-down (left = 1, right = 3, other/middle/extra = 25):
+			// record where it landed and which button. locationInWindow is
+			// in the event's own window's coordinates (bottom-left origin);
+			// flip y against that window's content height to match the
+			// layout's top-left origin. buttonNumber is 0-based (0 left, 1
+			// right, 2 middle, 3+ extras) — stored 1-based to match
+			// FrameEvents.click's 1 = left / 2 = right contract. clickCount
+			// gives double/triple clicks; modifierFlags are masked to the
+			// device-independent bits.
+			if (type == 1 || type == 3 || type == 25) {
+				id evwin = ((id(*)(id, SEL))objc_msgSend)(event, sel_registerName("window"));
+				id cv = ((id(*)(id, SEL))objc_msgSend)(evwin, sel_registerName("contentView"));
+				CGRect frame = ((CGRect(*)(id, SEL))objc_msgSend)(cv, sel_registerName("frame"));
+				CGPoint loc = ((CGPoint(*)(id, SEL))objc_msgSend)(event, sel_registerName("locationInWindow"));
+				nomen_last_click_x = (int)loc.x;
+				nomen_last_click_y = (int)(frame.size.height - loc.y);
+				nomen_last_click_button = (int)(((long(*)(id, SEL))objc_msgSend)(event, sel_registerName("buttonNumber"))) + 1;
+				nomen_last_click_count = (int)((unsigned long(*)(id, SEL))objc_msgSend)(event, sel_registerName("clickCount"));
+				nomen_last_click_modifiers = (int)(((unsigned long(*)(id, SEL))objc_msgSend)(event, sel_registerName("modifierFlags")) & 0xFFF00000ULL);
+			}
+			// A scroll-wheel event (NSEventTypeScrollWheel = 22): accumulate
+			// the deltas for this frame. AppKit deltaY is positive scrolling
+			// up/away from the user; deltaX is positive scrolling right.
+			if (type == 22) {
+				nomen_scroll_dy_acc += ((double(*)(id, SEL))objc_msgSend)(event, sel_registerName("deltaY"));
+				nomen_scroll_dx_acc += ((double(*)(id, SEL))objc_msgSend)(event, sel_registerName("deltaX"));
+			}
+			// A key-down (NSEventTypeKeyDown = 10): record the hardware
+			// keycode (Space = 49, Return = 36, Delete = 51, Esc = 53,
+			// arrows = 123–126, letters a…z = 0–25), the modifiers, and
+			// whether this is an auto-repeat (a held key — filter it for
+			// first-press-only shortcuts).
+			if (type == 10) {
+				nomen_last_key_code = (int)((unsigned long(*)(id, SEL))objc_msgSend)(event, sel_registerName("keyCode"));
+				nomen_last_key_modifiers = (int)(((unsigned long(*)(id, SEL))objc_msgSend)(event, sel_registerName("modifierFlags")) & 0xFFF00000ULL);
+				nomen_last_key_repeat = ((BOOL(*)(id, SEL))objc_msgSend)(event, sel_registerName("isARepeat")) ? 1 : 0;
+			}
+			// A key-up (NSEventTypeKeyUp = 11): press-and-hold handling.
+			if (type == 11) {
+				nomen_last_key_up_code = (int)((unsigned long(*)(id, SEL))objc_msgSend)(event, sel_registerName("keyCode"));
+			}
+			// A pointer move (NSMouseMoved = 5; the dragged variants 6/7/26
+			// while a button is held): record where the pointer is now.
+			if (type == 5 || type == 6 || type == 7 || type == 26) {
+				id evwin = ((id(*)(id, SEL))objc_msgSend)(event, sel_registerName("window"));
+				id cv = ((id(*)(id, SEL))objc_msgSend)(evwin, sel_registerName("contentView"));
+				CGRect frame = ((CGRect(*)(id, SEL))objc_msgSend)(cv, sel_registerName("frame"));
+				CGPoint loc = ((CGPoint(*)(id, SEL))objc_msgSend)(event, sel_registerName("locationInWindow"));
+				nomen_last_mouse_move_x = (int)loc.x;
+				nomen_last_mouse_move_y = (int)(frame.size.height - loc.y);
+			}
+			if (type == 1) had_click = 1; // NSLeftMouseDown = 1
+			if (type == 3) had_click = 2; // NSRightMouseDown = 3 (reported as 2)
+		}
+		// Process run loop sources (Apple Events, timers) so that dock Quit
+		// and other system interactions work without NSApplication.run().
+		CFRunLoopRunInMode(kCFRunLoopDefaultMode, 0, 1);
+		// Frame time: the interval since the previous pump (0 on the first).
+		double now = CFAbsoluteTimeGetCurrent();
+		if (nomen_last_pump_time != 0.0) {
+			nomen_last_dt_ms = (now - nomen_last_pump_time) * 1000.0;
+		}
+		nomen_last_pump_time = now;
+		int result = had_click;
+		// Stamp the kind for the drains (Container.take_right_click reads
+		// it in the handle_events pass that follows this pump).
+		nomen_last_click_kind = had_click;
+		((void(*)(id, SEL))objc_msgSend)(pool, sel_registerName("drain"));
+		return result;
+		```
+		```
+		#arch: aarch64_use_c
+		#platform: macos
+		// A manual event loop has no autorelease pool of its own: AppKit
+		// autoreleases objects on every pump (events, strings, cell caches)
+		// and without a pool they accumulate for the process lifetime — the
+		// loop leaked tens of MB per second and a busy window eventually
+		// died. One pool per pump; the returned had_click is a plain int.
+		id pool = ((id(*)(id, SEL))objc_msgSend)(
+			((id(*)(id, SEL))objc_msgSend)((id)objc_getClass("NSAutoreleasePool"), sel_registerName("alloc")),
+			sel_registerName("init"));
 		id app = ((id(*)(id, SEL))objc_msgSend)((id)objc_getClass("NSApplication"), sel_registerName("sharedApplication"));
 		id distant_past = ((id(*)(id, SEL))objc_msgSend)((id)objc_getClass("NSDate"), sel_registerName("distantPast"));
 		id default_mode = ((id(*)(id, SEL, const char*))objc_msgSend)(
 			(id)objc_getClass("NSString"), sel_registerName("stringWithUTF8String:"), "kCFRunLoopDefaultMode");
 		int had_click = 0;
+		// This pump's mouse record: zeroed first, so a quiet pump expires
+		// the previous frame's edge — the getters and drains read these,
+		// and 0 means "no mouse-down / no scroll this frame".
+		nomen_last_click_button = 0;
+		nomen_last_click_count = 0;
+		nomen_last_click_modifiers = 0;
+		nomen_scroll_dx_acc = 0.0;
+		nomen_scroll_dy_acc = 0.0;
+		nomen_last_key_code = -1;
+		nomen_last_key_modifiers = 0;
+		nomen_last_key_repeat = 0;
+		nomen_last_key_up_code = -1;
+		nomen_last_mouse_move_x = -1;
+		nomen_last_mouse_move_y = -1;
 		while (1) {
 			id event = ((id(*)(id, SEL, unsigned long long, id, id, BOOL))objc_msgSend)(
 				app, sel_registerName("nextEventMatchingMask:untilDate:inMode:dequeue:"),
@@ -182,37 +454,540 @@ pub mv struct Window : Control {
 			if (!event) break;
 			((void(*)(id, SEL, id))objc_msgSend)(app, sel_registerName("sendEvent:"), event);
 			long type = ((long(*)(id, SEL))objc_msgSend)(event, sel_registerName("type"));
+			// A mouse-down (left = 1, right = 3, other/middle/extra = 25):
+			// record where it landed and which button. locationInWindow is
+			// in the event's own window's coordinates (bottom-left origin);
+			// flip y against that window's content height to match the
+			// layout's top-left origin. buttonNumber is 0-based (0 left, 1
+			// right, 2 middle, 3+ extras) — stored 1-based to match
+			// FrameEvents.click's 1 = left / 2 = right contract. clickCount
+			// gives double/triple clicks; modifierFlags are masked to the
+			// device-independent bits.
+			if (type == 1 || type == 3 || type == 25) {
+				id evwin = ((id(*)(id, SEL))objc_msgSend)(event, sel_registerName("window"));
+				id cv = ((id(*)(id, SEL))objc_msgSend)(evwin, sel_registerName("contentView"));
+				CGRect frame = ((CGRect(*)(id, SEL))objc_msgSend)(cv, sel_registerName("frame"));
+				CGPoint loc = ((CGPoint(*)(id, SEL))objc_msgSend)(event, sel_registerName("locationInWindow"));
+				nomen_last_click_x = (int)loc.x;
+				nomen_last_click_y = (int)(frame.size.height - loc.y);
+				nomen_last_click_button = (int)(((long(*)(id, SEL))objc_msgSend)(event, sel_registerName("buttonNumber"))) + 1;
+				nomen_last_click_count = (int)((unsigned long(*)(id, SEL))objc_msgSend)(event, sel_registerName("clickCount"));
+				nomen_last_click_modifiers = (int)(((unsigned long(*)(id, SEL))objc_msgSend)(event, sel_registerName("modifierFlags")) & 0xFFF00000ULL);
+			}
+			// A scroll-wheel event (NSEventTypeScrollWheel = 22): accumulate
+			// the deltas for this frame. AppKit deltaY is positive scrolling
+			// up/away from the user; deltaX is positive scrolling right.
+			if (type == 22) {
+				nomen_scroll_dy_acc += ((double(*)(id, SEL))objc_msgSend)(event, sel_registerName("deltaY"));
+				nomen_scroll_dx_acc += ((double(*)(id, SEL))objc_msgSend)(event, sel_registerName("deltaX"));
+			}
+			// A key-down (NSEventTypeKeyDown = 10): record the hardware
+			// keycode (Space = 49, Return = 36, Delete = 51, Esc = 53,
+			// arrows = 123–126, letters a…z = 0–25), the modifiers, and
+			// whether this is an auto-repeat (a held key — filter it for
+			// first-press-only shortcuts).
+			if (type == 10) {
+				nomen_last_key_code = (int)((unsigned long(*)(id, SEL))objc_msgSend)(event, sel_registerName("keyCode"));
+				nomen_last_key_modifiers = (int)(((unsigned long(*)(id, SEL))objc_msgSend)(event, sel_registerName("modifierFlags")) & 0xFFF00000ULL);
+				nomen_last_key_repeat = ((BOOL(*)(id, SEL))objc_msgSend)(event, sel_registerName("isARepeat")) ? 1 : 0;
+			}
+			// A key-up (NSEventTypeKeyUp = 11): press-and-hold handling.
+			if (type == 11) {
+				nomen_last_key_up_code = (int)((unsigned long(*)(id, SEL))objc_msgSend)(event, sel_registerName("keyCode"));
+			}
+			// A pointer move (NSMouseMoved = 5; the dragged variants 6/7/26
+			// while a button is held): record where the pointer is now.
+			if (type == 5 || type == 6 || type == 7 || type == 26) {
+				id evwin = ((id(*)(id, SEL))objc_msgSend)(event, sel_registerName("window"));
+				id cv = ((id(*)(id, SEL))objc_msgSend)(evwin, sel_registerName("contentView"));
+				CGRect frame = ((CGRect(*)(id, SEL))objc_msgSend)(cv, sel_registerName("frame"));
+				CGPoint loc = ((CGPoint(*)(id, SEL))objc_msgSend)(event, sel_registerName("locationInWindow"));
+				nomen_last_mouse_move_x = (int)loc.x;
+				nomen_last_mouse_move_y = (int)(frame.size.height - loc.y);
+			}
 			if (type == 1) had_click = 1; // NSLeftMouseDown = 1
+			if (type == 3) had_click = 2; // NSRightMouseDown = 3 (reported as 2)
+		}
+		// Process run loop sources (Apple Events, timers) so that dock Quit
+		// and other system interactions work without NSApplication.run().
+		CFRunLoopRunInMode(kCFRunLoopDefaultMode, 0, 1);
+		// Frame time: the interval since the previous pump (0 on the first).
+		double now = CFAbsoluteTimeGetCurrent();
+		if (nomen_last_pump_time != 0.0) {
+			nomen_last_dt_ms = (now - nomen_last_pump_time) * 1000.0;
+		}
+		nomen_last_pump_time = now;
+		int result = had_click;
+		// Stamp the kind for the drains (Container.take_right_click reads
+		// it in the handle_events pass that follows this pump).
+		nomen_last_click_kind = had_click;
+		((void(*)(id, SEL))objc_msgSend)(pool, sel_registerName("drain"));
+		return result;
+		```
+		```
+		#arch: c
+		#platform: ios
+		return 0;
+		```
+		```
+		#arch: aarch64_use_c
+		#platform: ios
+		return 0;
+		```
+	}
+
+	// Returns true if the window is still on screen. Use this to exit a
+	// manual event loop when the user closes the window.
+	pub func is_visible = (self, out bool) {
+		```
+		#arch: c
+		#platform: macos
+		BOOL vis = ((BOOL(*)(id, SEL))objc_msgSend)((id)self->handle, sel_registerName("isVisible"));
+		return vis;
+		```
+		```
+		#arch: aarch64_use_c
+		#platform: macos
+		BOOL vis = ((BOOL(*)(id, SEL))objc_msgSend)((id)self->handle, sel_registerName("isVisible"));
+		return vis;
+		```
+		```
+		#arch: c
+		#platform: ios
+		BOOL vis = ((BOOL(*)(id, SEL))objc_msgSend)((id)self->handle, sel_registerName("isKeyWindow"));
+		return vis;
+		```
+		```
+		#arch: aarch64_use_c
+		#platform: ios
+		BOOL vis = ((BOOL(*)(id, SEL))objc_msgSend)((id)self->handle, sel_registerName("isKeyWindow"));
+		return vis;
+		```
+	}
+
+	// Returns the x coordinate (in the window's content view) of the most
+	// recent mouse-down (left or right). The pump (process_events) captures
+	// the coordinates when the event is handled, so drag/move events that
+	// follow in the same batch cannot make them stale. Call after
+	// process_events returned 1 or 2 (-1 before any click was ever seen).
+	pub func click_x = (self, out int) {
+		```
+		#arch: c
+		#platform: macos
+		return nomen_last_click_x;
+		```
+		```
+		#arch: aarch64_use_c
+		#platform: macos
+		return nomen_last_click_x;
+		```
+		```
+		#arch: c
+		#platform: ios
+		return -1;
+		```
+		```
+		#arch: aarch64_use_c
+		#platform: ios
+		return -1;
+		```
+	}
+
+	// Returns the y coordinate (flipped to top-left origin) of the most
+	// recent mouse-down, in the window's content view. Captured by the pump;
+	// see click_x.
+	pub func click_y = (self, out int) {
+		```
+		#arch: c
+		#platform: macos
+		return nomen_last_click_y;
+		```
+		```
+		#arch: aarch64_use_c
+		#platform: macos
+		return nomen_last_click_y;
+		```
+		```
+		#arch: c
+		#platform: ios
+		return -1;
+		```
+		```
+		#arch: aarch64_use_c
+		#platform: ios
+		return -1;
+		```
+	}
+
+	// ── The full mouse record (this frame's pump) ──
+	// The exhaustive input surface beside click_x/click_y: EVERY button
+	// (middle, mouse 4+), the click count (double/triple), and the modifier
+	// flags. All five are per-frame: stamped by the pump that saw the
+	// events, zeroed by the next — so a handler registered on
+	// `on_mouse_down` (Container.take_mouse_down) or a `frame` reading
+	// FrameEvents sees exactly this frame's record. `mouse_button` is
+	// 1-based (1 left, 2 right, 3 middle, 4+ extra buttons), 0 on a quiet
+	// frame — the same contract as FrameEvents.mouse_button.
+	//
+	// Modifier bits (NSEventModifierFlagDeviceIndependentFlagsMask, already
+	// applied by the pump): Command = 0x100000, Option = 0x80000,
+	// Control = 0x40000, Shift = 0x20000, Function = 0x800000.
+
+	pub func mouse_button = (self, out int) {
+		```
+		#arch: c
+		#platform: macos
+		return nomen_last_click_button;
+		```
+		```
+		#arch: aarch64_use_c
+		#platform: macos
+		return nomen_last_click_button;
+		```
+		```
+		#arch: c
+		#platform: ios
+		return 0;
+		```
+		```
+		#arch: aarch64_use_c
+		#platform: ios
+		return 0;
+		```
+	}
+
+	pub func mouse_click_count = (self, out int) {
+		```
+		#arch: c
+		#platform: macos
+		return nomen_last_click_count;
+		```
+		```
+		#arch: aarch64_use_c
+		#platform: macos
+		return nomen_last_click_count;
+		```
+		```
+		#arch: c
+		#platform: ios
+		return 0;
+		```
+		```
+		#arch: aarch64_use_c
+		#platform: ios
+		return 0;
+		```
+	}
+
+	pub func mouse_modifiers = (self, out int) {
+		```
+		#arch: c
+		#platform: macos
+		return nomen_last_click_modifiers;
+		```
+		```
+		#arch: aarch64_use_c
+		#platform: macos
+		return nomen_last_click_modifiers;
+		```
+		```
+		#arch: c
+		#platform: ios
+		return 0;
+		```
+		```
+		#arch: aarch64_use_c
+		#platform: ios
+		return 0;
+		```
+	}
+
+	// This frame's accumulated scroll deltas (AppKit deltaY/deltaX: dy is
+	// positive scrolling up/away from the user, dx positive scrolling
+	// right), truncated to ints. Scroll events accumulate across the pump's
+	// batch — a trackpad frame sums every small event — and expire with the
+	// frame. `Scrollable.on_scroll` is the registered-handler form.
+	pub func scroll_dx = (self, out int) {
+		```
+		#arch: c
+		#platform: macos
+		return (int)nomen_scroll_dx_acc;
+		```
+		```
+		#arch: aarch64_use_c
+		#platform: macos
+		return (int)nomen_scroll_dx_acc;
+		```
+		```
+		#arch: c
+		#platform: ios
+		return 0;
+		```
+		```
+		#arch: aarch64_use_c
+		#platform: ios
+		return 0;
+		```
+	}
+
+	pub func scroll_dy = (self, out int) {
+		```
+		#arch: c
+		#platform: macos
+		return (int)nomen_scroll_dy_acc;
+		```
+		```
+		#arch: aarch64_use_c
+		#platform: macos
+		return (int)nomen_scroll_dy_acc;
+		```
+		```
+		#arch: c
+		#platform: ios
+		return 0;
+		```
+		```
+		#arch: aarch64_use_c
+		#platform: ios
+		return 0;
+		```
+	}
+
+	// ── The keyboard record (this frame's pump) ──
+	// Hardware keycodes (NSEventKeyCode): Space = 49, Return = 36,
+	// Delete = 51, Esc = 53, arrows = 123–126, letters a…z = 0–25.
+	// `on_key_down` / `on_key_up` (Container.take_key_down / take_key_up)
+	// are the registered forms; FrameEvents carries the same record
+	// (key_code / key_modifiers / key_repeat / key_up_code). All per-frame:
+	// -1 = no key-down/key-up this frame.
+
+	pub func key_code = (self, out int) {
+		```
+		#arch: c
+		#platform: macos
+		return nomen_last_key_code;
+		```
+		```
+		#arch: aarch64_use_c
+		#platform: macos
+		return nomen_last_key_code;
+		```
+		```
+		#arch: c
+		#platform: ios
+		return -1;
+		```
+		```
+		#arch: aarch64_use_c
+		#platform: ios
+		return -1;
+		```
+	}
+
+	pub func key_modifiers = (self, out int) {
+		```
+		#arch: c
+		#platform: macos
+		return nomen_last_key_modifiers;
+		```
+		```
+		#arch: aarch64_use_c
+		#platform: macos
+		return nomen_last_key_modifiers;
+		```
+		```
+		#arch: c
+		#platform: ios
+		return 0;
+		```
+		```
+		#arch: aarch64_use_c
+		#platform: ios
+		return 0;
+		```
+	}
+
+	pub func key_repeat = (self, out bool) {
+		```
+		#arch: c
+		#platform: macos
+		return nomen_last_key_repeat != 0;
+		```
+		```
+		#arch: aarch64_use_c
+		#platform: macos
+		return nomen_last_key_repeat != 0;
+		```
+		```
+		#arch: c
+		#platform: ios
+		return 0;
+		```
+		```
+		#arch: aarch64_use_c
+		#platform: ios
+		return 0;
+		```
+	}
+
+	pub func key_up_code = (self, out int) {
+		```
+		#arch: c
+		#platform: macos
+		return nomen_last_key_up_code;
+		```
+		```
+		#arch: aarch64_use_c
+		#platform: macos
+		return nomen_last_key_up_code;
+		```
+		```
+		#arch: c
+		#platform: ios
+		return -1;
+		```
+		```
+		#arch: aarch64_use_c
+		#platform: ios
+		return -1;
+		```
+	}
+
+	// ── The pointer-move record (this frame's pump) ──
+	// The current pointer position — moves (and drags) stamped by the pump,
+	// -1 on a frame with no movement. `on_mouse_move`
+	// (Container.take_mouse_move) is the registered-handler form; hover,
+	// cursors, and tooltips hit-test this against Container.contains.
+
+	pub func mouse_x = (self, out int) {
+		```
+		#arch: c
+		#platform: macos
+		return nomen_last_mouse_move_x;
+		```
+		```
+		#arch: aarch64_use_c
+		#platform: macos
+		return nomen_last_mouse_move_x;
+		```
+		```
+		#arch: c
+		#platform: ios
+		return -1;
+		```
+		```
+		#arch: aarch64_use_c
+		#platform: ios
+		return -1;
+		```
+	}
+
+	pub func mouse_y = (self, out int) {
+		```
+		#arch: c
+		#platform: macos
+		return nomen_last_mouse_move_y;
+		```
+		```
+		#arch: aarch64_use_c
+		#platform: macos
+		return nomen_last_mouse_move_y;
+		```
+		```
+		#arch: c
+		#platform: ios
+		return -1;
+		```
+		```
+		#arch: aarch64_use_c
+		#platform: ios
+		return -1;
+		```
+	}
+
+	// ── Frame time ──
+	// Milliseconds since the previous pump (0 on the first frame) — the
+	// animation clock. `FrameEvents.dt` carries the same value.
+
+	pub func dt = (self, out int) {
+		```
+		#arch: c
+		#platform: macos
+		return (int)nomen_last_dt_ms;
+		```
+		```
+		#arch: aarch64_use_c
+		#platform: macos
+		return (int)nomen_last_dt_ms;
+		```
+		```
+		#arch: c
+		#platform: ios
+		return 0;
+		```
+		```
+		#arch: aarch64_use_c
+		#platform: ios
+		return 0;
+		```
+	}
+
+	// ── Window resize ──
+	// `on_resize` (Container.take_resize) fires on the frame whose content
+	// rect changed; the new size rides the dispatch window via these
+	// getters. The framework has ALREADY re-laid-out the registered roots
+	// (the delegate + the relayout pass) — handlers re-layout app-owned
+	// panes (tab pages, split panes). FrameEvents.resized / width / height
+	// carry the same record for `frame`.
+
+	// Stamp the resize record — run's resize detection calls this (the
+	// record lives in C statics shared with Container.take_resize; params
+	// because raw blocks in deep control flow can only address them).
+	func stamp_resize = (self, bool on, int w, int h) {
+		```
+		#arch: c
+		#platform: macos
+		extern int nomen_last_resized;
+		extern int nomen_last_resize_w;
+		extern int nomen_last_resize_h;
+		nomen_last_resized = on ? 1 : 0;
+		if (on) {
+			nomen_last_resize_w = w;
+			nomen_last_resize_h = h;
 		}
-		// Process run loop sources (Apple Events, timers) so that dock Quit
-		// and other system interactions work without NSApplication.run().
-		CFRunLoopRunInMode(kCFRunLoopDefaultMode, 0, 1);
-		return had_click;
 		```
 		```
 		#arch: aarch64_use_c
 		#platform: macos
-		id app = ((id(*)(id, SEL))objc_msgSend)((id)objc_getClass("NSApplication"), sel_registerName("sharedApplication"));
-		id distant_past = ((id(*)(id, SEL))objc_msgSend)((id)objc_getClass("NSDate"), sel_registerName("distantPast"));
-		id default_mode = ((id(*)(id, SEL, const char*))objc_msgSend)(
-			(id)objc_getClass("NSString"), sel_registerName("stringWithUTF8String:"), "kCFRunLoopDefaultMode");
-		int had_click = 0;
-		while (1) {
-			id event = ((id(*)(id, SEL, unsigned long long, id, id, BOOL))objc_msgSend)(
-				app, sel_registerName("nextEventMatchingMask:untilDate:inMode:dequeue:"),
-				0xFFFFFFFFFFFFFFFFULL, // NSEventMaskAny
-				distant_past,          // untilDate — returns immediately if no events
-				default_mode,          // inMode
-				1);                    // dequeue
-			if (!event) break;
-			((void(*)(id, SEL, id))objc_msgSend)(app, sel_registerName("sendEvent:"), event);
-			long type = ((long(*)(id, SEL))objc_msgSend)(event, sel_registerName("type"));
-			if (type == 1) had_click = 1; // NSLeftMouseDown = 1
+		extern int nomen_last_resized;
+		extern int nomen_last_resize_w;
+		extern int nomen_last_resize_h;
+		nomen_last_resized = on ? 1 : 0;
+		if (on) {
+			nomen_last_resize_w = w;
+			nomen_last_resize_h = h;
 		}
-		// Process run loop sources (Apple Events, timers) so that dock Quit
-		// and other system interactions work without NSApplication.run().
-		CFRunLoopRunInMode(kCFRunLoopDefaultMode, 0, 1);
-		return had_click;
+		```
+		```
+		#arch: c
+		#platform: ios
+		```
+		```
+		#arch: aarch64_use_c
+		#platform: ios
+		```
+	}
+
+	pub func resize_width = (self, out int) {
+		```
+		#arch: c
+		#platform: macos
+		return nomen_last_resize_w;
+		```
+		```
+		#arch: aarch64_use_c
+		#platform: macos
+		return nomen_last_resize_w;
 		```
 		```
 		#arch: c
@@ -226,114 +1001,80 @@ pub mv struct Window : Control {
 		```
 	}
 
-	// Returns true if the window is still on screen. Use this to exit a
-	// manual event loop when the user closes the window.
-	pub func is_visible = (self, out bool) {
+	pub func resize_height = (self, out int) {
 		```
 		#arch: c
 		#platform: macos
-		BOOL vis = ((BOOL(*)(id, SEL))objc_msgSend)((id)self->handle, sel_registerName("isVisible"));
-		return vis;
+		return nomen_last_resize_h;
 		```
 		```
 		#arch: aarch64_use_c
 		#platform: macos
-		BOOL vis = ((BOOL(*)(id, SEL))objc_msgSend)((id)self->handle, sel_registerName("isVisible"));
-		return vis;
+		return nomen_last_resize_h;
 		```
 		```
 		#arch: c
 		#platform: ios
-		BOOL vis = ((BOOL(*)(id, SEL))objc_msgSend)((id)self->handle, sel_registerName("isKeyWindow"));
-		return vis;
+		return 0;
 		```
 		```
 		#arch: aarch64_use_c
 		#platform: ios
-		BOOL vis = ((BOOL(*)(id, SEL))objc_msgSend)((id)self->handle, sel_registerName("isKeyWindow"));
-		return vis;
+		return 0;
 		```
 	}
 
-	// Returns the x coordinate (in the window's content view) of the most
-	// recent mouse-down. Call after process_events returned 1.
-	pub func click_x = (self, out int) {
+	// ── Close interception ──
+	// The red button routes through the App's `close_requested` (which may
+	// refuse — the unsaved-changes pattern): the delegate refuses the
+	// native close and sets a pending flag, and run consults the app on the
+	// next frame. Programmatic `close()` is forced and bypasses this.
+
+	pub func close_pending = (self, out bool) {
 		```
 		#arch: c
 		#platform: macos
-		id app = ((id(*)(id, SEL))objc_msgSend)((id)objc_getClass("NSApplication"), sel_registerName("sharedApplication"));
-		id event = ((id(*)(id, SEL))objc_msgSend)(app, sel_registerName("currentEvent"));
-		if (!event) return -1;
-		long type = ((long(*)(id, SEL))objc_msgSend)(event, sel_registerName("type"));
-		if (type != 1) return -1; // NSLeftMouseDown = 1
-		// locationInWindow is a CGPoint inside the event; read it via struct-return
-		CGPoint loc = ((CGPoint(*)(id, SEL))objc_msgSend)(event, sel_registerName("locationInWindow"));
-		return (int)loc.x;
+		extern int nomen_close_pending;
+		return nomen_close_pending != 0;
 		```
 		```
 		#arch: aarch64_use_c
 		#platform: macos
-		id app = ((id(*)(id, SEL))objc_msgSend)((id)objc_getClass("NSApplication"), sel_registerName("sharedApplication"));
-		id event = ((id(*)(id, SEL))objc_msgSend)(app, sel_registerName("currentEvent"));
-		if (!event) return -1;
-		long type = ((long(*)(id, SEL))objc_msgSend)(event, sel_registerName("type"));
-		if (type != 1) return -1; // NSLeftMouseDown = 1
-		// locationInWindow is a CGPoint inside the event; read it via struct-return
-		CGPoint loc = ((CGPoint(*)(id, SEL))objc_msgSend)(event, sel_registerName("locationInWindow"));
-		return (int)loc.x;
+		extern int nomen_close_pending;
+		return nomen_close_pending != 0;
 		```
 		```
 		#arch: c
 		#platform: ios
-		return -1;
+		return 0;
 		```
 		```
 		#arch: aarch64_use_c
 		#platform: ios
-		return -1;
+		return 0;
 		```
 	}
 
-	// Returns the y coordinate (flipped to top-left origin) of the most
-	// recent mouse-down, in the window's content view.
-	pub func click_y = (self, out int) {
+	pub func clear_close_pending = (self) {
 		```
 		#arch: c
 		#platform: macos
-		id app = ((id(*)(id, SEL))objc_msgSend)((id)objc_getClass("NSApplication"), sel_registerName("sharedApplication"));
-		id event = ((id(*)(id, SEL))objc_msgSend)(app, sel_registerName("currentEvent"));
-		if (!event) return -1;
-		long type = ((long(*)(id, SEL))objc_msgSend)(event, sel_registerName("type"));
-		if (type != 1) return -1; // NSLeftMouseDown = 1
-		CGPoint loc = ((CGPoint(*)(id, SEL))objc_msgSend)(event, sel_registerName("locationInWindow"));
-		id cv = ((id(*)(id, SEL))objc_msgSend)((id)self->handle, sel_registerName("contentView"));
-		CGRect frame = ((CGRect(*)(id, SEL))objc_msgSend)(cv, sel_registerName("frame"));
-		// NSWindow coords are bottom-left origin; flip to top-left for layout math
-		return (int)(frame.size.height - loc.y);
+		extern int nomen_close_pending;
+		nomen_close_pending = 0;
 		```
 		```
 		#arch: aarch64_use_c
 		#platform: macos
-		id app = ((id(*)(id, SEL))objc_msgSend)((id)objc_getClass("NSApplication"), sel_registerName("sharedApplication"));
-		id event = ((id(*)(id, SEL))objc_msgSend)(app, sel_registerName("currentEvent"));
-		if (!event) return -1;
-		long type = ((long(*)(id, SEL))objc_msgSend)(event, sel_registerName("type"));
-		if (type != 1) return -1; // NSLeftMouseDown = 1
-		CGPoint loc = ((CGPoint(*)(id, SEL))objc_msgSend)(event, sel_registerName("locationInWindow"));
-		id cv = ((id(*)(id, SEL))objc_msgSend)((id)self->handle, sel_registerName("contentView"));
-		CGRect frame = ((CGRect(*)(id, SEL))objc_msgSend)(cv, sel_registerName("frame"));
-		// NSWindow coords are bottom-left origin; flip to top-left for layout math
-		return (int)(frame.size.height - loc.y);
+		extern int nomen_close_pending;
+		nomen_close_pending = 0;
 		```
 		```
 		#arch: c
 		#platform: ios
-		return -1;
 		```
 		```
 		#arch: aarch64_use_c
 		#platform: ios
-		return -1;
 		```
 	}
 
@@ -409,6 +1150,270 @@ pub mv struct Window : Control {
 		```
 	}
 
+	// Resize the window's content area to width x height (displayed). The
+	// programmatic stand-in for a user drag: it fires the same
+	// windowDidResize: notifications (and the Container resize delegate), so
+	// tests can exercise resize relayout headlessly.
+	pub func set_size = (self, int width, int height) {
+		```
+		#arch: c
+		#platform: macos
+		((void(*)(id, SEL, double, double))objc_msgSend)(
+			(id)self->handle, sel_registerName("setContentSize:"), (double)width, (double)height);
+		```
+		```
+		#arch: aarch64_use_c
+		#platform: macos
+		((void(*)(id, SEL, double, double))objc_msgSend)(
+			(id)self->handle, sel_registerName("setContentSize:"), (double)width, (double)height);
+		```
+		```
+		#arch: c
+		#platform: ios
+		((void(*)(id, SEL, CGRect))objc_msgSend)(
+			(id)self->handle, sel_registerName("setFrame:"),
+			((CGRect(*)(double, double, double, double))CGRectMake)(0, 0, (double)width, (double)height));
+		```
+		```
+		#arch: aarch64_use_c
+		#platform: ios
+		((void(*)(id, SEL, CGRect))objc_msgSend)(
+			(id)self->handle, sel_registerName("setFrame:"),
+			((CGRect(*)(double, double, double, double))CGRectMake)(0, 0, (double)width, (double)height));
+		```
+	}
+
+	// ── The App run loop (see App.nm) ──
+
+	// Register the layout root for Window.run: the root Container's layout
+	// re-runs on start, on every live-resize delegate tick, and on each
+	// frame where the content rect changed. The grid must outlive the run
+	// (an app field — registration stores its address). Call from
+	// App.start; also arms the resize delegate's target pair.
+	pub func set_content = (ref self, ref Container grid) {
+		```
+		#arch: c
+		#platform: macos
+		#scope: file
+		static void *nomen_run_root_grid = 0;
+		static void *nomen_run_root_win = 0;
+		```
+		```
+		#arch: aarch64_use_c
+		#platform: macos
+		#scope: file
+		static void *nomen_run_root_grid = 0;
+		static void *nomen_run_root_win = 0;
+		```
+		```
+		#arch: c
+		#platform: macos
+		extern void nomen_set_resize_target(void *, void *);
+		nomen_run_root_grid = (void *)grid;
+		nomen_run_root_win = (void *)self;
+		nomen_set_resize_target((void *)grid, (void *)self);
+		```
+		```
+		#arch: aarch64_use_c
+		#platform: macos
+		extern void nomen_set_resize_target(void *, void *);
+		nomen_run_root_grid = (void *)grid;
+		nomen_run_root_win = (void *)self;
+		nomen_set_resize_target((void *)grid, (void *)self);
+		```
+		```
+		#arch: c
+		#platform: ios
+		/* TODO: iOS (see #init) */
+		```
+		```
+		#arch: aarch64_use_c
+		#platform: ios
+		/* TODO: iOS (see #init) */
+		```
+	}
+
+	// One framework relayout pass: the registered root Container, then every
+	// registered Scrollable's document dance (`first` drives its one-time
+	// scroll_to_top), then every registered pane root's layout (tabs pages /
+	// split panes re-frame when THIS pass frames their host view — the app
+	// cannot know the moment, so registration hands the timing here).
+	func relayout = (self, int first) {
+		```
+		#arch: c
+		#platform: macos
+		extern void nomen_layout_thunk(struct Container *, struct Window *);
+		extern void nomen_scroll_relayout_all(void *, long);
+		extern void nomen_pane_relayout_all(void);
+		if (nomen_run_root_grid) {
+			nomen_layout_thunk((struct Container *)nomen_run_root_grid, (struct Window *)self);
+		}
+		nomen_scroll_relayout_all((void *)self, first);
+		nomen_pane_relayout_all();
+		```
+		```
+		#arch: aarch64_use_c
+		#platform: macos
+		extern void nomen_layout_thunk(struct Container *, struct Window *);
+		extern void nomen_scroll_relayout_all(void *, long);
+		extern void nomen_pane_relayout_all(void);
+		if (nomen_run_root_grid) {
+			nomen_layout_thunk((struct Container *)nomen_run_root_grid, (struct Window *)self);
+		}
+		nomen_scroll_relayout_all((void *)self, first);
+		nomen_pane_relayout_all();
+		```
+		```
+		#arch: c
+		#platform: ios
+		/* TODO: iOS (see #init) */
+		```
+		```
+		#arch: aarch64_use_c
+		#platform: ios
+		/* TODO: iOS (see #init) */
+		```
+	}
+
+	// Arm mouse-MOVED delivery. AppKit sends move events only when the
+	// window opts in — run() arms it before the loop; manual-loop apps
+	// pumping process_events directly call this once after creating the
+	// window. Idempotent.
+	pub func arm_mouse_moves = (self) {
+		```
+		#arch: c
+		#platform: macos
+		((void(*)(id, SEL, BOOL))objc_msgSend)(
+			(id)self->handle, sel_registerName("setAcceptsMouseMovedEvents:"), 1);
+		```
+		```
+		#arch: aarch64_use_c
+		#platform: macos
+		((void(*)(id, SEL, BOOL))objc_msgSend)(
+			(id)self->handle, sel_registerName("setAcceptsMouseMovedEvents:"), 1);
+		```
+		```
+		#arch: c
+		#platform: ios
+		```
+		```
+		#arch: aarch64_use_c
+		#platform: ios
+		```
+	}
+
+	// Close the window (the programmatic stand-in for the red button) — the
+	// run loop exits on the next `is_visible` check. Programmatic close is
+	// FORCED: it bypasses the close_requested interception (the delegate's
+	// windowShouldClose: sees nomen_close_forced and allows). Only the red
+	// button routes through `close_requested`.
+	pub func close = (self) {
+		```
+		#arch: c
+		#platform: macos
+		extern int nomen_close_forced;
+		nomen_close_forced = 1;
+		((void(*)(id, SEL, id))objc_msgSend)((id)self->handle, sel_registerName("performClose:"), (id)0);
+		```
+		```
+		#arch: aarch64_use_c
+		#platform: macos
+		extern int nomen_close_forced;
+		nomen_close_forced = 1;
+		((void(*)(id, SEL, id))objc_msgSend)((id)self->handle, sel_registerName("performClose:"), (id)0);
+		```
+		```
+		#arch: c
+		#platform: ios
+		/* TODO: iOS (see #init) */
+		```
+		```
+		#arch: aarch64_use_c
+		#platform: ios
+		/* TODO: iOS (see #init) */
+		```
+	}
+
+	// Run the app: the framework owns everything from here until the window
+	// closes. Order: `app.start` (the app registers its layout roots and its
+	// click handlers while in final storage), the pre-show layout pass,
+	// `show`, the post-show pass (the toolbar settles the content rect only
+	// after show; this pass also performs the one-time scroll_to_top), then
+	// the loop — pump events, detect resizes (framework relayout already
+	// applied), drain the app's registered handlers (its synthesized
+	// `handle_events` pump — the control-event desugars), and hand the app
+	// a FrameEvents each frame.
+	// The app is consumed: it is destroyed when the loop exits (controls
+	// release, buffers free).
+	pub func run = (ref self, mv App app) {
+		app.start(ref self)
+		Container.arm_resize_delegate(self)
+		self.arm_mouse_moves()
+		self.relayout(0)
+		self.show()
+		self.relayout(1)
+		var int prev_w = self.content_width()
+		var int prev_h = self.content_height()
+		var ev = FrameEvents()
+		while self.is_visible() {
+			// Close interception: the delegate refused the native close and
+			// set the pending flag; consult the app. Accept → forced close
+			// (bypasses the delegate); decline → window stays, flag cleared.
+			if self.close_pending() {
+				if app.close_requested(ref self) {
+					self.close()
+				}
+				self.clear_close_pending()
+			}
+			// An accepted close above releases the native window mid-frame;
+			// skip the rest of this iteration (the while re-checks and
+			// exits).
+			if self.is_visible() {
+				ev.click = Window.process_events()
+				ev.click_x = self.click_x()
+				ev.click_y = self.click_y()
+				ev.mouse_button = self.mouse_button()
+				ev.mouse_click_count = self.mouse_click_count()
+				ev.mouse_modifiers = self.mouse_modifiers()
+				ev.scroll_dx = self.scroll_dx()
+				ev.scroll_dy = self.scroll_dy()
+				ev.key_code = self.key_code()
+				ev.key_modifiers = self.key_modifiers()
+				ev.key_repeat = self.key_repeat()
+				ev.key_up_code = self.key_up_code()
+				ev.mouse_x = self.mouse_x()
+				ev.mouse_y = self.mouse_y()
+				ev.dt = self.dt()
+				ev.resized = false
+				self.stamp_resize(false, 0, 0)
+				var int cur_w = self.content_width()
+				var int cur_h = self.content_height()
+				if cur_w != prev_w {
+					ev.resized = true
+				}
+				if cur_h != prev_h {
+					ev.resized = true
+				}
+				if ev.resized {
+					prev_w = cur_w
+					prev_h = cur_h
+					ev.width = cur_w
+					ev.height = cur_h
+					self.stamp_resize(true, cur_w, cur_h)
+					self.relayout(0)
+				}
+				// The window refreshes the per-frame event sources (the
+				// first-responder snapshot feeds the focus/blur drains), then the
+				// app's synthesized `handle_events` pump drains registered
+				// handlers — conformers without registrations inherit the
+				// trait's empty default. One arm per registered control.
+				nomen_window_focus_poll(self.handle)
+				app.handle_events(ref self)
+				app.frame(ref self, ev)
+			}
+		}
+	}
+
 	// ── Control trait conformance ──
 	// The window is the layout root: it measures to its content-view size and
 	// applies a frame to the native NSWindow/UIWindow.
@@ -431,16 +1436,22 @@ pub mv struct Window : Control {
 		```
 		#arch: c
 		#platform: macos
-		((void(*)(id, SEL, CGRect))objc_msgSend)(
-			(id)self->handle, sel_registerName("setFrame:"),
-			((CGRect(*)(double, double, double, double))CGRectMake)((double)x, (double)y, (double)width, (double)height));
+		// NSWindow has no plain `setFrame:` (that is NSView's) — the window
+		// API takes the display flag.
+		((void(*)(id, SEL, CGRect, BOOL))objc_msgSend)(
+			(id)self->handle, sel_registerName("setFrame:display:"),
+			((CGRect(*)(double, double, double, double))CGRectMake)((double)x, (double)y, (double)width, (double)height),
+			1);
 		```
 		```
 		#arch: aarch64_use_c
 		#platform: macos
-		((void(*)(id, SEL, CGRect))objc_msgSend)(
-			(id)self->handle, sel_registerName("setFrame:"),
-			((CGRect(*)(double, double, double, double))CGRectMake)((double)x, (double)y, (double)width, (double)height));
+		// NSWindow has no plain `setFrame:` (that is NSView's) — the window
+		// API takes the display flag.
+		((void(*)(id, SEL, CGRect, BOOL))objc_msgSend)(
+			(id)self->handle, sel_registerName("setFrame:display:"),
+			((CGRect(*)(double, double, double, double))CGRectMake)((double)x, (double)y, (double)width, (double)height),
+			1);
 		```
 		```
 		#arch: c
@@ -493,3 +1504,449 @@ pub mv struct Window : Control {
 		```
 	}
 }
+
+// Arm click recording on a registered view. NSButton-family controls are
+// armed at construction (nomen_control_arm_clicks) and already push to the
+// ring; this re-arms those harmlessly and covers every OTHER view through
+// an NSClickGestureRecognizer whose handler records the recognized view —
+// the Nomen handle — into the same ring. Idempotent per handle (the armed
+// set below — a desugar dispatch arm calls this every frame, and a fresh
+// recognizer per call would accumulate); the recognizer target class is
+// still built once per process.
+// ── Registered control events (focus / blur / input) ──
+//
+// The desugar's control-carried events beyond clicks (docs/HANDLERS.md):
+// `self.<field>.on_focus / on_blur / on_input(func () { ... })`. The
+// window is the focus authority, so the snapshot lives here: the
+// synthesized focus dispatcher calls `nomen_window_focus_poll` ONCE per
+// frame (prev/cur first responder — the field editor maps back to the
+// editing control), then each arm is a pure snapshot compare via
+// `nomen_control_take_focus` / `take_blur` — order-independent across
+// arms, and both sides of a handoff (A's blur, B's focus) fire in the
+// same frame. Input edges are per-control text compares
+// (`nomen_control_take_input`): the field editor writes through to the
+// control's stringValue while typing, so each keystroke is one edge.
+
+// Refresh the focus snapshot (prev/cur first responder of `window`).
+// Idempotent per frame; the synthesized focus dispatcher calls it once
+// before the arms.
+pub func nomen_window_focus_poll = (uint64 window) {
+	```
+	#arch: c
+	#platform: macos
+	#scope: file
+	// Shared with the take_focus / take_blur drains (same TU): the snapshot
+	// has external linkage and ONE definition (here); the drains declare it
+	// extern.
+	unsigned long long nomen_focus_prev = 0;
+	unsigned long long nomen_focus_cur = 0;
+	void *nomen_focus_window = 0;
+	static id nomen_focus_responder(void *win) {
+		id fr = ((id(*)(id, SEL))objc_msgSend)((id)win, sel_registerName("firstResponder"));
+		// While a text control is being edited, the first responder is the
+		// window's FIELD EDITOR — map it back to the editing control (the
+		// editor's delegate) so focus edges name the control.
+		if (((BOOL(*)(id, SEL, id))objc_msgSend)(fr, sel_registerName("isKindOfClass:"), (id)objc_getClass("NSTextView"))) {
+			id d = ((id(*)(id, SEL))objc_msgSend)(fr, sel_registerName("delegate"));
+			if (d) fr = d;
+		}
+		return fr;
+	}
+	```
+	```
+	#arch: aarch64_use_c
+	#platform: macos
+	#scope: file
+	unsigned long long nomen_focus_prev = 0;
+	unsigned long long nomen_focus_cur = 0;
+	void *nomen_focus_window = 0;
+	static id nomen_focus_responder(void *win) {
+		id fr = ((id(*)(id, SEL))objc_msgSend)((id)win, sel_registerName("firstResponder"));
+		if (((BOOL(*)(id, SEL, id))objc_msgSend)(fr, sel_registerName("isKindOfClass:"), (id)objc_getClass("NSTextView"))) {
+			id d = ((id(*)(id, SEL))objc_msgSend)(fr, sel_registerName("delegate"));
+			if (d) fr = d;
+		}
+		return fr;
+	}
+	```
+	```
+	#arch: c
+	#platform: macos
+	void *win = (void *)window;
+	id fr = nomen_focus_responder(win);
+	if (nomen_focus_window != win) {
+		// A different window took the snapshot: re-baseline (no edge).
+		nomen_focus_window = win;
+		nomen_focus_cur = (unsigned long long)(void *)fr;
+		nomen_focus_prev = nomen_focus_cur;
+	} else {
+		nomen_focus_prev = nomen_focus_cur;
+		nomen_focus_cur = (unsigned long long)(void *)fr;
+	}
+	```
+	```
+	#arch: aarch64_use_c
+	#platform: macos
+	void *win = (void *)window;
+	id fr = nomen_focus_responder(win);
+	if (nomen_focus_window != win) {
+		nomen_focus_window = win;
+		nomen_focus_cur = (unsigned long long)(void *)fr;
+		nomen_focus_prev = nomen_focus_cur;
+	} else {
+		nomen_focus_prev = nomen_focus_cur;
+		nomen_focus_cur = (unsigned long long)(void *)fr;
+	}
+	```
+	```
+	#arch: c
+	#platform: ios
+	/* TODO: iOS (first responder via UITextField delegates) */
+	```
+	```
+	#arch: aarch64_use_c
+	#platform: ios
+	/* TODO: iOS (see #arch: c) */
+	```
+}
+
+// Whether the most recent pump saw a right-mouse-down (the same record
+// FrameEvents.click reports as 2). Read by Container.take_right_click —
+// the on_right_click drain (docs/HANDLERS.md). The pump stamps the kind
+// on EVERY call — a quiet pump stamps 0 — so the edge expires with the
+// frame: the drains see it exactly in the handle_events pass that follows
+// the pump, and no clearing handshake is needed. The record is
+// window-level (one per process, like click_x/click_y): every registered
+// arm sees the edge (broadcast), and the HANDLER disambiguates — read the
+// click through the dispatch window (win.click_x()/click_y()), translate
+// for scrollables (content_click), hit-test children (contains).
+pub func nomen_window_had_right_click = (out bool) {
+	```
+	#arch: c
+	#platform: macos
+	// One definition lives in process_events' file-scope block (this file);
+	// the extern keeps this function's TU-independent (split builds).
+	extern int nomen_last_click_kind;
+	return nomen_last_click_kind == 2;
+	```
+	```
+	#arch: aarch64_use_c
+	#platform: macos
+	extern int nomen_last_click_kind;
+	return nomen_last_click_kind == 2;
+	```
+	```
+	#arch: c
+	#platform: ios
+	return 0;
+	```
+	```
+	#arch: aarch64_use_c
+	#platform: ios
+	return 0;
+	```
+}
+
+// Focus EDGE drain: true when `handle` GAINED first-responder status this
+// frame. Pure snapshot compare — no state update, so any number of
+// focus/blur arms can poll the same frame in any order.
+pub func nomen_control_take_focus = (uint64 handle, out bool) {
+	```
+	#arch: c
+	#platform: macos
+	#scope: file
+	extern unsigned long long nomen_focus_prev;
+	extern unsigned long long nomen_focus_cur;
+	extern void *nomen_focus_window;
+	static id nomen_focus_responder(void *win);
+	```
+	```
+	#arch: c
+	#platform: macos
+	int known = nomen_focus_window != 0;
+	id fr = known ? nomen_focus_responder(nomen_focus_window) : 0;
+	int gained =
+		known && ((unsigned long long)(void *)fr == handle) && (nomen_focus_prev != handle);
+	return gained;
+	```
+	```
+	#arch: aarch64_use_c
+	#platform: macos
+	#scope: file
+	extern unsigned long long nomen_focus_prev;
+	extern unsigned long long nomen_focus_cur;
+	extern void *nomen_focus_window;
+	static id nomen_focus_responder(void *win);
+	```
+	```
+	#arch: aarch64_use_c
+	#platform: macos
+	int known = nomen_focus_window != 0;
+	id fr = known ? nomen_focus_responder(nomen_focus_window) : 0;
+	int gained =
+		known && ((unsigned long long)(void *)fr == handle) && (nomen_focus_prev != handle);
+	return gained;
+	```
+	```
+	#arch: c
+	#platform: ios
+	return 0;
+	```
+	```
+	#arch: aarch64_use_c
+	#platform: ios
+	return 0;
+	```
+}
+
+// Blur EDGE drain: true when `handle` LOST first-responder status this
+// frame (it was focused on the previous poll and is not now).
+pub func nomen_control_take_blur = (uint64 handle, out bool) {
+	```
+	#arch: c
+	#platform: macos
+	#scope: file
+	extern unsigned long long nomen_focus_prev;
+	extern unsigned long long nomen_focus_cur;
+	extern void *nomen_focus_window;
+	static id nomen_focus_responder(void *win);
+	```
+	```
+	#arch: c
+	#platform: macos
+	int known = nomen_focus_window != 0;
+	id fr = known ? nomen_focus_responder(nomen_focus_window) : 0;
+	int lost =
+		known && (nomen_focus_prev == handle) && ((unsigned long long)(void *)fr != handle);
+	return lost;
+	```
+	```
+	#arch: aarch64_use_c
+	#platform: macos
+	#scope: file
+	extern unsigned long long nomen_focus_prev;
+	extern unsigned long long nomen_focus_cur;
+	extern void *nomen_focus_window;
+	static id nomen_focus_responder(void *win);
+	```
+	```
+	#arch: aarch64_use_c
+	#platform: macos
+	int known = nomen_focus_window != 0;
+	id fr = known ? nomen_focus_responder(nomen_focus_window) : 0;
+	int lost =
+		known && (nomen_focus_prev == handle) && ((unsigned long long)(void *)fr != handle);
+	return lost;
+	```
+	```
+	#arch: c
+	#platform: ios
+	return 0;
+	```
+	```
+	#arch: aarch64_use_c
+	#platform: ios
+	return 0;
+	```
+}
+
+// Text-INPUT edge drain: true when the control's text changed since the
+// last drain for this handle (the field editor writes through to the
+// control's stringValue while typing, so each keystroke is one edge).
+// Last-seen text is tracked per handle.
+pub func nomen_control_take_input = (uint64 handle, out bool) {
+	```
+	#arch: c
+	#platform: macos
+	#scope: file
+	struct nomen_input_seen {
+		void *handle;
+		char *last;
+	};
+	static struct nomen_input_seen nomen_input_seen[32];
+	static int nomen_input_seen_count = 0;
+	```
+	```
+	#arch: c
+	#platform: macos
+	struct nomen_input_seen *e = 0;
+	for (int i = 0; i < nomen_input_seen_count; i++) {
+		if (nomen_input_seen[i].handle == (void *)handle) {
+			e = &nomen_input_seen[i];
+			break;
+		}
+	}
+	if (!e && nomen_input_seen_count < 32) {
+		e = &nomen_input_seen[nomen_input_seen_count++];
+		e->handle = (void *)handle;
+		e->last = 0;
+	}
+	if (!e) return 0;
+	// stringValue returns the live text (the field editor writes through to
+	// it while typing); UTF8String goes through the returned NSString.
+	id s = ((id(*)(id, SEL))objc_msgSend)((id)handle, sel_registerName("stringValue"));
+	const char *cur = ((const char *(*)(id, SEL))objc_msgSend)(s, sel_registerName("UTF8String"));
+	// First sight of a handle: record the baseline silently — no edge.
+	if (!e->last) {
+		e->last = strdup(cur);
+		return 0;
+	}
+	int changed = strcmp(e->last, cur) != 0;
+	if (changed) {
+		free(e->last);
+		e->last = strdup(cur);
+	}
+	return changed;
+	```
+	```
+	#arch: aarch64_use_c
+	#platform: macos
+	#scope: file
+	struct nomen_input_seen {
+		void *handle;
+		char *last;
+	};
+	static struct nomen_input_seen nomen_input_seen[32];
+	static int nomen_input_seen_count = 0;
+	```
+	```
+	#arch: aarch64_use_c
+	#platform: macos
+	struct nomen_input_seen *e = 0;
+	for (int i = 0; i < nomen_input_seen_count; i++) {
+		if (nomen_input_seen[i].handle == (void *)handle) {
+			e = &nomen_input_seen[i];
+			break;
+		}
+	}
+	if (!e && nomen_input_seen_count < 32) {
+		e = &nomen_input_seen[nomen_input_seen_count++];
+		e->handle = (void *)handle;
+		e->last = 0;
+	}
+	if (!e) return 0;
+	// stringValue returns the live text (the field editor writes through to
+	// it while typing); UTF8String goes through the returned NSString.
+	id s = ((id(*)(id, SEL))objc_msgSend)((id)handle, sel_registerName("stringValue"));
+	const char *cur = ((const char *(*)(id, SEL))objc_msgSend)(s, sel_registerName("UTF8String"));
+	// First sight of a handle: record the baseline silently — no edge.
+	if (!e->last) {
+		e->last = strdup(cur);
+		return 0;
+	}
+	int changed = strcmp(e->last, cur) != 0;
+	if (changed) {
+		free(e->last);
+		e->last = strdup(cur);
+	}
+	return changed;
+	```
+	```
+	#arch: c
+	#platform: ios
+	return 0;
+	```
+	```
+	#arch: aarch64_use_c
+	#platform: ios
+	return 0;
+	```
+}
+
+pub func nomen_window_clicks_init = (uint64 handle) {
+	```
+	#arch: c
+	#platform: macos
+	#scope: file
+	// The armed set: handles this process already armed (a desugar dispatch
+	// arm re-calls per frame; re-arming would stack recognizers).
+	static unsigned long long nomen_armed_handles[128];
+	static int nomen_armed_count = 0;
+	// The shared gesture target (one class pair per process; the handler
+	// reads the gesture's view — the Nomen handle — and pushes the same
+	// ring the button family's target/action uses).
+	static void nomen_view_click_gesture(id self, SEL cmd, id gesture) {
+		(void)self; (void)cmd;
+		id view = ((id(*)(id, SEL))objc_msgSend)(gesture, sel_registerName("view"));
+		nomen_click_push((unsigned long long)(void *)view);
+	}
+	static void nomen_window_click_arm(unsigned long long handle) {
+		for (int i = 0; i < nomen_armed_count; i++) {
+			if (nomen_armed_handles[i] == handle) return;
+		}
+		if (nomen_armed_count < 128) nomen_armed_handles[nomen_armed_count++] = handle;
+		Class Tc = objc_getClass("NomenViewClickTarget");
+		if (!Tc) {
+			Tc = objc_allocateClassPair(objc_getClass("NSObject"), "NomenViewClickTarget", 0);
+			if (Tc) {
+				class_addMethod(Tc, sel_registerName("viewClickGesture:"), (IMP)nomen_view_click_gesture, "v@:@");
+				objc_registerClassPair(Tc);
+			}
+		}
+		if (!Tc) return;
+		id target = ((id(*)(id, SEL))objc_msgSend)((id)Tc, sel_registerName("new"));
+		id rec = ((id(*)(id, SEL))objc_msgSend)((id)objc_getClass("NSClickGestureRecognizer"), sel_registerName("alloc"));
+		rec = ((id(*)(id, SEL, id, SEL))objc_msgSend)(
+			rec, sel_registerName("initWithTarget:action:"), (id)target, sel_registerName("viewClickGesture:"));
+		((void(*)(id, SEL, id))objc_msgSend)((id)handle, sel_registerName("addGestureRecognizer:"), (id)rec);
+	}
+	```
+	```
+	#arch: c
+	#platform: macos
+	nomen_window_click_arm(handle);
+	```
+	```
+	#arch: aarch64_use_c
+	#platform: macos
+	#scope: file
+	// The armed set: handles this process already armed (a desugar dispatch
+	// arm re-calls per frame; re-arming would stack recognizers).
+	static unsigned long long nomen_armed_handles[128];
+	static int nomen_armed_count = 0;
+	// Forward declaration: the ring lives in Control.nm's file-scope
+	// block, whose carrier may hoist AFTER this one (build order, not
+	// source order).
+	static void nomen_click_push(unsigned long long h);
+	static void nomen_view_click_gesture(id self, SEL cmd, id gesture) {
+		(void)self; (void)cmd;
+		id view = ((id(*)(id, SEL))objc_msgSend)(gesture, sel_registerName("view"));
+		nomen_click_push((unsigned long long)(void *)view);
+	}
+	static void nomen_window_click_arm(unsigned long long handle) {
+		for (int i = 0; i < nomen_armed_count; i++) {
+			if (nomen_armed_handles[i] == handle) return;
+		}
+		if (nomen_armed_count < 128) nomen_armed_handles[nomen_armed_count++] = handle;
+		Class Tc = objc_getClass("NomenViewClickTarget");
+		if (!Tc) {
+			Tc = objc_allocateClassPair(objc_getClass("NSObject"), "NomenViewClickTarget", 0);
+			if (Tc) {
+				class_addMethod(Tc, sel_registerName("viewClickGesture:"), (IMP)nomen_view_click_gesture, "v@:@");
+				objc_registerClassPair(Tc);
+			}
+		}
+		if (!Tc) return;
+		id target = ((id(*)(id, SEL))objc_msgSend)((id)Tc, sel_registerName("new"));
+		id rec = ((id(*)(id, SEL))objc_msgSend)((id)objc_getClass("NSClickGestureRecognizer"), sel_registerName("alloc"));
+		rec = ((id(*)(id, SEL, id, SEL))objc_msgSend)(
+			rec, sel_registerName("initWithTarget:action:"), (id)target, sel_registerName("viewClickGesture:"));
+		((void(*)(id, SEL, id))objc_msgSend)((id)handle, sel_registerName("addGestureRecognizer:"), (id)rec);
+	}
+	```
+	```
+	#arch: aarch64_use_c
+	#platform: macos
+	nomen_window_click_arm(handle);
+	```
+	```
+	#arch: c
+	#platform: ios
+	/* TODO: iOS (UITapGestureRecognizer shape; see nomen_control_arm_clicks) */
+	```
+	```
+	#arch: aarch64_use_c
+	#platform: ios
+	/* TODO: iOS (UITapGestureRecognizer shape; see nomen_control_arm_clicks) */
+	```
+}