@creezio/shell-ui 0.22.0

package/ui/lib/ai-screencast-hub.ts

@@ -0,0 +1,127 @@
+/**
+ * Hub screencast des espaces IA — côté serveur Next (mémoire process).
+ *
+ * L'app desktop POSTe des frames JPEG (base64) via
+ * POST /api/v1/desktop/screencast/frame ; les spectateurs s'abonnent en SSE
+ * via GET /api/v1/tasks/screencast/:aiUserId/stream.
+ *
+ * Backpressure : on ne garde QUE la dernière frame par IA. Chaque spectateur
+ * a un slot « latest » écrasé à chaque publication ; la livraison est
+ * planifiée (setImmediate) et n'envoie que la frame la plus récente — un
+ * spectateur lent saute des frames au lieu d'accumuler une file.
+ *
+ * Singleton globalThis : survit au HMR dev, simple module en prod.
+ */
+
+export type ScreencastFrame = {
+  /** JPEG base64 (sans préfixe data:). */
+  data: string;
+  seq: number;
+  ts: number;
+};
+
+type Viewer = {
+  id: number;
+  onFrame: (frame: ScreencastFrame) => void;
+  latest: ScreencastFrame | null;
+  scheduled: boolean;
+};
+
+type Channel = {
+  viewers: Map<number, Viewer>;
+  lastFrame: ScreencastFrame | null;
+  seq: number;
+};
+
+const g = globalThis as unknown as {
+  __tf2ScreencastHub?: Map<string, Channel>;
+  __tf2ScreencastViewerId?: number;
+};
+
+function hub(): Map<string, Channel> {
+  if (!g.__tf2ScreencastHub) g.__tf2ScreencastHub = new Map();
+  return g.__tf2ScreencastHub;
+}
+
+function channel(aiUserId: string): Channel {
+  const h = hub();
+  let ch = h.get(aiUserId);
+  if (!ch) {
+    ch = { viewers: new Map(), lastFrame: null, seq: 0 };
+    h.set(aiUserId, ch);
+  }
+  return ch;
+}
+
+function nextViewerId(): number {
+  g.__tf2ScreencastViewerId = (g.__tf2ScreencastViewerId || 0) + 1;
+  return g.__tf2ScreencastViewerId;
+}
+
+/** Planifie la livraison de la dernière frame au spectateur (skip si déjà planifiée). */
+function scheduleDeliver(viewer: Viewer): void {
+  if (viewer.scheduled) return;
+  viewer.scheduled = true;
+  setImmediate(() => {
+    viewer.scheduled = false;
+    const frame = viewer.latest;
+    viewer.latest = null;
+    if (!frame) return;
+    try {
+      viewer.onFrame(frame);
+    } catch {
+      /* spectateur mort — l'unsubscribe SSE fera le ménage */
+    }
+  });
+}
+
+/**
+ * Publie une frame (appelé par la route desktop). Retourne le nombre de
+ * spectateurs — l'app desktop s'auto-arrête si 0 plusieurs fois de suite.
+ */
+export function publishScreencastFrame(
+  aiUserId: string,
+  dataB64: string,
+): { viewers: number; seq: number } {
+  const ch = channel(aiUserId);
+  ch.seq += 1;
+  const frame: ScreencastFrame = { data: dataB64, seq: ch.seq, ts: Date.now() };
+  ch.lastFrame = frame;
+  ch.viewers.forEach((viewer) => {
+    viewer.latest = frame;
+    scheduleDeliver(viewer);
+  });
+  return { viewers: ch.viewers.size, seq: ch.seq };
+}
+
+/**
+ * Abonne un spectateur. La dernière frame connue est livrée immédiatement
+ * (affichage instantané si le screencast tourne déjà). Retourne l'unsubscribe.
+ */
+export function subscribeScreencast(
+  aiUserId: string,
+  onFrame: (frame: ScreencastFrame) => void,
+): () => void {
+  const ch = channel(aiUserId);
+  const viewer: Viewer = {
+    id: nextViewerId(),
+    onFrame,
+    latest: ch.lastFrame,
+    scheduled: false,
+  };
+  ch.viewers.set(viewer.id, viewer);
+  if (viewer.latest) scheduleDeliver(viewer);
+  return () => {
+    ch.viewers.delete(viewer.id);
+  };
+}
+
+export function screencastViewerCount(aiUserId: string): number {
+  return hub().get(aiUserId)?.viewers.size || 0;
+}
+
+/** Purge la dernière frame (fin de session — évite une image périmée). */
+export function clearScreencastFrame(aiUserId: string): void {
+  const ch = hub().get(aiUserId);
+  if (ch) ch.lastFrame = null;
+}

