@7365admin1/layer-common 4.122.2 → 4.123.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @iservice365/layer-common
 
+## 4.123.0
+
+### Minor Changes
+
+- 9f32850: Robots: new "Setup" view on the Super Admin site screen (`view="setup"`). One checklist per site - robot module on, robots added (with vendor prerequisites), robots online (with the reason when not), building map saved, floors on the map, lifts with 2+ stops, lift gateway connected (and whether floor/door are decoded), HERO Fleet Core linked (optional), client roles with robot rights, and "Ready for client". Each step shows Done / Needs action / Waiting on others / Check manually, one plain line why, and one button to the existing screen that does it. Worked out only from existing reads; nothing is written. After adding a robot, Super Admin lands on Setup (`navigate` event). "Open HERO Fleet Core" (Super Admin) and "Import from HERO Fleet Core" now show disabled with a short reason instead of disappearing.
+
+## 4.122.3
+
+### Patch Changes
+
+- 6d9f5ad: Lift queue: when no robot ride is being drawn and the lift's read-only gateway is connected, the car in the shaft now follows the real lift - it moves to the lift's current floor, the doors open and close with the lift's door state, the car shows an up/down arrow while moving, and it turns the alert colour in fire/emergency modes. Before, the card text updated but the car only ever moved for robot rides.
+
 ## 4.122.2
 
 ### Patch Changes
