@geastack/apple 0.2.8

package/targets/macos/check-module-graph-freshness.mjs

@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+
+import fs from 'node:fs'
+import path from 'node:path'
+import crypto from 'node:crypto'
+
+const args = process.argv.slice(2)
+
+function value(name) {
+  const index = args.indexOf(name)
+  return index >= 0 ? args[index + 1] || '' : ''
+}
+
+const graphPath = path.resolve(value('--graph') || '')
+const referencePath = path.resolve(value('--reference') || '')
+if (!value('--graph') || !value('--reference')) {
+  process.stderr.write('usage: check-module-graph-freshness.mjs --graph <graph.json> --reference <stamp>\n')
+  process.exit(1)
+}
+if (!fs.existsSync(graphPath) || !fs.existsSync(referencePath)) process.exit(0)
+
+const graph = JSON.parse(fs.readFileSync(graphPath, 'utf8'))
+const graphDir = path.dirname(graphPath)
+const referenceMtime = fs.statSync(referencePath).mtimeMs
+const visited = new Set()
+
+function realInputFor(module) {
+  if (module?.assetSource && path.isAbsolute(module.assetSource)) return module.assetSource
+  const moduleFile = module?.file
+  if (!moduleFile || !path.isAbsolute(moduleFile)) return ''
+  if (fs.existsSync(moduleFile)) return moduleFile
+  // The native asset Vite plugin represents binary imports as virtual sibling
+  // modules. The graph records the virtual id; the real binary remains the
+  // generation input whose content/mtime must invalidate generated C++.
+  const assetStubSuffix = '.geaassetstub.js'
+  if (moduleFile.endsWith(assetStubSuffix)) {
+    return moduleFile.slice(0, -assetStubSuffix.length)
+  }
+  return moduleFile
+}
+
+for (const module of Array.isArray(graph.modules) ? graph.modules : []) {
+  const input = realInputFor(module)
+  if (!input || visited.has(input)) continue
+  visited.add(input)
+  if (!fs.existsSync(input)) {
+    process.stdout.write(`missing:${input}\n`)
+    process.exit(0)
+  }
+  const stat = fs.statSync(input)
+  if (stat.mtimeMs > referenceMtime) {
+    process.stdout.write(`newer:${input}\n`)
+    process.exit(0)
+  }
+
+  // Static assets are represented in the compiler graph by synthetic JS
+  // modules, so their originalSource snapshot contains the URL-export module,
+  // not the binary bytes. Compare the content digest captured in the graph to
+  // catch restored/backdated binary changes exactly.
+  if (module.assetSource && typeof module.assetSha256 === 'string') {
+    const currentSha256 = crypto.createHash('sha256').update(fs.readFileSync(input)).digest('hex')
+    if (currentSha256 !== module.assetSha256) {
+      process.stdout.write(`content:${input}\n`)
+      process.exit(0)
+    }
+    continue
+  }
+
+  // Most module-graph original snapshots are byte-for-byte source copies.
+  // Comparing those catches checkouts/restores that preserve or backdate
+  // mtimes. Some Vite plugins intentionally rewrite their "original" snapshot;
+  // detect that baseline and leave those modules on the mtime path above.
+  if (!module.originalSource) continue
+  const snapshot = path.resolve(graphDir, module.originalSource)
+  if (!fs.existsSync(snapshot)) continue
+  const current = fs.readFileSync(input)
+  const captured = fs.readFileSync(snapshot)
+  if (current.length === captured.length && !current.equals(captured)) {
+    process.stdout.write(`content:${input}\n`)
+    process.exit(0)
+  }
+}

package/targets/macos/compiler-input-fingerprint.mjs

