@7365admin1/layer-common 4.53.0 → 4.54.1

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @iservice365/layer-common
 
+## 4.54.1
+
+### Patch Changes
+
+- 401e0a2: Robot detail: when the robot cannot be read, show the API's plain reason (e.g. "Ounitech rejected the robot list (sign-in) ...") under the title instead of only "Reconnecting". `mergeLiveStates` carries the optional `reason` from `/robots/states`.
+
+## 4.54.0
+
+### Minor Changes
+
+- 6bfc7d1: Robots (PadBot S2 and all brands): a robot no longer vanishes from the map on one missed or failed reading - the last position is kept for up to 15 s, drawn faded with "last seen N s ago", then "Reconnecting"; the floor becomes unknown only when the robot says so; an online robot without a position reads "Position not reported right now". Patrol routes whose stops cannot be placed on the plan are listed ("Stops: Gate → Lobby"), never drawn at a guessed spot; when the brand keeps schedules to itself (`scheduleShared: false`) the panel says so and shows recent patrol runs plus a clearly labelled guess ("Looks like ... runs daily around 20:00"). Live view opens in the page (HD / Smooth, re-minted before expiry, never stored; iframe / native video / "Open in new tab" / RTMP explanation), also from the fleet row menu. Alert photos ("Photo", "Thermal photo") on the fault bar and Alerts rows. Go to point / Set position pick from the robot's saved points when its maps list them (`go-to-point`; Set position only on the robot's floor, with a confirmation line). Manual control (only when the server reports `manualDrive` and the user can update robots): hold-to-move with a big STOP, head controls, heartbeat-guarded session that ends on release, tab hide, close or connection loss.
+
 ## 4.53.0
 
 ### Minor Changes
@@ -1563,11 +1575,11 @@
   `utils/console-tier.ts` + `composables/useConsoleTier.ts` mirror the server's
   own rule from two endpoints the console already calls, unprojected:
 
-                                                                                                                                                                                                                                    GET /api/members/user/:user/app/admin    the Seven365 staff membership
-                                                                                                                                                                                                                                    GET /api/roles/id/:role                  that membership's role document
+                                                                                                                                                                                                                                        GET /api/members/user/:user/app/admin    the Seven365 staff membership
+                                                                                                                                                                                                                                        GET /api/roles/id/:role                  that membership's role document
 
-                                                                                                                                                                                                                                    owner  = member.type === "admin" && role.type === "admin" && role.default === true
-                                                                                                                                                                                                                                    staff  = member.type === "admin" && role.type === "admin"
+                                                                                                                                                                                                                                        owner  = member.type === "admin" && role.type === "admin" && role.default === true
+                                                                                                                                                                                                                                        staff  = member.type === "admin" && role.type === "admin"
 
   `role.default` is the marker because it is the only property of a platform
   staff role no API caller can set - `role.controller.ts` validates create and

package/assets/css/robot-hero.css

