@trillboards/edge-sdk 0.2.137 → 0.2.140

package/deploy/macos/README.md

@@ -49,7 +49,12 @@ delivered **only by pairing** — it is never baked into the `.pkg`.
    **Start setup**. Follow **Welcome → Account → Account setup → Plan & Payment**.
    Sign in with Google or email, choose the account if you manage more than one,
    accept the current agreements, then choose a plan
-   and finish secure Stripe checkout. Cancelling checkout preserves account setup;
+   and finish secure Stripe checkout. The first browser step opens a **Sense Anything
+   setup** tab in the system default browser. Keep it open: Google and checkout
+   links originate from this tab so they stay in that browser/profile. **Reopen
+   setup tab** is an explicit recovery through the current default browser; it
+   revokes the old tab's connection. Agreement review and the authenticated
+   recorder/camera wizard open in owned Connector windows on the Mac. Cancelling checkout preserves account setup;
    use **Back to plans** in the Connector to retry. Existing subscribed accounts
    resume at recorder setup. The Connector checks subscription access automatically
    before opening the signed-in Sense Anything camera wizard,
@@ -180,3 +185,18 @@ runs the local model:
 The pairing endpoint (`POST /v2/earner/cameras/pair`), the config shape, and the
 local-first sensing runtime are shared across all platforms — only the
 service-supervisor wrapper differs.
+
+### Browser continuity implementation
+
+`installerBrowserSession.ts` serves one loopback-only setup tab. Its capability
+is carried in the initial fragment and tab session storage, then authenticated
+in request headers. Host/origin checks reject rebinding and cross-origin access;
+only one tab owner receives pending actions. Later stages never use the OS opener
+unless the user explicitly requests recovery. Links use a user gesture and
+`noopener noreferrer`; Google and Stripe stay in the real external browser.
+
+The Mac shell receives the one-use camera grant over inherited pipe descriptor
+198, passed explicitly through `pair.command`. It is never placed in logs or the
+progress file. Camera and legal views use separate nonpersistent WebKit stores
+and restricted navigation hosts. The native release build smoke-tests pipe
+delivery, cancellation, and temporary-directory handling.

package/deploy/macos/TrillboardsSetupApp.m

@@ -1,4 +1,5 @@
 #import <Cocoa/Cocoa.h>
+#import <WebKit/WebKit.h>
 #import <errno.h>
 #import <fcntl.h>
 #import <signal.h>
@@ -37,8 +38,22 @@ static BOOL acquireSetupInstanceLock(void) {
   return NO;
 }
 
-@interface TrillboardsSetupDelegate : NSObject <NSApplicationDelegate>
+@interface TrillboardsSetupDelegate : NSObject <NSApplicationDelegate, NSWindowDelegate, WKNavigationDelegate, WKUIDelegate>
 @property(nonatomic, strong) NSWindow *window;
+@property(nonatomic, strong) NSDictionary *guidanceCatalog;
+@property(nonatomic, strong) NSView *guidancePanel;
+@property(nonatomic, strong) NSTextField *guidanceTitle;
+@property(nonatomic, strong) NSTextField *guidanceBody;
+@property(nonatomic, strong) NSButton *guidanceToggle;
+@property(nonatomic, strong) NSButton *guidanceRestore;
+@property(nonatomic, strong) NSMutableSet<NSString *> *dismissedGuidance;
+
+@property(nonatomic, strong) NSFileHandle *setupOutput;
+@property(nonatomic, strong) NSMutableData *setupOutputBuffer;
+@property(nonatomic, strong) NSWindow *cameraWindow;
+@property(nonatomic, strong) WKWebView *cameraWebView;
+@property(nonatomic, strong) NSWindow *legalWindow;
+@property(nonatomic, strong) WKWebView *legalWebView;
 @property(nonatomic, strong) NSTextField *headline;
 @property(nonatomic, strong) NSTextField *detail;
 @property(nonatomic, strong) NSTextField *statusValue;
