@xenon-device-management/xenon 2.17.0 → 2.17.1

package/lib/public/assets/{webhook-settings-CBVB5lxi.js → webhook-settings-DukgCe1u.js}

@@ -1 +1 @@
-import{t as P,r as l,X as p,j as e,P as w,A as x,C as V,Q as I}from"./index-Dk5J6HB1.js";/* empty css                 */import{F as k}from"./FieldGroup-CtnCDshE.js";import{S as U}from"./select-DZoRKNti.js";import{P as B}from"./page-header-DhXCwpml.js";import{T as D}from"./trash-2-DO8fv6w4.js";import{P as _}from"./plus-BKboorfa.js";import{C as J}from"./circle-x-CHxSRLHp.js";import{C as K}from"./circle-check-Day0HjW4.js";import{Z as M}from"./zap-BMrTJO6M.js";import{A as X}from"./activity-CvuZdQYu.js";import"./utils-CDN07tui.js";const Z=["udid","name","host","platform"],q=["udid","name","host","platform"],G=["sessionId","sessionName","failureReason","udid","deviceName","platform","osVersion","startTime","endTime"],Q=["windowDays","totalHeals","distinctSelectors"],Y={device_offline:Z,device_new:q,session_failed:G,selector_health_digest:Q},ee=Y,se={eventType:"The event: device_offline, session_failed, ...",udid:"The device's id",name:"The device's name",host:"The machine it is plugged into",platform:"android or ios",sessionId:"The session's id",sessionName:"The session's name, if the test gave it one",failureReason:"Why it failed",deviceName:"The device's name",osVersion:"The device's OS version",startTime:"When it started (ISO 8601)",endTime:"When it ended (ISO 8601)",windowDays:"How many days the digest covers",totalHeals:"Heals in that time",distinctSelectors:"Selectors that were healed"};function te(o){const c=["eventType"];for(const u of o)for(const h of ee[u]??[])c.includes(h)||c.push(h);return c}const ae=[{id:"slack",label:"Slack message"},{id:"webhook",label:"JSON (event and payload)"}];function oe(o){return o.payloadTemplate?"CUSTOM":o.type==="slack"?"SLACK":"JSON"}const j=[{id:"device_offline",label:"Device offline",icon:V,tone:"red"},{id:"device_new",label:"New device",icon:_,tone:"green"},{id:"session_failed",label:"Session failed",icon:J,tone:"amber"},{id:"selector_health_digest",label:"Selector health digest",icon:I,tone:"green"}],be=()=>{const{toast:o}=P(),[c,u]=l.useState([]),[h,N]=l.useState(!0),[r,y]=l.useState(""),[i,S]=l.useState(["device_offline","session_failed"]),[f,T]=l.useState(!1),[C,A]=l.useState(!1),[d,E]=l.useState(!1),[m,g]=l.useState(""),[b,O]=l.useState("slack");l.useEffect(()=>{v()},[]);const v=async()=>{N(!0);try{const s=await p.getWebhookConfigs();u(s||[])}catch(s){console.error("Failed to load webhook configs",s),o("Failed to load webhooks.","error")}finally{N(!1)}},W=async()=>{if(!r.trim()){o("Webhook URL is required.","error");return}if(i.length===0){o("Select at least one trigger event.","error");return}T(!0);try{await p.addWebhookConfig(r.trim(),i,b,m||void 0),y(""),g(""),E(!1),O("slack"),S(["device_offline","session_failed"]),await v(),o("Webhook saved.","success")}catch(s){console.error("Failed to add webhook",s),o(`Failed to add webhook: ${s.message||"unknown error"}`,"error")}finally{T(!1)}},$=async(s,t)=>{if(window.confirm(`Remove webhook for "${t}"?`))try{await p.deleteWebhookConfig(s),await v(),o("Webhook removed.","success")}catch(a){console.error("Failed to delete webhook",a),o(`Failed to delete: ${a.message||"unknown error"}`,"error")}},L=async()=>{if(!r.trim()||i.length===0)return;A(!0);const s=t=>{var a;return((a=j.find(n=>n.id===t))==null?void 0:a.label)??t};try{for(const t of i)try{await p.testWebhook(r.trim(),b,m||void 0,t)}catch(a){o(`Test failed for ${s(t)}: ${a.message||"check the URL"}`,"error");return}o(i.length===1?`Test message delivered: ${s(i[0])}.`:`Test messages delivered: ${i.map(s).join(", ")}.`,"success")}finally{A(!1)}},R=s=>{S(t=>t.includes(s)?t.filter(a=>a!==s):[...t,s])},z=s=>{g(t=>t+`{{${s}}} `)};return e.jsxs("div",{className:"settings-container",children:[e.jsx(B,{icon:w,title:"Notifications",subtitle:"Configure Slack or generic webhooks to receive alerts for critical infrastructure events."}),e.jsxs("div",{className:"settings-content",children:[h?e.jsxs("div",{className:"settings-loading",style:{height:200},children:[e.jsx(x,{className:"animate-spin",size:28}),e.jsx("span",{children:"Loading webhooks…"})]}):c.length===0?e.jsxs("div",{className:"empty-state",children:[e.jsx("div",{className:"empty-state__icon",children:e.jsx(w,{size:28})}),e.jsx("h3",{className:"empty-state__title",children:"No webhooks configured"}),e.jsx("p",{className:"empty-state__copy",children:"Wire up a Slack incoming webhook or any HTTPS endpoint to receive alerts when devices go offline, new devices register, or sessions fail. Configure your first webhook below."})]}):e.jsx("div",{className:"webhook-list-grid",children:c.map(s=>{const t=(()=>{try{return JSON.parse(s.events)}catch{return[]}})();return e.jsxs("div",{className:"webhook-row-card",children:[e.jsxs("div",{className:"webhook-row-card__header",children:[e.jsx("span",{className:`pill-chip ${s.payloadTemplate?"pill-chip--admin":"pill-chip--scope"}`,children:oe(s)}),e.jsx("span",{className:"webhook-row-card__url",title:s.url,children:s.url}),e.jsxs("button",{type:"button",className:"row-action row-action--danger",onClick:()=>$(s.id,s.url),"aria-label":`Remove webhook for ${s.url}`,children:[e.jsx(D,{size:13}),e.jsx("span",{children:"Remove"})]})]}),e.jsx("div",{className:"webhook-row-card__events",children:t.length===0?e.jsx("span",{className:"webhook-row-card__no-events",children:"No triggers"}):t.map(a=>{const n=j.find(H=>H.id===a),F=(n==null?void 0:n.icon)??w;return e.jsxs("span",{className:`event-pill event-pill--${(n==null?void 0:n.tone)||"gray"}`,children:[e.jsx(F,{size:11}),(n==null?void 0:n.label)||a]},a)})})]},s.id)})}),e.jsxs("div",{className:"add-webhook-card",children:[e.jsxs("div",{className:"add-webhook-card__header",children:[e.jsx(_,{size:14}),e.jsx("span",{children:"Add a new webhook"})]}),e.jsxs("div",{className:"add-webhook-card__body",children:[e.jsx(k,{label:"Webhook URL",description:"The endpoint we POST webhook events to.",htmlFor:"webhook-url",children:e.jsx("div",{className:"setting-input-wrapper",children:e.jsx("input",{id:"webhook-url",type:"url",placeholder:"https://hooks.slack.com/services/...",value:r,onChange:s=>y(s.target.value)})})}),e.jsx(k,{label:"Message format",description:m.trim()?"Your custom payload is sent as written, whatever the format.":"Slack message for a Slack incoming webhook; JSON for anything else.",htmlFor:"webhook-format",children:e.jsx(U,{id:"webhook-format",value:b,onChange:s=>O(s.target.value),children:ae.map(s=>e.jsx("option",{value:s.id,children:s.label},s.id))})}),e.jsx(k,{label:"Trigger events",children:e.jsx("div",{className:"event-toggle-grid",children:j.map(s=>{const t=i.includes(s.id),a=s.icon;return e.jsxs("button",{type:"button",role:"checkbox","aria-checked":t,className:`event-toggle event-toggle--${s.tone} ${t?"is-selected":""}`,onClick:()=>R(s.id),children:[e.jsx(a,{size:14,className:"event-toggle__lead"}),e.jsx("span",{children:s.label}),t&&e.jsx(K,{size:14,className:"event-toggle__check"})]},s.id)})})}),e.jsxs("div",{className:"template-section",children:[e.jsxs("button",{type:"button",className:"template-section__toggle",onClick:()=>E(!d),"aria-expanded":d,children:[e.jsx(M,{size:14,className:d?"tone-amber":"tone-dim"}),e.jsx("span",{children:"Use custom payload (optional)"}),e.jsx("span",{className:"template-section__indicator",children:d?"−":"+"})]}),d&&e.jsxs("div",{className:"template-editor",children:[e.jsx("p",{className:"template-editor__hint",children:"Define a JSON or text template. Click a name below to insert it; the names are the ones your selected events carry."}),e.jsx("div",{className:"template-editor__chips",children:te(i).map(s=>e.jsx("button",{type:"button",className:"template-editor__chip","aria-label":`{{${s}}}`,title:se[s],onClick:()=>z(s),children:`{{${s}}}`},s))}),e.jsx("textarea",{className:"template-editor__textarea",placeholder:'Example: { "text": "Alert: Device {{udid}} is offline!" }',value:m,onChange:s=>g(s.target.value),rows:4})]})]})]}),e.jsxs("div",{className:"add-webhook-card__footer",children:[e.jsxs("button",{type:"button",className:"page-header-action page-header-action--ghost",onClick:L,disabled:!r.trim()||i.length===0||C,"aria-label":"Send test",title:i.length===0?"Select a trigger event to send a sample of":"Sends a sample message for each selected event",children:[C?e.jsx(x,{size:14,className:"animate-spin"}):e.jsx(X,{size:14}),e.jsx("span",{children:"Send test"})]}),e.jsxs("button",{type:"button",className:"page-header-action",onClick:W,disabled:f||!r.trim(),children:[f?e.jsx(x,{size:14,className:"animate-spin"}):e.jsx(_,{size:14}),e.jsx("span",{children:f?"Saving…":"Save webhook"})]})]})]})]})]})};export{be as WebhookSettings};
+import{t as P,r as l,X as p,j as e,P as w,A as x,C as V,Q as I}from"./index-BpqyclNY.js";/* empty css                 */import{F as k}from"./FieldGroup-CaQNXgcE.js";import{S as U}from"./select-Cx4JDzsR.js";import{P as B}from"./page-header-CAbH1O1a.js";import{T as D}from"./trash-2-BIRm2KVs.js";import{P as _}from"./plus-BT9mk2gj.js";import{C as J}from"./circle-x-C8GvvXVt.js";import{C as K}from"./circle-check-Crt-G_uy.js";import{Z as M}from"./zap-BE9gacFj.js";import{A as X}from"./activity-pEyAdE-M.js";import"./utils-CDN07tui.js";const Z=["udid","name","host","platform"],q=["udid","name","host","platform"],G=["sessionId","sessionName","failureReason","udid","deviceName","platform","osVersion","startTime","endTime"],Q=["windowDays","totalHeals","distinctSelectors"],Y={device_offline:Z,device_new:q,session_failed:G,selector_health_digest:Q},ee=Y,se={eventType:"The event: device_offline, session_failed, ...",udid:"The device's id",name:"The device's name",host:"The machine it is plugged into",platform:"android or ios",sessionId:"The session's id",sessionName:"The session's name, if the test gave it one",failureReason:"Why it failed",deviceName:"The device's name",osVersion:"The device's OS version",startTime:"When it started (ISO 8601)",endTime:"When it ended (ISO 8601)",windowDays:"How many days the digest covers",totalHeals:"Heals in that time",distinctSelectors:"Selectors that were healed"};function te(o){const c=["eventType"];for(const u of o)for(const h of ee[u]??[])c.includes(h)||c.push(h);return c}const ae=[{id:"slack",label:"Slack message"},{id:"webhook",label:"JSON (event and payload)"}];function oe(o){return o.payloadTemplate?"CUSTOM":o.type==="slack"?"SLACK":"JSON"}const j=[{id:"device_offline",label:"Device offline",icon:V,tone:"red"},{id:"device_new",label:"New device",icon:_,tone:"green"},{id:"session_failed",label:"Session failed",icon:J,tone:"amber"},{id:"selector_health_digest",label:"Selector health digest",icon:I,tone:"green"}],be=()=>{const{toast:o}=P(),[c,u]=l.useState([]),[h,N]=l.useState(!0),[r,y]=l.useState(""),[i,S]=l.useState(["device_offline","session_failed"]),[f,T]=l.useState(!1),[C,A]=l.useState(!1),[d,E]=l.useState(!1),[m,g]=l.useState(""),[b,O]=l.useState("slack");l.useEffect(()=>{v()},[]);const v=async()=>{N(!0);try{const s=await p.getWebhookConfigs();u(s||[])}catch(s){console.error("Failed to load webhook configs",s),o("Failed to load webhooks.","error")}finally{N(!1)}},W=async()=>{if(!r.trim()){o("Webhook URL is required.","error");return}if(i.length===0){o("Select at least one trigger event.","error");return}T(!0);try{await p.addWebhookConfig(r.trim(),i,b,m||void 0),y(""),g(""),E(!1),O("slack"),S(["device_offline","session_failed"]),await v(),o("Webhook saved.","success")}catch(s){console.error("Failed to add webhook",s),o(`Failed to add webhook: ${s.message||"unknown error"}`,"error")}finally{T(!1)}},$=async(s,t)=>{if(window.confirm(`Remove webhook for "${t}"?`))try{await p.deleteWebhookConfig(s),await v(),o("Webhook removed.","success")}catch(a){console.error("Failed to delete webhook",a),o(`Failed to delete: ${a.message||"unknown error"}`,"error")}},L=async()=>{if(!r.trim()||i.length===0)return;A(!0);const s=t=>{var a;return((a=j.find(n=>n.id===t))==null?void 0:a.label)??t};try{for(const t of i)try{await p.testWebhook(r.trim(),b,m||void 0,t)}catch(a){o(`Test failed for ${s(t)}: ${a.message||"check the URL"}`,"error");return}o(i.length===1?`Test message delivered: ${s(i[0])}.`:`Test messages delivered: ${i.map(s).join(", ")}.`,"success")}finally{A(!1)}},R=s=>{S(t=>t.includes(s)?t.filter(a=>a!==s):[...t,s])},z=s=>{g(t=>t+`{{${s}}} `)};return e.jsxs("div",{className:"settings-container",children:[e.jsx(B,{icon:w,title:"Notifications",subtitle:"Configure Slack or generic webhooks to receive alerts for critical infrastructure events."}),e.jsxs("div",{className:"settings-content",children:[h?e.jsxs("div",{className:"settings-loading",style:{height:200},children:[e.jsx(x,{className:"animate-spin",size:28}),e.jsx("span",{children:"Loading webhooks…"})]}):c.length===0?e.jsxs("div",{className:"empty-state",children:[e.jsx("div",{className:"empty-state__icon",children:e.jsx(w,{size:28})}),e.jsx("h3",{className:"empty-state__title",children:"No webhooks configured"}),e.jsx("p",{className:"empty-state__copy",children:"Wire up a Slack incoming webhook or any HTTPS endpoint to receive alerts when devices go offline, new devices register, or sessions fail. Configure your first webhook below."})]}):e.jsx("div",{className:"webhook-list-grid",children:c.map(s=>{const t=(()=>{try{return JSON.parse(s.events)}catch{return[]}})();return e.jsxs("div",{className:"webhook-row-card",children:[e.jsxs("div",{className:"webhook-row-card__header",children:[e.jsx("span",{className:`pill-chip ${s.payloadTemplate?"pill-chip--admin":"pill-chip--scope"}`,children:oe(s)}),e.jsx("span",{className:"webhook-row-card__url",title:s.url,children:s.url}),e.jsxs("button",{type:"button",className:"row-action row-action--danger",onClick:()=>$(s.id,s.url),"aria-label":`Remove webhook for ${s.url}`,children:[e.jsx(D,{size:13}),e.jsx("span",{children:"Remove"})]})]}),e.jsx("div",{className:"webhook-row-card__events",children:t.length===0?e.jsx("span",{className:"webhook-row-card__no-events",children:"No triggers"}):t.map(a=>{const n=j.find(H=>H.id===a),F=(n==null?void 0:n.icon)??w;return e.jsxs("span",{className:`event-pill event-pill--${(n==null?void 0:n.tone)||"gray"}`,children:[e.jsx(F,{size:11}),(n==null?void 0:n.label)||a]},a)})})]},s.id)})}),e.jsxs("div",{className:"add-webhook-card",children:[e.jsxs("div",{className:"add-webhook-card__header",children:[e.jsx(_,{size:14}),e.jsx("span",{children:"Add a new webhook"})]}),e.jsxs("div",{className:"add-webhook-card__body",children:[e.jsx(k,{label:"Webhook URL",description:"The endpoint we POST webhook events to.",htmlFor:"webhook-url",children:e.jsx("div",{className:"setting-input-wrapper",children:e.jsx("input",{id:"webhook-url",type:"url",placeholder:"https://hooks.slack.com/services/...",value:r,onChange:s=>y(s.target.value)})})}),e.jsx(k,{label:"Message format",description:m.trim()?"Your custom payload is sent as written, whatever the format.":"Slack message for a Slack incoming webhook; JSON for anything else.",htmlFor:"webhook-format",children:e.jsx(U,{id:"webhook-format",value:b,onChange:s=>O(s.target.value),children:ae.map(s=>e.jsx("option",{value:s.id,children:s.label},s.id))})}),e.jsx(k,{label:"Trigger events",children:e.jsx("div",{className:"event-toggle-grid",children:j.map(s=>{const t=i.includes(s.id),a=s.icon;return e.jsxs("button",{type:"button",role:"checkbox","aria-checked":t,className:`event-toggle event-toggle--${s.tone} ${t?"is-selected":""}`,onClick:()=>R(s.id),children:[e.jsx(a,{size:14,className:"event-toggle__lead"}),e.jsx("span",{children:s.label}),t&&e.jsx(K,{size:14,className:"event-toggle__check"})]},s.id)})})}),e.jsxs("div",{className:"template-section",children:[e.jsxs("button",{type:"button",className:"template-section__toggle",onClick:()=>E(!d),"aria-expanded":d,children:[e.jsx(M,{size:14,className:d?"tone-amber":"tone-dim"}),e.jsx("span",{children:"Use custom payload (optional)"}),e.jsx("span",{className:"template-section__indicator",children:d?"−":"+"})]}),d&&e.jsxs("div",{className:"template-editor",children:[e.jsx("p",{className:"template-editor__hint",children:"Define a JSON or text template. Click a name below to insert it; the names are the ones your selected events carry."}),e.jsx("div",{className:"template-editor__chips",children:te(i).map(s=>e.jsx("button",{type:"button",className:"template-editor__chip","aria-label":`{{${s}}}`,title:se[s],onClick:()=>z(s),children:`{{${s}}}`},s))}),e.jsx("textarea",{className:"template-editor__textarea",placeholder:'Example: { "text": "Alert: Device {{udid}} is offline!" }',value:m,onChange:s=>g(s.target.value),rows:4})]})]})]}),e.jsxs("div",{className:"add-webhook-card__footer",children:[e.jsxs("button",{type:"button",className:"page-header-action page-header-action--ghost",onClick:L,disabled:!r.trim()||i.length===0||C,"aria-label":"Send test",title:i.length===0?"Select a trigger event to send a sample of":"Sends a sample message for each selected event",children:[C?e.jsx(x,{size:14,className:"animate-spin"}):e.jsx(X,{size:14}),e.jsx("span",{children:"Send test"})]}),e.jsxs("button",{type:"button",className:"page-header-action",onClick:W,disabled:f||!r.trim(),children:[f?e.jsx(x,{size:14,className:"animate-spin"}):e.jsx(_,{size:14}),e.jsx("span",{children:f?"Saving…":"Save webhook"})]})]})]})]})]})};export{be as WebhookSettings};

