nomen-lang 0.7.0 → 0.8.0

package/core/System/Buffer.nm

@@ -220,6 +220,14 @@ pub struct Buffer<T> {
 	// reaching here is always a value type (primitive or struct).
 
 	func alloc = (ref self, int size, out int: out >= size) {
+		// Reclaim the old slab before the fresh calloc (the raw body runs
+		// for scalar / trivially-destructible elements — plain bytes, so a
+		// straight free is sound; mv element types take the specialized
+		// body, which per-element destroys first). The exact-cap contract
+		// is preserved: the fresh slab is calloc'd at exactly `size`.
+		if self.data != 0 {
+			free(self.data)
+		}
 		self.cap = size
 		self.data = calloc(size, T_SIZE)
 		return self.cap
@@ -550,6 +558,30 @@ pub struct Buffer<T> {
 		self.replace(i, value)
 	}
 
+	// Address of slot `i` (library-only): the ELEMENT BORROW primitive —
+	// `ref T x = list.at(i)` (docs/HANDLERS.md Stage 4, the dynamic-tree
+	// dispatch) lowers to this, binding the alias to the slot itself rather
+	// than to a bitwise copy. The pointer is valid while the buffer is
+	// exclusively borrowed and not resized; a `ref self` call on the buffer
+	// (push/pop/set/…) invalidates the borrow through the ordinary
+	// borrow-invalidation rules. Library-internal: the caller (the `List`
+	// wrapper, or trusted internals) bounds-checks; the body is raw-only so
+	// the missing-return net does not apply to the raw return.
+	pub func slot_ptr = (ref self, int i, out ptr T) {
+		```
+		#arch: c
+		return (T*)(unsigned long long)self->data + i;
+		```
+		```
+		#arch: aarch64
+		// x19 = self, x1 = i — the slot address (the load primitive's
+		// address-of: data + i * T_SIZE), returned in x0.
+		ldr x8, [x19, #8]
+		mov x9, #T_SIZE
+		madd x0, x1, x9, x8
+		```
+	}
+
 	// Move slot src into slot dst: overwrite dst with src's bytes and zero
 	// src, so exactly ONE slot owns the value afterwards. The
 	// ownership-transferring primitive behind backward-shift deletion

package/core/System/ClassBuffer.nm

@@ -58,6 +58,30 @@ pub struct ClassBuffer<T> {
 		```
 	}
 
+	// Address of slot `i` (library-only): the ELEMENT BORROW primitive for
+	// trait/class elements — `ref T x = list.at(i)` (docs/HANDLERS.md Stage
+	// 4) reaches here through the List wrapper when the element is a trait
+	// (the items buffer is a ClassBuffer). ClassBuffer slots are 8-byte
+	// handles, so the slot's CONTENT is the instance pointer: return the
+	// stored word, not the slot's address. Library-internal: bounds are the
+	// caller's obligation (the List wrapper constrains them).
+	pub func slot_ptr = (ref self, int i, out ptr T) {
+		```
+		#arch: c
+		// The slot's address: through the alias, reads and writes hit the
+		// stored handle word. void* converts to the caller's `T*` spelling.
+		return (void *)&((unsigned long long *)self->data)[i];
+		```
+		```
+		#arch: aarch64
+		// 8-byte slots: the address of slot i — loading through it yields
+		// the stored handle.
+		ldr x8, [x19, #8]
+		lsl x9, x1, #3
+		add x0, x9, x8
+		```
+	}
+
 	// Generic (T-typed) counterparts of the _int primitives. ClassBuffer only
 	// ever holds 8-byte class pointers (T_SIZE is 8), so these are
 	// behaviorally identical to their _int counterparts — they exist so

package/core/System/Controls/Alert.nm

@@ -0,0 +1,326 @@
+/**
+ * A system alert dialog (NSAlert)
+ *
+ * An OWNING STRUCT (STRUCT_PLAN_3 Phase R, tranche 4 — the shape menu): the
+ * single field is a platform handle, so the value is movable and its
+ * `#destroy` releases what the handle names. The constructor's `self` is
+ * the inline instance (the `.` accessor); methods keep the pointer form.
+ *
+ * Window-coordinated: `run` enters NSAlert's own modal loop (it blocks the
+ * caller and pumps its own events, so it works with the manual loop), and
+ * returns the clicked button's index (first button = 0). iOS defers —
+ * UIAlertController needs a presenting view controller (TODO stubs; see
+ * GUI_PLAN Tier 1 #19).
+ **/
+pub mv struct Alert : Control {
+	var uint64 handle = 0
+
+	// The `#handle` hook synthesizes `NameHandle` — a copyable, non-owning
+	// twin (same public bare-self methods, no destroy) so closures can
+	// capture this control without moving it. See GUI.md, "Handles".
+	#handle = () {}
+
+	pub func #init = (self) {
+		```
+		#arch: c
+		#platform: macos
+		id alert = ((id(*)(id, SEL))objc_msgSend)(
+			((id(*)(id, SEL))objc_msgSend)((id)objc_getClass("NSAlert"), sel_registerName("alloc")),
+			sel_registerName("init"));
+		self.handle = (uint64_t)alert;
+		```
+		```
+		#arch: aarch64_use_c
+		#platform: macos
+		id alert = ((id(*)(id, SEL))objc_msgSend)(
+			((id(*)(id, SEL))objc_msgSend)((id)objc_getClass("NSAlert"), sel_registerName("alloc")),
+			sel_registerName("init"));
+		self->handle = (uint64_t)alert;
+		```
+		```
+		#arch: c
+		#platform: ios
+		/* TODO: iOS — UIAlertController needs a presenting view controller
+		 * (see GUI_PLAN Tier 1 #19; defer the iOS block). */
+		```
+		```
+		#arch: aarch64_use_c
+		#platform: ios
+		/* TODO: iOS — UIAlertController needs a presenting view controller
+		 * (see GUI_PLAN Tier 1 #19; defer the iOS block). */
+		```
+	}
+
+	// The alert's headline (bold first line).
+	pub func set_title = (self, string title) {
+		```
+		#arch: c
+		#platform: macos
+		((void(*)(id, SEL, id))objc_msgSend)(
+			(id)self->handle, sel_registerName("setMessageText:"),
+			((id(*)(id, SEL, const char*))objc_msgSend)(
+				(id)objc_getClass("NSString"), sel_registerName("stringWithUTF8String:"), title.ptr));
+		```
+		```
+		#arch: aarch64_use_c
+		#platform: macos
+		((void(*)(id, SEL, id))objc_msgSend)(
+			(id)self->handle, sel_registerName("setMessageText:"),
+			((id(*)(id, SEL, const char*))objc_msgSend)(
+				(id)objc_getClass("NSString"), sel_registerName("stringWithUTF8String:"), title.ptr));
+		```
+		```
+		#arch: c
+		#platform: ios
+		/* TODO: iOS (see #init) */
+		```
+		```
+		#arch: aarch64_use_c
+		#platform: ios
+		/* TODO: iOS (see #init) */
+		```
+	}
+
+	pub func title = (self, out string) {
+		```
+		#arch: c
+		#platform: macos
+		id str = ((id(*)(id, SEL))objc_msgSend)(
+			(id)self->handle, sel_registerName("messageText"));
+		if (!str) return (nomen_string){ strdup(""), 0 };
+		const char *cstr = ((const char*(*)(id, SEL))objc_msgSend)(
+			str, sel_registerName("UTF8String"));
+		return (nomen_string){ strdup(cstr), (long)strlen(cstr) };
+		```
+		```
+		#arch: aarch64_use_c
+		#platform: macos
+		id str = ((id(*)(id, SEL))objc_msgSend)(
+			(id)self->handle, sel_registerName("messageText"));
+		if (!str) return (nomen_string){ strdup(""), 0 };
+		const char *cstr = ((const char*(*)(id, SEL))objc_msgSend)(
+			str, sel_registerName("UTF8String"));
+		return (nomen_string){ strdup(cstr), (long)strlen(cstr) };
+		```
+		```
+		#arch: c
+		#platform: ios
+		/* TODO: iOS (see #init) */
+		return (nomen_string){ strdup(""), 0 };
+		```
+		```
+		#arch: aarch64_use_c
+		#platform: ios
+		/* TODO: iOS (see #init) */
+		return (nomen_string){ strdup(""), 0 };
+		```
+	}
+
+	// The explanatory second line.
+	pub func set_message = (self, string message) {
+		```
+		#arch: c
+		#platform: macos
+		((void(*)(id, SEL, id))objc_msgSend)(
+			(id)self->handle, sel_registerName("setInformativeText:"),
+			((id(*)(id, SEL, const char*))objc_msgSend)(
+				(id)objc_getClass("NSString"), sel_registerName("stringWithUTF8String:"), message.ptr));
+		```
+		```
+		#arch: aarch64_use_c
+		#platform: macos
+		((void(*)(id, SEL, id))objc_msgSend)(
+			(id)self->handle, sel_registerName("setInformativeText:"),
+			((id(*)(id, SEL, const char*))objc_msgSend)(
+				(id)objc_getClass("NSString"), sel_registerName("stringWithUTF8String:"), message.ptr));
+		```
+		```
+		#arch: c
+		#platform: ios
+		/* TODO: iOS (see #init) */
+		```
+		```
+		#arch: aarch64_use_c
+		#platform: ios
+		/* TODO: iOS (see #init) */
+		```
+	}
+
+	pub func message = (self, out string) {
+		```
+		#arch: c
+		#platform: macos
+		id str = ((id(*)(id, SEL))objc_msgSend)(
+			(id)self->handle, sel_registerName("informativeText"));
+		if (!str) return (nomen_string){ strdup(""), 0 };
+		const char *cstr = ((const char*(*)(id, SEL))objc_msgSend)(
+			str, sel_registerName("UTF8String"));
+		return (nomen_string){ strdup(cstr), (long)strlen(cstr) };
+		```
+		```
+		#arch: aarch64_use_c
+		#platform: macos
+		id str = ((id(*)(id, SEL))objc_msgSend)(
+			(id)self->handle, sel_registerName("informativeText"));
+		if (!str) return (nomen_string){ strdup(""), 0 };
+		const char *cstr = ((const char*(*)(id, SEL))objc_msgSend)(
+			str, sel_registerName("UTF8String"));
+		return (nomen_string){ strdup(cstr), (long)strlen(cstr) };
+		```
+		```
+		#arch: c
+		#platform: ios
+		/* TODO: iOS (see #init) */
+		return (nomen_string){ strdup(""), 0 };
+		```
+		```
+		#arch: aarch64_use_c
+		#platform: ios
+		/* TODO: iOS (see #init) */
+		return (nomen_string){ strdup(""), 0 };
+		```
+	}
+
+	// Append a button (left to right). The FIRST button is the default
+	// (Return); the clicked one's index is what `run` returns. A fresh
+	// NSAlert carries one default button ("OK") — the first
+	// `add_button` REPLACES it, so the count stays what the app adds.
+	pub func add_button = (self, string title) {
+		```
+		#arch: c
+		#platform: macos
+		((void(*)(id, SEL, id))objc_msgSend)(
+			(id)self->handle, sel_registerName("addButtonWithTitle:"),
+			((id(*)(id, SEL, const char*))objc_msgSend)(
+				(id)objc_getClass("NSString"), sel_registerName("stringWithUTF8String:"), title.ptr));
+		```
+		```
+		#arch: aarch64_use_c
+		#platform: macos
+		((void(*)(id, SEL, id))objc_msgSend)(
+			(id)self->handle, sel_registerName("addButtonWithTitle:"),
+			((id(*)(id, SEL, const char*))objc_msgSend)(
+				(id)objc_getClass("NSString"), sel_registerName("stringWithUTF8String:"), title.ptr));
+		```
+		```
+		#arch: c
+		#platform: ios
+		/* TODO: iOS (see #init) */
+		```
+		```
+		#arch: aarch64_use_c
+		#platform: ios
+		/* TODO: iOS (see #init) */
+		```
+	}
+
+	// How many buttons the alert carries.
+	pub func button_count = (self, out int) {
+		```
+		#arch: c
+		#platform: macos
+		id buttons = ((id(*)(id, SEL))objc_msgSend)(
+			(id)self->handle, sel_registerName("buttons"));
+		return (int)((long(*)(id, SEL))objc_msgSend)(buttons, sel_registerName("count"));
+		```
+		```
+		#arch: aarch64_use_c
+		#platform: macos
+		id buttons = ((id(*)(id, SEL))objc_msgSend)(
+			(id)self->handle, sel_registerName("buttons"));
+		return (int)((long(*)(id, SEL))objc_msgSend)(buttons, sel_registerName("count"));
+		```
+		```
+		#arch: c
+		#platform: ios
+		/* TODO: iOS (see #init) */
+		return 0;
+		```
+		```
+		#arch: aarch64_use_c
+		#platform: ios
+		/* TODO: iOS (see #init) */
+		return 0;
+		```
+	}
+
+	// Show the alert modally and return the clicked button's index (0 =
+	// first button). BLOCKS in NSAlert's own modal loop until dismissed —
+	// call it from the event thread when the manual loop can afford to
+	// pause (NSAlert pumps its own events, so the UI stays live).
+	pub func run = (self, out int) {
+		```
+		#arch: c
+		#platform: macos
+		long code = ((long(*)(id, SEL))objc_msgSend)(
+			(id)self->handle, sel_registerName("runModal"));
+		return (int)(code - 1000); // NSModalResponseOK = 1000 + button index
+		```
+		```
+		#arch: aarch64_use_c
+		#platform: macos
+		long code = ((long(*)(id, SEL))objc_msgSend)(
+			(id)self->handle, sel_registerName("runModal"));
+		return (int)(code - 1000); // NSModalResponseOK = 1000 + button index
+		```
+		```
+		#arch: c
+		#platform: ios
+		/* TODO: iOS (see #init) */
+		return 0;
+		```
+		```
+		#arch: aarch64_use_c
+		#platform: ios
+		/* TODO: iOS (see #init) */
+		return 0;
+		```
+	}
+
+	// ── Control trait conformance ──
+	// An alert is a modal, not an in-window view: it measures to nothing and
+	// the layout engine never frames it. The conformance exists so an Alert
+	// can sit in a Control-typed slot without special-casing.
+	pub func set_frame = (ref self, int x, int y, int width, int height) {
+		// No-op: modals are positioned by the window server.
+	}
+
+	pub func intrinsic_size = (self, out Size) {
+		var s = Size()
+		return s
+	}
+
+	pub func measure = (self, BoxConstraints constraints, out Size) {
+		var s = Size()
+		return s
+	}
+
+	func #destroy = () {
+		```
+		#arch: c
+		#platform: macos
+		if (self->handle) {
+			((void(*)(id, SEL))objc_msgSend)((id)self->handle, sel_registerName("release"));
+			self->handle = 0;
+		}
+		```
+		```
+		#arch: aarch64_use_c
+		#platform: macos
+		if (self->handle) {
+			((void(*)(id, SEL))objc_msgSend)((id)self->handle, sel_registerName("release"));
+			self->handle = 0;
+		}
+		```
+		```
+		#arch: c
+		#platform: ios
+		/* TODO: iOS (see #init) */
+		```
+		```
+		#arch: aarch64_use_c
+		#platform: ios
+		/* TODO: iOS (see #init) */
+		```
+	}
+}

package/core/System/Controls/App.nm

@@ -0,0 +1,147 @@
+/**
+ * The App contract: the object Window.run drives
+ *
+ * The WinForms/Swift shape for a manual-loop toolkit: instead of pumping
+ * `Window.process_events` and re-checking sizes in a `while` loop, the app
+ * declares a struct conforming to `App`, moves it into `win.run(mv app)`,
+ * and the WINDOW owns everything else — the event pump, the autorelease
+ * pool, resize detection, and the relayout of the hosted content (the root
+ * `Container` from `win.set_content` plus every `Scrollable.set_content`
+ * document). The app implements four hooks:
+ *
+ * - `start` — called once, after the app has been moved into its final
+ *   storage but before the window is shown. Register the layout roots here
+ *   (`win.set_content(ref grid)`, `scroll.set_content(ref grid)`) and do
+ *   any wiring that needs stable addresses — including click handlers
+ *   (`self.btn.on_click(func () { ... })`).
+ * - `frame` — called every iteration of the run loop with a `FrameEvents`
+ *   value: the full input record for this frame (click kind/coordinates,
+ *   `mouse_button`/`mouse_click_count`/`mouse_modifiers` — every button,
+ *   `scroll_dx`/`scroll_dy`, the keyboard record
+ *   `key_code`/`key_modifiers`/`key_repeat`/`key_up_code`, the pointer
+ *   position `mouse_x`/`mouse_y`, and frame time `dt`), and `resized`
+ *   + the new size when the window's content rect changed. Per-frame value
+ *   polling (slider → progress mirrors), coordinate-driven input that no
+ *   event names, and app-owned pane relayouts live here — registered
+ *   click, right-click, mouse-down, scroll, key, move, and resize handlers
+ *   dispatch earlier, in `handle_events` (the `.on_click` /
+ *   `.on_right_click` / `.on_mouse_down` / `.on_scroll` / `.on_key_down` /
+ *   `.on_key_up` / `.on_mouse_move` / `.on_resize` desugars), and close
+ *   requests consult `close_requested`.
+ * - `handle_events` — the per-frame event pump: drains every registered
+ *   control event (clicks, focus/blur, text input). Declared here as a
+ *   default-empty method; the `.on_<event>(closure)` desugars
+ *   (docs/HANDLERS.md) synthesize the override on conformers with
+ *   registrations, so user code only writes the registration and never
+ *   sees the machinery. New control events extend the pump's arms — the
+ *   App contract is fixed.
+ * - `run_handler` — the up-call protocol (Stage 3): a composite with an
+ *   enrolled event calls back `owner.run_handler(id, ref win)` from its
+ *   `tick` (the app forwards itself down once per tick). Default-empty;
+ *   the desugar synthesizes the override dispatching ids to the app's
+ *   `.on_<event>` handlers.
+ *
+ * Handlers are METHODS on the app (the `ref self` receiver), so app state —
+ * every control field — is reachable without lambda captures (capturing a
+ * control MOVES it; a capture-free method reference moves nothing). The
+ * `.on_click` desugar is that shape with registration ergonomics: the
+ * closure you write IS hoisted into a hidden method, and the dispatch
+ * borrow of `self` is taken by the run loop per frame.
+ **/
+pub trait App {
+	// Called once before the window is shown, after the app is in its
+	// final storage. Register layout roots here.
+	func start = (ref self, ref Window win) {
+	}
+
+	// Called every frame until the window closes.
+	func frame = (ref self, ref Window win, FrameEvents ev) {
+	}
+
+	// The per-frame event pump: drains every registered control event —
+	// clicks, focus/blur, text input — through arms the `.on_<event>`
+	// desugar (docs/HANDLERS.md) synthesizes on conformers with
+	// registrations: one hidden method per closure, one drain arm per
+	// registered control, one event-source prologue per family.
+	// `Window.run` calls it before `frame`. New control events are new arms
+	// in this one slot — the App contract never grows with the event
+	// catalog. Conformers without registrations inherit this empty default
+	// (trait defaults have precedent: `Enumerable.length`).
+	func handle_events = (ref self, ref Window win) {
+	}
+
+	// The up-call protocol (docs/HANDLERS.md Stage 3): a composite the app
+	// has enrolled events on calls back into this — `owner.run_handler(id,
+	// ref win)` from its `tick` — one vtable hop into the desugar's
+	// synthesized override, whose arms dispatch the id to the app's handler.
+	// The borrow flows down per call; nothing outlives it. Default-empty,
+	// like `handle_events`.
+	func run_handler = (ref self, int id, ref Window win) {
+	}
+
+	// Close interception (the unsaved-changes pattern): run consults this
+	// on the frame after the user requests close (the red button — the
+	// delegate refuses the native close and sets a pending flag). Return
+	// false to refuse: the window stays, the flag is cleared, and a later
+	// close request consults again. Programmatic `win.close()` is FORCED
+	// and bypasses this — handlers closing their own window never trip the
+	// interception. Default: allow.
+	func close_requested = (ref self, ref Window win, out bool) {
+		return true
+	}
+}
+
+/**
+ * One frame's input state, passed to App.frame
+ *
+ * Pure scalars, so the by-value parameter copies safely (no destroy).
+ * Click coordinates are the window's content coordinates, top-left origin
+ * (the same values `Window.click_x`/`click_y` report) — translate through
+ * `content_click` before hit-testing controls hosted on a Scrollable.
+ **/
+pub mv struct FrameEvents {
+	// 0 = no mouse-down this frame, 1 = left, 2 = right (edge-triggered:
+	// only the frame that pumped the event reports it).
+	pub var int click = 0
+	pub var int click_x = -1
+	pub var int click_y = -1
+	// The full mouse record for this frame (0 = no mouse-down): the 1-based
+	// button number (1 left, 2 right, 3 middle, 4+ extra buttons), the
+	// AppKit click count (2 = double-click), and the device-independent
+	// modifier flags (Command = 0x100000, Option = 0x80000, Control =
+	// 0x40000, Shift = 0x20000). The same values the `win.mouse_button()` /
+	// `mouse_click_count()` / `mouse_modifiers()` getters report to
+	// `on_mouse_down` handlers. `click` remains the left/right compat view.
+	pub var int mouse_button = 0
+	pub var int mouse_click_count = 0
+	pub var int mouse_modifiers = 0
+	// This frame's accumulated scroll-wheel deltas (dy positive scrolling
+	// up/away, dx positive right; trackpad frames sum every small event).
+	// `Scrollable.on_scroll` is the registered-handler form.
+	pub var int scroll_dx = 0
+	pub var int scroll_dy = 0
+	// The keyboard record for this frame (-1 = no key this frame): the
+	// hardware keycode of the last key-down (Space = 49, Return = 36,
+	// arrows = 123–126, letters a…z = 0–25), the modifiers at key-down,
+	// whether it was an auto-repeat, and the keycode of the last key-up.
+	// `on_key_down` / `on_key_up` are the registered-handler forms; text
+	// ENTRY flows through `on_input` (the field editor), not here.
+	pub var int key_code = -1
+	pub var int key_modifiers = 0
+	pub var bool key_repeat = false
+	pub var int key_up_code = -1
+	// The pointer-MOVE record for this frame (-1 = no movement): the
+	// current pointer position. `on_mouse_move` is the registered-handler
+	// form; hover/tooltips hit-test this against Container.contains.
+	pub var int mouse_x = -1
+	pub var int mouse_y = -1
+	// Milliseconds since the previous frame (0 on the first) — the
+	// animation clock. `win.dt()` reports the same value.
+	pub var int dt = 0
+	// True when the window's content rect changed since the last frame —
+	// the framework has already re-laid-out the registered roots; re-layout
+	// App-owned panes (tab pages, split panes) here.
+	pub var bool resized = false
+	pub var int width = 0
+	pub var int height = 0
+}