feat: render particle clouds for selected tags

assets/konva/app.js

@@ -582,14 +582,17 @@ window.companion = {
 
   updateCloud(particles) {
     particlesLayer.destroyChildren();
-    particles.forEach(({ x, y, weight }) => {
+    if (particles.length > 0) {
-      particlesLayer.add(new Konva.Circle({
+      const maxW = Math.max(...particles.map(p => p.weight));
-        x: x * PPM, y: y * PPM,
+      particles.forEach(({ x, y, weight }) => {
-        radius: 2,
+        particlesLayer.add(new Konva.Circle({
-        fill: `rgba(255,152,0,${Math.max(0, Math.min(1, weight))})`,
+          x: x * PPM, y: y * PPM,
-        listening: false,
+          radius: 2,
-      }));
+          fill: `rgba(255,152,0,${maxW > 0 ? weight / maxW : 0})`,
-    });
+          listening: false,
+        }));
+      });
+    }
     particlesLayer.batchDraw();
   },
 

lib/data/repositories/phoenix_tag_repository.dart

@@ -53,13 +53,21 @@ class PhoenixTagRepository implements TagRepository {
       });
 
   @override
-  Stream<List<Particle>> watchParticleCloud() =>
+  Stream<ParticleSnapshot> watchParticleCloud(String tagId) =>
-      realtime.channel('localiserd').map((payload) {
+      realtime
-        final list = payload['particles'] as List<dynamic>? ?? [];
+          .channelMessages('particles:$tagId')
-        return list
+          .where((m) => m.event == 'particles_updated')
-            .map((j) => Particle.fromJson(j as Map<String, dynamic>))
+          .map((m) {
-            .toList();
+            final est = m.payload['estimate'] as Map<String, dynamic>;
-      });
+            final list = m.payload['particles'] as List<dynamic>;
+            return ParticleSnapshot(
+              tagId: tagId,
+              estimate: Estimate.fromJson(est),
+              particles: list
+                  .map((j) => Particle.fromJson(j as Map<String, dynamic>))
+                  .toList(),
+            );
+          });
 
   @override
   Stream<Map<int, List<String>>> watchRoomOccupancy() async* {

lib/data/repositories/tag_repository.dart

@@ -11,8 +11,8 @@ abstract class TagRepository {
   /// Live stream of all tag positions, pushed by localiserd over Phoenix channel.
   Stream<List<TagPosition>> watchPositions();
 
-  /// Live stream of particle filter cloud snapshots.
+  /// Live stream of particle filter cloud snapshots for [tagId].
-  Stream<List<Particle>> watchParticleCloud();
+  Stream<ParticleSnapshot> watchParticleCloud(String tagId);
 
   /// Room occupancy delta stream.
   /// room_id -> list of tag_id strings currently in that room.

lib/data/sources/ble/tag_scanner.dart

@@ -50,8 +50,7 @@ class TagScanResult {
 class TagScanner {
   static final _eddystoneGuid = Guid('feaa');
 
-  // Continuously scans for iBeacon / AltBeacon / Eddystone-UID, restarting
+  // Continuously scans for iBeacon / AltBeacon / Eddystone-UID
-  // each time the scan window closes, until the returned stream is cancelled.
   Stream<TagScanResult> scan() {
     StreamSubscription<List<ScanResult>>? resultsSub;
     final seen = <String, int>{}; // tagId -> last rssi, for dedup

lib/domain/models/particle.dart

@@ -12,6 +12,32 @@ class Particle {
   factory Particle.fromJson(Map<String, dynamic> json) => Particle(
         x: (json['x'] as num).toDouble(),
         y: (json['y'] as num).toDouble(),
-        weight: (json['weight'] as num).toDouble(),
+        weight: (json['w'] as num).toDouble(),
       );
 }
+
+/// Position estimate from the particle filter (weighted mean).
+class Estimate {
+  const Estimate({required this.x, required this.y});
+
+  final double x;
+  final double y;
+
+  factory Estimate.fromJson(Map<String, dynamic> json) => Estimate(
+        x: (json['x'] as num).toDouble(),
+        y: (json['y'] as num).toDouble(),
+      );
+}
+
+/// A single `particles_updated` push from the server: estimate + raw cloud.
+class ParticleSnapshot {
+  const ParticleSnapshot({
+    required this.tagId,
+    required this.estimate,
+    required this.particles,
+  });
+
+  final String tagId;
+  final Estimate estimate;
+  final List<Particle> particles;
+}

lib/features/floorplan/floor_plan_screen.dart

@@ -4,6 +4,7 @@ import 'package:go_router/go_router.dart';
 
 import '../../domain/models/floor_plan_mode.dart';
 import '../../domain/models/sensor.dart';
+import '../../domain/models/tag.dart';
 import '../../providers.dart';
 import '../ble_provision/ble_provision_sheet.dart';
 import '../sensors/sensor_detail_sheet.dart';
@@ -87,6 +88,7 @@ class _FloorPlanScreenState extends ConsumerState<FloorPlanScreen> {
     final roomsAsync = ref.watch(roomsProvider);
     final sensorsAsync = ref.watch(sensorsProvider);
     final placingSensor = ref.watch(sensorPlacementProvider);
+    final trackedTag = ref.watch(trackedTagProvider);
 
     ref.listen(roomsProvider, (_, next) {
       next.whenData((r) => _editorKey.currentState?.loadFloorPlan(r));
@@ -112,8 +114,14 @@ class _FloorPlanScreenState extends ConsumerState<FloorPlanScreen> {
     ref.listen(tagPositionsProvider, (_, next) {
       next.whenData((t) => _editorKey.currentState?.updateTags(t));
     });
-    ref.listen(particleCloudProvider, (_, next) {
+    if (trackedTag != null) {
-      next.whenData((p) => _editorKey.currentState?.updateParticleCloud(p));
+      ref.listen(particleSnapshotProvider(trackedTag.tagId), (_, next) {
+        next.whenData(
+            (snap) => _editorKey.currentState?.updateParticleCloud(snap.particles));
+      });
+    }
+    ref.listen(trackedTagProvider, (prev, next) {
+      if (next == null) _editorKey.currentState?.updateParticleCloud([]);
     });
     ref.listen(sensorPlacementProvider, (prev, next) => _applyPlacementState());
 
@@ -244,6 +252,19 @@ class _FloorPlanScreenState extends ConsumerState<FloorPlanScreen> {
                         ],
                       ),
                     ),
+                  // Tracking card overlay
+                  if (trackedTag != null && placingSensor == null)
+                    Positioned(
+                      top: 16,
+                      left: 16,
+                      right: 16,
+                      child: _TrackingCard(
+                        tag: trackedTag,
+                        onStop: () {
+                          ref.read(trackedTagProvider.notifier).state = null;
+                        },
+                      ),
+                    ),
                   // Placement mode overlay
                   if (placingSensor != null) ...[
                     const Center(child: _PlacementDot()),
@@ -390,6 +411,42 @@ class _PlacementDot extends StatelessWidget {
   }
 }
 
+class _TrackingCard extends StatelessWidget {
+  const _TrackingCard({required this.tag, required this.onStop});
+
+  final Tag tag;
+  final VoidCallback onStop;
+
+  @override
+  Widget build(BuildContext context) {
+    final theme = Theme.of(context);
+    return Card(
+      elevation: 4,
+      child: Padding(
+        padding: const EdgeInsets.symmetric(horizontal: 12, vertical: 10),
+        child: Row(
+          children: [
+            const Icon(Icons.radar),
+            const SizedBox(width: 10),
+            Expanded(
+              child: Column(
+                crossAxisAlignment: CrossAxisAlignment.start,
+                mainAxisSize: MainAxisSize.min,
+                children: [
+                  Text(tag.name, style: theme.textTheme.labelLarge),
+                  Text('Tracking particle cloud',
+                      style: theme.textTheme.bodySmall),
+                ],
+              ),
+            ),
+            TextButton(onPressed: onStop, child: const Text('Stop')),
+          ],
+        ),
+      ),
+    );
+  }
+}
+
 class _PlacementCard extends StatelessWidget {
   const _PlacementCard({
     required this.sensor,

lib/features/floorplan/widgets/floor_plan_editor.dart

@@ -181,6 +181,7 @@ class FloorPlanEditorState extends State<FloorPlanEditor> {
       final payload = jsonEncode(
         particles.map((p) => {'x': p.x, 'y': p.y, 'weight': p.weight}).toList(),
       );
+
       await _controller.runJavaScript('window.companion.updateCloud($payload)');
     });
   }

lib/features/tags/tag_detail_sheet.dart

@@ -1,5 +1,6 @@
 import 'package:flutter/material.dart';
 import 'package:flutter_riverpod/flutter_riverpod.dart';
+import 'package:go_router/go_router.dart';
 
 import '../../domain/models/tag.dart';
 import '../../providers.dart';
@@ -36,9 +37,7 @@ class _TagDetailSheetState extends ConsumerState<TagDetailSheet> {
     final name = _nameCtrl.text.trim();
     setState(() => _editing = false);
     if (name.isEmpty || name == tag.name) return;
-    await ref
+    await ref.read(tagRepositoryProvider).updateTag(tag.id, name: name);
-        .read(tagRepositoryProvider)
-        .updateTag(tag.id, name: name);
     ref.invalidate(tagProvider(tag.id));
     ref.invalidate(tagsProvider);
   }
@@ -48,7 +47,7 @@ class _TagDetailSheetState extends ConsumerState<TagDetailSheet> {
       context: context,
       builder: (ctx) => AlertDialog(
         title: const Text('Remove tag?'),
-        content: const Text('This will unenrol the tag from the system.'),
+        content: const Text('This will delete the tag from the system.'),
         actions: [
           TextButton(
             onPressed: () => Navigator.of(ctx).pop(false),
@@ -75,16 +74,15 @@ class _TagDetailSheetState extends ConsumerState<TagDetailSheet> {
   Widget build(BuildContext context) {
     final tagAsync = ref.watch(tagProvider(widget.tagId));
     final occupancy = ref.watch(roomOccupancyProvider);
+    final trackedTag = ref.watch(trackedTagProvider);
 
     return tagAsync.when(
       loading: () => const SizedBox(
         height: 200,
         child: Center(child: CircularProgressIndicator()),
       ),
-      error: (e, _) => SizedBox(
+      error: (e, _) =>
-        height: 200,
+          SizedBox(height: 200, child: Center(child: Text(e.toString()))),
-        child: Center(child: Text(e.toString())),
-      ),
       data: (tag) {
         if (!_editing) _nameCtrl.text = tag.name;
 
@@ -118,16 +116,21 @@ class _TagDetailSheetState extends ConsumerState<TagDetailSheet> {
                     ),
                   ),
                 ),
-                const SizedBox(height: 16),
+                const SizedBox(height: 8),
                 Row(
                   children: [
+                    Icon(
+                      tag.currentRoomId != null
+                          ? Icons.label
+                          : Icons.label_outline,
+                    ),
+                    const SizedBox(width: 8),
                     Expanded(
                       child: _editing
                           ? TextField(
                               controller: _nameCtrl,
                               autofocus: true,
-                              style:
+                              style: Theme.of(context).textTheme.titleLarge,
-                                  Theme.of(context).textTheme.titleLarge,
                               decoration: const InputDecoration(
                                 isDense: true,
                                 border: InputBorder.none,
@@ -145,9 +148,9 @@ class _TagDetailSheetState extends ConsumerState<TagDetailSheet> {
                       onPressed: _editing
                           ? () => _saveName(tag)
                           : () => setState(() {
-                                _editing = true;
+                              _editing = true;
-                                _nameCtrl.text = tag.name;
+                              _nameCtrl.text = tag.name;
-                              }),
+                            }),
                     ),
                   ],
                 ),
@@ -165,6 +168,32 @@ class _TagDetailSheetState extends ConsumerState<TagDetailSheet> {
                     value: _formatLastSeen(tag.lastSeen!),
                   ),
                 const SizedBox(height: 24),
+                FilledButton.tonal(
+                  onPressed: () {
+                    final isTracking = trackedTag?.tagId == tag.tagId;
+                    ref.read(trackedTagProvider.notifier).state = isTracking
+                        ? null
+                        : tag;
+                    // TODO: move screen to floor plan
+                  },
+                  child: Row(
+                    mainAxisAlignment: MainAxisAlignment.center,
+                    children: [
+                      Icon(
+                        trackedTag?.tagId == tag.tagId
+                            ? Icons.radar
+                            : Icons.radar_outlined,
+                      ),
+                      const SizedBox(width: 8),
+                      Text(
+                        trackedTag?.tagId == tag.tagId
+                            ? 'Hide particle cloud'
+                            : 'View particle cloud',
+                      ),
+                    ],
+                  ),
+                ),
+                const SizedBox(height: 8),
                 TextButton(
                   style: TextButton.styleFrom(
                     foregroundColor: Theme.of(context).colorScheme.error,
@@ -193,11 +222,11 @@ class _InfoRow extends StatelessWidget {
       padding: const EdgeInsets.symmetric(vertical: 6),
       child: Row(
         children: [
-          Expanded(
+          Text(label, style: Theme.of(context).textTheme.bodyMedium),
-            child: Text(label,
+          SizedBox(width: 12),
-                style: Theme.of(context).textTheme.bodySmall),
+          Flexible(
+            child: Text(value, style: Theme.of(context).textTheme.labelMedium),
           ),
-          Text(value, style: Theme.of(context).textTheme.bodyMedium),
         ],
       ),
     );

lib/providers.dart

@@ -190,7 +190,12 @@ final roomOccupancyProvider = StreamProvider<Map<int, List<String>>>((ref) {
   return ref.watch(tagRepositoryProvider).watchRoomOccupancy();
 });
 
-final particleCloudProvider = StreamProvider<List<Particle>>((ref) {
+/// The tag whose particle cloud is being visualised on the floor plan.
-  final repo = ref.watch(tagRepositoryProvider);
+/// Null when no tag is tracked.
-  return repo.watchParticleCloud();
+final trackedTagProvider = StateProvider<Tag?>((ref) => null);
+
+/// Live particle snapshots for a specific tag (keyed by tag_id string).
+final particleSnapshotProvider =
+    StreamProvider.autoDispose.family<ParticleSnapshot, String>((ref, tagId) {
+  return ref.watch(tagRepositoryProvider).watchParticleCloud(tagId);
 });