@@ -163,6 +178,11 @@ static BOOL acquireSetupInstanceLock(void) {
 - (void)stopPairProcess {
   pid_t pid = self.pairProcessIdentifier;
   self.pairProcessIdentifier = 0;
+  if (self.setupOutput) {
+    self.setupOutput.readabilityHandler = nil;
+    [self.setupOutput closeFile];
+    self.setupOutput = nil;
+  }
   if (self.setupInput) {
     [self.setupInput closeFile];
     self.setupInput = nil;
@@ -206,9 +226,18 @@ static BOOL acquireSetupInstanceLock(void) {
     return NO;
   }
 
+  int outputPipe[2];
+  if (pipe(outputPipe) != 0) {
+    close(logFd); close(inputPipe[0]); close(inputPipe[1]);
+    if (error) *error = [NSError errorWithDomain:NSPOSIXErrorDomain code:errno userInfo:nil];
+    return NO;
+  }
   posix_spawn_file_actions_t fileActions;
   posix_spawnattr_t attributes;
   posix_spawn_file_actions_init(&fileActions);
+  posix_spawn_file_actions_adddup2(&fileActions, outputPipe[1], 198);
+  posix_spawn_file_actions_addclose(&fileActions, outputPipe[0]);
+  posix_spawn_file_actions_addclose(&fileActions, outputPipe[1]);
   posix_spawn_file_actions_adddup2(&fileActions, logFd, STDOUT_FILENO);
   posix_spawn_file_actions_adddup2(&fileActions, logFd, STDERR_FILENO);
   posix_spawn_file_actions_adddup2(&fileActions, inputPipe[0], STDIN_FILENO);
@@ -239,12 +268,24 @@ static BOOL acquireSetupInstanceLock(void) {
   posix_spawn_file_actions_destroy(&fileActions);
   close(logFd);
   close(inputPipe[0]);
+  close(outputPipe[1]);
   if (spawnError != 0) {
     close(inputPipe[1]);
+    close(outputPipe[0]);
     if (error) *error = [NSError errorWithDomain:NSPOSIXErrorDomain code:spawnError userInfo:nil];
     return NO;
   }
 
+  self.setupOutputBuffer = [NSMutableData data];
+  self.setupOutput = [[NSFileHandle alloc] initWithFileDescriptor:outputPipe[0] closeOnDealloc:YES];
+  __weak typeof(self) outputSelf = self;
+  self.setupOutput.readabilityHandler = ^(NSFileHandle *handle) {
+    NSData *data = handle.availableData;
+    if (data.length == 0) { handle.readabilityHandler = nil; return; }
+    dispatch_async(dispatch_get_main_queue(), ^{
+      if (outputSelf.setupOutput == handle) [outputSelf receiveSetupOutput:data];
+    });
+  };
   self.setupInput = [[NSFileHandle alloc] initWithFileDescriptor:inputPipe[1] closeOnDealloc:YES];
   self.pairProcessIdentifier = pid;
   dispatch_source_t source = dispatch_source_create(DISPATCH_SOURCE_TYPE_PROC,
@@ -265,6 +306,11 @@ static BOOL acquireSetupInstanceLock(void) {
   int status = 0;
   pid_t waited = waitpid(pid, &status, 0);
   self.pairProcessIdentifier = 0;
+  if (self.setupOutput) {
+    self.setupOutput.readabilityHandler = nil;
+    [self.setupOutput closeFile];
+    self.setupOutput = nil;
+  }
   if (self.setupInput) {
     [self.setupInput closeFile];
     self.setupInput = nil;
@@ -289,13 +335,14 @@ static BOOL acquireSetupInstanceLock(void) {
 
 - (void)buildWindow {
   self.window = [[NSWindow alloc]
-      initWithContentRect:NSMakeRect(0, 0, 760, 540)
+      initWithContentRect:NSMakeRect(0, 0, 760, 700)
                 styleMask:NSWindowStyleMaskTitled | NSWindowStyleMaskClosable | NSWindowStyleMaskMiniaturizable
                   backing:NSBackingStoreBuffered
                     defer:NO];
   self.window.title = @"Sense Anything Connector";
-  self.window.minSize = NSMakeSize(760, 540);
-  self.window.maxSize = NSMakeSize(760, 540);
+  self.window.delegate = self;
+  self.window.minSize = NSMakeSize(760, 700);
+  self.window.maxSize = NSMakeSize(760, 700);
   [self.window center];
 
   NSView *root = self.window.contentView;
@@ -341,7 +388,7 @@ static BOOL acquireSetupInstanceLock(void) {
   [root addSubview:self.statusValue];
 
   self.googleReopenButton = [[NSButton alloc] initWithFrame:NSMakeRect(360, 219, 218, 28)];
-  self.googleReopenButton.title = @"Open sign-in again";
+  self.googleReopenButton.title = @"Reopen setup tab";
   self.googleReopenButton.bezelStyle = NSBezelStyleRounded;
   self.googleReopenButton.target = self;
   self.googleReopenButton.action = @selector(googleReopenPressed);
@@ -497,10 +544,85 @@ static BOOL acquireSetupInstanceLock(void) {
   [self.chooseAccountPanel addSubview:self.chooseAccountSubmit];
   [root addSubview:self.chooseAccountPanel];
 
+  // Reserve a separate help region; never cover native forms or recovery actions.
+  for (NSView *view in root.subviews) {
+    NSRect frame = view.frame;
+    frame.origin.y += 160;
+    view.frame = frame;
+  }
+  NSView *guideSidebar = [[NSView alloc] initWithFrame:NSMakeRect(0, 0, 190, 160)];
+  guideSidebar.wantsLayer = YES;
+  guideSidebar.layer.backgroundColor = NSColor.controlBackgroundColor.CGColor;
+  [root addSubview:guideSidebar];
+  NSString *guidePath = [NSBundle.mainBundle pathForResource:@"setup-guidance" ofType:@"json"];
+  NSData *guideData = guidePath ? [NSData dataWithContentsOfFile:guidePath] : nil;
+  id catalog = guideData ? [NSJSONSerialization JSONObjectWithData:guideData options:0 error:nil] : nil;
+  self.guidanceCatalog = [catalog isKindOfClass:NSDictionary.class] ? catalog : @{};
+  self.dismissedGuidance = [NSMutableSet set];
+  self.guidanceToggle = [NSButton checkboxWithTitle:@"Guiding tips" target:self action:@selector(toggleGuidance)];
+  self.guidanceToggle.frame = NSMakeRect(24, 118, 150, 24);
+  self.guidanceToggle.state = [NSUserDefaults.standardUserDefaults boolForKey:@"setupGuidingTipsDisabled"] ? NSControlStateValueOff : NSControlStateValueOn;
+  [root addSubview:self.guidanceToggle];
+  self.guidanceRestore = [self panelButton:@"Show this tip" frame:NSMakeRect(20, 80, 150, 28) action:@selector(restoreGuidance)];
+  [root addSubview:self.guidanceRestore];
+  self.guidancePanel = [[NSView alloc] initWithFrame:NSMakeRect(236, 12, 465, 145)];
+  self.guidancePanel.wantsLayer = YES;
+  self.guidancePanel.layer.backgroundColor = [NSColor colorWithCalibratedRed:1 green:0.96 blue:0.91 alpha:1].CGColor;
+  self.guidancePanel.layer.borderColor = [NSColor colorWithCalibratedRed:0.93 green:0.65 blue:0.40 alpha:1].CGColor;
+  self.guidancePanel.layer.borderWidth = 1;
+  self.guidancePanel.layer.cornerRadius = 10;
+  self.guidanceTitle = [self label:@"" size:13 weight:NSFontWeightSemibold frame:NSMakeRect(14, 94, 405, 40)];
+  self.guidanceBody = [self label:@"" size:12 weight:NSFontWeightRegular frame:NSMakeRect(14, 35, 435, 60)];
+  self.guidanceTitle.textColor = [NSColor colorWithCalibratedRed:0.28 green:0.20 blue:0.14 alpha:1];
+  self.guidanceBody.textColor = [NSColor colorWithCalibratedRed:0.38 green:0.29 blue:0.23 alpha:1];
+  [self.guidancePanel addSubview:self.guidanceTitle];
+  [self.guidancePanel addSubview:self.guidanceBody];
+  NSButton *dismiss = [self panelButton:@"×" frame:NSMakeRect(424, 110, 30, 26) action:@selector(dismissGuidance)];
+  dismiss.accessibilityLabel = @"Dismiss this tip";
+  [self.guidancePanel addSubview:dismiss];
+  [self.guidancePanel addSubview:[self panelButton:@"More help" frame:NSMakeRect(8, 5, 110, 26) action:@selector(showGuidanceDetail)]];
+  [root addSubview:self.guidancePanel];
+
   self.onboardingPanels = @[self.accountPanel, self.termsPanel, self.planPanel, self.chooseAccountPanel];
   [self showOnboardingPanel:nil];
 }
 
+- (void)renderGuidance {
+  NSDictionary *guide = self.guidanceCatalog[self.lastStage];
+  BOOL enabled = self.guidanceToggle.state == NSControlStateValueOn;
+  BOOL dismissed = [self.dismissedGuidance containsObject:self.lastStage];
+  self.guidancePanel.hidden = !enabled || dismissed || ![guide isKindOfClass:NSDictionary.class];
+  self.guidanceRestore.hidden = !enabled || !dismissed;
+  self.guidanceTitle.stringValue = [guide[@"title"] isKindOfClass:NSString.class] ? guide[@"title"] : @"";
+  self.guidanceBody.stringValue = [guide[@"body"] isKindOfClass:NSString.class] ? guide[@"body"] : @"";
+}
+
+- (void)toggleGuidance {
+  [NSUserDefaults.standardUserDefaults setBool:self.guidanceToggle.state != NSControlStateValueOn forKey:@"setupGuidingTipsDisabled"];
+  [self.dismissedGuidance removeAllObjects];
+  [self renderGuidance];
+}
+
+- (void)dismissGuidance {
+  [self.dismissedGuidance addObject:self.lastStage];
+  [self renderGuidance];
+}
+
+- (void)restoreGuidance {
+  [self.dismissedGuidance removeObject:self.lastStage];
+  [self renderGuidance];
+}
+
+- (void)showGuidanceDetail {
+  NSDictionary *guide = self.guidanceCatalog[self.lastStage];
+  if (![guide[@"detail"] isKindOfClass:NSString.class]) return;
+  NSAlert *alert = [[NSAlert alloc] init];
+  alert.messageText = self.guidanceTitle.stringValue;
+  alert.informativeText = guide[@"detail"];
+  [alert addButtonWithTitle:@"Got it"];
+  [alert beginSheetModalForWindow:self.window completionHandler:nil];
+}
+
 - (void)showOnboardingPanel:(NSView *)panel {
   for (NSView *candidate in self.onboardingPanels ?: @[]) candidate.hidden = candidate != panel;
   BOOL showStatus = panel == nil;
@@ -537,7 +659,7 @@ static BOOL acquireSetupInstanceLock(void) {
 }
 
 - (void)googleReopenPressed {
-  [self sendOnboardingCommand:@{ @"action": @"google_reopen" }];
+  [self sendOnboardingCommand:@{ @"action": @"browser_reopen" }];
 }
 
 - (void)googlePressed {
@@ -586,15 +708,15 @@ static BOOL acquireSetupInstanceLock(void) {
 }
 
 - (void)reviewTermsPressed {
-  [self openURL:@"https://trillboards.com/legal/terms"];
+  [self showLegalURL:@"https://trillboards.com/legal/terms"];
 }
 
 - (void)reviewPrivacyPressed {
-  [self openURL:@"https://trillboards.com/legal/privacy-policy"];
+  [self showLegalURL:@"https://trillboards.com/legal/privacy-policy"];
 }
 
 - (void)reviewDpaPressed {
-  [self openURL:@"https://trillboards.com/legal/data-processing"];
+  [self showLegalURL:@"https://trillboards.com/legal/data-processing"];
 }
 
 - (void)termsSubmitPressed {
@@ -624,6 +746,7 @@ static BOOL acquireSetupInstanceLock(void) {
 - (void)showWelcome {
   [self showOnboardingPanel:nil];
   self.lastStage = @"welcome";
+  [self renderGuidance];
   self.headline.stringValue = @"Set up this computer for CCTV";
   self.detail.stringValue = @"Connect your Sense Anything account, find your recorder, and verify every camera before screens are created.";
   self.statusValue.stringValue = @"About 5 minutes";
@@ -639,6 +762,7 @@ static BOOL acquireSetupInstanceLock(void) {
 - (void)showLocalError:(NSString *)title message:(NSString *)message {
   [self showOnboardingPanel:nil];
   self.lastStage = @"error";
+  [self renderGuidance];
   self.headline.stringValue = title;
   self.detail.stringValue = message;
   self.statusValue.stringValue = @"Setup stopped";
@@ -651,6 +775,14 @@ static BOOL acquireSetupInstanceLock(void) {
   self.googleReopenButton.hidden = YES;
 }
 
+- (void)windowWillClose:(NSNotification *)notification {
+  if (notification.object == self.window) {
+    [self.cameraWindow close];
+    [self.legalWindow close];
+    [NSApp terminate:nil];
+  }
+}
+
 - (void)closePressed {
   [self.window close];
 }
@@ -716,6 +848,7 @@ static BOOL acquireSetupInstanceLock(void) {
         }
         self.requiredUpdateURL = downloadURL;
         self.lastStage = @"update_required";
+        [self renderGuidance];
         self.headline.stringValue = @"Update required before setup can continue";
         self.detail.stringValue = @"Install the latest Sense Anything Connector, then reopen it to finish camera setup.";
         self.statusValue.stringValue = [NSString stringWithFormat:@"Version %@", availableText];
@@ -756,9 +889,11 @@ static BOOL acquireSetupInstanceLock(void) {
     [self sendOnboardingCommand:@{ @"action": @"refresh" }];
   } else if ([self.lastStage isEqualToString:@"waiting_for_account"] ||
       [self.lastStage isEqualToString:@"account_attention"]) {
-    [self openURL:self.portalURL];
-  } else if ([self.lastStage isEqualToString:@"ready"]) {
-    [self openURL:@"https://app.senseanything.com/sense/cameras"];
+    [self sendOnboardingCommand:@{ @"action": @"camera_reopen" }];
+    if (self.cameraWindow) [self.cameraWindow makeKeyAndOrderFront:nil];
+    else [self showLocalError:@"Camera setup unavailable" message:@"Restart setup to reconnect the camera window to your account."];
+  } else if ([@[@"ready", @"account_connected", @"discovering", @"devices_found", @"validating"] containsObject:self.lastStage]) {
+    if (self.cameraWindow) [self.cameraWindow makeKeyAndOrderFront:nil];
   } else if ([self.lastStage isEqualToString:@"local_ai_error"]) {
     [NSApp terminate:nil];
   } else if ([self.lastStage isEqualToString:@"welcome"] || [self.lastStage isEqualToString:@"error"]) {
@@ -767,6 +902,9 @@ static BOOL acquireSetupInstanceLock(void) {
 }
 
 - (void)startSetup {
+  [self stopPairProcess];
+  [self.cameraWindow close]; self.cameraWindow = nil; self.cameraWebView = nil;
+  [self.legalWindow close]; self.legalWindow = nil; self.legalWebView = nil;
   NSString *pairer = [self homePath:@"Library/Trillboards/edge/bin/trillboards-pair"];
   NSString *stateDirectory = [self homePath:@"Library/Application Support/Trillboards"];
   NSString *statePath = [stateDirectory stringByAppendingPathComponent:@"setup-progress.json"];
@@ -783,6 +921,7 @@ static BOOL acquireSetupInstanceLock(void) {
   if (![files fileExistsAtPath:logPath]) [files createFileAtPath:logPath contents:nil attributes:nil];
 
   self.lastStage = @"starting";
+  [self renderGuidance];
   self.setupStarted = YES;
   self.headline.stringValue = @"Starting camera setup";
   self.detail.stringValue = @"Connecting securely to Sense Anything.";
@@ -793,7 +932,7 @@ static BOOL acquireSetupInstanceLock(void) {
 
   NSError *error = nil;
   if (![self launchSetupExecutable:pairer
-                         arguments:@[@"--setup", @"--status-file", statePath]
+                         arguments:@[@"--setup", @"--status-file", statePath, @"--native-ui-fd", @"198"]
                            logPath:logPath
                              error:&error]) {
     [self showLocalError:@"Could not start setup" message:@"Reinstall the Sense Anything Connector, then try again."];
@@ -816,6 +955,7 @@ static BOOL acquireSetupInstanceLock(void) {
   if (!stage) return;
   NSString *previousStage = self.lastStage;
   self.lastStage = stage;
+  [self renderGuidance];
   if ([state[@"portalUrl"] isKindOfClass:NSString.class]) self.portalURL = state[@"portalUrl"];
   if ([state[@"title"] isKindOfClass:NSString.class]) self.headline.stringValue = state[@"title"];
   if ([state[@"message"] isKindOfClass:NSString.class]) self.detail.stringValue = state[@"message"];
@@ -902,6 +1042,7 @@ static BOOL acquireSetupInstanceLock(void) {
     self.googleReopenButton.hidden = NO;
   } else if ([stage isEqualToString:@"onboarding_checkout"]) {
     self.statusValue.stringValue = @"Waiting for Stripe";
+    self.googleReopenButton.hidden = NO;
   } else if ([stage isEqualToString:@"onboarding_install"]) {
     self.statusValue.stringValue = @"Onboarding complete";
   } else if (cameraCount.integerValue > 0) {
@@ -956,10 +1097,13 @@ static BOOL acquireSetupInstanceLock(void) {
     self.actionButton.title = @"Preparing cameras…";
     self.actionButton.enabled = NO;
   } else if ([stage isEqualToString:@"waiting_for_account"]) {
-    self.actionButton.title = @"Open Sense Anything";
+    self.actionButton.title = @"Open camera setup";
     self.actionButton.enabled = YES;
   } else if ([stage isEqualToString:@"account_attention"]) {
-    self.actionButton.title = @"Switch account";
+    self.actionButton.title = @"Open camera setup";
+    self.actionButton.enabled = YES;
+  } else if ([@[@"account_connected", @"discovering", @"devices_found", @"validating"] containsObject:stage] && self.cameraWindow) {
+    self.actionButton.title = @"Open camera setup";
     self.actionButton.enabled = YES;
   } else if ([stage isEqualToString:@"local_ai_error"]) {
     self.actionButton.title = @"Close";
@@ -1013,6 +1157,98 @@ static BOOL acquireSetupInstanceLock(void) {
   }
 }
 
+- (void)receiveSetupOutput:(NSData *)data {
+  if (self.terminating || !self.setupOutput) return;
+  [self.setupOutputBuffer appendData:data];
+  if (self.setupOutputBuffer.length > 16384) {
+    [self.setupOutputBuffer setLength:0];
+    [self showLocalError:@"Camera setup unavailable" message:@"Restart setup to reconnect the camera window."];
+    return;
+  }
+  NSData *newline = [@"\n" dataUsingEncoding:NSUTF8StringEncoding];
+  while (YES) {
+    NSRange boundary = [self.setupOutputBuffer rangeOfData:newline options:0 range:NSMakeRange(0, self.setupOutputBuffer.length)];
+    if (boundary.location == NSNotFound) break;
+    NSData *line = [self.setupOutputBuffer subdataWithRange:NSMakeRange(0, boundary.location)];
+    [self.setupOutputBuffer replaceBytesInRange:NSMakeRange(0, boundary.location + 1) withBytes:NULL length:0];
+    NSDictionary *message = [NSJSONSerialization JSONObjectWithData:line options:0 error:nil];
+    if (![message isKindOfClass:NSDictionary.class] || ![message[@"action"] isEqual:@"camera"] || ![message[@"url"] isKindOfClass:NSString.class]) continue;
+    NSURL *url = [NSURL URLWithString:message[@"url"]];
+    if (![url.scheme isEqual:@"https"] || ![url.host isEqual:@"app.senseanything.com"] || ![url.path isEqual:@"/sense/installer-return"]) {
+      [self showLocalError:@"Camera setup unavailable" message:@"The camera setup destination was not recognized."];
+      continue;
+    }
+    if (!self.cameraWebView) {
+      self.cameraWebView = [self setupWebView];
+      self.cameraWindow = [self contentWindow:@"Sense Anything — Recorder and cameras" webView:self.cameraWebView];
+    }
+    [self.cameraWebView loadRequest:[NSURLRequest requestWithURL:url]];
+    [self.cameraWindow makeKeyAndOrderFront:nil];
+  }
+}
+
+- (WKWebView *)setupWebView {
+  WKWebViewConfiguration *configuration = [[WKWebViewConfiguration alloc] init];
+  configuration.websiteDataStore = WKWebsiteDataStore.nonPersistentDataStore;
+  WKWebView *view = [[WKWebView alloc] initWithFrame:NSMakeRect(0, 0, 960, 700) configuration:configuration];
+  view.navigationDelegate = self;
+  view.UIDelegate = self;
+  return view;
+}
+
+- (NSWindow *)contentWindow:(NSString *)title webView:(WKWebView *)view {
+  NSWindow *window = [[NSWindow alloc] initWithContentRect:NSMakeRect(0, 0, 960, 700)
+      styleMask:NSWindowStyleMaskTitled | NSWindowStyleMaskClosable | NSWindowStyleMaskResizable
+      backing:NSBackingStoreBuffered defer:NO];
+  window.title = title;
+  window.releasedWhenClosed = NO;
+  window.contentView = view;
+  // An owned window stays with the installer rather than activating whichever
+  // unrelated browser window happens to be on another desktop.
+  [self.window addChildWindow:window ordered:NSWindowAbove];
+  NSRect visible = (self.window.screen ?: NSScreen.mainScreen).visibleFrame;
+  NSRect frame = window.frame;
+  frame.size.width = MIN(frame.size.width, NSWidth(visible) - 40);
+  frame.size.height = MIN(frame.size.height, NSHeight(visible) - 40);
+  frame.origin.x = MAX(NSMinX(visible) + 20, MIN(NSMinX(self.window.frame) + 30, NSMaxX(visible) - NSWidth(frame) - 20));
+  frame.origin.y = MAX(NSMinY(visible) + 20, MIN(NSMinY(self.window.frame) + 20, NSMaxY(visible) - NSHeight(frame) - 20));
+  [window setFrame:frame display:NO];
+  return window;
+}
+
+- (void)showLegalURL:(NSString *)string {
+  if (!self.legalWebView) {
+    self.legalWebView = [self setupWebView];
+    self.legalWindow = [self contentWindow:@"Sense Anything — Agreements" webView:self.legalWebView];
+  }
+  [self.legalWebView loadRequest:[NSURLRequest requestWithURL:[NSURL URLWithString:string]]];
+  [self.legalWindow makeKeyAndOrderFront:nil];
+}
+
+- (void)webView:(WKWebView *)webView decidePolicyForNavigationAction:(WKNavigationAction *)action
+    decisionHandler:(void (^)(WKNavigationActionPolicy))decisionHandler {
+  NSURL *url = action.request.URL;
+  BOOL allowedHost = webView == self.cameraWebView
+      ? [url.host isEqual:@"app.senseanything.com"]
+      : ([url.host isEqual:@"trillboards.com"] || [url.host isEqual:@"www.trillboards.com"]);
+  BOOL allowed = [url.scheme isEqual:@"https"] && allowedHost;
+  if (allowed && !action.targetFrame) {
+    [webView loadRequest:action.request];
+    decisionHandler(WKNavigationActionPolicyCancel);
+    return;
+  }
+  decisionHandler(allowed ? WKNavigationActionPolicyAllow : WKNavigationActionPolicyCancel);
+}
+
+- (void)webView:(WKWebView *)webView didFailProvisionalNavigation:(WKNavigation *)navigation withError:(NSError *)error {
+  (void)webView; (void)navigation;
+  if (error.code == NSURLErrorCancelled) return;
+  NSAlert *alert = [[NSAlert alloc] init];
+  alert.messageText = @"Could not load this setup page";
+  alert.informativeText = @"Check your internet connection, then reopen the page from the Connector.";
+  [alert beginSheetModalForWindow:self.window completionHandler:nil];
+}
+
 - (void)openURL:(NSString *)string {
   NSURL *url = [NSURL URLWithString:string];
   if (url) [NSWorkspace.sharedWorkspace openURL:url];
@@ -1020,6 +1256,43 @@ static BOOL acquireSetupInstanceLock(void) {
 
 @end
 
+static int runGuidanceSmokeTest(void) {
+  [NSApplication sharedApplication];
+  TrillboardsSetupDelegate *delegate = [[TrillboardsSetupDelegate alloc] init];
+  [delegate buildWindow];
+  if (delegate.guidanceCatalog.count == 0) return 1;
+  delegate.guidanceToggle.state = NSControlStateValueOn;
+  for (NSString *stage in delegate.guidanceCatalog) {
+    delegate.lastStage = stage;
+    [delegate renderGuidance];
+    if (delegate.guidancePanel.hidden || !delegate.guidanceTitle.stringValue.length) return 2;
+    for (NSTextField *field in @[delegate.guidanceTitle, delegate.guidanceBody]) {
+      NSRect textBounds = [field.attributedStringValue boundingRectWithSize:NSMakeSize(field.frame.size.width - 4, CGFLOAT_MAX)
+          options:NSStringDrawingUsesLineFragmentOrigin | NSStringDrawingUsesFontLeading];
+      if (textBounds.size.height > field.frame.size.height) {
+        fprintf(stderr, "Guidance text clipped at %s\n", stage.UTF8String);
+        return 3;
+      }
+    }
+    [delegate dismissGuidance];
+    if (!delegate.guidancePanel.hidden || delegate.guidanceRestore.hidden) return 4;
+    [delegate restoreGuidance];
+    if (delegate.guidancePanel.hidden) return 5;
+  }
+  delegate.lastStage = @"onboarding_terms";
+  delegate.termsCheck.state = NSControlStateValueOff;
+  delegate.termsSubmit.enabled = NO;
+  delegate.guidanceToggle.state = NSControlStateValueOff;
+  [delegate renderGuidance];
+  if (!delegate.guidancePanel.hidden || delegate.termsSubmit.enabled) return 6;
+  if (NSIntersectsRect(delegate.guidancePanel.frame, delegate.accountPanel.frame) ||
+      NSIntersectsRect(delegate.guidancePanel.frame, delegate.actionButton.frame)) return 7;
+  fprintf(stdout, "Native guidance stages, dismissal, text bounds and consent isolation passed.\n");
+  fflush(stdout);
+  [delegate.window close];
+  return 0;
+}
+
 static int runCancellationSmokeTest(void) {
   NSString *pidPath = [NSTemporaryDirectory()
       stringByAppendingPathComponent:[NSString stringWithFormat:@"trillboards-setup-child-%@.pid", NSUUID.UUID.UUIDString]];
@@ -1068,6 +1341,35 @@ static int runCancellationSmokeTest(void) {
   return 0;
 }
 
+@interface SetupPipeSmokeDelegate : TrillboardsSetupDelegate
+@property(nonatomic, strong) NSMutableData *received;
+@end
+@implementation SetupPipeSmokeDelegate
+- (void)receiveSetupOutput:(NSData *)data { [self.received appendData:data]; }
+@end
+
+static int runNativePipeSmokeTest(NSString *nodePath) {
+  SetupPipeSmokeDelegate *delegate = [[SetupPipeSmokeDelegate alloc] init];
+  delegate.received = [NSMutableData data];
+  NSError *error = nil;
+  if (![delegate launchSetupExecutable:@"/bin/bash"
+      arguments:@[@"-c", @"exec \"$1\" -e \"$2\"", @"pipe-smoke", nodePath,
+        @"require('fs').writeSync(198, 'native-ui-pipe-ok\\n'); setTimeout(() => {}, 10000)"]
+      logPath:@"/dev/null" error:&error]) return 1;
+  NSDate *deadline = [NSDate dateWithTimeIntervalSinceNow:3];
+  while (delegate.received.length == 0 && deadline.timeIntervalSinceNow > 0) {
+    [NSRunLoop.currentRunLoop runUntilDate:[NSDate dateWithTimeIntervalSinceNow:0.02]];
+  }
+  NSString *received = [[NSString alloc] initWithData:delegate.received encoding:NSUTF8StringEncoding];
+  [delegate stopPairProcess];
+  if (![received isEqualToString:@"native-ui-pipe-ok\n"]) {
+    fprintf(stderr, "Native setup private UI pipe did not deliver its message.\n");
+    return 1;
+  }
+  fprintf(stdout, "Sense Anything Connector private UI pipe smoke test passed.\n");
+  return 0;
+}
+
 static int runTemporaryDirectorySmokeTest(void) {
   const char *environmentTemporaryDirectory = getenv("TMPDIR");
   if (environmentTemporaryDirectory != NULL &&
@@ -1108,6 +1410,12 @@ int main(int argc, const char *argv[]) {
   // setup app or its pairing child retain that now-stale TMPDIR.
   normalizeTemporaryDirectory();
   @autoreleasepool {
+    if (argc == 3 && [[NSString stringWithUTF8String:argv[1]] isEqualToString:@"--smoke-test-ui-pipe"]) {
+      return runNativePipeSmokeTest([NSString stringWithUTF8String:argv[2]]);
+    }
+    if (argc == 2 && [[NSString stringWithUTF8String:argv[1]] isEqualToString:@"--smoke-test-guidance"]) {
+      return runGuidanceSmokeTest();
+    }
     if (argc == 2 && [[NSString stringWithUTF8String:argv[1]] isEqualToString:@"--smoke-test-cancel"]) {
       return runCancellationSmokeTest();
     }

package/deploy/macos/build-macos-pkg.sh

@@ -490,9 +490,10 @@ SETUP_APP_BIN="$SETUP_APP_MACOS/Sense Anything Connector"
 mkdir -p "$SETUP_APP_MACOS" "$SETUP_APP_RESOURCES"
 cp "$PKG_ROOT/deploy/branding/SenseAnythingConnector.icns" \
   "$SETUP_APP_RESOURCES/SenseAnythingConnector.icns"
+cp "$PKG_ROOT/deploy/setup-guidance.json" "$SETUP_APP_RESOURCES/setup-guidance.json"
 log "Building native Sense Anything Connector.app…"
 if [ "$UNIVERSAL" -eq 1 ]; then
-  clang -fobjc-arc -Wall -Wextra -Werror -O2 -mmacosx-version-min=12.0 -arch arm64 -arch x86_64 -framework Cocoa \
+  clang -fobjc-arc -Wall -Wextra -Werror -O2 -mmacosx-version-min=12.0 -arch arm64 -arch x86_64 -framework Cocoa -framework WebKit \
     "$PKG_ROOT/deploy/macos/TrillboardsSetupApp.m" -o "$SETUP_APP_BIN" \
     || die "native setup app universal build failed"
 else
@@ -500,13 +501,15 @@ else
     arm64) SETUP_ARCH="arm64";;
     x64) SETUP_ARCH="x86_64";;
   esac
-  clang -fobjc-arc -Wall -Wextra -Werror -O2 -mmacosx-version-min=12.0 -arch "$SETUP_ARCH" -framework Cocoa \
+  clang -fobjc-arc -Wall -Wextra -Werror -O2 -mmacosx-version-min=12.0 -arch "$SETUP_ARCH" -framework Cocoa -framework WebKit \
     "$PKG_ROOT/deploy/macos/TrillboardsSetupApp.m" -o "$SETUP_APP_BIN" \
     || die "native setup app build failed"
 fi
 chmod +x "$SETUP_APP_BIN"
 "$SETUP_APP_BIN" --smoke-test-cancel \
   || die "native setup app cancellation smoke test failed"
+"$SETUP_APP_BIN" --smoke-test-ui-pipe "$PAYLOAD/bin/node" \
+  || die "native setup private UI pipe smoke test failed"
 INSTALLER_TMP="$STAGE/PKInstallSandbox.trillboards-test/tmp"
 mkdir -p "$INSTALLER_TMP"
 TMPDIR="$INSTALLER_TMP" "$SETUP_APP_BIN" --smoke-test-tempdir \
@@ -534,6 +537,8 @@ cat > "$SETUP_APP/Contents/Info.plist" <<PLIST
 </plist>
 PLIST
 plutil -lint "$SETUP_APP/Contents/Info.plist" >/dev/null || die "native setup app Info.plist is invalid"
+"$SETUP_APP_BIN" --smoke-test-guidance \
+  || die "native setup guidance smoke test failed"
 file "$SETUP_APP_BIN" | grep -q 'Mach-O' || die "native setup app executable is not Mach-O"
 log "Native setup app staged: $SETUP_APP"
 

package/deploy/macos/pair.command

@@ -41,6 +41,7 @@ LABEL="com.trillboards.edge"
 API_BASE="${TRILLBOARDS_API_BASE:-}"
 HEADLESS_CODE=""
 UI_STATUS_FILE=""
+NATIVE_UI_ARGS=()
 
 # Parse args. First non-flag positional == the code (headless mode).
 while [ $# -gt 0 ]; do
@@ -48,6 +49,7 @@ while [ $# -gt 0 ]; do
     --api-base) API_BASE="$2"; shift 2;;
     --setup) SETUP_MODE=1; shift;;
     --status-file) UI_STATUS_FILE="$2"; shift 2;;
+    --native-ui-fd) NATIVE_UI_ARGS=(--native-ui-fd "$2"); shift 2;;
     -h|--help) sed -n '2,20p' "${BASH_SOURCE[0]}"; exit 0;;
     *) if [ -z "$HEADLESS_CODE" ]; then HEADLESS_CODE="$1"; fi; shift;;
   esac
@@ -368,7 +370,7 @@ if [ "${SETUP_MODE:-0}" = "1" ]; then
     # says legal + entitlement are current, so cameras cannot open early.
     # The same process keeps the authenticated session in memory through camera
     # setup and mints a one-use signed-in browser handoff at first launch.
-    "$LAUNCHER" installer-onboarding --config "$CONFIG" --status-file "$UI_STATUS_FILE"
+    "$LAUNCHER" installer-onboarding --config "$CONFIG" --status-file "$UI_STATUS_FILE" "${NATIVE_UI_ARGS[@]}"
   else
     "$LAUNCHER" setup --config "$CONFIG"
   fi