Phase 8: Project Management, find bar, presence and motion

The Project Management screen (/pm, view only) with Overview, Projects & units, Bottlenecks & aging, Hours vs target,
Quality & issues and Find jobs, the period picker, health per unit and per project, drill down, Excel (CSV) per table
and for all, and the PESCO production status report PDF with the controlled-copy stamp; every export logged as
"report exported". The find bar on every home screen: the full search set, the dropdowns, quick flags with Mine, the
flag kinds, Board and List with sorts, filters saved per browser; every filter applied by the server on the list and
the boards, with facets. Presence in packets with role, lock and revoke drop; the motion switch with reduced motion
honoured, card glides, glow and count-up; Back restores the scroll spot; sheet placement and the iPad layout pass. The
data book compared page by page with the old build and six layout differences fixed. Tests for the PM aggregates,
search, filters, presence and exports; Playwright scenarios for the PM screen, the find bar and presence at desktop and
iPad viewports. Docs updated; PLAN.md questions 38 to 42.

Co-Authored-By: Claude Fable 5.1 <[email protected]>

frontend/src/auth/useEvents.ts

@@ -1,5 +1,6 @@
 import { useContext, useEffect, useRef, useState, useSyncExternalStore } from "react";
 import { AuthCtx } from "./context";
+import { isScreen, SCREEN_LABELS } from "./roles";
 import type { PresenceUser } from "./types";
 
 interface EventHandlers {
@@ -7,6 +8,15 @@ interface EventHandlers {
   onRevoked: () => void;
   /** Called for every `changed` event. Later phases refresh their data from it. */
   onChanged?: (payload: unknown) => void;
+  /** Phase 8: this browser's own session was locked or unlocked, here or in another tab. */
+  onLockChange?: (action: "locked" | "unlocked") => void;
+}
+
+export interface EventsOptions {
+  /** The screen in view (the first path segment when it is a screen). The server shows it as the role. */
+  screen?: string | null;
+  /** While locked the stream stays open but takes no new screen or packet. */
+  locked?: boolean;
 }
 
 /** Phase 5: presence carries the packet each user has open. */
@@ -45,9 +55,19 @@ function subscribeFocus(fn: () => void): () => void {
 
 const getFocus = () => focusPacket;
 
-/** The stream URL for the packet in view. */
-export function eventsUrl(packetId: number | null): string {
-  return packetId ? `/api/events?packet_id=${encodeURIComponent(String(packetId))}` : "/api/events";
+/** The stream URL for the screen and the packet in view. */
+export function eventsUrl(packetId: number | null, screen: string | null = null): string {
+  const sp = new URLSearchParams();
+  if (screen) sp.set("screen", screen);
+  if (packetId) sp.set("packet_id", String(packetId));
+  const q = sp.toString();
+  return q ? `/api/events?${q}` : "/api/events";
+}
+
+/** The screen of a path: its first segment when that is a screen. */
+export function screenOf(pathname: string): string | null {
+  const seg = pathname.split("/")[1];
+  return isScreen(seg) ? seg : null;
 }
 
 /**
@@ -55,23 +75,30 @@ export function eventsUrl(packetId: number | null): string {
  * A `session` event with this session id and action "revoked" calls onRevoked.
  * `presence` is kept in state. The stream reopens when the packet in view changes.
  */
-export function useEvents(sessionId: string | null, handlers: EventHandlers): PresenceUser[] {
+export function useEvents(sessionId: string | null, handlers: EventHandlers, opts: EventsOptions = {}): PresenceUser[] {
   const [presence, setPresence] = useState<PresenceUser[]>([]);
-  const packetId = useSyncExternalStore(subscribeFocus, getFocus, getFocus);
+  const focus = useSyncExternalStore(subscribeFocus, getFocus, getFocus);
   const ref = useRef(handlers);
   useEffect(() => {
     ref.current = handlers;
   });
+  // While locked the stream keeps what it had: nothing new is sent about where this browser is.
+  const [held, setHeld] = useState<{ packetId: number | null; screen: string | null }>({ packetId: focus, screen: opts.screen ?? null });
+  const wantScreen = opts.screen ?? null;
+  if (!opts.locked && (held.packetId !== focus || held.screen !== wantScreen)) setHeld({ packetId: focus, screen: wantScreen });
+  const { packetId, screen } = held;
 
   useEffect(() => {
     if (!sessionId || typeof EventSource === "undefined") return;
-    const es = new EventSource(eventsUrl(packetId), { withCredentials: true });
+    const es = new EventSource(eventsUrl(packetId, screen), { withCredentials: true });
 
     es.addEventListener("session", (ev) => {
       const p = parse((ev as MessageEvent).data);
       if (p && typeof p === "object") {
         const o = p as { session_id?: unknown; action?: unknown };
-        if (o.session_id === sessionId && o.action === "revoked") ref.current.onRevoked();
+        if (o.session_id !== sessionId) return;
+        if (o.action === "revoked") ref.current.onRevoked();
+        else if (o.action === "locked" || o.action === "unlocked") ref.current.onLockChange?.(o.action);
       }
     });
     es.addEventListener("presence", (ev) => {
@@ -93,23 +120,37 @@ export function useEvents(sessionId: string | null, handlers: EventHandlers): Pr
       es.close();
       setPresence([]);
     };
-  }, [sessionId, packetId]);
+  }, [sessionId, packetId, screen]);
 
   return presence;
 }
 
-/** The other people on `packetId`, from the presence list. One entry per user, sorted by name. */
+/** The other people on `packetId`, from the presence list. One entry per user (one with a role first), sorted by name. */
 export function othersOn(users: readonly PacketPresenceUser[], packetId: number, myId: string | null | undefined): PacketPresenceUser[] {
-  const seen = new Set<string>();
-  const out: PacketPresenceUser[] = [];
+  const byUser = new Map<string, PacketPresenceUser>();
   for (const u of users) {
     if (u.packet_id === null || u.packet_id === undefined || Number(u.packet_id) !== packetId) continue;
     if (myId && u.user_id === myId) continue;
-    if (seen.has(u.user_id)) continue;
-    seen.add(u.user_id);
-    out.push(u);
+    const had = byUser.get(u.user_id);
+    if (!had || (!presenceRole(had) && presenceRole(u))) byUser.set(u.user_id, u);
   }
-  return out.sort((a, b) => a.display_name.localeCompare(b.display_name));
+  return [...byUser.values()].sort((a, b) => a.display_name.localeCompare(b.display_name));
+}
+
+/** The role shown next to a name: the server's role label, else the label of the screen the person has open. */
+export function presenceRole(u: Pick<PresenceUser, "role" | "screen">): string {
+  if (u.role) return u.role;
+  return u.screen && isScreen(u.screen) ? SCREEN_LABELS[u.screen] : "";
+}
+
+/** "Also in this packet now: Andy Welder (Weld Stall) · Wes Super (Supervisor)". Empty when alone. */
+export function presenceText(others: readonly PresenceUser[]): string {
+  if (!others.length) return "";
+  const names = others.map((u) => {
+    const r = presenceRole(u);
+    return r ? `${u.display_name} (${r})` : u.display_name;
+  });
+  return `Also in this packet now: ${names.join(" · ")}`;
 }
 
 /**