@@ -1237,3 +1237,23 @@ div.hero-editor__wp.hero-editor__sel, div.hero-editor__fid.hero-editor__sel { ou
 
 /* PadBot security extras: live video button row under the facts. */
 .hero-detail__video { margin: 10px 0 4px; }
+
+/* A kept (stale) reading: faded, no ping - never drawn as live (owner 2026-09-26). */
+.hero-bot--stale, .hero-me--stale { opacity: 0.45; }
+.hero-bot--stale .hero-bot__ping, .hero-bot--stale .hero-bmap__ping, .hero-me--stale .hero-me__ping, .hero-me--stale .hero-me__radar { display: none; }
+.hero-sched__hint { font-size: 12px; font-style: italic; opacity: 0.75; margin: 4px 0; }
+
+/* Live view / manual control / point picker dialogs */
+.hero-live__head { display: flex; align-items: center; gap: 8px; }
+.hero-live__quality button, .hero-drive__head button, .hero-pick__point { border: 1px solid var(--hero-line, currentColor); background: none; color: inherit; font: inherit; padding: 4px 10px; cursor: pointer; }
+.hero-live__quality button[aria-pressed="true"], .hero-pick__point[aria-pressed="true"] { background: var(--hero-accent); color: var(--hero-bg); }
+.hero-live__stage { min-height: 240px; display: flex; align-items: center; justify-content: center; background: #000; color: #fff; }
+.hero-live__video { width: 100%; aspect-ratio: 16 / 9; border: 0; background: #000; }
+.hero-live__copy { margin-top: 8px; }
+.hero-live__open { align-self: center; }
+.hero-drive__stop { width: 100%; padding: 18px; font-size: 24px; font-weight: 800; letter-spacing: 0.08em; color: #fff; background: #c62828; border: 0; cursor: pointer; }
+.hero-drive__pad { display: grid; grid-template-columns: repeat(3, 1fr); gap: 8px; }
+.hero-drive__pad button { padding: 16px 8px; border: 1px solid var(--hero-line, currentColor); background: var(--hero-surface); color: inherit; font: inherit; cursor: pointer; touch-action: none; user-select: none; }
+.hero-drive__pad button:active { background: var(--hero-accent); color: var(--hero-bg); }
+.hero-drive__head { display: flex; flex-wrap: wrap; align-items: center; gap: 6px; }
+.hero-pick__group { display: flex; flex-wrap: wrap; gap: 6px; align-items: center; margin-bottom: 6px; }

package/components/Robot/AlertsTable.vue

@@ -21,7 +21,10 @@
     @click:row="onRow"
   >
     <template #item.code="{ item }"><span class="hero-alert__code">{{ attentionText(item).code }}</span></template>
-    <template #item.message="{ item }">{{ attentionText(item).message }}</template>
+    <template #item.message="{ item }">
+      {{ attentionText(item).message }}
+      <template v-for="ph in photosOf(item)" :key="ph.label"> · <a :href="ph.url" target="_blank" rel="noopener noreferrer" @click.stop>{{ ph.label }}</a></template>
+    </template>
     <template #item.robot="{ item }"><span class="hero-table__name">{{ item.robot?.name }}</span></template>
     <template #item.site="{ item }"><span class="hero-dim">{{ item.client?.name }} · {{ item.site?.name }}</span></template>
     <template #item.floor="{ item }">
@@ -36,6 +39,7 @@
 import RobotFloorLabel from "./FloorLabel.vue";
 import RobotTable from "./Table.vue";
 import { attentionText, sinceText } from "../../utils/robot-display";
+import { faultPhotos } from "../../utils/robot-control";
 
 const props = withDefaults(
   defineProps<{
@@ -57,6 +61,11 @@ function floorOf(item: any) {
   const s = props.states[String(item?.robot?._id ?? "")];
   return s?.ok ? { floorNo: s.floorNo, floorKnown: s.floorKnown === true } : { floorNo: null, floorKnown: false };
 }
+/** The robot's photos for this alert, when its live fault is this one and carries them. */
+function photosOf(item: any) {
+  const f = props.states[String(item?.robot?._id ?? "")]?.fault;
+  return f && f.code === item?.code ? faultPhotos(f) : [];
+}
 function onRow(_e: unknown, { item }: { item: any }) {
   emit("open", item);
 }

package/components/Robot/BuildingMap.vue

@@ -163,6 +163,8 @@
               v-for="r in f.robots"
               :key="r.id"
               class="hero-bmap__anchor hero-bmap__bot"
+              :class="{ 'hero-bot--stale': r.stale }"
+              :title="r.stale ? `${r.name} · ${r.seen}` : undefined"
               :style="{ left: r.left, top: r.top, transition: `left ${tickMs}ms linear, top ${tickMs}ms linear`, '--hero-bot': toneColor(r) }"
             >
               <span class="hero-bmap__ping" aria-hidden="true" />

package/components/Robot/Detail.vue

@@ -20,14 +20,18 @@
   </div>
 
   <div v-if="error" class="hero-notice" role="alert">{{ error }}</div>
+  <div v-else-if="live && !live.ok && live.reason" class="hero-notice" role="status">Can't read this robot right now: {{ live.reason }}</div>
 
   <div v-if="fault" class="hero-faultbar" role="alert">
     <span class="hero-faultbar__code">{{ fault.code }}</span>
     <div>
       <div class="hero-faultbar__msg">{{ fault.message || fault.code }}</div>
-      <div class="hero-faultbar__since">Since {{ faultSince }} · notified once</div>
+      <div class="hero-faultbar__since">
+        Since {{ faultSince }} · notified once
+        <template v-for="ph in faultPhotos(fault)" :key="ph.label"> · <a :href="ph.url" target="_blank" rel="noopener noreferrer">{{ ph.label }}</a></template>
+      </div>
     </div>
-    <v-btn v-if="caps?.liveVideo === true && online" variant="outlined" size="small" :loading="videoBusy" @click="openVideo">Live video</v-btn>
+    <v-btn v-if="caps?.liveVideo === true && online" variant="outlined" size="small" @click="liveOpen = true">Live view</v-btn>
     <v-btn v-if="canResolve" variant="outlined" size="small" :loading="resolving" @click="resolveFault">Mark resolved</v-btn>
     <span class="hero-faultbar__badge">{{ faultBadge(fault) }}</span>
   </div>
@@ -41,8 +45,9 @@
     </div>
   </div>
   <div v-if="notReported" class="hero-notreported">{{ notReported }}</div>
-  <div v-if="caps?.liveVideo === true && online && !fault" class="hero-detail__video">
-    <v-btn variant="outlined" :loading="videoBusy" @click="openVideo">Live video</v-btn>
+  <div v-if="(caps?.liveVideo === true && online && !fault) || canDrive" class="hero-detail__video">
+    <v-btn v-if="caps?.liveVideo === true && online && !fault" variant="outlined" @click="liveOpen = true">Live view</v-btn>
+    <v-btn v-if="canDrive" variant="outlined" @click="driveOpen = true">Manual control</v-btn>
   </div>
 
   <div v-if="commands.length">
@@ -67,10 +72,26 @@
           robotType === "security" ? "days · start–end · floor · checkpoints × rounds" : "days · start–end · jobs per floor · passes"
         }}</span>
       </div>
-      <div v-if="!schedule.length" class="hero-sched__empty">No schedule yet.</div>
+      <template v-if="!schedule.length && robotType === 'security' && patrol?.scheduleShared === false">
+        <div class="hero-sched__empty">Patrol schedules are set in the PadBot app. PadBot doesn't share them with us yet.</div>
+        <div v-if="runHint" class="hero-sched__hint">{{ runHint }} - a guess from recent runs, not the schedule.</div>
+        <template v-if="recentRuns.length">
+          <div class="hero-aside__hint">Recent patrol runs</div>
+          <div v-for="r in recentRuns" :key="r.key" class="hero-sched__row">
+            <b>{{ r.when }}</b><span>{{ r.route }} · {{ r.result }}</span><span>{{ r.detail }}</span>
+          </div>
+        </template>
+      </template>
+      <div v-else-if="!schedule.length" class="hero-sched__empty">No schedule yet.</div>
       <div v-for="p in schedule" :key="p.key" class="hero-sched__row">
         <b>{{ p.days }}</b><span>{{ p.time }}</span><span>{{ p.jobs }}</span>
       </div>
+      <template v-if="unplacedRoutes.length">
+        <div class="hero-aside__hint">Patrol routes (stops not placed on the plan)</div>
+        <div v-for="r in unplacedRoutes" :key="r.id" class="hero-sched__row">
+          <b>{{ r.name }}</b><span>Stops: {{ r.text }}</span>
+        </div>
+      </template>
     </div>
 
     <div>
@@ -82,6 +103,7 @@
         :name="record?.name"
         :status-label="statusLabel"
         :point="posLive ? point : null"
+        :stale="shown?.stale === true"
         :heading="headingDeg(shown)"
         :trail="trail"
         :readout="readout"
@@ -131,6 +153,16 @@
     </div>
   </v-dialog>
 
+  <v-dialog v-model="liveOpen" width="860">
+    <RobotLiveView v-if="liveOpen" :robot-id="robotId" :name="record?.name" @close="liveOpen = false" />
+  </v-dialog>
+  <v-dialog v-model="driveOpen" width="520" persistent>
+    <RobotManualDrive v-if="driveOpen" :robot-id="robotId" :name="record?.name" @close="driveOpen = false" />
+  </v-dialog>
+  <v-dialog v-model="pickOpen" width="520">
+    <RobotPointPicker v-if="pickOpen && pickKind" :kind="pickKind" :groups="pointGroups" :floor-no="live?.floorNo ?? null" @close="pickOpen = false" @pick="onPick" />
+  </v-dialog>
+
   <RobotToast v-model="toast" />
 </template>
 
@@ -144,6 +176,10 @@ import RobotLivePlan from "./LivePlan.vue";
 import RobotToast from "./Toast.vue";
 import RobotForm from "./Form.vue";
 import RobotPatrolHistory from "./PatrolHistory.vue";
+import RobotLiveView from "./LiveView.vue";
+import RobotManualDrive from "./ManualDrive.vue";
+import RobotPointPicker from "./PointPicker.vue";
+import { faultPhotos } from "../../utils/robot-control";
 import useRobotLive, { siteStatesFeed } from "../../composables/useRobotLive";
 import {
   brandName,
@@ -157,7 +193,12 @@ import {
   mergePose,
   notReportedLine,
   optimisticMode,
+  patrolRecordRow,
+  patrolRunHint,
   patrolScheduleRows,
+  pointCommandBody,
+  savedPointGroups,
+  unplacedStopsText,
   planPoint,
   positionText,
   robotErrorMessage,
@@ -173,6 +214,8 @@ import {
   type TLiveRobotState,
   type TPatrolRouteView,
   type TRobotCommandKind,
+  type TSavedPoint,
+  type TSavedPointGroup,
 } from "../../utils/robot-display";
 
 const props = withDefaults(
@@ -207,8 +250,8 @@ const {
   deleteRobot,
   getRobotMaps,
   getRobotMapImages,
-  getLiveVideo,
   resolveRobotAlerts,
+  getPatrolHistory,
 } = useRobots();
 
 const record = ref<Record<string, any> | null>(null);
@@ -282,7 +325,7 @@ watch(
     if (p && posLive.value && isMoving(statusMode.value)) trail.value = trailPush(trail.value, p);
   },
 );
-const readout = computed(() => `${positionText(live.value, caps.value)} · ${speedText(prevPose.value, nextPose.value, statusMode.value)}`);
+const readout = computed(() => `${positionText(live.value, caps.value, now.value)} · ${speedText(prevPose.value, nextPose.value, statusMode.value)}`);
 
 const spot = ref<Array<{ x: number; y: number }>>([]);
 const spotOn = computed(() => showSpotClean({ canCommand: props.canCommand, capabilities: caps.value, online: online.value, type: robotType.value }));
@@ -299,14 +342,25 @@ const planHint = computed(() => {
 
 /* ---- schedule: cleaning plans from the brand, or the patrol contract ---- */
 const plans = ref<Array<Record<string, any>>>([]);
-const patrol = ref<{ supported?: boolean; routes?: TPatrolRouteView[]; schedule?: any[] } | null>(null);
+const patrol = ref<{ supported?: boolean; routes?: TPatrolRouteView[]; schedule?: any[]; scheduleShared?: boolean } | null>(null);
 const schedule = computed(() => (robotType.value === "security" ? patrolScheduleRows(patrol.value) : cleaningScheduleRows(plans.value)));
+const unplacedRoutes = computed(() =>
+  (patrol.value?.routes ?? []).map((r) => ({ id: r.id, name: r.name, text: unplacedStopsText(r) })).filter((r) => r.text),
+);
+// The brand keeps its schedules to itself: recent runs (and a labelled guess) instead.
+const runs = ref<any[]>([]);
+const recentRuns = computed(() => runs.value.slice(0, 5).map((r) => patrolRecordRow(r, now.value)));
+const runHint = computed(() => patrolRunHint(runs.value, now.value));
 
 async function loadSchedule() {
   if (!record.value || noInterface.value) return;
   try {
-    if (robotType.value === "security") patrol.value = await getPatrolRoutes(props.robotId);
-    else plans.value = (await getRobotPlans(props.robotId))?.items ?? [];
+    if (robotType.value === "security") {
+      patrol.value = await getPatrolRoutes(props.robotId);
+      if (patrol.value?.scheduleShared === false && caps.value?.patrolHistory === true && !runs.value.length) {
+        runs.value = (await getPatrolHistory(props.robotId, { page: 1, limit: 20 }).catch(() => null))?.items ?? [];
+      }
+    } else plans.value = (await getRobotPlans(props.robotId))?.items ?? [];
   } catch {
     // A schedule the brand cannot serve reads "No schedule yet"; the facts still show.
   }
@@ -356,7 +410,23 @@ async function run(kind: TRobotCommandKind | "spot", body: Record<string, unknow
     busy.value = null;
   }
 }
-function send(kind: TRobotCommandKind) {
+/* Go to point / Set position: the robot's own saved points when its brand lists them (PadBot). */
+const pointGroups = ref<TSavedPointGroup[]>([]);
+const pickOpen = ref(false);
+const pickKind = ref<"navigate" | "relocalize" | null>(null);
+async function send(kind: TRobotCommandKind) {
+  if (kind === "navigate" || kind === "relocalize") {
+    try {
+      pointGroups.value = savedPointGroups((await getRobotMaps(props.robotId))?.items);
+    } catch {
+      pointGroups.value = [];
+    }
+    if (pointGroups.value.length) {
+      pickKind.value = kind;
+      pickOpen.value = true;
+      return;
+    }
+  }
   const body = commandBody(kind, live.value);
   if (!body) {
     toast.value = `${commandLabel(kind)}: the robot's position is not known yet.`;
@@ -399,26 +469,22 @@ async function sendSpot() {
   }
 }
 
-/* ---- security-robot extras: live video (minted per click, never kept), resolve an alarm ---- */
-const videoBusy = ref(false);
-async function openVideo() {
-  // Opened before the await so the browser treats it as the click's own window.
-  const win = typeof window !== "undefined" ? window.open("", "_blank") : null;
-  videoBusy.value = true;
-  try {
-    const { url } = await getLiveVideo(props.robotId);
-    if (!/^https?:\/\//i.test(url)) throw new Error("The robot's cloud sent a video link this page cannot open.");
-    if (win) {
-      win.opener = null;
-      win.location.href = url;
-    } else toast.value = "Allow pop-ups to watch the robot's live video.";
-  } catch (e) {
-    win?.close();
-    toast.value = robotErrorMessage(e, "Could not open the live video.");
-  } finally {
-    videoBusy.value = false;
+function onPick(p: TSavedPoint) {
+  const kind = pickKind.value;
+  pickOpen.value = false;
+  if (!kind) return;
+  const body = pointCommandBody(kind, p, live.value);
+  if (!body) {
+    toast.value = "Set position: the robot is not on that floor.";
+    return;
   }
+  run(kind, body);
 }
+
+/* ---- security-robot extras: live view (minted per open, never kept), manual control, resolve an alarm ---- */
+const liveOpen = ref(false);
+const driveOpen = ref(false);
+const canDrive = computed(() => props.canCommand && caps.value?.manualDrive === true && online.value);
 const canResolve = computed(
   () => props.canCommand && caps.value?.resolveAlerts === true && faultBadge(fault.value) === "ALARM" && typeof fault.value?.code === "string",
 );

package/components/Robot/Fleet.vue

@@ -172,6 +172,12 @@
                   </template>
                   <v-list density="compact">
                     <v-list-item title="Schedule" prepend-icon="mdi-calendar-clock" @click="openPlans(item)" />
+                    <v-list-item
+                      v-if="states[item._id]?.capabilities?.liveVideo === true && states[item._id]?.online === true"
+                      title="Live view"
+                      prepend-icon="mdi-cctv"
+                      @click="liveRobot = item"
+                    />
                     <!--
                       Only for a brand that can take a click on the plan. A brand
                       without it gets no control, not one the server refuses.
@@ -349,9 +355,14 @@
       </v-row>
     </template>
   </ConfirmDialog>
+
+  <v-dialog :model-value="!!liveRobot" width="860" @update:model-value="(v) => !v && (liveRobot = null)">
+    <RobotLiveView v-if="liveRobot" :robot-id="String(liveRobot._id)" :name="liveRobot.name" @close="liveRobot = null" />
+  </v-dialog>
 </template>
 
 <script lang="ts" setup>
+import RobotLiveView from "./LiveView.vue";
 /**
  * The fleet screen, shared by every application that shows robots.
  *
@@ -700,6 +711,8 @@ function onCreated() {
 
 onMounted(load);
 onBeforeUnmount(stopWatching);
+/** The row whose Live view is open (security robots with a camera URL). */
+const liveRobot = ref<any>(null);
 </script>
 
 <style scoped>

package/components/Robot/LivePlan.vue

@@ -15,7 +15,7 @@
       <span class="hero-cross hero-cross--h" :style="{ top: point.top, transition: `top ${tickMs}ms linear` }" aria-hidden="true" />
       <span class="hero-cross hero-cross--v" :style="{ left: point.left, transition: `left ${tickMs}ms linear` }" aria-hidden="true" />
       <div class="hero-readout">{{ readout }}</div>
-      <div class="hero-me" :style="{ left: point.left, top: point.top, transition: `left ${tickMs}ms linear, top ${tickMs}ms linear` }">
+      <div class="hero-me" :class="{ 'hero-me--stale': stale }" :style="{ left: point.left, top: point.top, transition: `left ${tickMs}ms linear, top ${tickMs}ms linear` }">
         <div class="hero-me__tag">{{ name }} <span>{{ statusLabel }}</span></div>
         <div class="hero-me__radar" aria-hidden="true" />
         <div class="hero-me__ping" aria-hidden="true" />
@@ -52,8 +52,10 @@ withDefaults(
     spot?: Array<{ x: number; y: number }>;
     pick?: boolean;
     tickMs?: number;
+    /** The last reading kept through a short gap: drawn faded, never as live. */
+    stale?: boolean;
   }>(),
-  { name: "", statusLabel: "", point: null, heading: 0, trail: () => [], readout: "", lost: false, route: null, routeMoving: false, spot: () => [], pick: false, tickMs: 1200 },
+  { stale: false, name: "", statusLabel: "", point: null, heading: 0, trail: () => [], readout: "", lost: false, route: null, routeMoving: false, spot: () => [], pick: false, tickMs: 1200 },
 );
 const emit = defineEmits<{ pick: [point: { x: number; y: number }] }>();
 </script>

package/components/Robot/LiveView.vue

@@ -0,0 +1,107 @@
+<template>
+  <!--
+    The robot's current camera stream, in the page (security robots, liveVideo).
+    The URL is minted per open and re-minted shortly before it expires; it is
+    never stored. What the browser cannot play in place opens in a new tab.
+  -->
+  <div class="hero-dialog hero-live" role="dialog" aria-labelledby="hero-live-title">
+    <div class="hero-live__head">
+      <div id="hero-live-title" class="hero-dialog__title">Live view · {{ name }}</div>
+      <span class="hero-head__spacer" />
+      <div class="hero-live__quality" role="group" aria-label="Quality">
+        <button type="button" :aria-pressed="quality === 'smooth'" @click="quality = 'smooth'">Smooth</button>
+        <button type="button" :aria-pressed="quality === 'hd'" @click="quality = 'hd'">HD</button>
+      </div>
+    </div>
+
+    <div class="hero-live__stage">
+      <div v-if="loading && !url" class="hero-muted">Connecting to the robot's camera…</div>
+      <div v-else-if="error" class="hero-notice" role="alert">{{ error }}</div>
+      <template v-else-if="url">
+        <video v-if="plays" :key="url" class="hero-live__video" :src="url" controls autoplay muted playsinline @error="error = CAMERA_DOWN" />
+        <iframe
+          v-else-if="kind === 'page'"
+          :key="url"
+          class="hero-live__video"
+          :src="url"
+          title="Robot camera"
+          sandbox="allow-scripts allow-same-origin"
+          allow="autoplay; fullscreen"
+          allowfullscreen
+          referrerpolicy="no-referrer"
+        />
+        <div v-else-if="kind === 'rtmp'" class="hero-dialog__body">
+          This stream uses RTMP, which browsers can't play. Open it in a player app such as VLC.
+          <div class="hero-live__copy">
+            <v-btn variant="outlined" size="small" @click="copy">Copy stream link</v-btn>
+          </div>
+        </div>
+        <div v-else class="hero-dialog__body">This stream can't play inside the page in this browser. Open it in a new tab.</div>
+      </template>
+    </div>
+
+    <div class="hero-dialog__actions">
+      <a v-if="url && kind !== 'rtmp'" class="hero-live__open" :href="url" target="_blank" rel="noopener noreferrer">Open in new tab</a>
+      <span class="hero-head__spacer" />
+      <v-btn variant="outlined" @click="emit('close')">Close</v-btn>
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { computed, onBeforeUnmount, ref, watch } from "vue";
+import { liveVideoKind, remintDelayMs } from "../../utils/robot-control";
+
+const props = defineProps<{ robotId: string; name?: string }>();
+const emit = defineEmits<{ close: [] }>();
+const { getLiveVideo } = useRobots();
+
+const CAMERA_DOWN = "The robot's camera isn't available right now.";
+const quality = ref<"hd" | "smooth">("smooth");
+const url = ref("");
+const error = ref("");
+const loading = ref(false);
+let timer: ReturnType<typeof setTimeout> | undefined;
+let alive = true;
+
+const kind = computed(() => liveVideoKind(url.value));
+const plays = computed(
+  () =>
+    kind.value === "video" ||
+    (kind.value === "hls" && typeof document !== "undefined" && !!document.createElement("video").canPlayType("application/vnd.apple.mpegurl")),
+);
+
+async function mint() {
+  clearTimeout(timer);
+  loading.value = true;
+  error.value = "";
+  try {
+    const res = await getLiveVideo(props.robotId, quality.value);
+    if (!alive) return;
+    if (liveVideoKind(res?.url) === "bad") throw new Error(CAMERA_DOWN);
+    url.value = res.url;
+    const wait = remintDelayMs(res?.expiresAt);
+    if (wait !== null) timer = setTimeout(mint, wait);
+  } catch {
+    if (alive) {
+      url.value = "";
+      error.value = CAMERA_DOWN;
+    }
+  } finally {
+    loading.value = false;
+  }
+}
+async function copy() {
+  try {
+    await navigator.clipboard.writeText(url.value);
+  } catch {
+    /* the link is still shown by the browser's own copy */
+  }
+}
+watch(quality, mint, { immediate: true });
+onBeforeUnmount(() => {
+  alive = false;
+  clearTimeout(timer);
+  url.value = "";
+});
+</script>

package/components/Robot/ManualDrive.vue

@@ -0,0 +1,128 @@
+<template>
+  <!--
+    Manual control (Manager only, PADBOT_MANUAL_DRIVE on the server). Hold a
+    button to move; letting go stops. The server forwards motion only while
+    this screen's heartbeat keeps arriving and stops the robot the moment it
+    does not - closing, hiding the tab or losing the connection all stop it.
+  -->
+  <div class="hero-dialog hero-drive" role="dialog" aria-labelledby="hero-drive-title" tabindex="-1" @keydown="onKey" @keyup="onKeyUp">
+    <div id="hero-drive-title" class="hero-dialog__title">Manual control · {{ name }}</div>
+    <div v-if="starting" class="hero-muted">Starting manual control…</div>
+    <div v-else-if="ended" class="hero-notice" role="alert">{{ ended }}</div>
+    <template v-else>
+      <div class="hero-dialog__body">Hold a button to move. Let go and the robot stops. {{ speedLimitText(limits) }}.</div>
+      <button type="button" class="hero-drive__stop" @click="client?.stop()">STOP</button>
+      <div class="hero-drive__pad" aria-label="Drive">
+        <span />
+        <button type="button" v-bind="hold('forward')">▲ Forward</button>
+        <span />
+        <button type="button" v-bind="hold('left')">◀ Turn left</button>
+        <span />
+        <button type="button" v-bind="hold('right')">Turn right ▶</button>
+        <span />
+        <button type="button" v-bind="hold('back')">▼ Back</button>
+        <span />
+      </div>
+      <div class="hero-drive__head" aria-label="Head">
+        <span class="hero-muted">Head</span>
+        <button type="button" @click="client?.look('left')">Look left</button>
+        <button type="button" @click="client?.look('right')">Look right</button>
+        <button type="button" @click="client?.look('up')">Look up</button>
+        <button type="button" @click="client?.look('down')">Look down</button>
+        <button type="button" @click="client?.look('centre')">Centre</button>
+      </div>
+    </template>
+    <div class="hero-dialog__actions">
+      <v-btn variant="outlined" @click="close">Close</v-btn>
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { onBeforeUnmount, onMounted, ref } from "vue";
+import { createDriveClient, speedLimitText, type TDriveDirection, type TDriveLimits } from "../../utils/robot-control";
+import { robotErrorMessage } from "../../utils/robot-display";
+
+const props = defineProps<{ robotId: string; name?: string }>();
+const emit = defineEmits<{ close: [] }>();
+const { startDrive, driveSignal } = useRobots();
+
+const starting = ref(true);
+const ended = ref("");
+const limits = ref<TDriveLimits | null>(null);
+let client: ReturnType<typeof createDriveClient> | null = null;
+
+const release = () => client?.release();
+function hold(dir: TDriveDirection) {
+  return {
+    onPointerdown: (e: PointerEvent) => {
+      (e.target as HTMLElement).setPointerCapture?.(e.pointerId);
+      client?.press(dir);
+    },
+    onPointerup: release,
+    onPointerleave: release,
+    onPointercancel: release,
+    onBlur: release,
+    onContextmenu: (e: Event) => {
+      e.preventDefault();
+      release();
+    },
+  };
+}
+const KEYS: Record<string, TDriveDirection> = { ArrowUp: "forward", ArrowDown: "back", ArrowLeft: "left", ArrowRight: "right" };
+function onKey(e: KeyboardEvent) {
+  if (e.key === " ") {
+    e.preventDefault();
+    client?.stop();
+  } else if (KEYS[e.key] && !e.repeat) {
+    e.preventDefault();
+    client?.press(KEYS[e.key]!);
+  }
+}
+function onKeyUp(e: KeyboardEvent) {
+  if (KEYS[e.key]) release();
+}
+
+const finish = () => client?.end();
+const onHidden = () => {
+  if (document.visibilityState === "hidden") finish();
+};
+function close() {
+  finish();
+  emit("close");
+}
+
+onMounted(async () => {
+  document.addEventListener("visibilitychange", onHidden);
+  window.addEventListener("pagehide", finish);
+  window.addEventListener("beforeunload", finish);
+  window.addEventListener("blur", release);
+  try {
+    const res = await startDrive(props.robotId);
+    const l = res?.limits ?? {};
+    limits.value = {
+      maxLinear: Number(l.maxLinear) || 0.3,
+      maxAngular: Number(l.maxAngular) || 30,
+      heartbeatMs: Math.min(100, Number(l.heartbeatMs) || 100),
+      headPan: Array.isArray(l.headPan) ? l.headPan : [-90, 90],
+      headTilt: Array.isArray(l.headTilt) ? l.headTilt : [-15, 30],
+    };
+    client = createDriveClient({
+      send: (body, opts) => driveSignal(props.robotId, res.session, body, opts),
+      limits: limits.value,
+      onEnd: (reason) => (ended.value = reason || "Manual control ended."),
+    });
+  } catch (e) {
+    ended.value = robotErrorMessage(e, "Manual control could not start.");
+  } finally {
+    starting.value = false;
+  }
+});
+onBeforeUnmount(() => {
+  finish();
+  document.removeEventListener("visibilitychange", onHidden);
+  window.removeEventListener("pagehide", finish);
+  window.removeEventListener("beforeunload", finish);
+  window.removeEventListener("blur", release);
+});
+</script>

package/components/Robot/MiniMap.vue

@@ -33,7 +33,8 @@
         :key="r.id"
         type="button"
         class="hero-bot"
-        :title="r.name"
+        :class="{ 'hero-bot--stale': r.stale }"
+        :title="r.stale ? `${r.name} · ${r.seen}` : r.name"
         :style="{ left: r.left, top: r.top, transition: `left ${tickMs}ms linear, top ${tickMs}ms linear`, '--hero-bot': toneColor(r) }"
         @click="emit('open', r.id)"
       >

package/components/Robot/PointPicker.vue

@@ -0,0 +1,33 @@
+<template>
+  <!-- Go to point / Set position: the robot's own saved points, per map. -->
+  <div class="hero-dialog" role="dialog" aria-labelledby="hero-pick-title">
+    <div id="hero-pick-title" class="hero-dialog__title">{{ kind === "navigate" ? "Go to point" : "Set position" }}</div>
+    <div v-if="kind === 'relocalize'" class="hero-dialog__body">Only points on the floor the robot reports are listed.</div>
+    <div v-if="!groups.length" class="hero-muted">No saved points{{ kind === "relocalize" ? " on the robot's current floor" : "" }}.</div>
+    <div v-for="g in groups" :key="g.mapId" class="hero-pick__group">
+      <div class="hero-aside__title">{{ g.title }}</div>
+      <button v-for="p in g.points" :key="p.targetPointId" type="button" class="hero-pick__point" :aria-pressed="chosen === p" @click="chosen = p">
+        {{ p.name }} <span class="hero-dim">{{ p.type }}</span>
+      </button>
+    </div>
+    <div v-if="chosen && kind === 'relocalize'" class="hero-notice">
+      Only do this when the robot is standing at {{ chosen.name }} right now - it tells the robot where it is.
+    </div>
+    <div class="hero-dialog__actions">
+      <v-btn variant="outlined" @click="emit('close')">Cancel</v-btn>
+      <v-btn color="primary" variant="flat" :disabled="!chosen" @click="chosen && emit('pick', chosen)">
+        {{ kind === "navigate" ? `Send to ${chosen?.name ?? "point"}` : `Robot is at ${chosen?.name ?? "point"}` }}
+      </v-btn>
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { computed, ref } from "vue";
+import type { TSavedPoint, TSavedPointGroup } from "../../utils/robot-display";
+
+const props = defineProps<{ kind: "navigate" | "relocalize"; groups: TSavedPointGroup[]; floorNo?: number | null }>();
+const emit = defineEmits<{ close: []; pick: [point: TSavedPoint] }>();
+const chosen = ref<TSavedPoint | null>(null);
+const groups = computed(() => (props.kind === "relocalize" ? props.groups.filter((g) => g.floorNo !== null && g.floorNo === props.floorNo) : props.groups));
+</script>

package/composables/useRobots.ts

@@ -286,14 +286,53 @@ export default function useRobots() {
   /* ---------------------------------------- security-robot extras (brand capability-gated) */
 
   /** `liveVideo`: the robot's camera URL, minted now (valid until `expiresAt`). Open it; never store it. */
-  function getLiveVideo(id: string) {
+  function getLiveVideo(id: string, quality: "hd" | "smooth" = "smooth") {
     return useNuxtApp().$api<{ url: string; expiresAt: string | null }>(`/api/robots/${id}/live-video`, {
       method: "POST",
       query: { appSlug },
-      body: {},
+      body: { quality },
     });
   }
 
+  /** Manual control (Manager only): open a drive session. 400 carries the plain reason it cannot start. */
+  function startDrive(id: string) {
+    return useNuxtApp().$api<{ session: string; limits: Record<string, any> }>(`/api/robots/${id}/drive`, {
+      method: "POST",
+      query: { appSlug },
+      body: { action: "start" },
+    });
+  }
+
+  /**
+   * One signal on an open drive session (beat / move / stop / head / end).
+   * Plain `fetch` so the page-closing "end" can go out with `keepalive`;
+   * never throws - answers `{ ok, status, message }`.
+   */
+  async function driveSignal(id: string, session: string, body: Record<string, unknown>, opts: { keepalive?: boolean } = {}) {
+    const base = useRuntimeConfig().public?.apiBase ?? "";
+    const query = appSlug ? `?appSlug=${encodeURIComponent(appSlug)}` : "";
+    try {
+      const res = await fetch(`${base}/api/robots/${id}/drive/${encodeURIComponent(session)}${query}`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json", Accept: "application/json" },
+        credentials: "include",
+        keepalive: opts.keepalive === true,
+        body: JSON.stringify(body),
+      });
+      let message = "";
+      if (!res.ok) {
+        try {
+          message = String((await res.json())?.message ?? "");
+        } catch {
+          /* no body */
+        }
+      }
+      return { ok: res.ok, status: res.status, message };
+    } catch {
+      return { ok: false, status: 0, message: "" };
+    }
+  }
+
   /** `resolveAlerts`: mark the robot's open alerts (of one code, or all) resolved in the brand's system. */
   function resolveRobotAlerts(id: string, code?: string) {
     return useNuxtApp().$api<{ resolved: number }>(`/api/robots/${id}/alerts/resolve`, {
@@ -556,6 +595,8 @@ export default function useRobots() {
     getRobotPlans,
     sendRobotCommand,
     getLiveVideo,
+    startDrive,
+    driveSignal,
     resolveRobotAlerts,
     getPatrolHistory,
     getPatrolVisits,

package/package.json

@@ -2,7 +2,7 @@
   "name": "@7365admin1/layer-common",
   "license": "MIT",
   "type": "module",
-  "version": "4.53.0",
+  "version": "4.54.1",
   "author": "7365admin1",
   "main": "./nuxt.config.ts",
   "//files": "What a consumer extending this layer actually loads. Without this npm ships the whole working tree - the changesets, the CI workflows, the render harness in tools/ and any scratch directory that happened to exist at publish time. Nuxt resolves a layer by directory, so every runtime directory below has to stay listed; adding a new top-level runtime directory means adding it here too.",

package/utils/robot-control.ts

@@ -0,0 +1,159 @@
+/**
+ * Web-only robot controls: the live-view player's URL handling and the
+ * manual-drive client. Not part of the mobile-synced `robot-display.ts`
+ * (mobile has no live view or manual control - parity exception, like map
+ * editing, decision 81).
+ */
+
+/* ============================================================ live view */
+
+export type TVideoKind = "hls" | "video" | "flv" | "rtmp" | "page" | "bad";
+
+/**
+ * What kind of stream URL the robot's cloud handed us.
+ * ponytail: no hls.js / mpegts.js yet - the real PadBot URL type is unknown;
+ * HLS plays natively where the browser can (Safari), FLV and HLS elsewhere
+ * get "Open in new tab". Add the player library once a real URL is seen.
+ */
+export function liveVideoKind(url: unknown): TVideoKind {
+  if (typeof url !== "string") return "bad";
+  if (/^rtmps?:\/\//i.test(url)) return "rtmp";
+  if (!/^https?:\/\//i.test(url)) return "bad";
+  const path = url.split(/[?#]/)[0]!.toLowerCase();
+  if (path.endsWith(".m3u8")) return "hls";
+  if (path.endsWith(".flv")) return "flv";
+  if (/\.(mp4|webm)$/.test(path)) return "video";
+  return "page";
+}
+
+/** When to ask for a fresh URL: 30 s before it expires (never sooner than 5 s); null when it does not expire. */
+export function remintDelayMs(expiresAt: unknown, now: number = Date.now()): number | null {
+  const t = typeof expiresAt === "string" ? Date.parse(expiresAt) : NaN;
+  if (!Number.isFinite(t)) return null;
+  return Math.max(5_000, t - now - 30_000);
+}
+
+/* ======================================================== manual drive */
+
+export type TDriveLimits = {
+  maxLinear: number;
+  maxAngular: number;
+  heartbeatMs: number;
+  commandMaxMs?: number;
+  headPan: [number, number];
+  headTilt: [number, number];
+};
+export type TDriveDirection = "forward" | "back" | "left" | "right";
+export type TDriveSend = (body: Record<string, unknown>, opts?: { keepalive?: boolean }) => Promise<{ ok: boolean; status: number; message: string }>;
+
+/** Chassis vector for a held direction, at the server's cap (left turn = positive angular speed). */
+export function driveVector(dir: TDriveDirection, limits: Pick<TDriveLimits, "maxLinear" | "maxAngular">) {
+  if (dir === "forward") return { lv: limits.maxLinear, av: 0 };
+  if (dir === "back") return { lv: -limits.maxLinear, av: 0 };
+  return { lv: 0, av: dir === "left" ? limits.maxAngular : -limits.maxAngular };
+}
+
+/** "Speed limited to 0.3 m/s". */
+export const speedLimitText = (limits: Pick<TDriveLimits, "maxLinear"> | null | undefined) =>
+  limits && Number.isFinite(limits.maxLinear) ? `Speed limited to ${limits.maxLinear} m/s` : "";
+
+const MOVE_REPEAT_MS = 500;
+
+/**
+ * The screen side of a drive session: a heartbeat every `heartbeatMs` for as
+ * long as the dialog is open, a move on press and every 500 ms while held, a
+ * stop on release. Any refused signal ends the session (the server has
+ * already stopped the robot) and `onEnd` gets the server's words.
+ */
+export function createDriveClient(o: {
+  send: TDriveSend;
+  limits: TDriveLimits;
+  onEnd: (reason: string) => void;
+  setInterval?: typeof setInterval;
+  clearInterval?: typeof clearInterval;
+}) {
+  const si = o.setInterval ?? setInterval;
+  const ci = o.clearInterval ?? clearInterval;
+  let seq = 0;
+  let ended = false;
+  let held: TDriveDirection | null = null;
+  let moveTimer: ReturnType<typeof setInterval> | null = null;
+  const head = { pan: 0, tilt: 0 };
+
+  const post = (body: Record<string, unknown>, opts?: { keepalive?: boolean }) => {
+    if (ended) return;
+    const signal = { seq: ++seq, ...body };
+    void o.send(signal, opts).then((r) => {
+      if (!r.ok && body.action !== "end") end(r.message || (r.status ? "Manual control ended." : "Manual control ended: connection lost."), false);
+    });
+  };
+  const beatTimer = si(() => post({ action: "beat" }), o.limits.heartbeatMs);
+  post({ action: "beat" });
+
+  function clearMove() {
+    if (moveTimer) ci(moveTimer);
+    moveTimer = null;
+  }
+  function end(reason = "", tellServer = true) {
+    if (ended) return;
+    clearMove();
+    ci(beatTimer);
+    if (tellServer) post({ action: "end" }, { keepalive: true });
+    ended = true;
+    held = null;
+    o.onEnd(reason);
+  }
+  return {
+    press(dir: TDriveDirection) {
+      if (ended) return;
+      held = dir;
+      clearMove();
+      const send = () => held && post({ action: "move", ...driveVector(held, o.limits) });
+      send();
+      moveTimer = si(send, MOVE_REPEAT_MS);
+    },
+    release() {
+      if (ended || !held) return;
+      held = null;
+      clearMove();
+      post({ action: "stop" });
+    },
+    /** The big STOP: always sends, held or not. */
+    stop() {
+      held = null;
+      clearMove();
+      post({ action: "stop" });
+    },
+    look(dir: "left" | "right" | "up" | "down" | "centre", step = 15) {
+      if (dir === "centre") {
+        head.pan = head.tilt = 0;
+        return post({ action: "head", axis: "reset" });
+      }
+      const clamp = (v: number, [lo, hi]: [number, number]) => Math.max(lo, Math.min(hi, v));
+      if (dir === "left" || dir === "right") {
+        head.pan = clamp(head.pan + (dir === "left" ? step : -step), o.limits.headPan);
+        return post({ action: "head", axis: "pan", angle: head.pan });
+      }
+      head.tilt = clamp(head.tilt + (dir === "up" ? step : -step), o.limits.headTilt);
+      post({ action: "head", axis: "tilt", angle: head.tilt });
+    },
+    end: (reason = "") => end(reason, true),
+    get ended() {
+      return ended;
+    },
+    get held() {
+      return held;
+    },
+  };
+}
+
+/* ======================================================== alert photos */
+
+/** "Photo" / "Thermal photo" links for a fault that carries the robot's pictures (http/https only). */
+export function faultPhotos(fault: { imageUrl?: unknown; thermalImageUrl?: unknown } | null | undefined): Array<{ label: string; url: string }> {
+  const ok = (v: unknown): v is string => typeof v === "string" && /^https?:\/\//i.test(v);
+  return [
+    ...(ok(fault?.imageUrl) ? [{ label: "Photo", url: fault!.imageUrl as string }] : []),
+    ...(ok(fault?.thermalImageUrl) ? [{ label: "Thermal photo", url: fault!.thermalImageUrl as string }] : []),
+  ];
+}

package/utils/robot-display.ts

@@ -598,6 +598,8 @@ export type TLiveRobotState = {
   ok: boolean;
   /** false = its brand has no interface: nothing to show, ever. */
   monitorable?: boolean;
+  /** When `ok` is false: why, in words (e.g. "Ounitech rejected the robot list (sign-in) (code X: ...)"). */
+  reason?: string;
   online?: boolean;
   mode?: string;
   batteryPercent?: number | null;
@@ -609,28 +611,85 @@ export type TLiveRobotState = {
   /** The brand's own status words ("CLEANING_AUTO"), quoted as "Brand status". */
   statusName?: string;
   model?: string;
-  fault?: { code: string; message?: string; since?: number } | null;
+  fault?: { code: string; message?: string; since?: number; imageUrl?: string | null; thermalImageUrl?: string | null } | null;
   capabilities?: Record<string, unknown>;
   lastSeenAt?: string | null;
+  /** Epoch ms of the last answer that was read (set by `mergeLiveStates`). */
+  readAt?: number;
+  /** Epoch ms when the shown position was reported. */
+  positionAt?: number;
+  /** true = what is shown is the last reading, kept through a short gap - drawn faded with "last seen". */
+  stale?: boolean;
 };
 
+/** A gap shorter than this keeps the last reading (faded, "last seen N s ago"); longer reads "Reconnecting". */
+export const LIVE_GRACE_MS = 15_000;
+
+const hasPos = (s: Partial<TLiveRobotState> | null | undefined) =>
+  (!!s?.position && finite(s.position.x) && finite(s.position.y)) || (!!s?.planPosition && finite(s.planPosition.x) && finite(s.planPosition.y));
+
 /**
- * Fold one poll's answer into the live map. A robot that did not answer
- * REPLACES its old state with `{ ok: false }`: a stale battery or position
- * must never stay on screen as if live. Robots not in this answer keep theirs.
+ * Fold one poll's answer into the live map. Robots not in this answer keep theirs.
+ *
+ * One missed or failed update must not make a robot vanish from the map
+ * (owner, 2026-09-26: it disappeared and came back while moving). So:
+ *  - no answer (`ok: false`): the last reading is kept, marked `stale`, for
+ *    up to `LIVE_GRACE_MS` after it was read; past that it is REPLACED by
+ *    `{ ok: false }` ("Reconnecting") - a stale battery or position is never
+ *    kept as if live;
+ *  - an answer without a position: the last position is kept (stale) within
+ *    the same window, unless the robot now says it is offline or that its
+ *    floor is unknown (`floorKnown: false`);
+ *  - an answer without floor fields keeps the last floor.
  */
 export function mergeLiveStates(
   prev: Record<string, TLiveRobotState>,
   items: Array<Partial<TLiveRobotState> & { id?: unknown }> | null | undefined,
+  now: number = Date.now(),
 ): Record<string, TLiveRobotState> {
   const next = { ...prev };
   for (const item of items ?? []) {
     if (!item || typeof item.id !== "string") continue;
-    next[item.id] = item.ok === true ? ({ ...item, ok: true } as TLiveRobotState) : { id: item.id, ok: false, monitorable: item.monitorable !== false };
+    const p = prev[item.id];
+    const recent = (at: number | undefined) => finite(at) && now - at <= LIVE_GRACE_MS;
+    if (item.ok !== true) {
+      next[item.id] =
+        item.monitorable !== false && p?.ok && recent(p.readAt)
+          ? { ...p, stale: true }
+          : {
+              id: item.id,
+              ok: false,
+              monitorable: item.monitorable !== false,
+              // The API's plain reason, so the detail screen says WHY instead of only "Reconnecting".
+              ...(typeof item.reason === "string" && item.reason ? { reason: item.reason.slice(0, 300) } : {}),
+            };
+      continue;
+    }
+    const s = { ...item, ok: true, readAt: now, stale: false } as TLiveRobotState;
+    if (!("floorKnown" in item) && !("floorNo" in item) && p?.ok) {
+      s.floorNo = p.floorNo;
+      s.floorKnown = p.floorKnown;
+    }
+    if (hasPos(item)) s.positionAt = now;
+    else if (p?.ok && hasPos(p) && recent(p.positionAt) && item.online !== false && item.floorKnown !== false) {
+      s.position = p.position ?? null;
+      s.planPosition = p.planPosition ?? null;
+      s.positionAt = p.positionAt;
+      s.stale = true;
+    }
+    next[item.id] = s;
   }
   return next;
 }
 
+/** "last seen 8 s ago" for a kept (stale) reading, "" when it is fresh. */
+export function staleText(live: TLiveRobotState | null | undefined, now: number = Date.now()): string {
+  if (!live?.stale) return "";
+  const at = finite(live.positionAt) ? live.positionAt : live.readAt;
+  if (!finite(at)) return "last reading";
+  return `last seen ${Math.max(0, Math.round((now - at) / 1000))} s ago`;
+}
+
 /**
  * What the Status cell says for a row: the live mode when read; "Reconnecting"
  * when the last poll got no answer; "Offline" from the stored record while no
@@ -731,7 +790,7 @@ export function brandName(brand: unknown, brands?: Array<{ brand?: unknown; disp
 
 /* ------------------------------------------------------------- mini-map */
 
-export type TMapRobot = { id: string; name: string; mode?: string; type?: string; left: string; top: string; rot: string };
+export type TMapRobot = { id: string; name: string; mode?: string; type?: string; left: string; top: string; rot: string; stale?: boolean; seen?: string };
 
 const finite = (v: unknown): v is number => typeof v === "number" && Number.isFinite(v);
 
@@ -800,7 +859,8 @@ export function mapRobots(
     const live = states[id];
     if (!placeable(live) || live!.floorNo !== floor) return [];
     const at = planPoint(live as any)!;
-    return [{ id, name: String(r.name ?? ""), mode: live!.mode, type: r.type as string, ...at, rot: `rotate(${headingDeg(live)}deg)` }];
+    // A kept (stale) reading is drawn faded with "last seen N s ago" - never as live.
+    return [{ id, name: String(r.name ?? ""), mode: live!.mode, type: r.type as string, ...at, rot: `rotate(${headingDeg(live)}deg)`, stale: live!.stale === true, seen: staleText(live) }];
   });
 }
 
@@ -828,33 +888,47 @@ export type TPatrolRouteView = {
   floorNo: number | null;
   checkpoints: Array<{ name: string; x: number; y: number }>;
   currentCheckpoint: number | null;
+  /** Every stop's name in order, placed on the plan or not (PadBot); a route with none placed is listed, never drawn. */
+  stops?: string[];
 };
 
+const placed = (c: { x?: unknown; y?: unknown }) => finite(c?.x) && finite(c?.y);
+
+/** "Gate → Lobby → Car park" for a route whose stops cannot be placed on the plan; "" when it can be drawn. */
+export function unplacedStopsText(route: Pick<TPatrolRouteView, "checkpoints" | "stops"> | null | undefined): string {
+  if (!route || (route.checkpoints ?? []).filter(placed).length >= 2 || !route.stops?.length) return "";
+  return route.stops.join(" → ");
+}
+
 /** The SVG path of a closed route on a `w` x `h` viewBox (checkpoints are 0-100 shares of the plan). */
 export function routePathD(checkpoints: Array<{ x: number; y: number }>, w = 400, h = 300): string {
-  if (!checkpoints?.length) return "";
+  checkpoints = (checkpoints ?? []).filter(placed);
+  if (checkpoints.length < 2) return "";
   return checkpoints.map((p, i) => `${i ? "L" : "M"}${((p.x / 100) * w).toFixed(1)} ${((p.y / 100) * h).toFixed(1)}`).join(" ") + " Z";
 }
 
 /** Numbered checkpoint markers for every route; `current` = the one the robot is heading for. */
 export function routeMarks(routes: TPatrolRouteView[]) {
   return routes.flatMap((r) =>
-    r.checkpoints.map((c, i) => ({
+    r.checkpoints.flatMap((c, i) => (!placed(c) ? [] : [{
       key: `${r.id}-${i}`,
       n: i + 1,
       left: `${c.x}%`,
       top: `${c.y}%`,
       label: c.name,
       current: r.currentCheckpoint === i,
-    })),
+    }])),
   );
 }
 
 /** A route-name tag at each route's first checkpoint. */
 export function routeTags(routes: TPatrolRouteView[]) {
   return routes
-    .filter((r) => r.checkpoints.length)
-    .map((r) => ({ key: r.id, name: r.name, count: r.checkpoints.length, left: `${r.checkpoints[0]!.x}%`, top: `${r.checkpoints[0]!.y}%` }));
+    .filter((r) => r.checkpoints.some(placed))
+    .map((r) => {
+      const first = r.checkpoints.find(placed)!;
+      return { key: r.id, name: r.name, count: r.checkpoints.length, left: `${first.x}%`, top: `${first.y}%` };
+    });
 }
 
 /**
@@ -995,6 +1069,84 @@ export function commandBody(kind: TRobotCommandKind, live: TLiveRobotState | nul
   return finite(live?.floorNo) ? { kind, floorNo: live!.floorNo, x: p.x, y: p.y, theta: p.theta } : null;
 }
 
+/* ------------------------------------------ saved points (Go to point / Set position) */
+
+/** §5.1 target point types, in words. */
+export const POINT_TYPE_TEXT: Readonly<Record<number, string>> = { 0: "Point", 3: "Lift", 4: "Loading", 6: "Access door", 10: "Charging" };
+
+export type TSavedPoint = { mapId: string; targetPointId: string; name: string; type: string; floorNo: number | null; x: number; y: number; yaw: number };
+export type TSavedPointGroup = { mapId: string; title: string; floorNo: number | null; points: TSavedPoint[] };
+
+/**
+ * The robot's own saved points, per map ("Lobby map · L3"), from `/robots/:id/maps`
+ * items that carry `targetPoints` (PadBot). [] for brands without them - they
+ * keep the current-pose behaviour of `commandBody`.
+ */
+export function savedPointGroups(maps: Array<Record<string, any>> | null | undefined): TSavedPointGroup[] {
+  return (Array.isArray(maps) ? maps : []).flatMap((m) => {
+    const floorNo = Number.isInteger(m?.floor) ? (m.floor as number) : null;
+    const points = (Array.isArray(m?.targetPoints) ? m.targetPoints : [])
+      .filter((t: any) => typeof t?.targetPointId === "string" && t.targetPointId && finite(t.worldX) && finite(t.worldY))
+      .map((t: any) => ({
+        mapId: String(m.mapId ?? t.mapId ?? ""),
+        targetPointId: t.targetPointId,
+        name: String(t.name || "Unnamed point"),
+        type: POINT_TYPE_TEXT[t.targetPointType] ?? "Point",
+        floorNo,
+        x: t.worldX,
+        y: t.worldY,
+        yaw: finite(t.yaw) ? t.yaw : 0,
+      }));
+    if (!points.length || !m?.mapId) return [];
+    const name = String(m.mapDisplayName || m.mapName || "Map");
+    return [{ mapId: String(m.mapId), title: floorNo === null ? name : `${name} · ${levelText(floorNo)}`, floorNo, points }];
+  });
+}
+
+/**
+ * The command for a picked saved point. Go to point names the point
+ * (`go-to-point`); Set position tells the robot it stands there now - only on
+ * the floor the robot reports (null otherwise).
+ */
+export function pointCommandBody(kind: "navigate" | "relocalize", point: TSavedPoint, live: TLiveRobotState | null | undefined): Record<string, unknown> | null {
+  if (kind === "navigate") return { kind: "go-to-point", mapId: point.mapId, targetPointId: point.targetPointId };
+  if (point.floorNo === null || !finite(live?.floorNo) || live!.floorNo !== point.floorNo) return null;
+  return { kind: "relocalize", floorNo: point.floorNo, x: point.x, y: point.y, theta: (point.yaw * Math.PI) / 180 };
+}
+
+/* ------------------------------------------ recent patrol runs (no schedule API) */
+
+/**
+ * A HINT, never a schedule: when the same route started on at least 3 of the
+ * last 7 days inside one 60-minute window, "Looks like "Night round" runs
+ * daily around 20:00 (based on the last 7 days)". Local clock. "" otherwise.
+ */
+export function patrolRunHint(records: Array<{ routeName?: unknown; startedAt?: unknown }> | null | undefined, now: number = Date.now()): string {
+  const since = now - 7 * 86_400_000;
+  const byRoute = new Map<string, Array<{ day: string; min: number }>>();
+  for (const r of records ?? []) {
+    const t = typeof r?.startedAt === "string" ? Date.parse(r.startedAt) : NaN;
+    const name = typeof r?.routeName === "string" ? r.routeName.trim() : "";
+    if (!name || !finite(t) || t < since || t > now) continue;
+    const d = new Date(t);
+    byRoute.set(name, [...(byRoute.get(name) ?? []), { day: d.toDateString(), min: d.getHours() * 60 + d.getMinutes() }]);
+  }
+  let best: { name: string; days: number; min: number } | null = null;
+  for (const [name, runs] of byRoute) {
+    for (const start of runs) {
+      const inWin = runs.filter((x) => x.min >= start.min && x.min < start.min + 60);
+      const days = new Set(inWin.map((x) => x.day)).size;
+      if (days >= 3 && (!best || days > best.days)) {
+        best = { name, days, min: Math.round(inWin.reduce((s, x) => s + x.min, 0) / inWin.length / 5) * 5 };
+      }
+    }
+  }
+  if (!best) return "";
+  const hhmm = `${String(Math.floor(best.min / 60) % 24).padStart(2, "0")}:${String(best.min % 60).padStart(2, "0")}`;
+  const how = best.days >= 6 ? "daily" : `on ${best.days} of the last 7 days`;
+  return `Looks like "${best.name}" runs ${how} around ${hhmm} (based on the last 7 days)`;
+}
+
 /**
  * May the plan take spot-clean clicks? A Manager, a cleaning robot, a brand
  * that declares `spotClean`, and a robot confirmed online. (A busy robot keeps
@@ -1039,12 +1191,15 @@ export function speedText(
 }
 
 /** "x 17.9 · y 34.1 · 53°" (metres, the robot's map frame) - or "Reconnecting", or "Not reported". */
-export function positionText(live: TLiveRobotState | null | undefined, capabilities: Record<string, unknown> | null | undefined): string {
+export function positionText(live: TLiveRobotState | null | undefined, capabilities: Record<string, unknown> | null | undefined, now: number = Date.now()): string {
   if (capabilities?.readLocation !== true) return "Not reported";
   const p = live?.position;
-  if (!live?.ok || live.online === false || !p || !finite(p.x) || !finite(p.y)) return "Reconnecting";
+  if (!live?.ok || live.online === false) return "Reconnecting";
+  // Answering, but it has no position right now (e.g. not relocalised) - said, not guessed.
+  if (!p || !finite(p.x) || !finite(p.y)) return "Position not reported right now";
   const deg = finite(p.theta) ? Math.round(((((p.theta * 180) / Math.PI) % 360) + 360) % 360) : 0;
-  return `x ${p.x.toFixed(1)} · y ${p.y.toFixed(1)} · ${deg}°`;
+  const seen = staleText(live, now);
+  return `x ${p.x.toFixed(1)} · y ${p.y.toFixed(1)} · ${deg}°${seen ? ` · ${seen}` : ""}`;
 }
 
 export type TRobotFact = { label: string; value: string; dim: boolean };
@@ -1105,6 +1260,8 @@ export function mergePose(
   const plan = event.planPosition as { x?: unknown; y?: unknown } | null | undefined;
   return {
     ...live,
+    stale: false,
+    positionAt: Date.now(),
     position: { x, y, theta: finite(theta) ? theta : live.position?.theta ?? 0 },
     ...(plan && finite(plan.x) && finite(plan.y) ? { planPosition: { x: plan.x, y: plan.y } } : {}),
     ...(typeof mode === "string" && mode ? { mode } : {}),