package/ui/lib/ai-workspace-client.ts

@@ -0,0 +1,46 @@
+"use client";
+
+import { getShellDesktopApi, getShellUiBrand } from "@creezio/shell-ui";
+/**
+ * Ouverture du workspace visuel d'un collaborateur IA (« Voir comme IA »).
+ * Client uniquement — nécessite le bridge desktop (app Electron).
+ */
+export function aiWorkspaceAvailable(): boolean {
+  return (
+    typeof window !== "undefined" &&
+    Boolean(getShellDesktopApi()?.showAiWorkspace)
+  );
+}
+
+export async function openAiWorkspaceView(
+  userId: string,
+  label?: string,
+): Promise<{ ok: boolean; error?: string }> {
+  const desktop =
+    typeof window !== "undefined" ? getShellDesktopApi() : undefined;
+  if (!desktop?.showAiWorkspace) {
+    return { ok: false, error: "Disponible uniquement dans l'app desktop" };
+  }
+  const session = await fetch("/api/v1/auth/ai-workspace-session", {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ userId }),
+  });
+  const data = (await session.json().catch(() => ({}))) as {
+    token?: string;
+    error?: string;
+  };
+  if (!session.ok || !data.token) {
+    return { ok: false, error: data.error || "Session workspace refusée" };
+  }
+  const ensured = await desktop.ensureAiWorkspace?.({
+    userId,
+    token: data.token,
+    label,
+  });
+  if (!ensured?.ok) {
+    return { ok: false, error: "Workspace IA indisponible" };
+  }
+  await desktop.showAiWorkspace(userId);
+  return { ok: true };
+}

package/ui/lib/aid.ts

@@ -0,0 +1,22 @@
+/**
+ * Attribut data-* analytics / UiDriver — SoT = configureShellUiBrand({ aidAttr }).
+ * Défaut kit : data-creezio-aid (plus de data-tf2-aid hardcodé).
+ */
+import { getShellUiBrand } from "@creezio/shell-ui";
+
+export const DEFAULT_AID_ATTR = "data-creezio-aid";
+
+export function resolveAidAttr(): string {
+  return getShellUiBrand().aidAttr ?? DEFAULT_AID_ATTR;
+}
+
+/** Props React pour un élément instrumenté : { [aidAttr]: value }. */
+export function aidProps(value: string): Record<string, string> {
+  return { [resolveAidAttr()]: value };
+}
+
+/** Sélecteur CSS pour tout élément portant l'attribut aid courant. */
+export function aidSelector(value?: string): string {
+  const attr = resolveAidAttr();
+  return value != null ? `[${attr}="${value}"]` : `[${attr}]`;
+}

package/ui/lib/desktop-host.ts