package/lib/public/assets/{zap-BMrTJO6M.js → zap-BE9gacFj.js}

@@ -1,4 +1,4 @@
-import{c as a}from"./index-Dk5J6HB1.js";/**
+import{c as a}from"./index-BpqyclNY.js";/**
  * @license lucide-react v0.555.0 - ISC
  *
  * This source code is licensed under the ISC license.

package/lib/public/index.html

@@ -36,7 +36,7 @@
       Learn how to configure a non-root public URL by running `npm run build`.
     -->
   <title>Xenon</title>
-  <script type="module" crossorigin src="/xenon/assets/index-Dk5J6HB1.js"></script>
+  <script type="module" crossorigin src="/xenon/assets/index-BpqyclNY.js"></script>
   <link rel="stylesheet" crossorigin href="/xenon/assets/index-Bxoxt9sV.css">
 </head>
 

package/lib/src/app/openapi/control.yaml

@@ -1941,8 +1941,12 @@ paths:
       summary: Start the live preview and hold the device
       description: >-
         Starts the device's live preview and holds the device for you (`session_id` becomes
-        `manual_<yourUserId>_<udid>`), so automation is not given it while you watch. iOS starts
-        WebDriverAgent's MJPEG stream (and the go-ios tunnel on iOS 17+). Android starts an MJPEG
+        `manual_<yourUserId>_<udid>`), so automation is not given it while you watch. An iPhone
+        starts WebDriverAgent's MJPEG stream (and the go-ios tunnel on iOS 17+). An iOS simulator
+        starts nothing and is not held (its test holds it): it shows the picture of the test
+        running on it, from the WebDriverAgent the XCUITest driver runs for that test, and with no
+        test running it answers `409` with `error: simulator_needs_test` and a `message` saying
+        so. Android starts an MJPEG
         screen capture, or, when the server's `streaming.androidH264` setting is on and the device
         is not being recorded, an H.264 stream for the WebSocket in `h264Path`. Missing screen
         dimensions are filled in and saved.
@@ -2035,7 +2039,34 @@ paths:
         '404':
           $ref: '#/components/responses/ControlDeviceNotFound'
         '409':
-          $ref: '#/components/responses/ControlHeld'
+          description: >-
+            Another user holds the device, or it runs another user's Appium session (admins are
+            never refused), as for every device action. Or the device is an iOS simulator no test
+            runs on (`simulator_needs_test`): its screen shows only while a test runs on it.
+          content:
+            application/json:
+              schema:
+                oneOf:
+                  - $ref: '#/components/schemas/ControlDenied'
+                  - $ref: '#/components/schemas/ControlSimulatorNeedsTest'
+              examples:
+                held:
+                  summary: Another user's preview or recording
+                  value:
+                    success: false
+                    error: device_held_by_another_user
+                    message: >-
+                      Device is being controlled by Priya Raman. Ask them to release it, or use an
+                      admin key to force-release.
+                    holder:
+                      userId: c7a1e5d2-3f4b-4a9e-8c21-5b6d7e8f9a01
+                      name: Priya Raman
+                simulatorNeedsTest:
+                  summary: An iOS simulator no test runs on
+                  value:
+                    success: false
+                    error: simulator_needs_test
+                    message: A simulator's screen shows here only while a test runs on it.
         '429':
           $ref: '#/components/responses/RateLimited'
         '500':
@@ -2286,7 +2317,9 @@ paths:
         Says whether the device's preview is running and which transport a player should use
         (`type`: `h264` on Android when the server's `streaming.androidH264` setting is on and the
         device isn't being recorded, else `mjpeg`). A device with no preview answers `200` with
-        `status: stopped`. iOS adds WebDriverAgent's port, the start time and the last error.
+        `status: stopped`. iOS adds WebDriverAgent's port, the start time and the last error. A
+        simulator no test runs on answers `status: stopped` with `lastError` saying why it shows
+        nothing, and `reason: simulator_needs_test`.
 
 
         Open to watchers. Needs the `MEMBER` role; any scope will do.
@@ -2326,6 +2359,15 @@ paths:
                     udid: R5CT32ABCDE
                     status: stopped
                     type: mjpeg
+                simulatorWithoutTest:
+                  summary: An iOS simulator no test runs on
+                  value:
+                    udid: 35429994-B029-4AF4-9634-880B89DAC782
+                    status: stopped
+                    type: mjpeg
+                    mjpegPort: 9101
+                    lastError: A simulator's screen shows here only while a test runs on it.
+                    reason: simulator_needs_test
         '400':
           description: The udid is malformed.
           content:
@@ -3147,6 +3189,13 @@ components:
         lastError:
           type: string
           description: iOS only.
+        reason:
+          type: string
+          enum:
+            - simulator_needs_test
+          description: >-
+            Set when the preview is refused rather than failed: `simulator_needs_test`, an iOS
+            simulator no test runs on.
     ControlStreamLeaveResult:
       type: object
       properties:
@@ -3156,6 +3205,22 @@ components:
         pending:
           type: boolean
           example: true
+    ControlSimulatorNeedsTest:
+      type: object
+      required:
+        - error
+        - message
+      properties:
+        success:
+          type: boolean
+          example: false
+        error:
+          type: string
+          enum:
+            - simulator_needs_test
+        message:
+          type: string
+          description: Why the simulator shows nothing, for testers.
     ControlDenied:
       type: object
       required:

package/lib/src/app/routers/control.js

@@ -58,7 +58,7 @@ const InternalHttpClient_1 = require("../../InternalHttpClient");
 const device_service_1 = require("../../data-service/device-service");
 const UniversalMjpegProxy_1 = require("../../helpers/UniversalMjpegProxy");
 const DisplayStateService_1 = require("../../services/DisplayStateService");
-const IOSStreamService_1 = __importDefault(require("../../device-managers/ios/IOSStreamService"));
+const IOSStreamService_1 = __importStar(require("../../device-managers/ios/IOSStreamService"));
 const AndroidStreamService_1 = __importDefault(require("../../device-managers/android/AndroidStreamService"));
 const AndroidH264StreamService_1 = __importDefault(require("../../device-managers/android/AndroidH264StreamService"));
 const path_1 = __importDefault(require("path"));
@@ -748,9 +748,14 @@ router.post('/:udid/stream/start', (req, res) => __awaiter(void 0, void 0, void
         // Mark device as "Busy" so automation sessions don't pick it up.
         // Lock is keyed on the user, not the credential — see
         // src/services/device-access/deviceAccessPolicy.ts.
-        const manualSid = (0, manualLock_1.formatManualLock)(actorUserId, udid);
-        yield (0, device_service_1.blockDevice)(udid, device.host, manualSid);
-        logger_1.default.info(`Manual Control: Device ${udid} locked for active UI session (${manualSid}).`);
+        // A simulator is previewed only while a test holds it, so a preview hold
+        // adds nothing, and written after the test ended it would hold a free
+        // simulator for nobody's test.
+        if (!(0, IOSStreamService_1.isIosSimulator)(device)) {
+            const manualSid = (0, manualLock_1.formatManualLock)(actorUserId, udid);
+            yield (0, device_service_1.blockDevice)(udid, device.host, manualSid);
+            logger_1.default.info(`Manual Control: Device ${udid} locked for active UI session (${manualSid}).`);
+        }
         if (streamType === 'h264') {
             logger_1.default.info(`H.264 stream started for ${udid}`);
             return res.status(200).send({
@@ -774,6 +779,13 @@ router.post('/:udid/stream/start', (req, res) => __awaiter(void 0, void 0, void
         });
     }
     catch (err) {
+        // Not a failure: a simulator shows its running test's picture, and none
+        // runs. Said in plain words; the dashboard toasts it.
+        if (err instanceof IOSStreamService_1.SimulatorPreviewNeedsTest) {
+            return res
+                .status(409)
+                .send({ success: false, error: 'simulator_needs_test', message: err.message });
+        }
         logger_1.default.error(`Failed to start stream for ${udid}: ${err.message}`);
         return res.status(500).send({
             success: false,
@@ -1037,6 +1049,9 @@ router.get('/:udid/stream/status', (req, res) => __awaiter(void 0, void 0, void
         type,
         h264Path,
         mjpegPort: device.mjpegServerPort,
+        // Why a simulator shows nothing: a Live devices tile says it once it stops retrying.
+        lastError: (0, IOSStreamService_1.simulatorPreviewRefusal)(device),
+        reason: (0, IOSStreamService_1.simulatorPreviewRefusal)(device) ? 'simulator_needs_test' : undefined,
     });
 }));
 /**
@@ -1083,7 +1098,11 @@ router.get('/:udid/stream', (req, res) => __awaiter(void 0, void 0, void 0, func
             });
         }
         catch (err) {
-            logger_1.default.error(`Failed to start stream for ${udid}: ${err.message}`);
+            // A simulator no test runs on: expected, and asked again by each retry.
+            if (err instanceof IOSStreamService_1.SimulatorPreviewNeedsTest)
+                logger_1.default.debug(`${udid}: ${err.message}`);
+            else
+                logger_1.default.error(`Failed to start stream for ${udid}: ${err.message}`);
             return res.status(503).send({
                 error: 'Stream not available',
                 message: err.message,

package/lib/src/device-managers/ios/IOSStreamService.js

@@ -60,9 +60,11 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.StreamRestartRefused = exports.IOS_IDLE_STOP_MS = void 0;
+exports.SimulatorPreviewNeedsTest = exports.SIMULATOR_PREVIEW_NEEDS_TEST = exports.StreamRestartRefused = exports.IOS_IDLE_STOP_MS = void 0;
 exports.shouldStopIdleIosStream = shouldStopIdleIosStream;
 exports.heldByAppiumSession = heldByAppiumSession;
+exports.isIosSimulator = isIosSimulator;
+exports.simulatorPreviewRefusal = simulatorPreviewRefusal;
 const typedi_1 = require("typedi");
 const ProcessRegistry_1 = require("../../services/ProcessRegistry");
 const child_process_1 = require("child_process");
@@ -82,6 +84,7 @@ const iosStreamDiagnostics_1 = require("./iosStreamDiagnostics");
 const tunnelProcess_1 = require("./tunnelProcess");
 const IOSTunnels_1 = require("./IOSTunnels");
 const goIosBinary_1 = require("./goIosBinary");
+const appiumUmbrella_1 = require("../../sessions/appiumUmbrella");
 const device_service_1 = require("../../data-service/device-service");
 const manualLock_1 = require("../../services/recording/manualLock");
 const recording_store_1 = require("../../services/recording/recording-store");
@@ -113,9 +116,39 @@ function heldByAppiumSession(device) {
 class StreamRestartRefused extends Error {
 }
 exports.StreamRestartRefused = StreamRestartRefused;
+/** Why a simulator shows no live preview: for testers, on the device page and its tile. */
+exports.SIMULATOR_PREVIEW_NEEDS_TEST = "A simulator's screen shows here only while a test runs on it.";
+/** A simulator's preview was asked for while no test runs on it. */
+class SimulatorPreviewNeedsTest extends Error {
+    constructor() {
+        super(exports.SIMULATOR_PREVIEW_NEEDS_TEST);
+    }
+}
+exports.SimulatorPreviewNeedsTest = SimulatorPreviewNeedsTest;
+/**
+ * An iOS or tvOS simulator's row. `realDevice` is false only there among
+ * Apple rows (discovery writes it, the store reads a missing one as true); an
+ * Android emulator's is false too.
+ */
+function isIosSimulator(device) {
+    return (device === null || device === void 0 ? void 0 : device.realDevice) === false && (device.platform === 'ios' || device.platform === 'tvos');
+}
+/**
+ * Why this phone can't be previewed now, or undefined when it can: a
+ * simulator no Appium session holds.
+ */
+function simulatorPreviewRefusal(device) {
+    if (!isIosSimulator(device))
+        return undefined;
+    return heldByAppiumSession(device) ? undefined : exports.SIMULATOR_PREVIEW_NEEDS_TEST;
+}
+/** How many ended sessions a simulator preview remembers, to refuse a start mid-teardown. */
+const ENDED_SESSIONS_KEPT = 200;
 let IOSStreamService = class IOSStreamService {
     constructor() {
         this.sessions = new Map();
+        /** Sessions whose simulator previews have ended (endSimulatorPreviews), newest last. */
+        this.endedSimulatorSessions = new Set();
         this.startFlight = new singleFlight_1.SingleFlight();
         this.recoveryCooldowns = new Map(); // Track last recovery attempt time
         this.RECOVERY_COOLDOWN_MS = 30000; // 30s cooldown between recovery attempts
@@ -411,6 +444,10 @@ let IOSStreamService = class IOSStreamService {
             const session = this.sessions.get(udid);
             if (!session || session.status !== 'running')
                 return false;
+            // A simulator's preview has no process of its own to check or heal: the
+            // picture is its session's, and the preview ends with it.
+            if (session.simulatorSession)
+                return true;
             // 1. Process Check: verify child processes haven't exited
             const isWdaAlive = session.wdaProcess && session.wdaProcess.exitCode === null;
             const isWdaIproxyAlive = session.forwardWDAProcess && session.forwardWDAProcess.exitCode === null;
@@ -453,6 +490,9 @@ let IOSStreamService = class IOSStreamService {
     }
     startStream(udid) {
         return __awaiter(this, void 0, void 0, function* () {
+            const device = yield (0, ownDeviceRow_1.findOwnDevice)(udid);
+            if (isIosSimulator(device))
+                return this.startSimulatorStream(udid, device);
             // Check if stream is already running - avoid unnecessary restarts
             const existingSession = this.sessions.get(udid);
             if (existingSession && existingSession.status === 'running') {
@@ -811,6 +851,82 @@ let IOSStreamService = class IOSStreamService {
             return this.startFlight.run(udid, performStartup);
         });
     }
+    /**
+     * A simulator's preview is its running test's picture. The XCUITest
+     * driver's WDA serves it on this Mac at the session's mjpegServerPort, so
+     * this starts nothing (go-ios, iproxy and runwda reach only an iPhone) and
+     * leases no port (the session's are its own). With no test running there
+     * is nothing to show: refused in plain words, with no cool-down, since a
+     * test may start any moment.
+     *
+     * Through 2.15 a simulator went through the iPhone's start. With no test it
+     * failed, and left its iproxy forwards on the ports it had leased to the
+     * simulator: a test started meanwhile was given those ports and its WDA
+     * couldn't open them. With a test it read the picture through a forward
+     * that carries nothing, so a Live devices tile stayed empty.
+     */
+    startSimulatorStream(udid, device) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            let sessionId = simulatorPreviewRefusal(device) ? undefined : ((_a = device.session_id) !== null && _a !== void 0 ? _a : undefined);
+            // An ended test's row can still name it while its phone is being released.
+            if (sessionId && this.endedSimulatorSessions.has(sessionId))
+                sessionId = undefined;
+            // Only the ports of a session Appium has now: the row's would outlive it.
+            const driver = sessionId ? typedi_2.Container.get(appiumUmbrella_1.AppiumUmbrella).driverOptions(sessionId) : undefined;
+            const wdaPort = Number(driver === null || driver === void 0 ? void 0 : driver.wdaLocalPort);
+            const mjpegPort = Number(driver === null || driver === void 0 ? void 0 : driver.mjpegServerPort);
+            const existing = this.sessions.get(udid);
+            if (!sessionId || !wdaPort || !mjpegPort) {
+                if (existing)
+                    yield this.stopStream(udid);
+                throw new SimulatorPreviewNeedsTest();
+            }
+            if ((existing === null || existing === void 0 ? void 0 : existing.simulatorSession) === sessionId && existing.status === 'running') {
+                return { wdaPort: existing.wdaPort, mjpegPort: existing.mjpegPort };
+            }
+            // An earlier test's preview, or anything else held for this simulator.
+            if (existing)
+                yield this.stopStream(udid);
+            this.sessions.set(udid, {
+                udid,
+                wdaProcess: null,
+                forwardWDAProcess: null,
+                forwardMJPEGProcess: null,
+                tunnelPort: null,
+                wdaPort,
+                mjpegPort,
+                status: 'running',
+                startedAt: new Date(),
+                lastViewerAt: Date.now(),
+                viewerCount: 0,
+                simulatorSession: sessionId,
+            });
+            logger_1.default.info(`[${udid}] Simulator preview: the picture of session ${sessionId} (port ${mjpegPort})`);
+            return { wdaPort, mjpegPort };
+        });
+    }
+    /**
+     * End the simulator previews that show this session's picture. Called
+     * however the session ends (forgetSessionMemory): the driver's WDA may
+     * outlive it, but no test runs any more.
+     */
+    endSimulatorPreviews(sessionId) {
+        return __awaiter(this, void 0, void 0, function* () {
+            this.endedSimulatorSessions.add(sessionId);
+            if (this.endedSimulatorSessions.size > ENDED_SESSIONS_KEPT) {
+                const oldest = this.endedSimulatorSessions.values().next().value;
+                if (oldest !== undefined)
+                    this.endedSimulatorSessions.delete(oldest);
+            }
+            for (const [udid, session] of this.sessions.entries()) {
+                if (session.simulatorSession !== sessionId)
+                    continue;
+                logger_1.default.info(`[${udid}] Simulator preview ends with session ${sessionId}`);
+                yield this.stopStream(udid);
+            }
+        });
+    }
     killStaleProcesses(udid, wdaPort, mjpegPort) {
         return __awaiter(this, void 0, void 0, function* () {
             logger_1.default.info(`Cleaning up stale processes for ${udid} (Ports: ${wdaPort}, ${mjpegPort})`);
@@ -879,10 +995,16 @@ let IOSStreamService = class IOSStreamService {
      */
     stopStream(udid_1) {
         return __awaiter(this, arguments, void 0, function* (udid, opts = {}) {
-            var _a;
             const session = this.sessions.get(udid);
             if (!session)
                 return;
+            // A simulator's preview started nothing and leased no port: the ports and
+            // WDA are its session's. Only the entry goes (and a manual hold, below).
+            if (session.simulatorSession) {
+                this.sessions.delete(udid);
+                yield this.releaseManualHold(udid);
+                return;
+            }
             if (opts.forViewer &&
                 session.wdaProcess &&
                 (yield this.appiumSessionMayUse(udid, "the stream's WDA and go-ios tunnel"))) {
@@ -902,22 +1024,7 @@ let IOSStreamService = class IOSStreamService {
             // A stream attached to an Appium session's WDA started none.
             if (session.tunnelPort != null)
                 yield this.tunnels().stop(udid);
-            // Principal Fix: Only release the device lock if THIS STREAM SERVICE owns it.
-            // The lock could belong to an Appium automation session (session_id is a real UUID).
-            // We should only unblock if it's a manual control lock (session_id starts with 'manual_').
-            try {
-                const device = yield (0, ownDeviceRow_1.findOwnDevice)(udid);
-                if (device && ((_a = device.session_id) === null || _a === void 0 ? void 0 : _a.startsWith('manual_'))) {
-                    logger_1.default.info(`Stream Stop: Releasing manual control lock for ${udid}`);
-                    yield (0, device_service_1.unblockDevice)(udid, device.host);
-                }
-                else if (device && device.busy) {
-                    logger_1.default.info(`Stream Stop: Device ${udid} is busy with session ${device.session_id}. NOT releasing lock.`);
-                }
-            }
-            catch (e) {
-                logger_1.default.error(`Failed to check/release lock during stream stop for ${udid}: ${e}`);
-            }
+            yield this.releaseManualHold(udid);
             // Also clean up any orphan processes (belt and suspenders)
             yield this.cleanupOrphanTunnels(udid);
             // Release the port leases so the allocator can reuse these ports for other
@@ -933,6 +1040,28 @@ let IOSStreamService = class IOSStreamService {
             this.sessions.delete(udid);
         });
     }
+    /**
+     * Release the phone's manual hold (a preview's, a recording's), never an
+     * Appium session's claim: that session_id is a real id, not `manual_...`.
+     */
+    releaseManualHold(udid) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            try {
+                const device = yield (0, ownDeviceRow_1.findOwnDevice)(udid);
+                if (device && ((_a = device.session_id) === null || _a === void 0 ? void 0 : _a.startsWith('manual_'))) {
+                    logger_1.default.info(`Stream Stop: Releasing manual control lock for ${udid}`);
+                    yield (0, device_service_1.unblockDevice)(udid, device.host);
+                }
+                else if (device && device.busy) {
+                    logger_1.default.info(`Stream Stop: Device ${udid} is busy with session ${device.session_id}. NOT releasing lock.`);
+                }
+            }
+            catch (e) {
+                logger_1.default.error(`Failed to check/release lock during stream stop for ${udid}: ${e}`);
+            }
+        });
+    }
     updateWDASettings(wdaPort) {
         return __awaiter(this, void 0, void 0, function* () {
             const urls = [`http://127.0.0.1:${wdaPort}/appium/settings`];

package/lib/src/device-utils.js

@@ -45,7 +45,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getDeviceTypeFromApp = void 0;
+exports.BOOT_PROBE = exports.getDeviceTypeFromApp = void 0;
 exports.isAndroid = isAndroid;
 exports.deviceType = deviceType;
 exports.isIOS = isIOS;
@@ -59,6 +59,8 @@ exports.setUtilizationTime = setUtilizationTime;
 exports.getDeviceFiltersFromCapability = getDeviceFiltersFromCapability;
 exports.getRunningSessionsCount = getRunningSessionsCount;
 exports.updateDeviceList = updateDeviceList;
+exports.syncLocalDevices = syncLocalDevices;
+exports.reportDevicesToHub = reportDevicesToHub;
 exports.refreshSimulatorState = refreshSimulatorState;
 exports.setupCronCheckStaleDevices = setupCronCheckStaleDevices;
 exports.removeStaleDevices = removeStaleDevices;
@@ -530,6 +532,19 @@ function getRunningSessionsCount() {
     });
 }
 function updateDeviceList(local, hubArgument, tlsRejectUnauthorized) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const { devices, gone } = yield syncLocalDevices(local);
+        if (hubArgument) {
+            yield reportDevicesToHub(hubArgument, devices, gone, tlsRejectUnauthorized);
+        }
+        return devices;
+    });
+}
+/**
+ * This server's own phones: what discovery reports now is written to the
+ * table, and its own rows discovery no longer reports are removed (`gone`).
+ */
+function syncLocalDevices(local) {
     return __awaiter(this, void 0, void 0, function* () {
         const allExistingDevices = yield (0, device_service_1.getAllDevices)();
         const devices = yield getDeviceManager().getDevices(allExistingDevices);
@@ -547,28 +562,31 @@ function updateDeviceList(local, hubArgument, tlsRejectUnauthorized) {
             logger_1.default.info(`Removing ${staleLocalDevices.length} stale devices/simulators no longer discovered on this host.`);
             yield (0, device_service_1.removeDevice)(staleLocalDevices.map((d) => ({ udid: d.udid, host: d.host })));
         }
-        if (hubArgument) {
-            if (yield (0, helpers_1.isXenonRunning)(hubArgument, tlsRejectUnauthorized)) {
-                const nodeDevices = new NodeDevices_1.default(hubArgument, {
-                    tlsRejectUnauthorized,
-                    hubAccessKey: config_1.config.hubAccessKey,
-                    hubToken: config_1.config.hubToken,
-                });
-                try {
-                    yield nodeDevices.postDevicesToHub(devices, 'add');
-                    if (staleLocalDevices.length > 0) {
-                        yield nodeDevices.postDevicesToHub(staleLocalDevices, 'remove');
-                    }
-                }
-                catch (error) {
-                    logger_1.default.error(`Cannot send device list update. Reason: ${error}`);
+        return { devices, gone: staleLocalDevices };
+    });
+}
+/** A node tells its hub the phones it has, and the ones it no longer has. */
+function reportDevicesToHub(hubArgument, devices, gone, tlsRejectUnauthorized) {
+    return __awaiter(this, void 0, void 0, function* () {
+        if (yield (0, helpers_1.isXenonRunning)(hubArgument, tlsRejectUnauthorized)) {
+            const nodeDevices = new NodeDevices_1.default(hubArgument, {
+                tlsRejectUnauthorized,
+                hubAccessKey: config_1.config.hubAccessKey,
+                hubToken: config_1.config.hubToken,
+            });
+            try {
+                yield nodeDevices.postDevicesToHub(devices, 'add');
+                if (gone.length > 0) {
+                    yield nodeDevices.postDevicesToHub(gone, 'remove');
                 }
             }
-            else {
-                logger_1.default.warn(`Not sending device update since hub ${hubArgument} is not running`);
+            catch (error) {
+                logger_1.default.error(`Cannot send device list update. Reason: ${error}`);
             }
         }
-        return devices;
+        else {
+            logger_1.default.warn(`Not sending device update since hub ${hubArgument} is not running`);
+        }
     });
 }
 function refreshSimulatorState(pluginArgs, hostPort) {
@@ -590,11 +608,21 @@ function setupCronCheckStaleDevices(intervalMs, local, tlsRejectUnauthorized) {
         }), intervalMs);
     });
 }
+/**
+ * How a start asks another server whether it is alive: once, for at most 5 s.
+ * Appium opens its port only once every plugin's updateServer has finished,
+ * and the client's own way (four 30 s tries) held it closed for two minutes
+ * when a row named a host that drops packets. A live server answers in
+ * milliseconds; one that answers slower has its phones dropped and reports
+ * them again at its next report.
+ */
+exports.BOOT_PROBE = { timeoutMs: 5000, retry: false };
 /**
  * Remove devices where the host is not alive nor defined.
  * @param local the hosts this server files its own phones under
+ * @param probe how each host is asked (the client's own way when not given)
  */
-function removeStaleDevices(local, tlsRejectUnauthorized) {
+function removeStaleDevices(local, tlsRejectUnauthorized, probe) {
     return __awaiter(this, void 0, void 0, function* () {
         const allDevices = yield (0, device_service_1.getAllDevices)();
         const nodeId = typedi_1.Container.get(PluginContext_1.PluginContext).nodeId;
@@ -611,13 +639,13 @@ function removeStaleDevices(local, tlsRejectUnauthorized) {
         const aliveHosts = (yield Promise.allSettled(nodeHosts.map((host) => __awaiter(this, void 0, void 0, function* () {
             return {
                 host: host,
-                alive: yield (0, helpers_1.isXenonRunning)(host, tlsRejectUnauthorized),
+                alive: yield (0, helpers_1.isXenonRunning)(host, tlsRejectUnauthorized, probe),
             };
         }))));
         const aliveCloudHosts = (yield Promise.allSettled(cloudHosts.map((host) => __awaiter(this, void 0, void 0, function* () {
             return {
                 host: host,
-                alive: yield (0, helpers_1.isAppiumRunningAt)(host, tlsRejectUnauthorized),
+                alive: yield (0, helpers_1.isAppiumRunningAt)(host, tlsRejectUnauthorized, probe),
             };
         }))));
         // summarize alive hosts