@@ -0,0 +1,32 @@
+import { createHash } from 'node:crypto'
+import fs from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+// These are the compiler's shipped modules and runtime sources, not the native
+// executables, PCHs, package archives, or logs a tool may have left in dist.
+export function compilerInputFingerprint(root) {
+  const files = []
+  const visit = (directory, accepts) => {
+    for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+      const file = path.join(directory, entry.name)
+      if (entry.isDirectory()) visit(file, accepts)
+      else if (entry.isFile() && accepts(entry.name)) files.push(file)
+    }
+  }
+  visit(path.join(root, 'dist'), name => name.endsWith('.js') || name.endsWith('.d.ts'))
+  // cli-emit copies these from source, so hashing only dist could reuse stale
+  // runtime output after a header change. Include new runtime files as well.
+  visit(path.join(root, 'src/targets/cpp/runtime'), () => true)
+  files.push(path.join(root, 'package.json'))
+  const hash = createHash('sha256').update('gea-compiler-inputs-v1\0')
+  for (const file of files.sort()) {
+    hash.update(path.relative(root, file)).update('\0').update(fs.readFileSync(file)).update('\0')
+  }
+  return hash.digest('hex')
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  if (!process.argv[2]) throw new Error('Usage: compiler-input-fingerprint.mjs <compiler-root>')
+  process.stdout.write(compilerInputFingerprint(path.resolve(process.argv[2])))
+}

package/targets/macos/finalize-apple-native-output.mjs

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+
+import fs from 'node:fs'
+import path from 'node:path'
+
+function fail(message) {
+  process.stderr.write(`${message}\n`)
+  process.exit(1)
+}
+
+function readOption(name) {
+  const index = process.argv.indexOf(name)
+  return index >= 0 ? process.argv[index + 1] : undefined
+}
+
+function hasFlag(name) {
+  return process.argv.includes(name)
+}
+
+function isNonEmptyFile(filePath) {
+  try {
+    const stats = fs.statSync(filePath)
+    return stats.isFile() && stats.size > 0
+  } catch {
+    return false
+  }
+}
+
+const outDirOption = readOption('--out-dir')
+if (!outDirOption) fail('usage: finalize-apple-native-output.mjs --out-dir <generated-dir>')
+
+const outDir = path.resolve(outDirOption)
+const checkOnly = hasFlag('--check-only')
+const expectedState = readOption('--expected-state')
+if (expectedState !== undefined && expectedState !== '0' && expectedState !== '1') {
+  fail('--expected-state must be 0 or 1')
+}
+const supportPath = path.join(outDir, 'generated_support.hpp')
+const metadataPath = path.join(outDir, 'gea-apple-metadata.json')
+const bridgeDir = path.join(outDir, 'gea', 'apple')
+const bridgeHeader = path.join(bridgeDir, 'native_bridge.h')
+const bridgeSource = path.join(bridgeDir, 'native_bridge.mm')
+const bridgeInclude = '#include "gea/apple/native_bridge.h"'
+if (!isNonEmptyFile(supportPath)) {
+  fail(`generation did not produce a non-empty generated_support.hpp: ${supportPath}`)
+}
+const support = fs.readFileSync(supportPath, 'utf8')
+
+let state
+if (support.includes(bridgeInclude)) {
+  const missing = [bridgeHeader, bridgeSource].filter((file) => !isNonEmptyFile(file))
+  if (missing.length > 0) {
+    fail(`generated_support.hpp includes the Apple native bridge, but generation did not produce non-empty files: ${missing.join(', ')}`)
+  }
+  state = '1'
+} else {
+  state = '0'
+}
+
+if (expectedState !== undefined && state !== expectedState) {
+  fail(`generated Apple-native state ${state} does not match expected state ${expectedState}`)
+}
+
+if (checkOnly) {
+  if (state === '0') {
+    const stale = [metadataPath, bridgeDir].filter((file) => fs.existsSync(file))
+    if (stale.length > 0) fail(`cached non-Apple output retains stale Apple-native files: ${stale.join(', ')}`)
+  }
+} else if (state === '0') {
+  // The compiler does not own stale plugin output. Remove it only after a
+  // successful generation whose transformed support no longer references the
+  // bridge; failed generations therefore retain their last complete tree.
+  fs.rmSync(bridgeDir, { recursive: true, force: true })
+  fs.rmSync(metadataPath, { force: true })
+}
+
+process.stdout.write(state)

