@geastack/apple 0.2.8

package/targets/ios/main/renderer/view_reconciler.mm

@@ -0,0 +1,274 @@
+#import <QuartzCore/QuartzCore.h>
+
+#include "ios_renderer_internal.h"
+#include "canvas_view.h"
+#include "image_bridge.h"
+
+#include "ui/tree_internal.h"
+
+#import <objc/runtime.h>
+
+#include <algorithm>
+#include <cmath>
+#include <cstring>
+
+namespace gea::ios::renderer {
+namespace {
+
+bool nearlyEqual(CGFloat a, CGFloat b)
+{
+	return std::fabs(a - b) <= 0.5;
+}
+
+bool rectNearlyEqual(CGRect a, CGRect b)
+{
+	return nearlyEqual(a.origin.x, b.origin.x) &&
+	       nearlyEqual(a.origin.y, b.origin.y) &&
+	       nearlyEqual(a.size.width, b.size.width) &&
+	       nearlyEqual(a.size.height, b.size.height);
+}
+
+bool viewMatchesNode(UIView *view, const gea::embedded::ui::Node &node, const char *tagName)
+{
+	using gea::embedded::ui::NodeType;
+	if (node.type == NodeType::View && tagName && std::strcmp(tagName, "input") == 0) return false;
+	if (isScrollableNode(node)) return [view isKindOfClass:[GeaNativeScrollContainer class]];
+	switch (node.type) {
+	case NodeType::Text: return [view isKindOfClass:[GeaNativeLabel class]];
+	case NodeType::Button: return [view isKindOfClass:[GeaNativeButton class]];
+	case NodeType::Image: return [view isKindOfClass:[UIImageView class]];
+	case NodeType::Canvas: return [view isKindOfClass:[GeaCanvasView class]];
+	default: return [view isKindOfClass:[UIView class]] &&
+	                ![view isKindOfClass:[UILabel class]] &&
+	                ![view isKindOfClass:[UIControl class]] &&
+	                ![view isKindOfClass:[UIImageView class]] &&
+	                ![view isKindOfClass:[UIScrollView class]] &&
+	                ![view isKindOfClass:[GeaCanvasView class]];
+	}
+}
+
+UIView *makeViewForType(gea::embedded::ui::NodeType type, const char *tagName,
+                        const gea::embedded::ui::Node &node)
+{
+	using gea::embedded::ui::NodeType;
+	if (type == NodeType::View && tagName && std::strcmp(tagName, "input") == 0) return nil;
+	if (isScrollableNode(node)) return [[GeaNativeScrollContainer alloc] initWithFrame:CGRectZero];
+	switch (type) {
+	case NodeType::Text: {
+		GeaNativeLabel *label = [[GeaNativeLabel alloc] initWithFrame:CGRectZero];
+		label.numberOfLines = 0;
+		label.lineBreakMode = NSLineBreakByWordWrapping;
+		label.userInteractionEnabled = NO;
+		label.backgroundColor = UIColor.clearColor;
+		return label;
+	}
+	case NodeType::Image: {
+		UIImageView *imageView = [[UIImageView alloc] initWithFrame:CGRectZero];
+		imageView.userInteractionEnabled = NO;
+		return imageView;
+	}
+	case NodeType::Canvas: return [[GeaCanvasView alloc] initWithFrame:CGRectZero];
+	case NodeType::Button: {
+		GeaNativeButton *button = [GeaNativeButton buttonWithType:UIButtonTypeCustom];
+		button.nodeId = -1;
+		button.backgroundColor = UIColor.clearColor;
+		button.opaque = NO;
+		[button setTitle:nil forState:UIControlStateNormal];
+		[button addTarget:button action:@selector(handleTouchDown:) forControlEvents:UIControlEventTouchDown];
+		[button addTarget:button action:@selector(handleTouchDrag:) forControlEvents:UIControlEventTouchDragInside | UIControlEventTouchDragOutside];
+		[button addTarget:button action:@selector(handleTouchUpInside:) forControlEvents:UIControlEventTouchUpInside];
+		[button addTarget:button action:@selector(handleTouchUpOutside:) forControlEvents:UIControlEventTouchUpOutside];
+		[button addTarget:button action:@selector(handleTouchCancel:) forControlEvents:UIControlEventTouchCancel];
+		return button;
+	}
+	case NodeType::View:
+	case NodeType::VirtualList:
+	default: {
+		UIView *view = [[UIView alloc] initWithFrame:CGRectZero];
+		view.userInteractionEnabled = NO;
+		return view;
+	}
+	}
+}
+
+void applyViewStyle(UIView *view, const gea::embedded::ui::Node &node,
+                    int parentAbsX, int parentAbsY, CGFloat scale)
+{
+	const CGFloat x = static_cast<CGFloat>(node.layout.x - parentAbsX) * scale;
+	const CGFloat y = static_cast<CGFloat>(node.layout.y - parentAbsY) * scale;
+	const CGFloat w = static_cast<CGFloat>(node.layout.width) * scale;
+	const CGFloat h = static_cast<CGFloat>(node.layout.height) * scale;
+
+	// UIKit's `frame` is undefined while a non-identity transform is applied, and a
+	// transform always rotates about the layer's anchor point (center) rather than
+	// the CSS transform-origin. Re-feeding `frame` every animation frame under a
+	// live rotation corrupts the bounds, ballooning rotated nodes (e.g. clock
+	// hands). For rotated nodes drive geometry through bounds + center + anchorPoint
+	// so the size stays correct and the rotation pivots about transform-origin;
+	// otherwise keep the plain frame path that scroll containers rely on.
+	if ((gea::embedded::ui::rstyle(node.style).transform_rotate % 3600) != 0) {
+		const CGFloat originX = static_cast<CGFloat>(gea::embedded::ui::rstyle(node.style).transform_origin_x) / 1000.0;
+		const CGFloat originY = static_cast<CGFloat>(gea::embedded::ui::rstyle(node.style).transform_origin_y) / 1000.0;
+		const CGPoint anchor = CGPointMake(originX, originY);
+		if (!CGPointEqualToPoint(view.layer.anchorPoint, anchor)) view.layer.anchorPoint = anchor;
+		if (!nearlyEqual(view.bounds.size.width, w) || !nearlyEqual(view.bounds.size.height, h)) {
+			CGRect bounds = view.bounds;
+			bounds.size = CGSizeMake(w, h);
+			view.bounds = bounds;
+		}
+		const CGPoint center = CGPointMake(x + originX * w, y + originY * h);
+		if (!nearlyEqual(view.center.x, center.x) || !nearlyEqual(view.center.y, center.y)) {
+			view.center = center;
+		}
+		const CGFloat degrees = static_cast<CGFloat>(gea::embedded::ui::rstyle(node.style).transform_rotate) / 10.0;
+		view.transform = CGAffineTransformMakeRotation(degrees * static_cast<CGFloat>(M_PI / 180.0));
+	} else {
+		if (!CGAffineTransformIsIdentity(view.transform)) view.transform = CGAffineTransformIdentity;
+		if (!CGPointEqualToPoint(view.layer.anchorPoint, CGPointMake(0.5, 0.5))) {
+			view.layer.anchorPoint = CGPointMake(0.5, 0.5);
+		}
+		const CGRect nextFrame = CGRectMake(x, y, w, h);
+		if (!rectNearlyEqual(view.frame, nextFrame)) view.frame = nextFrame;
+	}
+	view.hidden = node.style.display == 1 || node.style.opacity == 0 || w <= 0 || h <= 0;
+	view.alpha = static_cast<CGFloat>(node.style.opacity) / 255.0;
+
+	view.backgroundColor = node.style.has_bg ? rgb565ToUIColor(node.style.bg_color) : UIColor.clearColor;
+	view.layer.borderWidth = static_cast<CGFloat>(std::max<int>(0, node.style.border_width)) * scale;
+	view.layer.borderColor = rgb565ToUIColor(node.style.border_color).CGColor;
+	const int tl = std::max<int>(0, node.style.border_radius[0]);
+	const int tr = std::max<int>(0, node.style.border_radius[1]);
+	const int br = std::max<int>(0, node.style.border_radius[2]);
+	const int bl = std::max<int>(0, node.style.border_radius[3]);
+	const CGFloat radius = (tl == tr && tr == br && br == bl)
+	                           ? static_cast<CGFloat>(tl)
+	                           : static_cast<CGFloat>(tl + tr + br + bl) / 4.0;
+	view.layer.cornerRadius = radius * scale;
+	view.clipsToBounds = view.layer.cornerRadius > 0 || node.style.overflow == 1 || node.style.overflow == 2;
+}
+
+void applyImageProps(UIImageView *imageView, const gea::embedded::ui::Node &node)
+{
+	NSNumber *currentId = objc_getAssociatedObject(imageView, "gea.image_id");
+	if (!currentId || currentId.intValue != node.image_id) {
+		imageView.image = gea::ios::imageForId(node.image_id);
+		objc_setAssociatedObject(imageView, "gea.image_id", @(node.image_id), OBJC_ASSOCIATION_RETAIN_NONATOMIC);
+	}
+	switch (node.style.image_fit) {
+	case 1: imageView.contentMode = UIViewContentModeScaleAspectFit; break;
+	case 2: imageView.contentMode = UIViewContentModeScaleAspectFill; break;
+	case 3: imageView.contentMode = UIViewContentModeCenter; break;
+	case 4: imageView.contentMode = UIViewContentModeScaleAspectFit; break;
+	default: imageView.contentMode = UIViewContentModeScaleToFill;
+	}
+	imageView.clipsToBounds = YES;
+}
+
+void applyCanvasProps(GeaCanvasView *canvasView, int nodeId)
+{
+	canvasView.nodeId = nodeId;
+	[canvasView setNeedsDisplay];
+}
+
+void applyTypeSpecificProps(UIView *view, const gea::embedded::ui::Node &node, int nodeId, CGFloat scale)
+{
+	using gea::embedded::ui::NodeType;
+	if ([view isKindOfClass:[GeaNativeScrollContainer class]]) {
+		applyScrollProps((GeaNativeScrollContainer *)view, node, nodeId, scale);
+	} else if (node.type == NodeType::Button) {
+		applyButtonProps((GeaNativeButton *)view, node, nodeId, scale);
+	} else if (node.type == NodeType::Text) {
+		applyTextProps((GeaNativeLabel *)view, node, scale);
+	} else if (node.type == NodeType::Image) {
+		applyImageProps((UIImageView *)view, node);
+	} else if (node.type == NodeType::Canvas) {
+		applyCanvasProps((GeaCanvasView *)view, nodeId);
+	}
+}
+
+UIView *ensureViewForNode(int nodeId, const gea::embedded::ui::Node &node)
+{
+	auto &tree = gea::embedded::ui::Tree::instance();
+	NSNumber *key = @(nodeId);
+	UIView *view = nodeIdToView()[key];
+	const char *tagName = tree.tagName(nodeId);
+	if (view && !viewMatchesNode(view, node, tagName)) {
+		[view removeFromSuperview];
+		[nodeIdToView() removeObjectForKey:key];
+		view = nil;
+	}
+	if (view) return view;
+	view = makeViewForType(node.type, tagName, node);
+	if (!view) return nil;
+	objc_setAssociatedObject(view, "gea.node_id", key, OBJC_ASSOCIATION_RETAIN_NONATOMIC);
+	nodeIdToView()[key] = view;
+	return view;
+}
+
+void syncRecursive(int nodeId, UIView *parent, int parentAbsX, int parentAbsY, CGFloat scale,
+                   NSMutableSet<NSNumber *> *unseen)
+{
+	using namespace gea::embedded::ui;
+	Tree &tree = Tree::instance();
+	if (nodeId < 0 || nodeId >= tree.nodeCount()) return;
+	const Node &node = tree.node(nodeId);
+	const char *tagName = tree.tagName(nodeId);
+	if (node.type == NodeType::View && tagName && std::strcmp(tagName, "input") == 0) return;
+
+	NSNumber *key = @(nodeId);
+	[unseen removeObject:key];
+	UIView *view = ensureViewForNode(nodeId, node);
+	if (!view) return;
+	if (view.superview != parent) {
+		[view removeFromSuperview];
+		[parent addSubview:view];
+	}
+	applyViewStyle(view, node, parentAbsX, parentAbsY, scale);
+	applyTypeSpecificProps(view, node, nodeId, scale);
+
+	UIView *parentForChildren = view;
+	int parentAbsXForChildren = node.layout.x;
+	int parentAbsYForChildren = node.layout.y;
+	if ([view isKindOfClass:[GeaNativeScrollContainer class]]) {
+		parentForChildren = ((GeaNativeScrollContainer *)view).contentView;
+		parentAbsYForChildren = node.layout.y - tree.scrollTop(nodeId);
+	}
+
+	for (int child = node.first_child; child >= 0; child = tree.node(child).next_sibling) {
+		syncRecursive(child, parentForChildren, parentAbsXForChildren, parentAbsYForChildren, scale, unseen);
+	}
+}
+
+}  // namespace
+
+void syncNativeTree(UIView *parentForRoot, int rootNodeId)
+{
+	using namespace gea::embedded::ui;
+	Tree &tree = Tree::instance();
+	if (!parentForRoot || rootNodeId < 0 || rootNodeId >= tree.nodeCount()) return;
+
+	NSMutableSet<NSNumber *> *unseen = [NSMutableSet setWithArray:[nodeIdToView() allKeys]];
+	const CGFloat scale = canvasScaleForView(parentForRoot);
+	syncRecursive(rootNodeId, parentForRoot, 0, 0, scale, unseen);
+
+	for (NSNumber *gone in unseen) {
+		UIView *view = nodeIdToView()[gone];
+		[view removeFromSuperview];
+		[nodeIdToView() removeObjectForKey:gone];
+	}
+}
+
+void teardownNativeTree()
+{
+	for (UIView *view in [nodeIdToView() allValues]) {
+		[view removeFromSuperview];
+	}
+	[nodeIdToView() removeAllObjects];
+}
+
+bool hasNativeTree()
+{
+	return nodeIdToView().count > 0;
+}
+
+}  // namespace gea::ios::renderer

