From 42fde86b9cbb66b998f24a01153023a52d1c8eaf Mon Sep 17 00:00:00 2001
From: PJ <ipriyanshujain@gmail.com>
Date: Sun, 7 Jun 2026 15:41:09 +0530
Subject: [PATCH] feat(companion): add simulator runner project skeleton

---
 .gitignore                                    |  4 +++
 .../PrivateAutomation/PrivateAutomation.h     | 35 ++++++++++++++++++
 companion/project.yml                         | 36 +++++++++++++++++++
 3 files changed, 75 insertions(+)
 create mode 100644 companion/Sources/PrivateAutomation/PrivateAutomation.h
 create mode 100644 companion/project.yml

diff --git a/.gitignore b/.gitignore
index b70c2f9..3786e83 100644
--- a/.gitignore
+++ b/.gitignore
@@ -52,6 +52,10 @@ replay-ui/node_modules/
 replay-ui/dist/
 replay-ui/.vite/
 
+# Simulator runner generated project and build output (xcodegen artifacts)
+companion/CompanionRunner.xcodeproj/
+companion/build/
+
 # folio-web frontend
 examples/folio-web/node_modules/
 examples/folio-web/dist/
diff --git a/companion/Sources/PrivateAutomation/PrivateAutomation.h b/companion/Sources/PrivateAutomation/PrivateAutomation.h
new file mode 100644
index 0000000..a86adbd
--- /dev/null
+++ b/companion/Sources/PrivateAutomation/PrivateAutomation.h
@@ -0,0 +1,35 @@
+#import <Foundation/Foundation.h>
+#import <CoreGraphics/CoreGraphics.h>
+
+// Private XCTest event-synthesis interfaces. These ship inside the testing
+// frameworks bundled with Xcode and are the only path to timestamped touch
+// events with millisecond-precision offsets. The selectors below were verified
+// present in Xcode 26's XCUIAutomation framework binary.
+
+NS_ASSUME_NONNULL_BEGIN
+
+// One pointer's path through a synthesized event. Offsets are seconds from the
+// start of the event record.
+@interface XCPointerEventPath : NSObject
+- (instancetype)initForTouchAtPoint:(CGPoint)point offset:(double)offset;
+- (void)moveToPoint:(CGPoint)point atOffset:(double)offset;
+- (void)pressDownAtOffset:(double)offset;
+- (void)liftUpAtOffset:(double)offset;
+@end
+
+// A complete synthesized event composed of one or more pointer paths.
+@interface XCSynthesizedEventRecord : NSObject
+- (instancetype)initWithName:(NSString *)name
+         interfaceOrientation:(NSInteger)interfaceOrientation;
+- (void)addPointerEventPath:(XCPointerEventPath *)pointerEventPath;
+@end
+
+// The runner-side session that delivers synthesized events to the system under
+// test.
+@interface XCTRunnerDaemonSession : NSObject
++ (instancetype)sharedSession;
+- (void)synthesizeEvent:(XCSynthesizedEventRecord *)eventRecord
+             completion:(void (^)(NSError *_Nullable error))completion;
+@end
+
+NS_ASSUME_NONNULL_END
diff --git a/companion/project.yml b/companion/project.yml
new file mode 100644
index 0000000..4ebd6a8
--- /dev/null
+++ b/companion/project.yml
@@ -0,0 +1,36 @@
+name: CompanionRunner
+options:
+  bundleIdPrefix: dev.sanderling
+  deploymentTarget:
+    iOS: "16.0"
+  createIntermediateGroups: true
+
+settings:
+  base:
+    CODE_SIGNING_ALLOWED: "NO"
+    CODE_SIGNING_REQUIRED: "NO"
+    SWIFT_VERSION: "5.0"
+
+targets:
+  CompanionRunnerUITests:
+    type: bundle.ui-testing
+    platform: iOS
+    productName: CompanionRunnerUITests
+    sources:
+      - Sources
+    settings:
+      base:
+        PRODUCT_BUNDLE_IDENTIFIER: dev.sanderling.companion
+        SWIFT_OBJC_BRIDGING_HEADER: Sources/PrivateAutomation/PrivateAutomation.h
+        OTHER_LDFLAGS:
+          - "-framework"
+          - "XCTest"
+
+schemes:
+  CompanionRunner:
+    build:
+      targets:
+        CompanionRunnerUITests: all
+    test:
+      targets:
+        - CompanionRunnerUITests