package/targets/macos/generate-resident-entry.mjs

@@ -0,0 +1,80 @@
+#!/usr/bin/env node
+// Per-resident-app entry.cpp generator (macOS-flavoured).
+// Mirrors the template in targets/esp32-s3-touch-amoled-2.06/main/CMakeLists.txt
+// but drops ESP-only host integration. Each entry.cpp exposes
+// <prefix>_init/_frame/_settings_toggle/_mirror_*/_lookup_font*/_ble_* so the
+// generated registry can populate a ResidentApp slot for this app.
+
+import { writeFileSync } from 'node:fs'
+
+const [, , prefix, outPath] = process.argv
+if (!prefix || !outPath) {
+  console.error('Usage: generate-resident-entry.mjs <prefix> <out-cpp>')
+  process.exit(1)
+}
+
+const code = `// Auto-generated by targets/macos/generate-resident-entry.mjs. Do not edit.
+#include "app.h"
+#include "gea/embedded.h"
+#include "graphics/font.h"
+#include "host/timers.h"
+#include "host/websocket.h"
+#include "host/rtc.h"
+#include "ui/document.h"
+#include "ui/style.h"
+
+extern void ${prefix}_top_level();
+extern void ${prefix}_register_styles();
+extern void gea_cpp_clear_microtasks();
+
+namespace gea::framework::app::generated::${prefix} {
+void drainMicrotasks();
+}  // namespace gea::framework::app::generated::${prefix}
+
+void __attribute__((weak)) ${prefix}_register_styles() {}
+
+void ${prefix}_init(int w, int h, double devicePixelRatio)
+{
+\tgea::embedded::ui::Document::setPreferredMountSize(w, h);
+\tgea::embedded::ui::setViewportMetrics(w, h, devicePixelRatio);
+\tgea::host::resetAnimationFrameCallbacks();
+\tgea::host::resetScheduledTimers();
+\tgea_cpp_clear_microtasks();
+\tgea::embedded::ui::StyleSheet::instance().clear();
+\t${prefix}_register_styles();
+\tgea::embedded::ui::Document::instance().clear();
+\t${prefix}_top_level();
+\tgea::embedded::ui::Document::instance().refreshMountedIfDirty();
+}
+
+void ${prefix}_frame(int timestamp_ms)
+{
+\t// Renderer callbacks create many short-lived native references. Keep the
+\t// cycle collector out of those callbacks so their stack-owned references
+\t// unwind before the collector traces the live graph.
+\t{
+\t\tgea::CycleCollectionDeferral deferCycleCollection;
+\t\tgea::framework::app::generated::${prefix}::drainMicrotasks();
+\t\tgea::host::runAnimationFrameCallbacks(static_cast<double>(timestamp_ms));
+\t\tgea::host::websocket::runCallbacks();
+\t\tgea::host::rtc::runCallbacks();
+\t\tgea::embedded::ui::Document::instance().frame(timestamp_ms);
+\t\tgea::embedded::ui::Document::instance().refreshMountedIfDirty();
+\t}
+\tgea::collectCyclesIfNeeded();
+}
+
+void ${prefix}_settings_toggle() {}
+int ${prefix}_mirror_begin_snapshot() { return 0; }
+int ${prefix}_mirror_begin_diff() { return 0; }
+int ${prefix}_mirror_next_record(unsigned char *, int) { return 0; }
+void ${prefix}_mirror_clear_dirty() {}
+void ${prefix}_ble_connected() {}
+void ${prefix}_ble_disconnected() {}
+void ${prefix}_ble_bound() {}
+// Note: <prefix>_lookup_font, lookup_font_for_family, lookup_font_family
+// come from each app's gea_embedded_font_generated.cpp — don't emit
+// duplicates here or the link fails with multiple-definition errors.
+`
+
+writeFileSync(outPath, code)

package/targets/macos/generate-resident-registry.mjs