package/targets/macos/Info.plist.in

@@ -0,0 +1,26 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+	<key>CFBundleDevelopmentRegion</key><string>en</string>
+	<key>CFBundleExecutable</key><string>@APP_EXEC@</string>
+	<key>CFBundleIdentifier</key><string>com.gea.@APP_ID@</string>
+	<key>CFBundleInfoDictionaryVersion</key><string>6.0</string>
+	<key>CFBundleName</key><string>@APP_NAME@</string>
+	<key>CFBundleIconFile</key><string>AppIcon</string>
+	<key>CFBundlePackageType</key><string>APPL</string>
+	<key>CFBundleShortVersionString</key><string>0.1.0</string>
+	<key>CFBundleVersion</key><string>1</string>
+	<key>LSMinimumSystemVersion</key><string>11.0</string>
+	<key>NSHighResolutionCapable</key><true/>
+	<key>NSPrincipalClass</key><string>NSApplication</string>
+	<!-- The fetch facade rides NSURLSession, which enforces App Transport
+	     Security. Framework apps talk to plain-http endpoints (LAN devices,
+	     local dev servers) exactly as they do on the ESP32 and raspberry-pi-os
+	     targets, where no ATS exists — allow those loads for parity. -->
+	<key>NSAppTransportSecurity</key>
+	<dict>
+		<key>NSAllowsArbitraryLoads</key><true/>
+	</dict>
+</dict>
+</plist>