@@ -3240,11 +3252,11 @@ Monthly report: a month that had patrols opens the list of that month's patrol r
   `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/components/Robot/FleetCoreButton.vue

@@ -16,24 +16,42 @@
   >
     Open HERO Fleet Core
   </v-btn>
+  <!-- `explain` (Super Admin screens): say why it cannot open instead of hiding it. -->
+  <span v-else-if="explain && checked" class="fleet-core-off">
+    <v-btn size="small" variant="tonal" prepend-icon="mdi-open-in-new" disabled>Open HERO Fleet Core</v-btn>
+    <span class="hero-muted fleet-core-off__why" role="status">{{ offReason }}</span>
+  </span>
   <span v-if="failed" class="hero-tag hero-tag--neutral" role="status">Could not open HERO Fleet Core. Try again.</span>
 </template>
 
 <script setup lang="ts">
-import { onMounted, ref } from "vue";
+import { computed, onMounted, ref } from "vue";
 import { openFleetCoreConsole } from "../../utils/robot-fleet-core";
 
+const props = withDefaults(defineProps<{ explain?: boolean }>(), { explain: false });
 const { getFleetCoreSession } = useRobots();
 const available = ref(false);
+const checked = ref(false);
+const refusedWith = ref(0);
+const offReason = computed(() =>
+  refusedWith.value === 404
+    ? "Not switched on on this server yet - a Seven365 engineer sets it up."
+    : refusedWith.value === 403
+      ? "Seven365 Super Admin only."
+      : "Could not reach HERO Fleet Core.",
+);
 const opening = ref(false);
 const failed = ref(false);
 
 onMounted(async () => {
   try {
     available.value = (await getFleetCoreSession({ check: true }))?.available === true;
-  } catch {
+    if (!available.value) refusedWith.value = 404;
+  } catch (e: any) {
     available.value = false;
+    refusedWith.value = Number(e?.statusCode ?? e?.status) || 0;
   }
+  checked.value = props.explain;
 });
 
 async function open() {
@@ -46,3 +64,8 @@ async function open() {
   opening.value = false;
 }
 </script>
+
+<style scoped>
+.fleet-core-off { display: inline-flex; flex-wrap: wrap; align-items: center; gap: 6px; }
+.fleet-core-off__why { font-size: 12px; }
+</style>

package/components/Robot/LiftQueue.vue

@@ -85,10 +85,13 @@
           <div
             class="hero-lift__carbox"
             :class="`hero-lift__carbox--${l.carTone}`"
-            :style="{ height: `${l.carH}px`, top: `${l.fromTop}px`, '--from': `${l.fromTop}px`, '--to': `${l.toTop}px`, animation: l.riding ? 'heroLift 6s ease-in-out infinite alternate' : 'none' }"
+            :style="{ height: `${l.carH}px`, top: `${l.fromTop}px`, '--from': `${l.fromTop}px`, '--to': `${l.toTop}px`, animation: l.riding ? 'heroLift 6s ease-in-out infinite alternate' : 'none', transition: l.live ? 'top 1.8s linear' : 'none' }"
           >
             <span class="hero-lift__carlabel">{{ l.carLabel }}</span>
-            <div class="hero-lift__doors" :style="{ animation: l.riding ? 'heroDoors 6s ease-in-out infinite' : 'none' }" />
+            <div
+              class="hero-lift__doors"
+              :style="l.live ? { transform: `scaleX(${1 - l.doors})`, transition: 'transform 0.8s ease' } : { animation: l.riding ? 'heroDoors 6s ease-in-out infinite' : 'none' }"
+            />
           </div>
         </div>
       </div>

package/components/Robot/MapEditor.vue

@@ -354,8 +354,9 @@
         <!-- ---- building file ---- -->
         <div class="hero-aside__title hero-editor__asidetitle">Building file · HERO Fleet Core</div>
         <div v-if="map?.rmf" class="hero-muted">{{ rmfLine(map.rmf) }}</div>
+        <div v-if="!fleetSite" class="hero-muted">{{ fleetImportOff }}</div>
         <div class="hero-editor__actions">
-          <button v-if="fleetSite" type="button" class="hero-editor__act" :disabled="planBusy || saving || state.dirty" :title="state.dirty ? 'Save your drawing first.' : ''" @click="importFleet">Import from HERO Fleet Core</button>
+          <button type="button" class="hero-editor__act" :disabled="!fleetSite || planBusy || saving || state.dirty" :title="!fleetSite ? fleetImportOff : state.dirty ? 'Save your drawing first.' : ''" @click="importFleet">Import from HERO Fleet Core</button>
           <button type="button" class="hero-editor__act" :disabled="planBusy || saving" @click="pickFile('building')">Import building file</button>
           <button type="button" class="hero-editor__act" :disabled="planBusy || saving" @click="pickFile('nav')">Import route map into {{ graphName(graph) }}</button>
           <button type="button" class="hero-editor__act" :disabled="!map?._id" @click="download('building')">Download building file</button>
@@ -439,6 +440,8 @@ import {
   type TShapeHandle,
 } from "../../utils/robot-building";
 
+// Shown instead of hiding "Import from HERO Fleet Core" (owner 2026-10-15: always say why).
+const fleetImportOff = "Import from HERO Fleet Core: only for a site whose robots run through HERO Fleet Core (a Seven365 engineer links them today).";
 const props = withDefaults(
   defineProps<{
     /** The site's saved building map, or null (the first save creates it). */

package/components/Robot/Setup.vue

@@ -0,0 +1,184 @@
+<template>
+  <!--
+    ROBOTICS SETUP (Seven365 Super Admin, owner 2026-10-15): one site's setup
+    as a checklist. Each step says Done / Needs action / Waiting on others /
+    Check manually, one plain line why, and ONE button to the screen that does
+    it. Worked out from the reads the robot screens already make
+    (`utils/robot-setup.ts`); nothing here writes.
+  -->
+  <div class="hero-head">
+    <div>
+      <button v-if="backToNetwork" type="button" class="hero-back hero-back--sm" @click="emit('network')">‹ Network</button>
+      <div class="hero-kicker hero-kicker--accent">{{ kicker }}</div>
+      <h2 class="hero-title">Robotics setup</h2>
+    </div>
+    <span class="hero-head__spacer" />
+    <span class="hero-tag hero-tag--neutral" role="status">Setup {{ progress.done }}/{{ progress.total }}</span>
+    <v-btn size="small" variant="text" :loading="busy" @click="refresh">Check again</v-btn>
+  </div>
+
+  <div v-if="error" class="hero-notice hero-notice--error" role="alert">{{ error }}</div>
+  <div v-else-if="next" class="hero-notice hero-notice--panel setup-next" role="status">
+    <div class="hero-notice__title">Next step: {{ next.title }}</div>
+    <div class="hero-notice__body">{{ next.reason }}</div>
+    <div v-if="next.note" class="hero-notice__body hero-muted">{{ next.note }}</div>
+    <div v-if="next.button" class="setup-next__act">
+      <RobotFleetCoreButton v-if="next.button.target === 'fleetcore'" explain />
+      <v-btn v-else size="small" color="primary" variant="flat" @click="go(next.button.target)">{{ next.button.label }}</v-btn>
+    </div>
+  </div>
+  <div v-else-if="!busy" class="hero-notice hero-notice--panel" role="status">
+    <div class="hero-notice__title">Ready for client</div>
+    <div class="hero-notice__body">Every step is done - the client can use their robots.</div>
+  </div>
+
+  <ol class="setup-list" aria-label="Setup steps">
+    <li v-for="(s, i) in steps" :key="s.key" class="setup-step" :data-status="s.status">
+      <span class="setup-step__n" aria-hidden="true">{{ i + 1 }}</span>
+      <div class="setup-step__body">
+        <div class="setup-step__title">
+          {{ s.title }}<span v-if="s.optional" class="hero-muted"> · optional</span>
+        </div>
+        <div class="setup-step__reason">{{ busy && !loaded ? "Checking…" : s.reason }}</div>
+        <div v-if="s.note" class="setup-step__reason hero-muted">{{ s.note }}</div>
+      </div>
+      <span class="hero-chip setup-step__chip" :class="`hero-tone--${TONE[s.status]}`">{{ busy && !loaded ? "Checking" : STATUS_TEXT[s.status] }}</span>
+      <span v-if="s.button" class="setup-step__act">
+        <RobotFleetCoreButton v-if="s.button.target === 'fleetcore'" explain />
+        <v-btn v-else size="small" variant="outlined" @click="go(s.button.target)">{{ s.button.label }}</v-btn>
+      </span>
+    </li>
+  </ol>
+</template>
+
+<script setup lang="ts">
+import { computed, ref, toRef, watch } from "vue";
+import RobotFleetCoreButton from "./FleetCoreButton.vue";
+import useRobotBuilding from "../../composables/useRobotBuilding";
+import useRobotLive, { siteStatesFeed } from "../../composables/useRobotLive";
+import { robotSetupSteps, setupProgress, STATUS_TEXT, type TSetupStatus, type TSetupTarget } from "../../utils/robot-setup";
+
+const props = withDefaults(
+  defineProps<{
+    organization: string;
+    site: string;
+    siteName?: string;
+    clientName?: string;
+    backToNetwork?: boolean;
+  }>(),
+  { siteName: "", clientName: "", backToNetwork: false },
+);
+const emit = defineEmits<{
+  /** A step's button: a site view (fleet / map / lifts), the client's details, or Add robot. */
+  go: [target: TSetupTarget];
+  network: [];
+}>();
+
+const TONE: Record<TSetupStatus, string> = { done: "success", action: "warning", waiting: "info", check: "neutral" };
+
+// Every robot at the site (both types): the building composable already reads them and the saved map.
+const { all, saved, names, loading, error, reload } = useRobotBuilding(toRef(props, "organization"), toRef(props, "site"), ref<"cleaning" | "security">("cleaning"));
+const kicker = computed(() => [props.clientName || names.value.clientName, props.siteName || names.value.siteName].filter(Boolean).join(" · "));
+
+const ids = computed(() => all.value.map((r) => String(r._id)).slice(0, 50));
+const { states } = useRobotLive(ids, siteStatesFeed(10000));
+
+const { getLiftQueue, getFleetCoreSession } = useRobots();
+const api = (url: string, query?: Record<string, any>) => useNuxtApp().$api<Record<string, any>>(url, { method: "GET", query });
+const unwrap = (res: any) => res?.data ?? res;
+
+const orgModules = ref<unknown[] | null | undefined>(undefined);
+const siteModules = ref<unknown[] | null | undefined>(undefined);
+const roles = ref<Array<Record<string, any>> | undefined>(undefined);
+const lifts = ref<Array<Record<string, any>> | undefined>(undefined);
+const fleetCore = ref<true | number | undefined>(undefined);
+const extrasBusy = ref(false);
+const loaded = ref(false);
+
+async function loadExtras() {
+  extrasBusy.value = true;
+  const org = props.organization;
+  const site = props.site;
+  const [o, s, r, f] = await Promise.allSettled([
+    api(`/api/organizations/org/id/${org}`),
+    api(`/api/sites/${site}`),
+    // `site` keeps this a plain read: the whole-org page-1 list seeds default roles when empty.
+    api("/api/roles", { org, site, page: 1, limit: 100 }),
+    getFleetCoreSession({ check: true }),
+  ]);
+  if (org !== props.organization || site !== props.site) return;
+  orgModules.value = o.status === "fulfilled" ? (unwrap(o.value)?.modules ?? null) : undefined;
+  siteModules.value = s.status === "fulfilled" ? (unwrap(s.value)?.metadata?.modules ?? null) : undefined;
+  roles.value = r.status === "fulfilled" ? (r.value?.items ?? unwrap(r.value)?.items ?? undefined) : undefined;
+  fleetCore.value =
+    f.status === "fulfilled" ? (f.value?.available === true ? true : 404) : Number((f.reason as any)?.statusCode ?? (f.reason as any)?.status) || undefined;
+  extrasBusy.value = false;
+}
+
+async function loadLifts() {
+  const id = saved.value?._id;
+  if (!id) return void (lifts.value = []);
+  lifts.value = (await getLiftQueue(String(id)).catch(() => null))?.items ?? undefined;
+}
+
+watch(() => [props.organization, props.site], loadExtras, { immediate: true });
+watch(() => saved.value?._id, loadLifts);
+watch([loading, extrasBusy], ([a, b]) => {
+  if (!a && !b) loaded.value = true;
+});
+
+const busy = computed(() => loading.value || extrasBusy.value);
+async function refresh() {
+  await Promise.all([reload(), loadExtras()]);
+  await loadLifts();
+}
+
+const steps = computed(() =>
+  robotSetupSteps({
+    orgModules: orgModules.value,
+    siteModules: siteModules.value,
+    robots: error.value ? undefined : all.value,
+    states: states.value as Record<string, Record<string, any>>,
+    savedMap: error.value ? undefined : saved.value,
+    lifts: lifts.value,
+    fleetCore: fleetCore.value,
+    roles: roles.value,
+  }),
+);
+const progress = computed(() => setupProgress(steps.value));
+const next = computed(() => (loaded.value ? steps.value.find((s) => !s.optional && s.key !== "ready" && s.status !== "done") ?? null : null));
+
+function go(target: TSetupTarget) {
+  if (target) emit("go", target);
+}
+</script>
+
+<style scoped>
+.setup-list { list-style: none; margin: 12px 0 0; padding: 0; display: grid; gap: 8px; }
+.setup-step {
+  display: grid;
+  grid-template-columns: 28px 1fr auto;
+  grid-template-areas: "n body chip" "n act act";
+  gap: 6px 10px;
+  align-items: start;
+  padding: 12px;
+  background: var(--hero-surface);
+  box-shadow: var(--hero-shadow-sm);
+  border-left: 3px solid var(--hero-divider);
+}
+.setup-step[data-status="done"] { border-left-color: rgb(var(--v-theme-success)); }
+.setup-step[data-status="action"] { border-left-color: rgb(var(--v-theme-warning)); }
+.setup-step[data-status="waiting"] { border-left-color: rgb(var(--v-theme-info)); }
+.setup-step__n { grid-area: n; font-family: var(--hero-font); font-weight: 800; opacity: 0.5; }
+.setup-step__body { grid-area: body; min-width: 0; }
+.setup-step__title { font-family: var(--hero-font); font-weight: 700; }
+.setup-step__reason { font-size: 13px; overflow-wrap: anywhere; }
+.setup-step__chip { grid-area: chip; }
+.setup-step__act { grid-area: act; display: flex; flex-wrap: wrap; gap: 6px; align-items: center; }
+.setup-next { margin-top: 8px; }
+.setup-next__act { margin-top: 8px; display: flex; flex-wrap: wrap; gap: 6px; align-items: center; }
+@media (max-width: 480px) {
+  .setup-step { grid-template-columns: 22px 1fr; grid-template-areas: "n body" "n chip" "n act"; }
+  .setup-step__chip { justify-self: start; }
+}
+</style>

package/components/Robot/SiteHeader.vue

@@ -35,7 +35,7 @@
     </div>
     <span class="hero-head__spacer" />
     <div class="hero-header__right">
-      <RobotFleetCoreButton />
+      <RobotFleetCoreButton :explain="superAdmin" />
       <RobotLiveIndicator :connected="connected" />
       <span class="hero-tag hero-tag--neutral">{{ role }}</span>
     </div>
@@ -58,8 +58,10 @@ withDefaults(
     type?: TRobotType;
     connected?: boolean;
     role?: string;
+    /** Seven365 Super Admin: say why HERO Fleet Core cannot open instead of hiding it. */
+    superAdmin?: boolean;
   }>(),
-  { orgName: "", sites: () => [], site: "", types: () => ["cleaning"], type: "cleaning", connected: true, role: "View-only" },
+  { superAdmin: false, orgName: "", sites: () => [], site: "", types: () => ["cleaning"], type: "cleaning", connected: true, role: "View-only" },
 );
 const emit = defineEmits<{ "update:site": [id: string]; "update:type": [type: TRobotType] }>();
 </script>

package/components/Robot/SiteScreen.vue

@@ -17,6 +17,7 @@
       :type="type"
       :connected="connected"
       :role="role"
+      :super-admin="superAdmin"
       @update:site="(id) => emit('update:site', id)"
       @update:type="setType"
     />
@@ -35,6 +36,17 @@
         @removed="onRemoved"
         @status="(s) => (connected = s.connected)"
       />
+      <RobotSetup
+        v-else-if="view === 'setup' && superAdmin"
+        :key="`setup:${site}:${setupKey}`"
+        :organization="organization"
+        :site="site"
+        :site-name="siteName || names.siteName"
+        :client-name="clientName || names.clientName"
+        :back-to-network="backToNetwork"
+        @go="onSetupGo"
+        @network="emit('network')"
+      />
       <RobotBuildingMap
         v-else-if="view === 'map'"
         :key="`map:${site}:${type}`"
@@ -129,6 +141,7 @@ import RobotLiftQueue from "./LiftQueue.vue";
 import RobotSiteAlerts from "./SiteAlerts.vue";
 import RobotActivityLog from "./ActivityLog.vue";
 import RobotForm from "./Form.vue";
+import RobotSetup from "./Setup.vue";
 import RobotToast from "./Toast.vue";
 import { roleLabel, type TRobotType } from "../../utils/robot-display";
 
@@ -148,8 +161,8 @@ const props = withDefaults(
     type?: TRobotType;
     /** One robot open, or none (the fleet). */
     robotId?: string;
-    /** Which screen: the fleet (default), the 3D building map, the lift queue, alerts or the activity log. A robot open wins. */
-    view?: "fleet" | "map" | "lifts" | "alerts" | "log";
+    /** Which screen: the fleet (default), setup (Super Admin), the 3D building map, the lift queue, alerts or the activity log. A robot open wins. */
+    view?: "setup" | "fleet" | "map" | "lifts" | "alerts" | "log";
     canSetup?: boolean;
     canEdit?: boolean;
     canCommand?: boolean;
@@ -182,6 +195,11 @@ const emit = defineEmits<{
   open: [id: string];
   back: [];
   network: [];
+  /**
+   * Super Admin setup: a step's button asks the host to show a site view
+   * (fleet / map / lifts / setup) or the client's details page ("client").
+   */
+  navigate: [target: string];
   /** Live feed health + open faults, for a host drawing its own header. */
   status: [status: { connected: boolean; faults: number }];
 }>();
@@ -224,10 +242,18 @@ watch(
 const addOpen = ref(false);
 const toast = ref("");
 const reloadKey = ref(0);
+const setupKey = ref(0);
 function onCreated() {
   addOpen.value = false;
   toast.value = "Robot saved · credentials hidden";
   reloadKey.value++;
+  setupKey.value++;
+  // Super Admin: straight to the site's setup, which says what to do next.
+  if (props.superAdmin) emit("navigate", "setup");
+}
+function onSetupGo(target: string) {
+  if (target === "add") addOpen.value = true;
+  else emit("navigate", target);
 }
 function onRemoved(name: string) {
   toast.value = `${name} removed`;

package/package.json

@@ -2,7 +2,7 @@
   "name": "@7365admin1/layer-common",
   "license": "MIT",
   "type": "module",
-  "version": "4.122.2",
+  "version": "4.123.0",
   "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-building.ts

@@ -1460,6 +1460,21 @@ export function liftQueueRows(lift: Record<string, any>, now = Date.now()): TLif
 const ROW_H = 44;
 const CAR_H = ROW_H - 14;
 
+/**
+ * A floor as the real lift shows it ("B1", "L34", "34", "G") -> the car's y on the rails. Between two rails
+ * (a floor the map has no rail for) the car sits proportionally between them; past the ends it sits on the end.
+ */
+export function liftFloorTop(display: unknown, floors: number[], topOf: (f: number) => number): number | null {
+  const parsed = newFloorNo(String(display ?? "").replace(/\s+/g, ""), []);
+  if (!("floorNo" in parsed) || !floors.length) return null;
+  const v = parsed.floorNo;
+  if (v <= floors[0]!) return topOf(floors[0]!);
+  if (v >= floors.at(-1)!) return topOf(floors.at(-1)!);
+  const i = floors.findIndex((f) => f >= v);
+  const lo = floors[i - 1]!, hi = floors[i]!;
+  return topOf(lo) + ((v - lo) / (hi - lo)) * (topOf(hi) - topOf(lo));
+}
+
 /** The whole card: header words, car status, shaft geometry, rows (README §5). */
 export function liftCard(lift: Record<string, any>, now = Date.now()) {
   const rows = liftQueueRows(lift, now);
@@ -1472,23 +1487,37 @@ export function liftCard(lift: Record<string, any>, now = Date.now()) {
   const rest = floors.includes(idleFloor) ? idleFloor : floors[0] ?? 1;
   const from = riding ? riding.fromNo : rest;
   const to = riding ? riding.toNo : rest;
+  // The real lift (read-only gateway), when no robot ride is drawn: the car follows its floor, doors and direction.
+  const gw = lift?.gateway;
+  const real = !riding && gw?.status === "connected" && gw.state ? gw.state : null;
+  const realTop = real ? liftFloorTop(real.currentFloor, floors, topOf) : null;
+  const live = realTop != null;
+  const realAlarm = live && [3, 4, 5].includes(Number(real.currentMode));
+  const arrow = live ? (real.motionState === 1 ? "▲" : real.motionState === 2 ? "▼" : "") : "";
   return {
     name: String(lift?.liftName ?? "Lift"),
     sub: rows.length ? `${riding ? 1 : 0} riding · ${waiting.length} waiting` : "idle",
-    carText: riding ? `Car · ${riding.robot} · ${riding.from} → ${riding.to}` : "Car idle",
-    carLabel: riding ? riding.robot.replace(/^HERO-/, "") : "",
-    carTone: riding ? "ink" : rows.some((r) => r.state === "timed out") ? "accent" : "neutral",
+    carText: riding
+      ? `Car · ${riding.robot} · ${riding.from} → ${riding.to}`
+      : live
+        ? `Car · floor ${real.currentFloor}${MOTION_TEXT[real.motionState] ? ` · ${MOTION_TEXT[real.motionState]!.toLowerCase()}` : ""}`
+        : "Car idle",
+    carLabel: riding ? riding.robot.replace(/^HERO-/, "") : arrow,
+    carTone: riding ? "ink" : realAlarm || rows.some((r) => r.state === "timed out") ? "accent" : live ? "ink" : "neutral",
+    /** Real lift drawn live: the car glides between readings; doors open (1) / half (0.5, moving) / shut (0). */
+    live,
+    doors: live ? (real.doorState === 2 ? 1 : real.doorState === 1 ? 0.5 : 0) : 0,
     riding: !!riding,
     empty: !rows.length,
     shaftH: (n - 1) * ROW_H + 24,
     carH: CAR_H,
-    fromTop: topOf(from) - CAR_H / 2,
-    toTop: topOf(to) - CAR_H / 2,
+    fromTop: (live ? realTop! : topOf(from)) - CAR_H / 2,
+    toTop: (live ? realTop! : topOf(to)) - CAR_H / 2,
     rails: [...floors].reverse().map((f) => ({
       floorNo: f,
       name: floorName(f),
       top: topOf(f),
-      lit: !!riding && (f === riding.fromNo || f === riding.toNo),
+      lit: riding ? f === riding.fromNo || f === riding.toNo : live && realTop === topOf(f),
       waiting: waiting.filter((w) => w.fromNo === f).map((w) => w.robot),
     })),
     rows,

package/utils/robot-setup.ts

@@ -0,0 +1,333 @@
+/**
+ * Robotics setup checklist (Seven365 Super Admin, one site): what is done,
+ * what needs doing and what waits on someone else, worked out ONLY from what
+ * the robot screens already read - nothing is ticked by hand, nothing stored.
+ * Pure: no Vue, no Nuxt (tested in robot-setup.test.ts).
+ *
+ * Every input may be `undefined` = "could not read it": that step then says
+ * "Check manually" with its link, never a guess.
+ */
+import { floorName } from "./robot-display.ts";
+
+export type TSetupStatus = "done" | "action" | "waiting" | "check";
+/** Where a step's button goes: a site view, the Add robot dialog, or the client's details page. */
+export type TSetupTarget = "client" | "add" | "fleet" | "map" | "lifts" | "fleetcore" | "";
+
+export type TSetupStep = {
+  key: string;
+  title: string;
+  status: TSetupStatus;
+  /** One plain-English line: why this status. */
+  reason: string;
+  /** A second line when it helps (vendor prerequisites, a sub-state). */
+  note?: string;
+  button: { label: string; target: TSetupTarget } | null;
+  /** Optional steps never block "Ready for client" and are not counted. */
+  optional?: boolean;
+};
+
+export type TSetupInput = {
+  /** `organizations.modules` (absent/empty = every module). */
+  orgModules?: unknown[] | null;
+  /** `sites.metadata.modules` (absent/empty = every module the client has). */
+  siteModules?: unknown[] | null;
+  /** Every robot at the site (both types). */
+  robots?: Array<Record<string, any>>;
+  /** Live states by robot id (`/robots/states`); missing ids = not read yet. */
+  states?: Record<string, Record<string, any>>;
+  /** The site's SAVED building map (`null` = none saved). */
+  savedMap?: Record<string, any> | null;
+  /** The lift queue items of the saved map, each with its `gateway` (or null). */
+  lifts?: Array<Record<string, any>>;
+  /** HERO Fleet Core `?check=1`: true, or the HTTP status that refused (404 = not switched on). */
+  fleetCore?: true | number;
+  /** The client's roles that apply at this site. */
+  roles?: Array<Record<string, any>>;
+};
+
+export const STATUS_TEXT: Record<TSetupStatus, string> = {
+  done: "Done",
+  action: "Needs action",
+  waiting: "Waiting on others",
+  check: "Check manually",
+};
+
+const ROBOT_MODULE = "robot-mgmt";
+const FLEET_CORE_BRAND = "fleet-core";
+
+/**
+ * Is the robot module on at one tier? Absent or empty = everything (the module
+ * gate fails open). ponytail: the server also treats a list holding no
+ * governed module at all as "everything"; that rare list reads "off" here.
+ */
+function moduleOn(list: unknown[] | null | undefined) {
+  if (!Array.isArray(list) || !list.length) return true;
+  return list.some((m) => String(m) === ROBOT_MODULE);
+}
+
+/** A role that lets client staff see robots: `*`, an empty list (= all), or any robot-mgmt right. */
+export function roleSeesRobots(role: Record<string, any> | null | undefined) {
+  const p = role?.permissions;
+  if (!Array.isArray(p)) return false;
+  return p.length === 0 || p.includes("*") || p.some((x) => typeof x === "string" && x.startsWith(`${ROBOT_MODULE}:`));
+}
+
+const names = (list: Array<Record<string, any>>, max = 3) => {
+  const n = list.map((r) => String(r?.name || "A robot"));
+  return n.length > max ? `${n.slice(0, max).join(", ")} and ${n.length - max} more` : n.join(", ");
+};
+
+/** Why one robot is not online, in words (vendor-specific hints where we know them). */
+export function offlineReason(robot: Record<string, any>, state: Record<string, any> | undefined) {
+  const name = String(robot?.name || "A robot");
+  if (!state) return `${name}: still checking.`;
+  if (state.monitorable === false) return `${name}: this brand has no live link, so its status cannot be read.`;
+  if (state.ok === false) {
+    const why = state.reason ? ` (${state.reason})` : "";
+    if (robot?.brand === "ounitech") return `${name}: the Ounitech cloud did not answer${why}. Ask Ounitech to link this robot's serial to our account.`;
+    if (robot?.brand === "padbot") return `${name}: the PadBot cloud did not answer${why}. Check the robot's key and token.`;
+    return `${name}: its cloud did not answer${why}.`;
+  }
+  return `${name}: its cloud says it is offline - switched off, charging dock unplugged or out of Wi-Fi.`;
+}
+
+const floorsOf = (map: Record<string, any> | null | undefined) =>
+  [...new Set<number>((map?.levels ?? []).map((l: any) => Number(l?.floorNo)).filter(Number.isInteger))].sort((a, b) => a - b);
+
+/** The checklist, in order, ending with "Ready for client". */
+export function robotSetupSteps(input: TSetupInput): TSetupStep[] {
+  const steps: TSetupStep[] = [];
+  const robots = input.robots;
+  const real = (robots ?? []).filter((r) => r?.brand !== "demo" && r?.demo !== true);
+
+  // 1. Robot module on for client + site.
+  if (input.orgModules === undefined || input.siteModules === undefined) {
+    steps.push({
+      key: "module",
+      title: "Robot module switched on",
+      status: "check",
+      reason: "Could not read the client's or the site's module list.",
+      button: { label: "Open client details", target: "client" },
+    });
+  } else {
+    const org = moduleOn(input.orgModules);
+    const site = moduleOn(input.siteModules);
+    steps.push({
+      key: "module",
+      title: "Robot module switched on",
+      status: org && site ? "done" : "action",
+      reason:
+        org && site
+          ? "The client and this site both have the robot module."
+          : !org
+            ? "The client's modules do not include Robot management, so their staff cannot see robots."
+            : "This site's modules do not include Robot management, so staff here cannot see robots.",
+      button: org && site ? null : { label: "Open client details", target: "client" },
+    });
+  }
+
+  // 2. Robots added.
+  const prereq = "Before adding: Ounitech must link each robot's serial to our Seven365 account; for PadBot, save the robot's points (charger, stops) in the PadBot app first.";
+  if (!robots) {
+    steps.push({ key: "robots", title: "Robots added", status: "check", reason: "Could not read this site's robots.", button: { label: "Open fleet", target: "fleet" } });
+  } else {
+    const demo = robots.length - real.length;
+    steps.push({
+      key: "robots",
+      title: "Robots added",
+      status: robots.length ? "done" : "action",
+      reason: robots.length
+        ? `${robots.length} robot${robots.length === 1 ? "" : "s"} at this site${demo ? ` (${demo} demo)` : ""}.`
+        : "No robots at this site yet.",
+      note: robots.length ? undefined : prereq,
+      button: { label: robots.length ? "+ Add another robot" : "+ Add robot", target: "add" },
+    });
+  }
+
+  // 3. Robots online.
+  if (!robots || !robots.length) {
+    steps.push({ key: "online", title: "Robots online", status: "action", reason: "Add a robot first.", button: null });
+  } else {
+    const states = input.states ?? {};
+    const unread = robots.filter((r) => !states[String(r._id)]);
+    const down = robots.filter((r) => {
+      const s = states[String(r._id)];
+      return s && !(s.ok === true && s.online !== false);
+    });
+    const vendorSide = down.filter((r) => states[String(r._id)]?.ok === false);
+    steps.push({
+      key: "online",
+      title: "Robots online",
+      status: down.length ? (vendorSide.length === down.length ? "waiting" : "action") : unread.length ? "check" : "done",
+      reason: down.length
+        ? `${robots.length - down.length} of ${robots.length} online. ${offlineReason(down[0]!, states[String(down[0]!._id)])}${down.length > 1 ? ` Also not online: ${names(down.slice(1))}.` : ""}`
+        : unread.length
+          ? `Still checking ${names(unread)}…`
+          : `All ${robots.length} robot${robots.length === 1 ? " is" : "s are"} online.`,
+      button: { label: "Open fleet", target: "fleet" },
+    });
+  }
+
+  // 4. Building map saved.
+  const map = input.savedMap;
+  if (map === undefined) {
+    steps.push({ key: "map", title: "Building map saved", status: "check", reason: "Could not read the saved building map.", button: { label: "Open building map", target: "map" } });
+  } else {
+    steps.push({
+      key: "map",
+      title: "Building map saved",
+      status: map ? "done" : "action",
+      reason: map
+        ? `Saved${map.source === FLEET_CORE_BRAND ? " (imported from HERO Fleet Core)" : ""}.`
+        : "No building map saved yet. Draw walls, doors and lift shafts in Edit map.",
+      button: { label: map ? "Open building map" : "Draw the map", target: "map" },
+    });
+  }
+
+  // 5. Floors present: one per floor the robots report.
+  const floors = floorsOf(map);
+  const reported = [
+    ...new Set<number>(
+      Object.values(input.states ?? {})
+        .filter((s) => s?.ok && s.floorKnown === true && Number.isInteger(s.floorNo))
+        .map((s) => Number(s.floorNo)),
+    ),
+  ];
+  const missing = reported.filter((f) => !floors.includes(f));
+  if (map === undefined) {
+    steps.push({ key: "floors", title: "Floors on the map", status: "check", reason: "Could not read the saved building map.", button: { label: "Open building map", target: "map" } });
+  } else if (!map) {
+    steps.push({ key: "floors", title: "Floors on the map", status: "action", reason: "Save a building map first.", button: null });
+  } else {
+    steps.push({
+      key: "floors",
+      title: "Floors on the map",
+      status: !floors.length || missing.length ? "action" : "done",
+      reason: !floors.length
+        ? "The saved map has no floors. Use Edit map → Add floor."
+        : missing.length
+          ? `Robots report ${missing.map(floorName).join(", ")}, which the map does not have. Add ${missing.length === 1 ? "it" : "them"} in Edit map → Add floor.`
+          : `${floors.map(floorName).join(", ")}${reported.length ? " - every floor the robots report." : "."}`,
+      button: { label: "Edit floors", target: "map" },
+    });
+  }
+
+  // 6. Lifts with 2+ stops.
+  const drawn = (map?.lifts ?? []) as Array<Record<string, any>>;
+  const usable = drawn.filter((l) => new Set(l?.floors ?? []).size >= 2);
+  const needLift = floors.length > 1 || reported.length > 1;
+  if (map === undefined) {
+    steps.push({ key: "lifts", title: "Lifts with 2 or more stops", status: "check", reason: "Could not read the saved building map.", button: { label: "Open building map", target: "map" } });
+  } else if (!usable.length && !needLift) {
+    steps.push({ key: "lifts", title: "Lifts with 2 or more stops", status: "done", reason: "One floor only - robots here do not need a lift.", button: null });
+  } else {
+    steps.push({
+      key: "lifts",
+      title: "Lifts with 2 or more stops",
+      status: usable.length ? "done" : "action",
+      reason: usable.length
+        ? `${usable.map((l) => `${l.name || "Lift"} (${(l.floors ?? []).length} stops)`).join(", ")}.`
+        : drawn.length
+          ? `${names(drawn)} ${drawn.length === 1 ? "has" : "have"} fewer than 2 stops. Tick each floor the lift stops at in Edit map.`
+          : "No lift drawn. Draw a lift shaft in Edit map and tick the floors it stops at.",
+      button: { label: usable.length ? "Open building map" : "Draw a lift", target: "map" },
+    });
+  }
+
+  // 7. Lift gateway connected (+ floor/door decoded).
+  if (!usable.length) {
+    steps.push({
+      key: "gateway",
+      title: "Lift gateway connected",
+      status: needLift ? "action" : "done",
+      reason: needLift ? "Draw a lift with 2 or more stops first." : "No lift, so no gateway needed.",
+      button: null,
+    });
+  } else if (input.lifts === undefined) {
+    steps.push({ key: "gateway", title: "Lift gateway connected", status: "check", reason: "Could not read the lift queue.", button: { label: "Open lift queue", target: "lifts" } });
+  } else {
+    const gws = input.lifts.filter((l) => l?.gateway).map((l) => ({ name: String(l.liftName ?? "Lift"), g: l.gateway as Record<string, any> }));
+    const up = gws.filter((x) => x.g.status === "connected");
+    const decoded = up.filter((x) => x.g.state && (x.g.state.currentFloor || x.g.state.doorState != null));
+    const other = gws.find((x) => x.g.status !== "connected");
+    steps.push({
+      key: "gateway",
+      title: "Lift gateway connected",
+      status: up.length ? "done" : gws.length ? "waiting" : "action",
+      reason: up.length
+        ? `${up.map((x) => x.name).join(", ")} connected.`
+        : other
+          ? other.g.status === "waiting"
+            ? `${other.name}: code made, waiting for the gateway box to report. Someone on site pastes the code into lift-gateway.ini and starts it.`
+            : other.g.status === "no-lift"
+              ? `${other.name}: the gateway is online but the lift board does not answer - check the RS-485 wiring.`
+              : `${other.name}: the gateway stopped reporting - check its power and network.`
+          : "No gateway yet. Open the lift queue and press Connect gateway on the lift.",
+      note: up.length
+        ? decoded.length === up.length
+          ? "Floor and door are read from the real lift."
+          : "Floor and door not decoded yet - waiting on the lift company's register list."
+        : undefined,
+      button: { label: up.length ? "Open lift queue" : "Connect gateway", target: "lifts" },
+    });
+  }
+
+  // 8. HERO Fleet Core (optional).
+  const fleetRobots = (robots ?? []).filter((r) => r?.brand === FLEET_CORE_BRAND);
+  steps.push({
+    key: "fleetcore",
+    title: "HERO Fleet Core linked",
+    optional: true,
+    status: fleetRobots.length || map?.source === FLEET_CORE_BRAND ? "done" : input.fleetCore === undefined ? "check" : "waiting",
+    reason: fleetRobots.length
+      ? `${fleetRobots.length} robot${fleetRobots.length === 1 ? "" : "s"} run through HERO Fleet Core.`
+      : map?.source === FLEET_CORE_BRAND
+        ? "The building map came from HERO Fleet Core."
+        : input.fleetCore === undefined
+          ? "Could not check HERO Fleet Core."
+          : input.fleetCore === true
+            ? "Optional. Linking this site's robots to HERO Fleet Core still needs a Seven365 engineer step today."
+            : input.fleetCore === 404
+              ? "Optional. HERO Fleet Core is not switched on on this server yet - a Seven365 engineer sets it up."
+              : "Optional. HERO Fleet Core is for Seven365 Super Admin only.",
+    button: input.fleetCore === true ? { label: "Open HERO Fleet Core", target: "fleetcore" } : null,
+  });
+
+  // 9. Client roles with robot rights.
+  if (!input.roles) {
+    steps.push({ key: "access", title: "Client staff can see robots", status: "check", reason: "Could not read the client's roles.", button: { label: "Open client details", target: "client" } });
+  } else {
+    const seeing = input.roles.filter(roleSeesRobots);
+    const named = seeing.filter((r) => Array.isArray(r.permissions) && r.permissions.length && !r.permissions.includes("*"));
+    steps.push({
+      key: "access",
+      title: "Client staff can see robots",
+      status: named.length ? "done" : "action",
+      reason: named.length
+        ? `${names(named)} ${named.length === 1 ? "has" : "have"} robot rights.`
+        : seeing.length
+          ? "Only full-access roles (such as the owner) can see robots. Give staff roles the Robot management rights."
+          : "No role at this client has robot rights yet. Give staff roles the Robot management rights.",
+      button: named.length ? null : { label: "Open client details", target: "client" },
+    });
+  }
+
+  // 10. Ready for client.
+  const required = steps.filter((s) => !s.optional);
+  const done = required.filter((s) => s.status === "done").length;
+  const next = required.find((s) => s.status !== "done");
+  steps.push({
+    key: "ready",
+    title: "Ready for client",
+    status: next ? (required.every((s) => s.status === "done" || s.status === "waiting") ? "waiting" : "action") : "done",
+    reason: next ? `${done} of ${required.length} steps done. Next: ${next.title}.` : "Every step is done - the client can use their robots.",
+    button: null,
+  });
+  return steps;
+}
+
+/** "Setup 6/9" for a chip: required steps done of required steps (the final "Ready" excluded). */
+export function setupProgress(steps: TSetupStep[]) {
+  const required = steps.filter((s) => !s.optional && s.key !== "ready");
+  return { done: required.filter((s) => s.status === "done").length, total: required.length };
+}