@fleetbase/fleetops-engine 0.6.48 → 0.6.50

package/addon/components/widget/kpi-tile.js

@@ -0,0 +1,168 @@
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { action } from '@ember/object';
+import { inject as service } from '@ember/service';
+import { task } from 'ember-concurrency';
+
+/**
+ * <Widget::KpiTile @slug="earnings" @title="..." @format="money" @showDelta={{true}}
+ *                  @showSparkline={{true}} @deltaInverse={{false}} @period="30d" />
+ *
+ * Renders a single KPI tile backed by `/fleet-ops/metrics/{slug}`. Hosts the
+ * format-specific value rendering, the optional period-over-period delta
+ * badge (with `deltaInverse` to flip semantics for inverse-good metrics like
+ * open_issues), and the optional sparkline line chart.
+ */
+export default class WidgetKpiTileComponent extends Component {
+    @service fetch;
+    @tracked data = null;
+    @tracked error = null;
+
+    get period() {
+        return this.args.period ?? '30d';
+    }
+
+    get showDelta() {
+        return this.args.showDelta ?? true;
+    }
+
+    get showSparkline() {
+        return this.args.showSparkline ?? true;
+    }
+
+    get deltaInverse() {
+        return this.args.deltaInverse ?? false;
+    }
+
+    get format() {
+        return this.args.format ?? this.data?.format ?? 'count';
+    }
+
+    get currency() {
+        return this.data?.currency ?? 'USD';
+    }
+
+    get deltaPct() {
+        return this.data?.delta_pct;
+    }
+
+    get hasDelta() {
+        return this.showDelta && typeof this.deltaPct === 'number';
+    }
+
+    get deltaStatus() {
+        const pct = this.deltaPct;
+        if (typeof pct !== 'number' || pct === 0) return 'info';
+        const positive = pct > 0;
+        const isGood = this.deltaInverse ? !positive : positive;
+        return isGood ? 'success' : 'danger';
+    }
+
+    get deltaText() {
+        const pct = this.deltaPct;
+        const sign = pct > 0 ? '+' : '';
+        return `${sign}${pct}%`;
+    }
+
+    /** Tints the card subtly based on trend direction so the dashboard pops. */
+    get cardAccentClass() {
+        const pct = this.deltaPct;
+        if (typeof pct !== 'number' || pct === 0) {
+            return 'kpi-accent-neutral';
+        }
+        const positive = pct > 0;
+        const isGood = this.deltaInverse ? !positive : positive;
+        return isGood ? 'kpi-accent-good' : 'kpi-accent-bad';
+    }
+
+    get valueTextClass() {
+        const pct = this.deltaPct;
+        if (typeof pct !== 'number' || pct === 0) {
+            return 'text-black dark:text-gray-100';
+        }
+        const positive = pct > 0;
+        const isGood = this.deltaInverse ? !positive : positive;
+        return isGood ? 'text-emerald-600 dark:text-emerald-400' : 'text-rose-600 dark:text-rose-400';
+    }
+
+    /** Neon palette per delta direction. Drives line + fill + value highlight. */
+    get accentColors() {
+        // Bright neon-ish trio that pops on the dark theme without being garish in light.
+        const good = { line: '#22c55e', fill: 'rgba(34, 197, 94, 0.22)', glow: 'rgba(34, 197, 94, 0.35)' };
+        const bad = { line: '#ef4444', fill: 'rgba(239, 68, 68, 0.22)', glow: 'rgba(239, 68, 68, 0.35)' };
+        const neutral = { line: '#3485e2', fill: 'rgba(52, 133, 226, 0.18)', glow: 'rgba(52, 133, 226, 0.30)' };
+
+        const pct = this.deltaPct;
+        if (typeof pct !== 'number' || pct === 0) return neutral;
+        const positive = pct > 0;
+        const isGood = this.deltaInverse ? !positive : positive;
+        return isGood ? good : bad;
+    }
+
+    get sparklineDatasets() {
+        const points = this.data?.sparkline?.data;
+        if (!points || points.length === 0) return null;
+
+        const { line, fill } = this.accentColors;
+
+        return [
+            {
+                data: points,
+                borderColor: line,
+                backgroundColor: fill,
+                pointRadius: 0,
+                borderWidth: 1.75,
+                tension: 0.4,
+                // Anchor the area fill to the chart's y=0 axis so the sparkline
+                // visually sits at the BOTTOM of the card regardless of the data range.
+                fill: 'origin',
+            },
+        ];
+    }
+
+    get sparklineLabels() {
+        return this.data?.sparkline?.labels ?? [];
+    }
+
+    get sparklineOptions() {
+        return {
+            responsive: true,
+            maintainAspectRatio: false,
+            animation: { duration: 600, easing: 'easeOutQuart' },
+            plugins: {
+                legend: { display: false },
+                tooltip: { enabled: false },
+            },
+            scales: {
+                x: { display: false },
+                // Lock min to 0 so flat-zero data sits flush along the bottom edge.
+                // suggestedMin/Max keep the line off the very top/bottom for non-zero data.
+                y: { display: false, min: 0, beginAtZero: true, grace: '5%' },
+            },
+            elements: { line: { borderJoinStyle: 'round' } },
+        };
+    }
+
+    constructor() {
+        super(...arguments);
+        this.load.perform();
+    }
+
+    @task *load() {
+        try {
+            this.data = yield this.fetch.get(`fleet-ops/metrics/${this.args.slug}`, {
+                period: this.period,
+                sparkline: this.showSparkline,
+                compare: this.showDelta,
+            });
+            this.error = null;
+        } catch (e) {
+            this.error = e?.message ?? 'Failed to load metric';
+        }
+    }
+
+    @action
+    refresh() {
+        this.load.perform();
+    }
+}