package/targets/macos/README.md

@@ -0,0 +1,131 @@
+# macOS target
+
+Build a gea-embedded app as a native Cocoa Mac app — `<Button>` becomes
+`NSButton`, `<Text>` becomes `NSTextField`, `<View>` becomes `NSView`,
+`<Image>` becomes `NSImageView`, `<canvas>` is a custom `NSView` backed by
+CoreGraphics, `<virtual-list>` is `NSScrollView`. The flex layout engine
+in `@geastack/engine`'s `ui/layout.cpp` computes frames; AppKit draws.
+
+## Build
+
+    targets/macos/build-macos.sh <app-id>
+    open dist/macos/<app-id>/<AppName>.app
+
+## Where the build writes
+
+Everything this target produces lands under the **app project** being built,
+never under this package: `<app>/dist/macos/<app-id>/<AppName>.app` for the
+bundle, `<app>/dist/macos/<app-id>/build/` for objects and PCHs, and
+`<app>/dist/macos/.generated/<app-id>/` for the generated C++. The app is the
+directory the build runs in: `gea build` runs this script in the app, and a
+direct run uses the invocation directory.
+
+This package is installed into an app's `node_modules`, so a package-relative
+output path hid every build inside a directory nobody opens and npm deletes on
+the next install. Set `GEA_MACOS_OUTPUT_DIR` to put the whole tree elsewhere.
+
+`<app-id>` is currently any name; when no generated app is present under
+`dist/macos/.generated/<app-id>/` the build falls back to a built-in
+Phase B smoke app (`macos_smoke_app.cpp`) that exercises View / Text /
+Button / event dispatch. Real geatsc-compiled apps drop into
+`dist/macos/.generated/` and supersede the smoke automatically — the
+JSX → C++ pipeline for the macOS target is a follow-up.
+
+## Hard-muted builds must prove artifact provenance
+
+For any verification that must not produce audio, configure the final native
+mute source and its literal on the build itself:
+
+```sh
+GEA_MACOS_HARD_MUTE_SOURCE=/absolute/path/to/the/committed/native/audio_source.mm \
+GEA_MACOS_HARD_MUTE_GATE=THE_NATIVE_MUTE_ENVIRONMENT_LITERAL \
+targets/macos/build-macos.sh <app-id>
+```
+
+Both variables are required together. After code signing, the build writes
+`dist/<app-id>/build/hard-mute-artifact-provenance.json` and statically proves:
+
+- the selected source is the committed blob at the recorded dependency revision;
+- exactly one linked object depends on that source and contains the gate;
+- `link.sig` records that exact object;
+- source, translation unit, depfile, link signature, object, and executable
+  SHA-256 values still match; and
+- the signed executable contains the same gate.
+
+Immediately before launch, rerun the no-launch check against the exact binary:
+
+```sh
+node targets/macos/preflight-hard-muted-artifact.mjs verify \
+  --manifest /absolute/path/to/build/hard-mute-artifact-provenance.json \
+  --executable "/absolute/path/to/App.app/Contents/MacOS/App" \
+  --source /absolute/path/to/the/committed/native/audio_source.mm \
+  --gate THE_NATIVE_MUTE_ENVIRONMENT_LITERAL
+```
+
+Do not launch unless this prints
+`PASS artifact-static-hard-mute-gate=present`. The checker reads files and Git
+metadata only; it does not execute the app or open an audio device. Any missing
+manifest, gate, changed dependency revision, or changed source/object/executable
+fails closed.
+
+## Architecture
+
+    JSX (or smoke C++) → Document / Tree mutations → Tree::computeLayout
+      → MacosRenderer::sync (walks the laid-out tree)
+        → ensureViewForNode dispatches on NodeType
+          → NSView / NSTextField / NSButton / NSImageView / GeaCanvasView
+            / NSScrollView
+          → applyViewStyle (frame, background, border, cornerRadius,
+            opacity, rotation, masksToBounds)
+          → applyTypeSpecificProps (per-type content)
+
+The display-list pipeline (`ui/render.cpp`, `ui/dirty_regions.cpp`) is
+bypassed on this target — AppKit owns its own invalidation. The
+custom touch/momentum code in `ui/input.cpp` is bypassed too;
+NSClickGestureRecognizer (on Views/anything with a pressId) and
+NSButton target/action dispatch Click+Press events back into
+`Tree::dispatchEvent`. NSScrollView gives VirtualList native momentum
+and elastic boundaries.
+
+The only intrusive change to the framework is `Tree::computeLayout`
+(peer of `refresh`) — it runs just the flex pass without building a
+display list, so other targets keep calling `refresh()` unchanged.
+
+## Frame loop
+
+`macos_main.mm` schedules a 60Hz `NSTimer` on `NSRunLoopCommonModes` so
+the loop keeps firing during live window-resize and other event-
+tracking modes. Each tick:
+
+1. `gea_embedded_app_frame(timestampMs)` lets the app update state
+2. Force `style.width/height` on the mounted root to the current window
+   content size — this is the macOS convention that makes the root
+   viewport track resize automatically
+3. `Tree::computeLayout(root, w, h)`
+4. `MacosRenderer::sync(rootView, root)`
+
+## Verification stub
+
+Running with `GEA_MACOS_VERIFY_ONCE=1` logs the tree, NSView hierarchy,
+fires a press on the first Button node twice, then exits. Useful for
+quick regression checks after changes to the renderer.
+
+## What works / what's stubbed
+
+Native: View / Text / Button / Image / Canvas / VirtualList; flex
+layout; click + press events; trackpad-momentum scroll; window resize
+(live + final); standard menu bar with Cmd-Q.
+
+Audio is real: `targets/shared/apple_audio.mm` (shared with iOS) backs
+`gea::platform::audio` with AVAudioEngine — sample-accurately scheduled,
+mixed oscillators on an `AVAudioSourceNode`, plus `playFile`/`playPcm` on
+`AVAudioPlayerNode`s. `targets/shared/build-audio-selftest.sh` builds and
+runs the measurement harness (offline render, RMS + measured frequency);
+`GEA_AUDIO_CAPTURE_RAW=<path>` captures a real app run for
+`targets/shared/analyze-audio-capture.mjs`.
+
+Stubbed for v1: WiFi (`macos_wifi`), BLE (`macos_ble`), IMU (`macos_imu`)
+— present only as link-satisfying no-ops; apps that depend on these will
+run but those calls return inert values. Custom font bundling, code
+signing with entitlements, notarisation, and the JSX → C++ pipeline for
+this target are follow-ups.