@@ -0,0 +1,141 @@
+#!/usr/bin/env node
+// Generates the macOS resident-apps registry .cpp. Mirrors the ESP32
+// generator (scripts/generate-resident-app-registry.mjs) but drops the
+// FreeRTOS / ESP_LOG machinery — macOS uses std::mutex for pending-launch
+// sync and just leaves the swap to be drained from the AppKit main tick.
+//
+// Usage: generate-resident-registry.mjs <out-cpp> <launcher-id> <app-id...>
+// First app-id is treated as the boot/active app.
+
+import { writeFileSync } from 'node:fs'
+
+const [, , outPath, launcherId, ...appIds] = process.argv
+if (!outPath || !launcherId || appIds.length === 0) {
+  console.error('Usage: generate-resident-registry.mjs <out-cpp> <launcher-id> <app-id...>')
+  process.exit(1)
+}
+
+const safe = (id) => id.replace(/[^A-Za-z0-9_]/g, '_')
+const prefix = (id) => `gea_resident_${safe(id)}`
+const quote = (s) => s.replace(/\\/g, '\\\\').replace(/"/g, '\\"')
+
+const lines = []
+lines.push('// Auto-generated by targets/macos/generate-resident-registry.mjs.')
+lines.push('// Do not edit.')
+lines.push('#include "app.h"')
+lines.push('#include "apps.h"')
+lines.push('#include "resident_apps.h"')
+lines.push('#include "graphics/font.h"')
+lines.push('')
+lines.push('#include <cstdio>')
+lines.push('#include <cstring>')
+lines.push('#include <mutex>')
+lines.push('')
+
+for (const id of appIds) {
+  const p = prefix(id)
+  lines.push(`extern void ${p}_init(int w, int h, double devicePixelRatio);`)
+  lines.push(`extern void ${p}_frame(int timestamp_ms);`)
+  lines.push(`extern void ${p}_settings_toggle();`)
+}
+lines.push('')
+
+lines.push('namespace gea::framework::apps {')
+lines.push('namespace {')
+lines.push(`constexpr const char *kLauncherAppId = "${quote(launcherId)}";`)
+lines.push('std::mutex &pendingLock() { static std::mutex m; return m; }')
+lines.push('char pendingLaunchAppId[64] = "";')
+lines.push('bool pendingValid = false;')
+lines.push('')
+lines.push('const ResidentApp residentApps[] = {')
+for (const id of appIds) {
+  const p = prefix(id)
+  lines.push('\t{')
+  lines.push(`\t\t.id = "${quote(id)}",`)
+  lines.push(`\t\t.displayFlushChunkRows = 0,`)
+  lines.push(`\t\t.displayFlushQueueDepth = 0,`)
+  lines.push(`\t\t.init = ${p}_init,`)
+  lines.push(`\t\t.frame = ${p}_frame,`)
+  lines.push(`\t\t.settingsToggle = ${p}_settings_toggle,`)
+  lines.push('\t},')
+}
+lines.push('};')
+lines.push(`constexpr int kResidentAppCount = ${appIds.length};`)
+lines.push('const ResidentApp *activeApp = &residentApps[0];')
+lines.push('')
+lines.push('const ResidentApp *findApp(const char *appId)')
+lines.push('{')
+lines.push("\tif (!appId || appId[0] == '\\0') return nullptr;")
+lines.push('\tfor (int i = 0; i < kResidentAppCount; i++) {')
+lines.push('\t\tif (std::strcmp(residentApps[i].id, appId) == 0) return &residentApps[i];')
+lines.push('\t}')
+lines.push('\treturn nullptr;')
+lines.push('}')
+lines.push('}  // namespace')
+lines.push('')
+lines.push('namespace generated {')
+lines.push('const ResidentApp *activeResidentApp() { return activeApp; }')
+lines.push('}  // namespace generated')
+lines.push('')
+lines.push('bool ResidentApps::isEnabled() { return kResidentAppCount > 0; }')
+lines.push('const char *ResidentApps::activeId() { return activeApp ? activeApp->id : nullptr; }')
+lines.push('')
+lines.push('bool ResidentApps::select(const char *appId)')
+lines.push('{')
+lines.push('\tconst ResidentApp *next = findApp(appId);')
+lines.push('\tif (!next) return false;')
+lines.push('\tactiveApp = next;')
+lines.push('\treturn true;')
+lines.push('}')
+lines.push('')
+lines.push('bool ResidentApps::requestLaunch(const char *appId)')
+lines.push('{')
+lines.push('\tif (!findApp(appId)) return false;')
+lines.push('\tstd::lock_guard guard(pendingLock());')
+lines.push('\tstd::snprintf(pendingLaunchAppId, sizeof(pendingLaunchAppId), "%s", appId);')
+lines.push('\tpendingValid = true;')
+lines.push('\treturn true;')
+lines.push('}')
+lines.push('')
+lines.push('bool ResidentApps::consumeLaunch(char *dst, std::size_t cap)')
+lines.push('{')
+lines.push('\tstd::lock_guard guard(pendingLock());')
+lines.push('\tif (!pendingValid) return false;')
+lines.push('\tif (dst && cap > 0) std::snprintf(dst, cap, "%s", pendingLaunchAppId);')
+lines.push('\tpendingValid = false;')
+lines.push("\tpendingLaunchAppId[0] = '\\0';")
+lines.push('\treturn true;')
+lines.push('}')
+lines.push('')
+lines.push('bool ResidentApps::returnToLauncher(const char *trigger)')
+lines.push('{')
+lines.push('\t(void)trigger;')
+lines.push('\tif (!activeApp || std::strcmp(activeApp->id, kLauncherAppId) == 0) return false;')
+lines.push('\treturn ResidentApps::requestLaunch(kLauncherAppId);')
+lines.push('}')
+lines.push('')
+lines.push('}  // namespace gea::framework::apps')
+lines.push('')
+// Application::init / frame / toggleSettings are normally provided by
+// gea_app_entry.cpp (single-app mode). In multi-app mode the launcher's
+// macOS build drops gea_app_entry.cpp and emits this version instead, so
+// Application::init dispatches to whichever resident is currently active.
+lines.push('namespace gea::framework::app {')
+lines.push('void Application::init(int width, int height, double devicePixelRatio)')
+lines.push('{')
+lines.push('\tconst auto *active = gea::framework::apps::generated::activeResidentApp();')
+lines.push('\tif (active && active->init) active->init(width, height, devicePixelRatio);')
+lines.push('}')
+lines.push('void Application::frame(int timestampMs)')
+lines.push('{')
+lines.push('\tconst auto *active = gea::framework::apps::generated::activeResidentApp();')
+lines.push('\tif (active && active->frame) active->frame(timestampMs);')
+lines.push('}')
+lines.push('void Application::toggleSettings()')
+lines.push('{')
+lines.push('\tconst auto *active = gea::framework::apps::generated::activeResidentApp();')
+lines.push('\tif (active && active->settingsToggle) active->settingsToggle();')
+lines.push('}')
+lines.push('}  // namespace gea::framework::app')
+
+writeFileSync(outPath, lines.join('\n') + '\n')

package/targets/macos/heavy-build-lock.sh

@@ -0,0 +1,176 @@
+#!/usr/bin/env bash
+
+# Optional workspace-wide resource lock for compiler-heavy native builds.
+#
+# Normal builds remain concurrent. Set GEA_SERIALIZE_HEAVY_BUILDS=1 only when
+# an uncontaminated benchmark or a memory-constrained machine needs global
+# serialization. Target/output correctness locks remain independent of this.
+
+GEA_HEAVY_BUILD_LOCK_HELD="${GEA_HEAVY_BUILD_LOCK_HELD:-0}"
+GEA_HEAVY_BUILD_LOCK_ACTIVE_PATH="${GEA_HEAVY_BUILD_LOCK_ACTIVE_PATH:-}"
+GEA_HEAVY_BUILD_LOCK_TOKEN="${GEA_HEAVY_BUILD_LOCK_TOKEN:-}"
+
+gea_heavy_build_lock_field() {
+  local lock_path="$1"
+  local field="$2"
+  sed -n "s/^${field}=//p" "$lock_path" 2>/dev/null | head -n 1
+}
+
+gea_heavy_build_process_start() {
+  local pid="$1"
+  ps -p "$pid" -o lstart= 2>/dev/null | sed 's/^[[:space:]]*//; s/[[:space:]]*$//'
+}
+
+gea_heavy_build_lock_owner_is_live() {
+  local lock_path="$1"
+  local owner_pid=""
+  local recorded_start=""
+  local current_start=""
+
+  owner_pid="$(gea_heavy_build_lock_field "$lock_path" pid)"
+  case "$owner_pid" in
+    ''|*[!0-9]*) return 1 ;;
+  esac
+  if ! kill -0 "$owner_pid" 2>/dev/null; then
+    return 1
+  fi
+
+  # A PID can be reused after a crashed owner. Match the process start time
+  # when both the recorded and current platform expose it.
+  recorded_start="$(gea_heavy_build_lock_field "$lock_path" process_start)"
+  current_start="$(gea_heavy_build_process_start "$owner_pid")"
+  if [ -n "$recorded_start" ] && [ -n "$current_start" ] && [ "$recorded_start" != "$current_start" ]; then
+    return 1
+  fi
+  return 0
+}
+
+gea_report_heavy_build_lock_owner() {
+  local lock_path="$1"
+  local owner_pid=""
+  local owner_kind=""
+  local owner_label=""
+  local owner_started=""
+
+  owner_pid="$(gea_heavy_build_lock_field "$lock_path" pid)"
+  owner_kind="$(gea_heavy_build_lock_field "$lock_path" kind)"
+  owner_label="$(gea_heavy_build_lock_field "$lock_path" label)"
+  owner_started="$(gea_heavy_build_lock_field "$lock_path" started_at)"
+  echo "Another heavyweight build is already using this workspace:" >&2
+  echo "  kind: ${owner_kind:-unknown}" >&2
+  echo "  target: ${owner_label:-unknown}" >&2
+  echo "  pid: ${owner_pid:-unknown}" >&2
+  echo "  started: ${owner_started:-unknown}" >&2
+  echo "Unset GEA_SERIALIZE_HEAVY_BUILDS or set GEA_ALLOW_CONCURRENT_HEAVY_BUILDS=1 to run concurrently." >&2
+}
+
+gea_acquire_heavy_build_lock() {
+  local lock_path="$1"
+  local kind="${2:-unknown}"
+  local label="${3:-unknown}"
+  local lock_parent=""
+  local candidate=""
+  local recovery_dir=""
+  local token=""
+  local process_start=""
+
+  # Concurrency is the normal developer workflow. The workspace-wide lock is
+  # deliberately opt-in for controlled benchmarks and low-memory machines.
+  if [ "${GEA_SERIALIZE_HEAVY_BUILDS:-0}" != "1" ]; then
+    return 0
+  fi
+  if [ "${GEA_ALLOW_CONCURRENT_HEAVY_BUILDS:-0}" = "1" ]; then
+    echo "Heavy-build resource lock overridden for $kind '$label'." >&2
+    return 0
+  fi
+  if [ "$GEA_HEAVY_BUILD_LOCK_HELD" = "1" ]; then
+    echo "Heavy-build resource lock is already held by this process." >&2
+    return 1
+  fi
+
+  lock_parent="$(dirname "$lock_path")"
+  if [ ! -d "$lock_parent" ]; then
+    echo "Heavy-build lock parent does not exist: $lock_parent" >&2
+    return 1
+  fi
+
+  token="$$.$(date +%s).${RANDOM:-0}"
+  candidate="$(mktemp "${lock_path}.candidate.XXXXXX")" || return 1
+  recovery_dir="${lock_path}.recovery"
+  process_start="$(gea_heavy_build_process_start "$$")"
+  kind="${kind//$'\n'/ }"
+  label="${label//$'\n'/ }"
+  (
+    umask 077
+    {
+      printf 'pid=%s\n' "$$"
+      printf 'token=%s\n' "$token"
+      printf 'process_start=%s\n' "$process_start"
+      printf 'kind=%s\n' "$kind"
+      printf 'label=%s\n' "$label"
+      printf 'started_at=%s\n' "$(date -u '+%Y-%m-%dT%H:%M:%SZ')"
+      printf 'host=%s\n' "$(hostname 2>/dev/null || echo unknown)"
+      printf 'command=%s\n' "$0"
+    } > "$candidate"
+  )
+
+  # `ln` installs a fully-written file atomically, avoiding mkdir+pid's small
+  # window where a contender can mistake a new lock for stale state.
+  if [ ! -d "$recovery_dir" ] && ln "$candidate" "$lock_path" 2>/dev/null; then
+    rm -f "$candidate"
+    GEA_HEAVY_BUILD_LOCK_HELD=1
+    GEA_HEAVY_BUILD_LOCK_ACTIVE_PATH="$lock_path"
+    GEA_HEAVY_BUILD_LOCK_TOKEN="$token"
+    return 0
+  fi
+
+  if gea_heavy_build_lock_owner_is_live "$lock_path"; then
+    rm -f "$candidate"
+    gea_report_heavy_build_lock_owner "$lock_path"
+    return 1
+  fi
+
+  # Serialize stale-owner recovery. Re-read after winning recovery ownership,
+  # because another contender may have replaced the stale file first.
+  if ! mkdir "$recovery_dir" 2>/dev/null; then
+    rm -f "$candidate"
+    echo "Heavy-build lock ownership is changing; retry the build." >&2
+    return 1
+  fi
+  if gea_heavy_build_lock_owner_is_live "$lock_path"; then
+    rmdir "$recovery_dir" 2>/dev/null || true
+    rm -f "$candidate"
+    gea_report_heavy_build_lock_owner "$lock_path"
+    return 1
+  fi
+
+  rm -f "$lock_path"
+  if ! ln "$candidate" "$lock_path" 2>/dev/null; then
+    rmdir "$recovery_dir" 2>/dev/null || true
+    rm -f "$candidate"
+    echo "Could not recover the stale heavy-build lock; retry the build." >&2
+    return 1
+  fi
+  rmdir "$recovery_dir" 2>/dev/null || true
+  rm -f "$candidate"
+  GEA_HEAVY_BUILD_LOCK_HELD=1
+  GEA_HEAVY_BUILD_LOCK_ACTIVE_PATH="$lock_path"
+  GEA_HEAVY_BUILD_LOCK_TOKEN="$token"
+}
+
+gea_release_heavy_build_lock() {
+  local owner_pid=""
+  local owner_token=""
+
+  if [ "$GEA_HEAVY_BUILD_LOCK_HELD" != "1" ] || [ -z "$GEA_HEAVY_BUILD_LOCK_ACTIVE_PATH" ]; then
+    return 0
+  fi
+  owner_pid="$(gea_heavy_build_lock_field "$GEA_HEAVY_BUILD_LOCK_ACTIVE_PATH" pid)"
+  owner_token="$(gea_heavy_build_lock_field "$GEA_HEAVY_BUILD_LOCK_ACTIVE_PATH" token)"
+  if [ "$owner_pid" = "$$" ] && [ "$owner_token" = "$GEA_HEAVY_BUILD_LOCK_TOKEN" ]; then
+    rm -f "$GEA_HEAVY_BUILD_LOCK_ACTIVE_PATH"
+  fi
+  GEA_HEAVY_BUILD_LOCK_HELD=0
+  GEA_HEAVY_BUILD_LOCK_ACTIVE_PATH=""
+  GEA_HEAVY_BUILD_LOCK_TOKEN=""
+}

package/targets/macos/main/canvas_view.h

@@ -0,0 +1,9 @@
+#pragma once
+
+#ifdef __OBJC__
+#import <AppKit/AppKit.h>
+
+@interface GeaCanvasView : NSView
+@property(nonatomic, assign) int nodeId;
+@end
+#endif