package/addon/components/widget/live-fleet.hbs

@@ -0,0 +1,122 @@
+<div class="fleet-ops-widget fleet-ops-live-fleet flex flex-col h-full {{@class}}" ...attributes>
+    <div class="flex items-center justify-between px-3 py-1.5 border dark:border-gray-700 border-gray-200 dark:bg-gray-800 bg-gray-50 rounded-t-md shadow-sm">
+        <span class="text-xs font-bold text-black dark:text-gray-100">{{t "widget.live-fleet.title"}}</span>
+        <div class="flex items-center gap-3 text-[10px] text-gray-500 dark:text-gray-400">
+            <span class="flex items-center" title="Drivers"><FaIcon @icon="id-card" class="mr-1" />{{this.drivers.length}}</span>
+            <span class="flex items-center" title="Vehicles"><FaIcon @icon="truck" class="mr-1" />{{this.vehicles.length}}</span>
+            <span class="flex items-center" title="Active orders"><FaIcon @icon="bolt" class="mr-1" />{{this.activeOrderCount}}</span>
+            <button type="button" class="text-gray-400 hover:text-gray-600 dark:hover:text-gray-200" {{on "click" this.refresh}}>
+                <FaIcon @icon="rotate" class={{if this.load.isRunning "animate-spin"}} />
+            </button>
+        </div>
+    </div>
+
+    <div class="flex-1 relative border border-t-0 dark:border-gray-700 border-gray-200 rounded-b-md overflow-hidden min-h-0 bg-gray-100 dark:bg-gray-900">
+        <div class="fleetbase-leaflet-map-container w-full h-full" {{set-container-dimensions}}>
+            <LeafletMap
+                class="w-full h-full"
+                @lat={{get this.center 0}}
+                @lng={{get this.center 1}}
+                @zoom={{this.zoom}}
+                @zoomControl={{true}}
+                @onLoad={{this.onMapLoad}}
+                {{set-container-dimensions}}
+                as |layers|
+            >
+                <layers.tile @url={{this.tileUrl}} />
+
+                {{#if this.load.isIdle}}
+                    {{! Drivers — fleetops' rotating tracking-marker matches the operational
+                         live-map's look and animates on heading changes. }}
+                    {{#each this.drivers as |driver|}}
+                        <layers.tracking-marker
+                            @id={{driver.uuid}}
+                            @publicId={{driver.public_id}}
+                            @location={{array driver.lat driver.lng}}
+                            @rotationAngle={{driver.heading}}
+                            @icon={{icon iconUrl=(or driver.vehicle_avatar driver.avatar_url "/engines-dist/images/map-marker.png") iconSize=(array 28 28) iconAnchor=(array 14 28)}}
+                            @draggable={{false}}
+                            as |marker|
+                        >
+                            <marker.popup @maxWidth="240" @minWidth="180">
+                                <div class="flex flex-row gap-2">
+                                    <div class="w-9 h-9 flex-shrink-0">
+                                        <img src={{or driver.avatar_url driver.vehicle_avatar}} alt={{driver.name}} class="rounded-md w-9 h-9 object-cover shadow-sm" />
+                                    </div>
+                                    <div class="flex-1 min-w-0">
+                                        <div class="text-xs font-semibold truncate">{{or driver.name "Driver"}}</div>
+                                        <div class="text-[11px]">
+                                            {{#if driver.current_order_uuid}}
+                                                <span class="text-blue-500"><FaIcon @icon="bolt" class="mr-1" />On order</span>
+                                            {{else if driver.online}}
+                                                <span class="text-green-500"><FaIcon @icon="circle" @size="2xs" class="mr-1" />Online</span>
+                                            {{else}}
+                                                <span class="text-gray-400"><FaIcon @icon="circle" @size="2xs" class="mr-1" />Offline</span>
+                                            {{/if}}
+                                        </div>
+                                        <div class="text-[10px] text-gray-400 mt-0.5 truncate">{{driver.lat}}, {{driver.lng}}</div>
+                                    </div>
+                                </div>
+                            </marker.popup>
+                            <marker.tooltip @permanent={{false}} @sticky={{true}} @direction="top">
+                                <div class="text-[11px] font-semibold">{{or driver.name "Driver"}}</div>
+                            </marker.tooltip>
+                        </layers.tracking-marker>
+                    {{/each}}
+
+                    {{! Vehicles — also rendered via tracking-marker so the heading
+                         animation applies on telematics-driven position updates. }}
+                    {{#each this.vehicles as |vehicle|}}
+                        <layers.tracking-marker
+                            @id={{vehicle.uuid}}
+                            @publicId={{vehicle.public_id}}
+                            @location={{array vehicle.lat vehicle.lng}}
+                            @rotationAngle={{vehicle.heading}}
+                            @icon={{icon iconUrl=(or vehicle.avatar_url vehicle.photo_url "/engines-dist/images/map-marker.png") iconSize=(array 28 28) iconAnchor=(array 14 28)}}
+                            @draggable={{false}}
+                            as |marker|
+                        >
+                            <marker.popup @maxWidth="240" @minWidth="180">
+                                <div class="flex flex-row gap-2">
+                                    <div class="w-9 h-9 flex-shrink-0">
+                                        <img src={{or vehicle.photo_url vehicle.avatar_url}} alt={{vehicle.name}} class="rounded-md w-9 h-9 object-cover shadow-sm" />
+                                    </div>
+                                    <div class="flex-1 min-w-0">
+                                        <div class="text-xs font-semibold truncate">{{or vehicle.name "Vehicle"}}</div>
+                                        {{#if vehicle.plate_number}}
+                                            <div class="text-[10px] text-gray-500 truncate">{{vehicle.plate_number}}</div>
+                                        {{/if}}
+                                        {{#if vehicle.driver_name}}
+                                            <div class="text-[11px] text-gray-600 dark:text-gray-300 truncate">
+                                                <FaIcon @icon="id-card" class="mr-1 text-gray-400" />{{vehicle.driver_name}}
+                                            </div>
+                                        {{/if}}
+                                        <div class="text-[10px] text-gray-400 mt-0.5 truncate">{{vehicle.lat}}, {{vehicle.lng}}</div>
+                                    </div>
+                                </div>
+                            </marker.popup>
+                            <marker.tooltip @permanent={{false}} @sticky={{true}} @direction="top">
+                                <div class="text-[11px] font-semibold">{{or vehicle.name "Vehicle"}}</div>
+                            </marker.tooltip>
+                        </layers.tracking-marker>
+                    {{/each}}
+                {{/if}}
+            </LeafletMap>
+        </div>
+
+        {{#if this.load.isRunning}}
+            <div class="absolute inset-0 flex items-center justify-center bg-white/70 dark:bg-gray-900/70 z-[400]">
+                <Spinner />
+            </div>
+        {{else if this.error}}
+            <div class="absolute inset-0 flex items-center justify-center text-xs text-red-500 z-[400]">{{this.error}}</div>
+        {{else if (not this.totalMarkerCount)}}
+            <div class="absolute inset-0 flex items-center justify-center pointer-events-none">
+                <div class="text-center text-[11px] text-gray-500 dark:text-gray-400 bg-white/90 dark:bg-gray-900/90 rounded-md px-3 py-2 shadow-sm">
+                    <FaIcon @icon="map-location-dot" class="text-xl block mb-1 opacity-50" />
+                    No active drivers or vehicles to display.
+                </div>
+            </div>
+        {{/if}}
+    </div>
+</div>

package/addon/components/widget/live-fleet.js

@@ -0,0 +1,365 @@
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { action } from '@ember/object';
+import { inject as service } from '@ember/service';
+import { getOwner } from '@ember/application';
+import { debug } from '@ember/debug';
+import { task } from 'ember-concurrency';
+import { renderCompleted, waitForInsertedAndSized } from '@fleetbase/ember-ui/utils/dom';
+import LeafletTrackingMarkerComponent from '../leaflet-tracking-marker';
+
+const DEFAULT_CENTER = [1.31, 103.85];
+const DEFAULT_ZOOM = 11;
+// Match the rest of fleetops' Leaflet maps (light Carto basemap), which keeps the
+// dashboard styling consistent with the operational live map. Falls back gracefully
+// in dark mode via the next-leaflet-container-map theming.
+const TILE_URL = 'https://{s}.basemaps.cartocdn.com/light_all/{z}/{x}/{y}.png';
+const TILE_URL_DARK = 'https://{s}.basemaps.cartocdn.com/dark_all/{z}/{x}/{y}.png';
+const TILE_ATTRIBUTION = '© OpenStreetMap contributors © CARTO';
+const RECONCILE_INTERVAL_MS = 5 * 60_000;
+
+/**
+ * Real-time fleet map. Initial GET seeds driver positions; the widget then
+ * subscribes to `company.{uuid}` and applies driver.location_changed deltas
+ * directly to the markers list. Full reconciliation every 5 minutes.
+ */
+export default class WidgetLiveFleetComponent extends Component {
+    static widgetId = 'fleet-ops-live-fleet-widget';
+
+    @service fetch;
+    @service socket;
+    @service currentUser;
+
+    @tracked data = null;
+    @tracked error = null;
+
+    tileAttribution = TILE_ATTRIBUTION;
+
+    get tileUrl() {
+        const isDark = typeof document !== 'undefined' && document.documentElement?.dataset?.theme === 'dark';
+        return isDark ? TILE_URL_DARK : TILE_URL;
+    }
+
+    socketChannel = null;
+    socketActive = false;
+    reconcileTimer = null;
+    /** Watches the map container for size changes (gridstack settle, sibling widgets
+     *  loading, theme/font swaps) and re-runs Leaflet's invalidateSize so the tile
+     *  layer always fills the actual painted bounds, not the bounds Leaflet measured
+     *  at first paint. */
+    #resizeObserver = null;
+    #resizeRaf = 0;
+
+    /**
+     * Deferred that resolves once <LeafletMap @onLoad> fires. Mirrors the
+     * leaflet-map-manager service's #mapSetPromise so we can synchronously
+     * wait for the map instance from anywhere in this component.
+     */
+    #map = null;
+    #mapSetPromise = null;
+    #resolveMapSet = null;
+
+    constructor() {
+        super(...arguments);
+        // Important: register tracking-marker against THIS owner's ember-leaflet
+        // service before any <LeafletMap> in our template is constructed.
+        //
+        // The fleetops `register-leaflet-tracking-marker` instance-initializer
+        // registers `tracking-marker` on the fleetops ENGINE's ember-leaflet
+        // service. When this widget is rendered from the host dashboard route
+        // (e.g. console.home), LazyEngineComponent resolves the component class
+        // from the engine but renders it under the HOST owner — so the
+        // <LeafletMap> inside this template injects the host's ember-leaflet
+        // service, which never received the registration. The yield for
+        // `layers.tracking-marker` silently resolves to undefined and no marker
+        // ever paints. Doing the registration on whatever owner this widget
+        // happens to live under closes that gap.
+        this.#ensureTrackingMarkerRegistered();
+        this.#patchLeafletDrawInitHook();
+        this.#resetMapDeferred();
+        this.load.perform();
+        this.subscribe();
+        this.reconcileTimer = setInterval(() => this.load.perform(), RECONCILE_INTERVAL_MS);
+    }
+
+    /**
+     * leaflet-draw's `Edit.Marker.js` registers an init hook on `L.Marker` that
+     * does `if (L.Edit.Marker) { this.editing = new L.Edit.Marker(this); … }`.
+     * The check is unguarded — it reads `.Marker` off `L.Edit` directly. When
+     * leaflet-draw is loaded but the dashboard route's window.L doesn't carry
+     * the `Edit` namespace (load-order race in the host route, or two leaflet
+     * copies in the runtime caused by engine/host module duplication), every
+     * marker creation throws a TypeError and our tracking-marker churn during
+     * dashboard switching repeats it thousands of times.
+     *
+     * Stubbing `L.Edit` to `{}` keeps the leaflet-draw hook's check (`if
+     * (L.Edit.Marker)`) safely falsy when the namespace is missing, so it
+     * becomes a no-op. If leaflet-draw HAS fully loaded, `L.Edit.Marker` is
+     * already set and the `||` keeps it.
+     *
+     * We don't need draw/editing handlers on dashboard markers anyway — this
+     * widget is read-only.
+     */
+    #patchLeafletDrawInitHook() {
+        const L = typeof window !== 'undefined' ? (window.L ?? window.leaflet) : null;
+        if (L && !L.Edit) {
+            L.Edit = {};
+        }
+        if (L && !L.Marker) {
+            L.Marker = {};
+        }
+    }
+
+    /**
+     * Idempotent: registers the fleetops `tracking-marker` component on the
+     * `ember-leaflet` service belonging to this widget's owner if it isn't
+     * already there. Safe to call multiple times across widget instances
+     * because we guard on `components.find(...)` before calling
+     * `registerComponent` (which throws on duplicate registration).
+     */
+    #ensureTrackingMarkerRegistered() {
+        const owner = getOwner(this);
+        const emberLeaflet = owner?.lookup?.('service:ember-leaflet');
+        if (!emberLeaflet) return;
+
+        const already = emberLeaflet.components?.find((c) => c.name === 'leaflet-tracking-marker' || c.as === 'tracking-marker');
+        if (already) return;
+
+        emberLeaflet.registerComponent('leaflet-tracking-marker', {
+            as: 'tracking-marker',
+            component: LeafletTrackingMarkerComponent,
+        });
+    }
+
+    willDestroy() {
+        super.willDestroy(...arguments);
+        this.unsubscribe();
+        if (this.reconcileTimer) clearInterval(this.reconcileTimer);
+        if (this.#resizeRaf) cancelAnimationFrame(this.#resizeRaf);
+        this.#resizeObserver?.disconnect();
+        this.#resizeObserver = null;
+    }
+
+    get drivers() {
+        return this.data?.drivers ?? [];
+    }
+
+    get vehicles() {
+        return this.data?.vehicles ?? [];
+    }
+
+    get activeOrderCount() {
+        return this.data?.active_orders?.length ?? 0;
+    }
+
+    /** Both drivers and vehicles are renderable map subjects — total chip count. */
+    get totalMarkerCount() {
+        return this.drivers.length + this.vehicles.length;
+    }
+
+    /** Center on the first available marker (driver, then vehicle), else default. */
+    get center() {
+        const first = this.drivers[0] ?? this.vehicles[0];
+        if (first?.lat && first?.lng) return [first.lat, first.lng];
+        return DEFAULT_CENTER;
+    }
+
+    get zoom() {
+        return DEFAULT_ZOOM;
+    }
+
+    statusColor(status) {
+        switch (status) {
+            case 'in_progress':
+            case 'enroute':
+            case 'dispatched':
+                return '#3485e2';
+            case 'completed':
+                return '#22c55e';
+            default:
+                return '#9ca3af';
+        }
+    }
+
+    @task *load() {
+        try {
+            // Wait for the LeafletMap to mount, finish loading, and have a non-zero
+            // container before we add markers. Without this, markers added to a
+            // not-yet-sized map silently no-op (the data arrives, count chip ticks
+            // up, but nothing paints).
+            yield this.ensureInteractive();
+            this.data = yield this.fetch.get('fleet-ops/analytics/live-fleet');
+            this.error = null;
+        } catch (e) {
+            this.error = e?.message ?? 'Failed to load live fleet';
+        }
+    }
+
+    /**
+     * Mirrors LeafletMapManagerService#ensureInteractive: waits for the
+     * Leaflet instance to be available + loaded, for the host DOM container
+     * to be inserted and sized, then forces a re-measure. Returns the map.
+     */
+    async ensureInteractive({ timeoutMs = 8000 } = {}) {
+        const map = await this.#whenMapLoaded({ timeoutMs });
+
+        const getContainer = () => map?.getContainer?.() || map?._container || null;
+
+        await renderCompleted();
+        await waitForInsertedAndSized(getContainer, { timeoutMs });
+
+        map.invalidateSize(false);
+
+        // Subsequent size changes (gridstack settling, sibling widgets loading,
+        // theme/font swaps, widget resize handles) need invalidateSize() again
+        // or the tile layer ends up clipped to the cached bounding box.
+        this.#attachResizeObserver(map, getContainer());
+
+        return map;
+    }
+
+    /**
+     * Watch the Leaflet container with a ResizeObserver and re-run invalidateSize
+     * on any dimension change. rAF-debounced so a stream of resize callbacks during
+     * a gridstack drag/animation collapses into one Leaflet recompute per frame.
+     */
+    #attachResizeObserver(map, container) {
+        if (!container || typeof ResizeObserver === 'undefined') return;
+        this.#resizeObserver?.disconnect();
+
+        this.#resizeObserver = new ResizeObserver(() => {
+            if (this.#resizeRaf) cancelAnimationFrame(this.#resizeRaf);
+            this.#resizeRaf = requestAnimationFrame(() => {
+                this.#resizeRaf = 0;
+                try {
+                    map.invalidateSize(false);
+                } catch (e) {
+                    debug(`[live-fleet] invalidateSize failed: ${e?.message ?? e}`);
+                }
+            });
+        });
+        this.#resizeObserver.observe(container);
+    }
+
+    /** Hook fired by <LeafletMap @onLoad>. Stores the instance + resolves the deferred. */
+    @action onMapLoad({ target: map }) {
+        this.#map = map;
+        this.#resolveMapSet?.(map);
+    }
+
+    /** ──────────────────────────────────────────────
+     *  Internal map-readiness deferred (same shape as
+     *  leaflet-map-manager.js).
+     *  ────────────────────────────────────────────── */
+
+    #resetMapDeferred() {
+        this.#mapSetPromise = new Promise((resolve) => {
+            this.#resolveMapSet = resolve;
+        });
+    }
+
+    async #waitForMap({ timeoutMs = 8000 } = {}) {
+        if (this.#map) return this.#map;
+
+        let to;
+        try {
+            return await Promise.race([
+                this.#mapSetPromise,
+                new Promise((_, rej) => {
+                    if (timeoutMs != null) {
+                        to = setTimeout(() => rej(new Error('waitForMap timed out')), timeoutMs);
+                    }
+                }),
+            ]);
+        } finally {
+            if (to) clearTimeout(to);
+        }
+    }
+
+    async #whenMapLoaded({ timeoutMs } = {}) {
+        const map = await this.#waitForMap({ timeoutMs });
+        if (map._loaded) return map;
+
+        return new Promise((resolve, reject) => {
+            let t;
+            const onLoad = () => {
+                clearTimeout(t);
+                map.off('load', onLoad);
+                resolve(map);
+            };
+            map.on('load', onLoad);
+            if (timeoutMs != null) {
+                t = setTimeout(() => {
+                    map.off('load', onLoad);
+                    reject(new Error('whenMapLoaded timed out'));
+                }, timeoutMs);
+            }
+        });
+    }
+
+    @action
+    refresh() {
+        this.load.perform();
+    }
+
+    async subscribe() {
+        const companyId = this.currentUser?.companyId;
+        if (!companyId) return;
+
+        try {
+            const sc = this.socket.instance();
+            const channel = sc.subscribe(`company.${companyId}`);
+            this.socketChannel = channel;
+            this.socketActive = true;
+
+            if (channel.state !== 'subscribed') {
+                await channel.subscribe();
+            }
+
+            for await (const msg of channel) {
+                if (!this.socketActive) break;
+                this.applyEvent(msg);
+            }
+        } catch (e) {
+            debug(`[live-fleet] socket error: ${e?.message ?? e}`);
+        }
+    }
+
+    async unsubscribe() {
+        this.socketActive = false;
+        try {
+            await this.socketChannel?.unsubscribe();
+        } catch (e) {
+            debug(`[live-fleet] unsubscribe error: ${e?.message ?? e}`);
+        }
+        this.socketChannel = null;
+    }
+
+    applyEvent(msg) {
+        if (!this.data || !msg) return;
+
+        switch (msg.event) {
+            case 'driver.location_changed':
+                this.applyLocationDelta(msg.data);
+                break;
+            case 'driver.online':
+            case 'driver.offline':
+                // Presence flips are reconciled on the next 5-min refetch.
+                break;
+            default:
+                return;
+        }
+    }
+
+    applyLocationDelta(data) {
+        if (!data?.uuid && !data?.driver_uuid) return;
+        const targetUuid = data.uuid ?? data.driver_uuid;
+        const lat = data.lat ?? data.latitude;
+        const lng = data.lng ?? data.longitude;
+        if (typeof lat !== 'number' || typeof lng !== 'number') return;
+
+        const drivers = (this.data.drivers ?? []).map((d) => (d.uuid === targetUuid ? { ...d, lat, lng, heading: data.heading ?? d.heading } : d));
+
+        this.data = { ...this.data, drivers };
+    }
+}