package/targets/macos/build-child-lifecycle.sh

@@ -0,0 +1,119 @@
+#!/usr/bin/env bash
+
+# Child-process lifecycle support for build-macos.sh. Keep this Bash 3.2
+# compatible: macOS still ships that version as /bin/bash.
+ACTIVE_BUILD_CHILD_PID=""
+PIDS=()
+
+macos_run_tracked_child() {
+  if [[ -n "$ACTIVE_BUILD_CHILD_PID" ]]; then
+    echo "Internal error: macOS build child $ACTIVE_BUILD_CHILD_PID is still active" >&2
+    return 1
+  fi
+
+  "$@" &
+  ACTIVE_BUILD_CHILD_PID="$!"
+  local child_pid="$ACTIVE_BUILD_CHILD_PID"
+  local status=0
+  if wait "$child_pid"; then
+    status=0
+  else
+    status="$?"
+  fi
+  ACTIVE_BUILD_CHILD_PID=""
+  return "$status"
+}
+
+macos_build_process_tree() {
+  local roots="$1"
+  if [[ -n "${MACOS_BUILD_PROCESS_TABLE_FILE:-}" ]]; then
+    cat "$MACOS_BUILD_PROCESS_TABLE_FILE"
+  else
+    ps -axo pid=,ppid= 2>/dev/null
+  fi | awk -v roots="$roots" '
+    BEGIN {
+      count = split(roots, root, " ")
+      for (i = 1; i <= count; i++) {
+        if (root[i] ~ /^[0-9]+$/) wanted[root[i]] = 1
+      }
+    }
+    {
+      pid[NR] = $1
+      parent[NR] = $2
+    }
+    END {
+      changed = 1
+      while (changed) {
+        changed = 0
+        for (i = 1; i <= NR; i++) {
+          if ((parent[i] in wanted) && wanted[parent[i]] == 1 && !(pid[i] in wanted)) {
+            wanted[pid[i]] = 1
+            changed = 1
+          }
+        }
+      }
+      for (candidate in wanted) {
+        if (wanted[candidate] == 1) print candidate
+      }
+    }
+  '
+}
+
+macos_build_pid_is_running() {
+  local pid="$1"
+  local state=""
+  kill -0 "$pid" 2>/dev/null || return 1
+  state="$(ps -o stat= -p "$pid" 2>/dev/null | awk 'NR == 1 { print $1 }')"
+  [[ -n "$state" && "$state" != Z* ]]
+}
+
+macos_terminate_and_reap_build_children() {
+  local roots=()
+  local tree=()
+  local root_list=""
+  local pid=""
+  local duplicate=0
+  local attempt=0
+  local any_running=0
+
+  if [[ "$ACTIVE_BUILD_CHILD_PID" =~ ^[0-9]+$ ]]; then
+    roots+=("$ACTIVE_BUILD_CHILD_PID")
+  fi
+  for pid in ${PIDS[@]+"${PIDS[@]}"}; do
+    [[ "$pid" =~ ^[0-9]+$ ]] || continue
+    duplicate=0
+    local existing=""
+    for existing in ${roots[@]+"${roots[@]}"}; do
+      if [[ "$existing" == "$pid" ]]; then duplicate=1; break; fi
+    done
+    if (( duplicate == 0 )); then roots+=("$pid"); fi
+  done
+  (( ${#roots[@]} > 0 )) || return 0
+
+  root_list="${roots[*]}"
+  while IFS= read -r pid; do
+    [[ "$pid" =~ ^[0-9]+$ ]] && tree+=("$pid")
+  done < <(macos_build_process_tree "$root_list")
+
+  # Signal the captured descendants and their direct build parents while the
+  # app-local lock is still held. The second pass escalates stubborn compiler
+  # processes; all directly-owned children are then waited to avoid zombies.
+  for pid in ${tree[@]+"${tree[@]}"}; do kill -TERM "$pid" 2>/dev/null || true; done
+  attempt=0
+  while (( attempt < 20 )); do
+    any_running=0
+    for pid in ${tree[@]+"${tree[@]}"}; do
+      if macos_build_pid_is_running "$pid"; then any_running=1; break; fi
+    done
+    (( any_running != 0 )) || break
+    sleep 0.05
+    attempt=$((attempt + 1))
+  done
+  for pid in ${tree[@]+"${tree[@]}"}; do
+    if macos_build_pid_is_running "$pid"; then kill -KILL "$pid" 2>/dev/null || true; fi
+  done
+  for pid in ${roots[@]+"${roots[@]}"}; do wait "$pid" 2>/dev/null || true; done
+
+  ACTIVE_BUILD_CHILD_PID=""
+  PIDS=()
+}