@@ -0,0 +1,114 @@
+"use client";
+
+import { getShellDesktopApi, getShellUiBrand } from "@creezio/shell-ui";
+/**
+ * Détection partagée « cette page tourne-t-elle dans un desktop client
+ * distant ? » (app Client kind=client, ou legacy joint en remote).
+ *
+ * - Navigateur pur (pas de getShellDesktopApi()) → l'UI est servie par le
+ *   serveur : on considère « hôte » (les panneaux desktop se rendent null
+ *   d'eux-mêmes hors Electron).
+ * - Desktop avec profil remote → client distant : les sections/actions qui
+ *   pilotent la stack locale (Hermes, n8n, tunnel, plugins, reindex…) sont
+ *   gérées par l'app Serveur, pas par ce poste.
+ *
+ * Résultat mis en cache pour la durée de vie de la page : le mode de
+ * connexion ne change jamais sans relance de l'app.
+ */
+
+export type DesktopHostInfo = {
+  /** true si getShellDesktopApi() existe (Electron). */
+  isDesktop: boolean;
+  /** true si les actions host-only ont un sens ici (hôte local ou navigateur). */
+  isHost: boolean;
+  appKind: "server" | "client" | "legacy" | null;
+};
+
+let cached: Promise<DesktopHostInfo> | null = null;
+
+export function getDesktopHostInfo(): Promise<DesktopHostInfo> {
+  if (cached) return cached;
+  cached = (async (): Promise<DesktopHostInfo> => {
+    if (typeof window === "undefined") {
+      return { isDesktop: false, isHost: true, appKind: null };
+    }
+    const api = getShellDesktopApi();
+    if (!api?.getConnectionProfile) {
+      return { isDesktop: false, isHost: true, appKind: null };
+    }
+    try {
+      const [profile, info] = await Promise.all([
+        api.getConnectionProfile(),
+        api.getInfo?.() ?? Promise.resolve(undefined),
+      ]);
+      return {
+        isDesktop: true,
+        isHost: profile.mode !== "remote",
+        appKind: info?.appKind ?? null,
+      };
+    } catch {
+      // IPC indisponible : ne pas casser l'UI, comportement hôte par défaut.
+      return { isDesktop: true, isHost: true, appKind: null };
+    }
+  })();
+  return cached;
+}
+
+/** Raccourci : true quand ce poste est un client distant (host-only à masquer). */
+export async function isRemoteDesktopClient(): Promise<boolean> {
+  const info = await getDesktopHostInfo();
+  return info.isDesktop && !info.isHost;
+}
+
+/* ── Miroir télémétrie flotte ────────────────────────────────────────────── */
+
+export type FleetActionPayload = {
+  type: string;
+  label: string;
+  path?: string;
+  userId?: string;
+  username?: string;
+  meta?: Record<string, unknown>;
+};
+
+/** null = résolution hôte en cours (on bufferise), sinon décision figée. */
+let fleetMirrorAllowed: boolean | null = null;
+let fleetMirrorBuffer: FleetActionPayload[] = [];
+const FLEET_MIRROR_BUFFER_MAX = 20;
+
+function sendFleetAction(payload: FleetActionPayload): void {
+  const api = typeof window !== "undefined" ? getShellDesktopApi() : undefined;
+  if (!api?.reportFleetAction) return;
+  // catch : best-effort — jamais de rejet non géré pour de la télémétrie.
+  void api.reportFleetAction(payload).catch(() => {});
+}
+
+/**
+ * Miroir flotte gaté : sur un client distant (app Client / legacy joint en
+ * remote), fleet:action est un canal host-only — on n'appelle simplement pas
+ * l'IPC au lieu de générer un rejet à chaque page vue / clic.
+ */
+export function mirrorFleetAction(payload: FleetActionPayload): void {
+  if (typeof window === "undefined") return;
+  if (!getShellDesktopApi()?.reportFleetAction) return;
+  if (fleetMirrorAllowed === true) {
+    sendFleetAction(payload);
+    return;
+  }
+  if (fleetMirrorAllowed === false) return;
+  // Résolution en cours : bufferiser les premiers événements pour ne pas
+  // perdre le page.view initial côté hôte.
+  fleetMirrorBuffer.push(payload);
+  if (fleetMirrorBuffer.length > FLEET_MIRROR_BUFFER_MAX) {
+    fleetMirrorBuffer = fleetMirrorBuffer.slice(-FLEET_MIRROR_BUFFER_MAX);
+  }
+  if (fleetMirrorBuffer.length > 1) return; // résolution déjà lancée
+  void isRemoteDesktopClient().then((remote) => {
+    fleetMirrorAllowed = !remote;
+    const pending = fleetMirrorBuffer;
+    fleetMirrorBuffer = [];
+    if (fleetMirrorAllowed) {
+      for (const p of pending) sendFleetAction(p);
+    }
+  });
+}

package/ui/lib/fleet-tracker-client.ts

