@trillboards/edge-sdk 0.2.138 → 0.2.140

package/deploy/macos/TrillboardsSetupApp.m

@@ -40,6 +40,14 @@ static BOOL acquireSetupInstanceLock(void) {
 
 @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;
@@ -327,14 +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.delegate = self;
-  self.window.minSize = NSMakeSize(760, 540);
-  self.window.maxSize = NSMakeSize(760, 540);
+  self.window.minSize = NSMakeSize(760, 700);
+  self.window.maxSize = NSMakeSize(760, 700);
   [self.window center];
 
   NSView *root = self.window.contentView;
@@ -536,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;
@@ -663,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";
@@ -678,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";
@@ -763,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];
@@ -835,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.";
@@ -868,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"];
@@ -1168,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]];
@@ -1288,6 +1413,9 @@ int main(int argc, const char *argv[]) {
     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,6 +490,7 @@ 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 -framework WebKit \
@@ -536,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/setup-guidance.json

@@ -0,0 +1,112 @@
+{
+  "welcome": {
+    "title": "Start on the computer that will stay here.",
+    "body": "Keep this computer powered and connected to the camera network. Have your recorder login ready.",
+    "detail": "A recorder is the box your cameras connect to, often called an NVR or DVR. Internet access alone does not mean this computer can reach it."
+  },
+  "starting": {
+    "title": "Start on the computer that will stay here.",
+    "body": "Keep this computer powered and connected to the camera network. Have your recorder login ready.",
+    "detail": "A recorder is the box your cameras connect to, often called an NVR or DVR. Internet access alone does not mean this computer can reach it."
+  },
+  "onboarding_account": {
+    "title": "Choose email or Google.",
+    "body": "Use your Sense Anything email and password, or continue with Google. New here? Create an account with either option.",
+    "detail": "Your Sense Anything login connects your account. Later, camera setup asks for the separate login for your recorder or camera."
+  },
+  "onboarding_google": {
+    "title": "Finish signing in in the setup browser tab.",
+    "body": "Keep the setup tab open, complete Google sign-in, then return to this window. Your setup stays here.",
+    "detail": "Choose the intended Google account. If the handoff does not complete, use the recovery action in this window instead of reinstalling."
+  },
+  "onboarding_choose_account": {
+    "title": "Check which account will own the cameras.",
+    "body": "Choose the account for this location before continuing. Use an account you are authorized to manage.",
+    "detail": "If you manage several businesses, check the account name. Follow any account-access notice above before proceeding."
+  },
+  "account_attention": {
+    "title": "Check which account will own the cameras.",
+    "body": "Choose the account for this location before continuing. Use an account you are authorized to manage.",
+    "detail": "If you manage several businesses, check the account name. Follow any account-access notice above before proceeding."
+  },
+  "onboarding_terms": {
+    "title": "Review the agreements before continuing.",
+    "body": "Open the agreement links and review the current terms. Accept only when you are authorized to do so.",
+    "detail": "Guiding tips are optional. Turning them off never accepts an agreement or changes a required account step."
+  },
+  "onboarding_plan": {
+    "title": "Choose the plan for this account.",
+    "body": "Check the plan and billing interval before continuing to secure Stripe checkout.",
+    "detail": "Existing subscription access is checked automatically. If payment is needed, complete checkout in the setup browser and return here."
+  },
+  "onboarding_checkout": {
+    "title": "Complete checkout in your browser.",
+    "body": "Keep the setup browser tab open. The Connector continues after subscription access is confirmed.",
+    "detail": "If you cancel checkout, account setup is preserved. Use Back to plans to retry. Avoid a second purchase while payment is still being confirmed."
+  },
+  "onboarding_install": {
+    "title": "Continue in camera setup.",
+    "body": "Keep the Connector running while you connect the recorder and check its channels in the camera setup window.",
+    "detail": "If camera setup asks for a code, use the current code shown in this Connector. An old code belongs to an earlier session."
+  },
+  "waiting_for_account": {
+    "title": "Continue in camera setup.",
+    "body": "Keep the Connector running while you connect the recorder and check its channels in the camera setup window.",
+    "detail": "If camera setup asks for a code, use the current code shown in this Connector. An old code belongs to an earlier session."
+  },
+  "account_connected": {
+    "title": "Continue in camera setup.",
+    "body": "Keep the Connector running while you connect the recorder and check its channels in the camera setup window.",
+    "detail": "If camera setup asks for a code, use the current code shown in this Connector. An old code belongs to an earlier session."
+  },
+  "discovering": {
+    "title": "Keep the recorder within reach.",
+    "body": "The Connector searches the local network. Select your recorder in camera setup and enter that device\u2019s login.",
+    "detail": "If nothing appears, check power and network connections or enter the recorder address manually. Guest Wi-Fi and isolated camera ports can prevent discovery."
+  },
+  "devices_found": {
+    "title": "Keep the recorder within reach.",
+    "body": "The Connector searches the local network. Select your recorder in camera setup and enter that device\u2019s login.",
+    "detail": "If nothing appears, check power and network connections or enter the recorder address manually. Guest Wi-Fi and isolated camera ports can prevent discovery."
+  },
+  "validating": {
+    "title": "Check each camera before adding it.",
+    "body": "Keep setup open while every channel is checked. Only validated feeds can be selected and added.",
+    "detail": "Empty, black or unreadable channels are left out. Check a missing camera\u2019s power, cable, permissions and stream settings, then retry in camera setup."
+  },
+  "cameras_created": {
+    "title": "Keep this computer awake while we finish.",
+    "body": "Camera pairing is saved. Let the local model and sensing service checks finish before closing setup.",
+    "detail": "The local model runs on this computer. If local AI needs attention, retry that step; you do not need to repeat camera pairing."
+  },
+  "local_ai": {
+    "title": "Keep this computer awake while we finish.",
+    "body": "Camera pairing is saved. Let the local model and sensing service checks finish before closing setup.",
+    "detail": "The local model runs on this computer. If local AI needs attention, retry that step; you do not need to repeat camera pairing."
+  },
+  "starting_service": {
+    "title": "Keep this computer awake while we finish.",
+    "body": "Camera pairing is saved. Let the local model and sensing service checks finish before closing setup.",
+    "detail": "The local model runs on this computer. If local AI needs attention, retry that step; you do not need to repeat camera pairing."
+  },
+  "local_ai_error": {
+    "title": "Retry local AI without pairing again.",
+    "body": "Your camera pairing is saved. Use Retry local AI to prepare the local model and service again.",
+    "detail": "Keep the computer powered and check its available disk space. Follow the error above. If the retry fails, contact support with the setup error, without camera credentials."
+  },
+  "ready": {
+    "title": "Leave this computer powered and connected.",
+    "body": "Sense Anything starts automatically when this computer logs in. Use View cameras to check sensing status.",
+    "detail": "Sleep, power loss or a disconnected camera network can interrupt sensing. Reopen Sense Anything Connector to resume or repair setup."
+  },
+  "error": {
+    "title": "Follow the setup notice above.",
+    "body": "Use the recovery action shown in this window. Keep your account and recorder credentials private.",
+    "detail": "If the problem continues, contact support with the visible error. Do not share passwords or camera stream links in screenshots."
+  },
+  "update_required": {
+    "title": "Follow the setup notice above.",
+    "body": "Use the recovery action shown in this window. Keep your account and recorder credentials private.",
+    "detail": "If the problem continues, contact support with the visible error. Do not share passwords or camera stream links in screenshots."
+  }
+}

package/deploy/windows/build-windows.ps1

@@ -193,6 +193,7 @@ Log "Bundled ffmpeg OK"
 # PATH=bin first so the connector's default ffmpeg='ffmpeg' resolves to OURS.
 Copy-Item -Force "$Here\trillboards-edge.cmd" "$Payload\bin\trillboards-edge.cmd"
 Copy-Item -Force "$Here\trillboards-pair.cmd" "$Payload\bin\trillboards-pair.cmd"
+Copy-Item -Force "$Here\..\setup-guidance.json" "$Payload\bin\setup-guidance.json"
 Copy-Item -Force "$Here\trillboards-setup.ps1" "$Payload\bin\trillboards-setup.ps1"
 Copy-Item -Force "$Here\trillboards-setup.vbs" "$Payload\bin\trillboards-setup.vbs"
 Copy-Item -Force "$Here\trillboards-edge-task.vbs" "$Payload\bin\trillboards-edge-task.vbs"

package/deploy/windows/trillboards-setup.ps1

@@ -120,8 +120,8 @@ function Format-ByteCount($Value) {
 $Form = New-Object System.Windows.Forms.Form
 $Form.Text = 'Sense Anything Connector'
 $Form.StartPosition = [System.Windows.Forms.FormStartPosition]::CenterScreen
-$Form.ClientSize = New-Object System.Drawing.Size(760, 540)
-$Form.MinimumSize = New-Object System.Drawing.Size(700, 520)
+$Form.ClientSize = New-Object System.Drawing.Size(760, 700)
+$Form.MinimumSize = New-Object System.Drawing.Size(760, 700)
 $Form.BackColor = [System.Drawing.Color]::White
 $Form.MaximizeBox = $false
 
@@ -224,6 +224,85 @@ $CloseAction.Size = New-Object System.Drawing.Size(100, 42)
 $CloseAction.Visible = $false
 $Form.Controls.Add($CloseAction)
 
+# Guidance preferences contain only a boolean; setup never depends on storage.
+$GuidancePreferencePath = Join-Path $StateDir 'setup-guiding-tips.json'
+$script:GuidanceCatalog = $null
+$script:DismissedGuidance = @{}
+$guidePath = Join-Path $BinDir 'setup-guidance.json'
+if (-not (Test-Path $guidePath)) { $guidePath = Join-Path $BinDir '..\setup-guidance.json' }
+try { $script:GuidanceCatalog = Get-Content -Raw $guidePath | ConvertFrom-Json } catch { }
+$guidanceDisabled = $false
+try { $guidanceDisabled = (Get-Content -Raw $GuidancePreferencePath | ConvertFrom-Json).disabled -eq $true } catch { }
+$GuidanceToggle = New-Object System.Windows.Forms.CheckBox
+$GuidanceToggle.Text = 'Guiding tips'
+$GuidanceToggle.Location = New-Object System.Drawing.Point(24, 510)
+$GuidanceToggle.Size = New-Object System.Drawing.Size(145, 28)
+$GuidanceToggle.Checked = -not $guidanceDisabled
+$Sidebar.Controls.Add($GuidanceToggle)
+$GuidanceRestore = New-Object System.Windows.Forms.Button
+$GuidanceRestore.Text = 'Show this tip'
+$GuidanceRestore.Location = New-Object System.Drawing.Point(24, 548)
+$GuidanceRestore.Size = New-Object System.Drawing.Size(140, 30)
+$Sidebar.Controls.Add($GuidanceRestore)
+$GuidancePanel = New-Object System.Windows.Forms.Panel
+$GuidancePanel.Location = New-Object System.Drawing.Point(236, 530)
+$GuidancePanel.Size = New-Object System.Drawing.Size(465, 150)
+$GuidancePanel.BackColor = [System.Drawing.Color]::FromArgb(255, 245, 232)
+$GuidancePanel.BorderStyle = [System.Windows.Forms.BorderStyle]::FixedSingle
+$Form.Controls.Add($GuidancePanel)
+$GuidanceTitle = New-Label -Text '' -Size 10 -Style ([System.Drawing.FontStyle]::Bold)
+$GuidanceTitle.Location = New-Object System.Drawing.Point(12, 9)
+$GuidanceTitle.Size = New-Object System.Drawing.Size(402, 38)
+$GuidanceTitle.ForeColor = [System.Drawing.Color]::FromArgb(71, 51, 36)
+$GuidancePanel.Controls.Add($GuidanceTitle)
+$GuidanceBody = New-Label -Text '' -Size 9
+$GuidanceBody.Location = New-Object System.Drawing.Point(12, 48)
+$GuidanceBody.Size = New-Object System.Drawing.Size(435, 62)
+$GuidanceBody.ForeColor = [System.Drawing.Color]::FromArgb(97, 74, 59)
+$GuidancePanel.Controls.Add($GuidanceBody)
+$GuidanceDismiss = New-Object System.Windows.Forms.Button
+$GuidanceDismiss.Text = 'x'
+$GuidanceDismiss.AccessibleName = 'Dismiss this tip'
+$GuidanceDismiss.Location = New-Object System.Drawing.Point(423, 8)
+$GuidanceDismiss.Size = New-Object System.Drawing.Size(28, 26)
+$GuidancePanel.Controls.Add($GuidanceDismiss)
+$GuidanceMore = New-Object System.Windows.Forms.Button
+$GuidanceMore.Text = 'More help'
+$GuidanceMore.Location = New-Object System.Drawing.Point(12, 115)
+$GuidanceMore.Size = New-Object System.Drawing.Size(100, 26)
+$GuidancePanel.Controls.Add($GuidanceMore)
+
+function Get-CurrentGuidance {
+  if ($null -eq $script:GuidanceCatalog) { return $null }
+  $entry = $script:GuidanceCatalog.PSObject.Properties[$script:LastStage]
+  if ($null -eq $entry) { return $null }
+  return $entry.Value
+}
+function Update-Guidance {
+  $guide = Get-CurrentGuidance
+  $dismissed = $script:DismissedGuidance.ContainsKey($script:LastStage)
+  $GuidancePanel.Visible = $GuidanceToggle.Checked -and -not $dismissed -and $null -ne $guide
+  $GuidanceRestore.Visible = $GuidanceToggle.Checked -and $dismissed
+  if ($null -ne $guide) {
+    $GuidanceTitle.Text = [string]$guide.title
+    $GuidanceBody.Text = [string]$guide.body
+  }
+}
+$GuidanceToggle.Add_CheckedChanged({
+  $script:DismissedGuidance.Clear()
+  Update-Guidance
+  try {
+    [void][System.IO.Directory]::CreateDirectory($StateDir)
+    @{ disabled = -not $GuidanceToggle.Checked } | ConvertTo-Json | Set-Content -Path $GuidancePreferencePath -Encoding UTF8
+  } catch { }
+})
+$GuidanceDismiss.Add_Click({ $script:DismissedGuidance[$script:LastStage] = $true; Update-Guidance })
+$GuidanceRestore.Add_Click({ $script:DismissedGuidance.Remove($script:LastStage); Update-Guidance })
+$GuidanceMore.Add_Click({
+  $guide = Get-CurrentGuidance
+  if ($null -ne $guide) { [void][System.Windows.Forms.MessageBox]::Show($Form, [string]$guide.detail, [string]$guide.title) }
+})
+
 # Native onboarding controls
 # These panels are real WinForms controls rather than a webview. Google and
 # Stripe alone open the system browser for provider-owned secure UI, then the
@@ -467,6 +546,7 @@ $PlanSubmit.Add_Click({
 function Show-Welcome {
   Set-OnboardingPanel $null
   $script:LastStage = 'welcome'
+  Update-Guidance
   $Headline.Text = 'Set up this computer for CCTV'
   $Detail.Text = 'Connect your Sense Anything account, find your recorder, and verify every camera before screens are created.'
   $StatusValue.Text = 'About 5 minutes'
@@ -481,6 +561,7 @@ function Show-Welcome {
 function Show-LocalError([string]$Title, [string]$Message) {
   Set-OnboardingPanel $null
   $script:LastStage = 'error'
+  Update-Guidance
   $Headline.Text = $Title
   $Detail.Text = $Message
   $StatusValue.Text = 'Setup stopped'
@@ -565,6 +646,7 @@ function Complete-UpdateCheck {
       }
       $script:RequiredUpdateUrl = $downloadUrl
       $script:LastStage = 'update_required'
+      Update-Guidance
       $Headline.Text = 'Update required before setup can continue'
       $Detail.Text = 'Install the latest Sense Anything Connector, then reopen it to finish camera setup.'
       $StatusValue.Text = "Version $availableText"
@@ -623,6 +705,7 @@ function Start-Setup {
   $Progress.Value = 8
   $Action.Enabled = $false
   $script:LastStage = 'starting'
+  Update-Guidance
   $script:SetupStarted = $true
 
   $startInfo = New-Object System.Diagnostics.ProcessStartInfo
@@ -653,6 +736,7 @@ function Start-LocalAiSetup {
   $Action.Text = 'Working...'
   $Action.Enabled = $false
   $script:LastStage = 'local_ai'
+  Update-Guidance
 
   $startInfo = New-Object System.Diagnostics.ProcessStartInfo
   $startInfo.FileName = 'powershell.exe'
@@ -721,6 +805,7 @@ function Render-State($State) {
   if (-not $stage) { return }
   $previousStage = $script:LastStage
   $script:LastStage = $stage
+  Update-Guidance
   $url = Get-StateValue $State 'portalUrl'
   if ($url) { $script:PortalUrl = [string]$url }
   $Headline.Text = [string](Get-StateValue $State 'title')
@@ -932,6 +1017,20 @@ $Timer.Add_Tick({
 })
 Show-Welcome
 if ($SmokeTest) {
+  if ($null -eq $script:GuidanceCatalog) { throw 'Setup guidance catalog is missing.' }
+  foreach ($entry in $script:GuidanceCatalog.PSObject.Properties) {
+    $script:LastStage = $entry.Name
+    Update-Guidance
+    foreach ($label in @($GuidanceTitle, $GuidanceBody)) {
+      $available = New-Object System.Drawing.Size(($label.Width - 6), 1000)
+      $measured = [System.Windows.Forms.TextRenderer]::MeasureText($label.Text, $label.Font, $available, [System.Windows.Forms.TextFormatFlags]::WordBreak)
+      if ($measured.Height -gt $label.Height) { throw "Setup guidance text clipped: $($entry.Name)" }
+    }
+  }
+  if ($GuidancePanel.Bounds.IntersectsWith($Action.Bounds) -or $GuidancePanel.Bounds.IntersectsWith($AccountPanel.Bounds)) {
+    throw 'Guidance overlaps setup controls.'
+  }
+  Show-Welcome
   if ($StepLabels.Count -ne 8 -or $Form.Controls.Count -lt 8 -or $Action.Text -ne 'Start setup') {
     throw 'Windows setup UI did not construct its expected controls.'
   }

package/dist/EdgeAgent.js

@@ -44,7 +44,7 @@ const edge_ads_1 = require("@trillboards/edge-ads");
 const CommandRouter_1 = require("./CommandRouter");
 const config_1 = require("./config");
 const dataDir_1 = require("./dataDir");
-const SDK_VERSION = '0.2.138';
+const SDK_VERSION = '0.2.140';
 class EdgeAgent extends events_1.EventEmitter {
     constructor(config, deps) {
         super();

package/dist/diagnose.d.ts

@@ -31,7 +31,7 @@ export interface DiagnosticReport {
         skipped: number;
     };
 }
-declare const SDK_VERSION = "0.2.138";
+declare const SDK_VERSION = "0.2.140";
 declare function checkNodeVersion(): CheckResult;
 declare function checkPlatform(): CheckResult;
 declare function checkMemory(): CheckResult;

package/dist/diagnose.js

@@ -63,7 +63,7 @@ const localNetworkAccess_1 = require("./localNetworkAccess");
 // ---------------------------------------------------------------------------
 // SDK version — mirrors package.json; kept in sync by CI
 // ---------------------------------------------------------------------------
-const SDK_VERSION = '0.2.138';
+const SDK_VERSION = '0.2.140';
 exports._SDK_VERSION = SDK_VERSION;
 // ---------------------------------------------------------------------------
 // ANSI helpers (no external deps)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trillboards/edge-sdk",
-  "version": "0.2.138",
+  "version": "0.2.140",
   "description": "Composable cross-platform Edge AI SDK for audience sensing on DOOH/CTV devices",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",