element-call/src/lotus/lotusDecorations.ts

/*
Copyright 2026 Lotus Guild

SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial
Please see LICENSE in the repository root for full details.
*/

import { useSyncExternalStore } from "react";
import { type IWidgetApiRequest } from "matrix-widget-api";

import { widget } from "../widget";
import { LotusWidgetActions, lotusSendToHost } from "./lotusWidget";

/**
 * Avatar decorations (#6 / A6). The Lotus host (cinny) owns the decoration
 * roster (MSC4133 profile decorations) and can't draw them on EC's in-call
 * video tiles from outside the iframe. So it pushes a `userId -> image URL`
 * map via the `io.lotus.decorations` widget action, and the tile avatar
 * component renders the overlay natively.
 */

let decorations: Readonly<Record<string, string>> = {};
const listeners = new Set<() => void>();

function emit(): void {
  for (const l of listeners) l();
}

// Stable module-scope subscribe reference, so `useSyncExternalStore` doesn't
// re-subscribe (add/remove the listener) on every render of a tile.
function subscribe(cb: () => void): () => void {
  listeners.add(cb);
  return () => listeners.delete(cb);
}

/** Subscribe a tile avatar to its participant's decoration URL (or undefined). */
export function useLotusDecoration(userId: string): string | undefined {
  return useSyncExternalStore(subscribe, () => decorations[userId]);
}

// [lotus #28] The decoration URL comes from the host, which builds it from an
// arbitrary (unvalidated on the wire) profile field. `safeImageUrl` used to
// accept ANY https origin, so the only thing stopping a third-party image
// beacon on every tile was the host happening to build the URL itself. Pin it
// to the actual decoration CDN origin(s) — cinny's `DECORATION_CDN`
// (`avatarDecorations.ts`) — plus `blob:`, which EC itself may use for local
// previews. Exported so a future CDN move is a one-line edit here.
export const ALLOWED_DECORATION_ORIGINS: readonly string[] = [
  "https://drive.lotusguild.org",
];

function safeImageUrl(raw: unknown): string | null {
  if (typeof raw !== "string") return null;
  try {
    const u = new URL(raw, window.location.href);
    if (u.protocol === "blob:") return u.href;
    return u.protocol === "https:" &&
      ALLOWED_DECORATION_ORIGINS.includes(u.origin)
      ? u.href
      : null;
  } catch {
    return null;
  }
}

// Ref-counted single registration: the decoration roster is app-wide (keyed by
// userId), so multiple tile/InCallView mounts must share ONE handler — otherwise
// each would reply to the same widget request (double-reply) and a transient
// remount would tear it down.
let registrations = 0;
let unregister: (() => void) | null = null;

/**
 * Register the `io.lotus.decorations` handler (ref-counted). No effect unless
 * the host sends the action. Returns a teardown function.
 */
export function startLotusDecorations(): () => void {
  const w = widget;
  if (!w) return () => undefined;

  if (registrations === 0) {
    const handler = (ev: CustomEvent<IWidgetApiRequest>): void => {
      w.api.transport.reply(ev.detail, {});
      const data = ev.detail.data as
        | { decorations?: Record<string, unknown> }
        | undefined;
      const next: Record<string, string> = {};
      if (data?.decorations && typeof data.decorations === "object") {
        // Cap the roster so a pathological map can't spawn unbounded overlays.
        for (const [userId, url] of Object.entries(data.decorations).slice(
          0,
          512,
        )) {
          const safe = safeImageUrl(url);
          if (safe) next[userId] = safe;
        }
      }
      decorations = next;
      emit();
    };
    w.lazyActions.on(LotusWidgetActions.Decorations, handler);
    unregister = (): void => {
      w.lazyActions.off(LotusWidgetActions.Decorations, handler);
    };
    // [lotus #17] An EC-side remount of InCallView/ActiveCall tears this
    // handler down and back up while cinny stays joined, and the host only
    // re-pushes decorations on a CHANGE to its roster — with an unchanged
    // member list it never re-sends, so the tiles would otherwise lose their
    // decorations for the rest of the call. Ask the host to re-push whatever
    // it currently has every time the handler (re)registers.
    lotusSendToHost(LotusWidgetActions.RequestState, {});
  }
  registrations += 1;

  return () => {
    registrations -= 1;
    if (registrations <= 0) {
      registrations = 0;
      unregister?.();
      unregister = null;
      // [lotus #17] Do NOT wipe the roster here. It used to reset to `{}` so a
      // decoration from call A couldn't leak onto a same-named user in call B,
      // but `decorations` is a module-scope singleton for the lifetime of the
      // PAGE (a fresh call is a fresh page/iframe load, which resets this
      // module anyway), while an EC-side handler remount within the SAME call
      // was wiping live decorations that the host has no reason to re-send
      // (see the request_state ask above, which covers hosts that don't
      // proactively resend). Listeners are still notified so a torn-down
      // period doesn't itself change anything visible.
      emit();
    }
  };
}