@@ -0,0 +1,237 @@
+import { getShellDesktopApi, getShellUiBrand } from "@creezio/shell-ui";
+/**
+ * Tracker produit flotte (renderer) — page views, clics, session.
+ * Envoie via getShellDesktopApi().reportFleetAction (opt-in côté main).
+ */
+
+import { mirrorFleetAction } from "./desktop-host";
+import { resolveAidAttr } from "./aid";
+
+type FleetReport = {
+  type?: string;
+  name?: string;
+  category?: string;
+  label: string;
+  path?: string;
+  referrerPath?: string;
+  userId?: string;
+  username?: string;
+  sessionId?: string;
+  surface?: string;
+  durationMs?: number;
+  meta?: Record<string, unknown>;
+};
+
+type Session = {
+  userId: string | null;
+  username: string | null;
+  sessionId: string | null;
+};
+
+let session: Session = {
+  userId: null,
+  username: null,
+  sessionId: null,
+};
+let currentPath: string | null = null;
+let pageEnteredAt = 0;
+let clickBound = false;
+let visibilityBound = false;
+
+function report(payload: FleetReport): void {
+  // Gaté : sur un client distant, fleet:action est host-only (voir desktop-host).
+  mirrorFleetAction({
+    type: payload.type || payload.name || "event",
+    label: payload.label,
+    path: payload.path,
+    userId: payload.userId ?? session.userId ?? undefined,
+    username: payload.username ?? session.username ?? undefined,
+    meta: {
+      ...(payload.meta || {}),
+      name: payload.name || payload.type,
+      category: payload.category || "ui",
+      sessionId: payload.sessionId ?? session.sessionId,
+      surface: payload.surface || "crm",
+      referrerPath: payload.referrerPath,
+      durationMs: payload.durationMs,
+    },
+  });
+}
+
+export function setFleetTrackerSession(next: {
+  userId?: string | null;
+  username?: string | null;
+  sessionId?: string | null;
+}): void {
+  const prev = session.userId;
+  session = {
+    userId: next.userId !== undefined ? next.userId : session.userId,
+    username: next.username !== undefined ? next.username : session.username,
+    sessionId: next.sessionId !== undefined ? next.sessionId : session.sessionId,
+  };
+  if (session.userId && session.userId !== prev) {
+    report({
+      name: "session.start",
+      type: "session.start",
+      category: "auth",
+      label: `Session ${session.username || session.userId}`,
+      path: typeof location !== "undefined" ? location.pathname : undefined,
+    });
+  }
+}
+
+function closePage(reason: string): void {
+  if (!currentPath || !pageEnteredAt) return;
+  const durationMs = Date.now() - pageEnteredAt;
+  report({
+    name: "page.hide",
+    type: "page.hide",
+    category: "navigation",
+    label: `Quitte ${currentPath}`,
+    path: currentPath,
+    durationMs,
+    meta: { reason },
+  });
+  pageEnteredAt = 0;
+}
+
+export function trackFleetPageView(path: string): void {
+  const next = String(path || "").slice(0, 300);
+  if (!next) return;
+  if (currentPath === next && pageEnteredAt) return;
+  const prev = currentPath;
+  if (prev) closePage("navigate");
+  currentPath = next;
+  pageEnteredAt = Date.now();
+  report({
+    name: "page.view",
+    type: "page.view",
+    category: "navigation",
+    label: `Page ${next}`,
+    path: next,
+    referrerPath: prev || undefined,
+  });
+}
+
+export function trackFleetEvent(payload: FleetReport): void {
+  report(payload);
+}
+
+function clickLabel(el: Element): string {
+  const aid = el.getAttribute(resolveAidAttr());
+  if (aid) return aid;
+  const aria = el.getAttribute("aria-label");
+  if (aria) return aria.slice(0, 120);
+  const title = el.getAttribute("title");
+  if (title) return title.slice(0, 120);
+  const text = (el.textContent || "").replace(/\s+/g, " ").trim();
+  if (text) return text.slice(0, 120);
+  const tag = el.tagName.toLowerCase();
+  const href = el.getAttribute("href");
+  if (href) return `${tag} ${href}`.slice(0, 120);
+  return tag;
+}
+
+function onClickCapture(ev: MouseEvent): void {
+  const t = ev.target;
+  if (!(t instanceof Element)) return;
+  const el =
+    t.closest(
+      `[${resolveAidAttr()}],button,a,[role='button'],[role='tab'],input[type='submit']`,
+    ) || null;
+  if (!el) return;
+  // Ignore chrome fenêtre / inputs texte purs
+  if (el.closest("." + getShellUiBrand().titlebarNoDragClass)) return;
+  if (
+    el instanceof HTMLInputElement &&
+    el.type !== "submit" &&
+    el.type !== "button" &&
+    el.type !== "checkbox" &&
+    el.type !== "radio"
+  ) {
+    return;
+  }
+  const aid = el.getAttribute(resolveAidAttr()) || undefined;
+  report({
+    name: "ui.click",
+    type: "ui.click",
+    category: "ui",
+    label: clickLabel(el),
+    path: currentPath || location.pathname,
+    meta: {
+      aid: aid || null,
+      tag: el.tagName.toLowerCase(),
+      role: el.getAttribute("role") || null,
+    },
+  });
+}
+
+function onVisibility(): void {
+  if (document.visibilityState === "hidden") {
+    closePage("hidden");
+  } else if (document.visibilityState === "visible" && currentPath) {
+    pageEnteredAt = Date.now();
+    report({
+      name: "page.view",
+      type: "page.view",
+      category: "navigation",
+      label: `Retour ${currentPath}`,
+      path: currentPath,
+      meta: { reason: "visible" },
+    });
+  }
+}
+
+export function ensureFleetTrackerDom(): void {
+  if (typeof document === "undefined") return;
+  if (!clickBound) {
+    document.addEventListener("click", onClickCapture, true);
+    clickBound = true;
+  }
+  if (!visibilityBound) {
+    document.addEventListener("visibilitychange", onVisibility);
+    visibilityBound = true;
+  }
+}
+
+export function trackFleetCommerce(opts: {
+  action: string;
+  entityType: string;
+  entityId?: string | number;
+  label?: string;
+  meta?: Record<string, unknown>;
+}): void {
+  report({
+    name: `commerce.${opts.action}`,
+    type: `commerce.${opts.action}`,
+    category: "commerce",
+    label:
+      opts.label ||
+      `${opts.action} ${opts.entityType}${opts.entityId != null ? ` #${opts.entityId}` : ""}`,
+    path: currentPath || undefined,
+    meta: {
+      entityType: opts.entityType,
+      entityId: opts.entityId != null ? String(opts.entityId) : null,
+      ...(opts.meta || {}),
+    },
+  });
+  // Persistance locale (Admin → Analytics) en plus du miroir flotte.
+  void import("@creezio/observability/ui")
+    .then(({ trackUsageEvent }) => {
+      trackUsageEvent({
+        eventType: `commerce.${opts.action}`,
+        category: "commerce",
+        label:
+          opts.label ||
+          `${opts.action} ${opts.entityType}${opts.entityId != null ? ` #${opts.entityId}` : ""}`,
+        meta: {
+          entityType: opts.entityType,
+          entityId: opts.entityId != null ? String(opts.entityId) : null,
+          ...(opts.meta || {}),
+        },
+      });
+    })
+    .catch(() => {
+      /* ignore — tests / environnements sans tracker */
+    });
+}

package/ui/lib/hermes-ui.ts

@@ -0,0 +1,114 @@
+import { getShellDesktopApi, getShellUiBrand } from "@creezio/shell-ui";
+/**
+ * Ouverture Hermes WebUI dans un onglet workspace (outil externe).
+ * URL dynamique (port libre desktop) — résolue via IPC getHermesStatus.
+ */
+
+import { isRemoteDesktopClient } from "./desktop-host";
+
+/** Partition Electron stable (catalogue outils ≥ 900000). */
+export const HERMES_WEBUI_SITE_ID = 900099;
+
+export const HERMES_WEBUI_TAB_TITLE = "Hermes";
+
+export type HermesWebuiOpenTarget = {
+  url: string;
+  siteId: number;
+  title: string;
+};
+
+/** Statut Hermes desktop — typé soft (API marque via getShellDesktopApi). */
+type HermesDesktopStatus = {
+  status?: string;
+  detail?: string | null;
+  uiUrl?: string | null;
+  webuiUrl?: string | null;
+  webuiStatus?: string | null;
+  bootstrapError?: string | null;
+};
+
+function cleanDetail(value: string | null | undefined): string {
+  return String(value || "").trim().replace(/\s+/g, " ");
+}
+
+/** Message actionnable fondé sur l’état réel, jamais sur l’ancien splash. */
+export function hermesUnavailableMessage(st: HermesDesktopStatus): string {
+  const detail = cleanDetail(st.bootstrapError || st.detail);
+  if (st.status === "starting" || st.status === "installing") {
+    return "Hermes est encore en cours de démarrage. " + getShellUiBrand().productName + " continue d’attendre l’API et la WebUI.";
+  }
+  if (st.status === "missing") {
+    return `Le runtime Hermes est absent ou incomplet${detail ? ` : ${detail}` : "."} Ouvrez Configuration → Hermes → Réparer.`;
+  }
+  if (st.status === "error") {
+    const timeout = /timeout|délai/i.test(detail);
+    return `${timeout ? "Le démarrage Hermes a dépassé le délai prévu" : "Hermes n’a pas pu démarrer"}${detail ? ` : ${detail}` : "."} Vous pouvez réessayer ; les détails sont dans Configuration → Hermes → Logs.`;
+  }
+  if (st.status === "running" && st.webuiStatus !== "running") {
+    return `L’API Hermes fonctionne, mais la WebUI est ${st.webuiStatus === "missing" ? "absente" : "indisponible"}${detail ? ` : ${detail}` : "."} Utilisez Réparer dans Configuration → Hermes.`;
+  }
+  if (st.status === "stopped") {
+    return `Hermes s’est arrêté après l’ouverture de ${getShellUiBrand().productName}${detail ? ` : ${detail}` : "."} Réessayez maintenant ou consultez Configuration → Hermes → Logs.`;
+  }
+  return `Hermes est indisponible (état ${st.status}, WebUI ${st.webuiStatus})${detail ? ` : ${detail}` : "."}`;
+}
+
+/** Résout l’URL et relance Hermes local une fois si nécessaire. */
+export async function resolveHermesWebuiOpenTarget(opts?: {
+  onRetry?: () => void;
+}): Promise<
+  HermesWebuiOpenTarget | { ok: false; error: string }
+> {
+  const api = typeof window !== "undefined" ? getShellDesktopApi() : undefined;
+  if (!api?.getHermesStatus) {
+    return {
+      ok: false,
+      error: "Hermes disponible uniquement dans l’app desktop.",
+    };
+  }
+  try {
+    let st = await api.getHermesStatus();
+    let url = (st.webuiUrl || "").trim();
+    if (
+      !url &&
+      st.status !== "skipped-remote-client" &&
+      st.status !== "remote" &&
+      api.retryHermes &&
+      // Client distant : hermes:retry est host-only, ne jamais le tenter.
+      !(await isRemoteDesktopClient())
+    ) {
+      opts?.onRetry?.();
+      st = await api.retryHermes();
+      url = (st.webuiUrl || "").trim();
+    }
+    if (!url) {
+      if (st.status === "skipped-remote-client") {
+        return {
+          ok: false,
+          error:
+            "Client distant — URL Hermes introuvable. Rejoignez un hôte via {slug}." + getShellUiBrand().publicHostSuffix + " (sous-domaine hermes.{slug}…).",
+        };
+      }
+      return {
+        ok: false,
+        error: hermesUnavailableMessage(st),
+      };
+    }
+    return {
+      url,
+      siteId: HERMES_WEBUI_SITE_ID,
+      title: HERMES_WEBUI_TAB_TITLE,
+    };
+  } catch (e) {
+    return {
+      ok: false,
+      error: e instanceof Error ? e.message : "Statut Hermes indisponible",
+    };
+  }
+}
+
+export function isHermesWebuiOpenTarget(
+  v: HermesWebuiOpenTarget | { ok: false; error: string },
+): v is HermesWebuiOpenTarget {
+  return Boolean(v && "url" in v && typeof v.url === "string");
+}