@tribe-nest/forge 3.34.0 → 3.36.0

package/src/server/index.ts

@@ -50,16 +50,17 @@ import type {
 import { collectionParamsToQuery, splitCollectionQuery } from "../data/collectionParams";
 // SEO context for structured data. Pure functions over plain data, so this is
 // safe in the React-free server entry.
-import {
-  seoContextFromSiteConfig,
-  type ReviewSchemaReview,
-  type SiteSeoContext,
-} from "../utils/structuredData";
+import { seoContextFromSiteConfig, type ReviewSchemaReview, type SiteSeoContext } from "../utils/structuredData";
 // Also React-free, so it belongs in this entry rather than being re-derived by
 // each route that needs share tags.
 import { buildHeadMeta } from "../utils/headMeta";
 export type { SiteSeoContext };
 import type { SiteConfig } from "../data/queries/useWebsite";
+// Type-only, so nothing from the React data layer reaches this React-free entry.
+// Re-exported so a route loader can name the shape it got back without importing
+// past `@tribe-nest/forge/server`.
+import type { FilmCatalogPage, PublicFilmDetail, PublicFilmEpisode, PublicFilmSummary } from "../data/queries/useFilms";
+export type { FilmCatalogPage, PublicFilmDetail, PublicFilmEpisode, PublicFilmSummary };
 
 /**
  * One public-API GET, KEEPING the failure reason. `getJson` (below) throws that
@@ -87,7 +88,11 @@ async function getJsonResult<T>(
 }
 
 /** GET a public endpoint and parse JSON, returning `null` on any failure. */
-async function getJson<T>(apiUrl: string, path: string, params?: Record<string, string | undefined>): Promise<T | null> {
+async function getJson<T>(
+  apiUrl: string,
+  path: string,
+  params?: Record<string, string | undefined>,
+): Promise<T | null> {
   const res = await getJsonResult<T>(apiUrl, path, params);
   return res.ok ? res.data : null;
 }
@@ -170,10 +175,7 @@ export async function fetchEntityReviewsServer(opts: {
  * site config is invisible there. Pair it with the entity fetch in one
  * `Promise.all` and the extra round trip costs nothing wall-clock.
  */
-export async function fetchSeoContextServer(opts: {
-  apiUrl: string;
-  profileId?: string;
-}): Promise<SiteSeoContext> {
+export async function fetchSeoContextServer(opts: { apiUrl: string; profileId?: string }): Promise<SiteSeoContext> {
   return seoContextFromSiteConfig(await fetchSiteConfig(opts));
 }
 
@@ -272,7 +274,11 @@ export async function fetchSiteBootstrap(opts: {
 }
 
 /** Fetch a single event by id or slug for SSR. */
-export function fetchEventServer(opts: { apiUrl: string; profileId?: string; idOrSlug: string }): Promise<IEvent | null> {
+export function fetchEventServer(opts: {
+  apiUrl: string;
+  profileId?: string;
+  idOrSlug: string;
+}): Promise<IEvent | null> {
   return getJson<IEvent>(opts.apiUrl, `/public/events/${encodeURIComponent(opts.idOrSlug)}`, {
     profileId: opts.profileId,
   });
@@ -366,6 +372,57 @@ export function fetchCourseServer(opts: {
   });
 }
 
+// --- Films and series (SSR) ---
+
+/**
+ * The published film/series catalogue, for SSR of `/i/films`.
+ *
+ * Returns the whole page envelope rather than just the rows, because `enabled`
+ * is load-bearing: with the film-rentals switch off the API answers 200 with an
+ * empty list and `enabled: false`, and a catalogue page that cannot tell that
+ * apart from "this creator has no films yet" would draw the wrong empty state.
+ * A network failure degrades to `enabled: false` with an empty list, which is
+ * the same safe nothing.
+ */
+export async function fetchFilmsServer(opts: {
+  apiUrl: string;
+  profileId?: string;
+  page?: number;
+  limit?: number;
+  kind?: "film" | "series";
+}): Promise<FilmCatalogPage> {
+  const res = await getJson<FilmCatalogPage>(opts.apiUrl, "/public/films", {
+    profileId: opts.profileId,
+    page: String(opts.page ?? 1),
+    limit: String(opts.limit ?? 20),
+    kind: opts.kind,
+  });
+  return res ?? { data: [], total: 0, page: opts.page ?? 1, limit: opts.limit ?? 20, enabled: false };
+}
+
+/**
+ * One title by slug, for SSR of `/i/films/$slug`.
+ *
+ * Deliberately UNAUTHENTICATED, and that is the paywall boundary: the loader
+ * runs on the server with no fan session, so `viewerRental` is always null here
+ * and no manifest URL, key URL or `hlsPrefix` can reach the SSR payload. The
+ * signed-in view is fetched from the browser by `useFilm`, which is the only
+ * place a rental is ever resolved. Do not "improve" this by forwarding a
+ * cookie: a leak the UI happens not to render is still a leak.
+ *
+ * `null` for a draft, an archived title, an unknown slug, another tenant's slug,
+ * or while the feature switch is off - all four indistinguishable on purpose.
+ */
+export function fetchFilmServer(opts: {
+  apiUrl: string;
+  profileId?: string;
+  slug: string;
+}): Promise<PublicFilmDetail | null> {
+  return getJson<PublicFilmDetail>(opts.apiUrl, `/public/films/${encodeURIComponent(opts.slug)}`, {
+    profileId: opts.profileId,
+  });
+}
+
 /** Fetch a single coaching product by id or slug for SSR. */
 export function fetchCoachingProductServer(opts: {
   apiUrl: string;
@@ -403,7 +460,9 @@ export function fetchBlogCategoryServer(opts: {
 
 /** All podcast shows for the profile, for SSR of the podcasts index. */
 export async function fetchPodcastsServer(opts: { apiUrl: string; profileId?: string }): Promise<PodcastShow[]> {
-  return (await getJson<PodcastShow[]>(opts.apiUrl, `/public/blog/posts/podcasts`, { profileId: opts.profileId })) ?? [];
+  return (
+    (await getJson<PodcastShow[]>(opts.apiUrl, `/public/blog/posts/podcasts`, { profileId: opts.profileId })) ?? []
+  );
 }
 
 /** A show's episodes (audio posts) in feed order, for SSR of a show/episode page. */
@@ -459,11 +518,11 @@ export function fetchCollectionQueryServer(opts: {
   query?: CollectionQuery;
 }): Promise<CollectionSearchResult | null> {
   const { scope, query } = splitCollectionQuery(opts.query);
-  return postJson<CollectionSearchResult>(
-    opts.apiUrl,
-    `/public/collections/${encodeURIComponent(opts.slug)}/query`,
-    { profileId: opts.profileId, scope, query },
-  );
+  return postJson<CollectionSearchResult>(opts.apiUrl, `/public/collections/${encodeURIComponent(opts.slug)}/query`, {
+    profileId: opts.profileId,
+    scope,
+    query,
+  });
 }
 
 /** Fetch a single published entry by slug for SSR. */

package/src/ui/headless/_tests/dialogPaystackStandDown.spec.tsx

@@ -0,0 +1,185 @@
+// @vitest-environment jsdom
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { act, render, fireEvent } from "@testing-library/react";
+
+/**
+ * The bug this file exists for: a fan on a code website could not pay with
+ * Paystack from inside a dialog.
+ *
+ * Paystack appends its checkout overlay to `document.body`. A modal Radix
+ * dialog sets `pointer-events: none` on that same body and traps focus inside
+ * its own content, so the popup arrives on top of the page, looks completely
+ * normal, and eats every click and keystroke aimed at it. The fan sees the card
+ * form and cannot type in it. Event tickets, courses, coaching, films,
+ * donations and offers all open the popup from inside one of these dialogs, so
+ * every one of them was unpayable on Paystack.
+ *
+ * It went unnoticed because the only inline-checkout UI coverage was the
+ * payment-link page, which is a plain page with no dialog on it.
+ *
+ * jsdom rather than `renderToStaticMarkup`: the whole behaviour is mount
+ * effects (Radix writes the body style on mount and restores it on unmount), so
+ * there is nothing to assert without a real DOM lifecycle.
+ */
+
+type ResumeOptions = {
+  onSuccess?: (t: { reference?: string }) => void;
+  onCancel?: () => void;
+  onLoad?: (r: unknown) => void;
+  onError?: (e: unknown) => void;
+};
+
+let captured: ResumeOptions = {};
+
+vi.mock("@paystack/inline-js", () => ({
+  default: class FakePaystackPop {
+    resumeTransaction(_accessCode: string, options: ResumeOptions = {}) {
+      captured = options;
+      options.onLoad?.({});
+      return {};
+    }
+    cancelTransaction() {}
+  },
+}));
+
+import { openPaystackCheckout } from "../../../utils/paystackCheckout";
+import { DialogRoot, DialogPortal, DialogOverlay, DialogContent, DialogTitle } from "../dialog";
+
+/** jsdom refuses real navigation, so `location` is replaced with a plain bag. */
+beforeEach(() => {
+  captured = {};
+  Object.defineProperty(window, "location", {
+    value: { href: "https://artist.test/tickets" },
+    writable: true,
+    configurable: true,
+  });
+});
+
+function Checkout({ open, onOpenChange }: { open: boolean; onOpenChange?: (next: boolean) => void }) {
+  return (
+    <DialogRoot open={open} onOpenChange={onOpenChange}>
+      <DialogPortal>
+        <DialogOverlay />
+        <DialogContent aria-describedby={undefined}>
+          <DialogTitle>Tickets</DialogTitle>
+          <button type="button">Pay</button>
+        </DialogContent>
+      </DialogPortal>
+    </DialogRoot>
+  );
+}
+
+/**
+ * Open the popup the way a pay button does, and leave it open.
+ *
+ * The attempt is handed back inside an object rather than as the promise
+ * itself: `await` flattens a promise returned from an async function, and this
+ * one deliberately does not settle until the fan acts.
+ */
+async function openPopup(): Promise<{ attempt: Promise<unknown> }> {
+  let attempt: Promise<unknown> = Promise.resolve();
+  await act(async () => {
+    attempt = openPaystackCheckout({ accessCode: "ac_1", checkoutUrl: "https://checkout.paystack.com/abc" });
+    // Let the dynamic import of the SDK land.
+    await Promise.resolve();
+    await Promise.resolve();
+  });
+  return { attempt };
+}
+
+/** Close the popup and let the attempt finish, as a dismissal does. */
+async function dismissPopup(attempt: Promise<unknown>): Promise<void> {
+  await act(async () => {
+    captured.onCancel?.();
+    await attempt;
+  });
+}
+
+describe("the dialog and the Paystack popup", () => {
+  it("locks the page while it is an ordinary modal", () => {
+    // The baseline, asserted so the rest of this file cannot pass by the
+    // dialog simply never being modal in the first place.
+    render(<Checkout open />);
+
+    expect(document.body.style.pointerEvents).toBe("none");
+  });
+
+  it("REGRESSION: releases the page the moment the popup opens", async () => {
+    render(<Checkout open />);
+    expect(document.body.style.pointerEvents).toBe("none");
+
+    const { attempt } = await openPopup();
+
+    // The fan can now reach the card form. This one assertion is the bug.
+    expect(document.body.style.pointerEvents).not.toBe("none");
+
+    await dismissPopup(attempt);
+  });
+
+  it("stays out of the way after a dismissal rather than remounting the checkout under the fan", async () => {
+    // Radix renders modal and non-modal content as different components, so
+    // flipping back would remount everything inside the dialog in front of
+    // somebody who just closed the popup and is about to try again.
+    render(<Checkout open />);
+    const { attempt } = await openPopup();
+
+    await dismissPopup(attempt);
+
+    expect(document.body.style.pointerEvents).not.toBe("none");
+  });
+
+  it("is a normal modal again the next time it opens", async () => {
+    // Closed by its owner setting `open` to false, with no `onOpenChange` in
+    // sight. That is how the ticket modal closes when a buyer sends their
+    // selection to the cart, and watching only `onOpenChange` left those
+    // dialogs non-modal for the rest of the visit.
+    const { rerender } = render(<Checkout open />);
+    const { attempt } = await openPopup();
+    await dismissPopup(attempt);
+
+    await act(async () => {
+      rerender(<Checkout open={false} />);
+    });
+    await act(async () => {
+      rerender(<Checkout open />);
+    });
+
+    expect(document.body.style.pointerEvents).toBe("none");
+  });
+
+  it("REGRESSION: Escape closes the payment window, not the checkout behind it", async () => {
+    // Non-modal dialogs still dismiss on Escape, and a fan pressing it means
+    // "close Paystack". Taking the checkout down with it loses the order.
+    const onOpenChange = vi.fn();
+    render(<Checkout open onOpenChange={onOpenChange} />);
+    const { attempt } = await openPopup();
+
+    await act(async () => {
+      fireEvent.keyDown(document, { key: "Escape" });
+    });
+
+    expect(onOpenChange).not.toHaveBeenCalledWith(false);
+
+    await dismissPopup(attempt);
+  });
+
+  it("REGRESSION: a click on Paystack's own backdrop does not close the checkout", async () => {
+    // Paystack's overlay is a node in THIS document, outside the dialog
+    // content, so a non-modal dialog reads a tap beside the card form as an
+    // outside interaction and dismisses.
+    const onOpenChange = vi.fn();
+    render(<Checkout open onOpenChange={onOpenChange} />);
+    const { attempt } = await openPopup();
+
+    const backdrop = document.createElement("div");
+    document.body.appendChild(backdrop);
+    await act(async () => {
+      fireEvent.pointerDown(backdrop);
+      fireEvent.mouseDown(backdrop);
+    });
+
+    expect(onOpenChange).not.toHaveBeenCalledWith(false);
+
+    await dismissPopup(attempt);
+  });
+});

package/src/ui/headless/dialog.tsx

@@ -1,14 +1,149 @@
-// Unstyled dialog primitives — thin re-export of Radix Dialog so the headless
+// Unstyled dialog primitives — a thin wrapper over Radix Dialog so the headless
 // blocks get portal + focus-trap + a11y + keyboard for free, with zero styling.
-export {
-  Root as DialogRoot,
+//
+// Thin, but no longer a bare re-export: `DialogRoot` and `DialogContent` stand
+// down while a Paystack popup is on screen. See `usePaystackPopupOpen` below
+// for why that is not optional.
+import * as React from "react";
+import {
+  Root,
   Trigger as DialogTrigger,
   Portal as DialogPortal,
   Overlay as DialogOverlay,
-  Content as DialogContent,
+  Content,
   Close as DialogClose,
   Title as DialogTitle,
   Description as DialogDescription,
 } from "@radix-ui/react-dialog";
+import { isPaystackPopupOpen, subscribeToPaystackPopup } from "../../utils/paystackCheckout";
 
+export { DialogTrigger, DialogPortal, DialogOverlay, DialogClose, DialogTitle, DialogDescription };
 export { Slot } from "@radix-ui/react-slot";
+
+/**
+ * Is Paystack's popup on screen right now?
+ *
+ * Exported for a site that builds its own dialog instead of using these
+ * primitives: the popup lives on `document.body`, so ANY modal layer that locks
+ * the page will lock the popup out with it.
+ */
+export function usePaystackPopupOpen(): boolean {
+  return React.useSyncExternalStore(
+    subscribeToPaystackPopup,
+    isPaystackPopupOpen,
+    // SSR: no popup can be open on the server, and guessing "yes" would render
+    // a non-modal dialog that turns modal on hydration.
+    () => false,
+  );
+}
+
+/**
+ * The dialog root, which STOPS BEING MODAL once a Paystack popup opens inside
+ * it.
+ *
+ * A modal Radix dialog sets `pointer-events: none` on `document.body` and traps
+ * focus in its own content. Paystack appends its overlay to the body, outside
+ * that content, so both of those apply to the popup: the fan sees the card form
+ * on top of everything, clicks it, and nothing happens — the dialog they opened
+ * it from is eating every event. Every Paystack pillar on a code website (event
+ * tickets, courses, coaching, films, donations, offers) opens the popup from
+ * inside one of these, so all six were unpayable.
+ *
+ * Non-modal content drops both behaviours, which is exactly the amount of
+ * getting-out-of-the-way required, and the popup's own overlay is still on top
+ * of the page at a z-index nothing here competes with.
+ *
+ * ## Why it does not switch back when the popup closes
+ *
+ * Radix renders modal and non-modal content as DIFFERENT components, so
+ * flipping the flag remounts everything inside the dialog. Once is free: the
+ * popup is covering the screen at that moment and the pillar hooks that hold
+ * the checkout state live OUTSIDE the dialog content. Flipping back on dismissal
+ * would remount a second time in front of the fan, resetting whatever they had
+ * typed into the step they are looking at. So the dialog stays non-modal until
+ * it CLOSES, and opens modal again next time.
+ *
+ * A host that passes `modal={false}` keeps it: this only ever removes modality.
+ */
+export function DialogRoot({
+  modal,
+  open,
+  onOpenChange,
+  ...props
+}: React.ComponentProps<typeof Root>): React.ReactElement {
+  const popupOpen = usePaystackPopupOpen();
+  const [stoodDown, setStoodDown] = React.useState(false);
+
+  React.useEffect(() => {
+    if (popupOpen) setStoodDown(true);
+  }, [popupOpen]);
+
+  /**
+   * Closing ends the stand-down, so the NEXT time this dialog opens it is an
+   * ordinary modal again.
+   *
+   * Both routes are covered on purpose. A CONTROLLED dialog can be closed by
+   * its owner setting `open` to false without `onOpenChange` ever firing (the
+   * ticket modal does exactly that when the buyer sends a selection to the
+   * cart), and an UNCONTROLLED one has no `open` prop to watch.
+   */
+  React.useEffect(() => {
+    if (open === false) setStoodDown(false);
+  }, [open]);
+
+  return (
+    <Root
+      {...props}
+      open={open}
+      modal={modal === false ? false : !stoodDown}
+      onOpenChange={(next) => {
+        if (!next) setStoodDown(false);
+        onOpenChange?.(next);
+      }}
+    />
+  );
+}
+
+/**
+ * The dialog body, which refuses to fight the Paystack popup for focus or for
+ * the fan's clicks.
+ *
+ * Three defaults have to be suspended while the popup is up, and all three are
+ * the dialog doing its job in a situation where its job is wrong:
+ *
+ *  - **Auto-focus on open.** A non-modal remount focuses its first control,
+ *    which would yank the caret out of the card field the fan is typing in.
+ *  - **Dismiss on outside interaction.** Paystack's backdrop is a click in THIS
+ *    document, outside this content, so closing the popup by tapping beside it
+ *    would take the checkout down with it.
+ *  - **Dismiss on Escape.** Same thing with the key that means "close the
+ *    payment window".
+ *
+ * Each host handler still runs; the suspension is applied after it, so a
+ * surface that wants its own behaviour keeps it everywhere except here.
+ */
+export const DialogContent = React.forwardRef<
+  React.ElementRef<typeof Content>,
+  React.ComponentPropsWithoutRef<typeof Content>
+>(function DialogContent({ onOpenAutoFocus, onInteractOutside, onEscapeKeyDown, ...props }, ref) {
+  const popupOpen = usePaystackPopupOpen();
+
+  return (
+    <Content
+      {...props}
+      ref={ref}
+      onOpenAutoFocus={(event) => {
+        onOpenAutoFocus?.(event);
+        if (popupOpen) event.preventDefault();
+      }}
+      onInteractOutside={(event) => {
+        onInteractOutside?.(event);
+        if (popupOpen) event.preventDefault();
+      }}
+      onEscapeKeyDown={(event) => {
+        onEscapeKeyDown?.(event);
+        if (popupOpen) event.preventDefault();
+      }}
+    />
+  );
+});

package/src/ui/headless/film/FilmWatermark.tsx

@@ -0,0 +1,180 @@
+import { useEffect, useMemo, useRef, useState, type CSSProperties } from "react";
+import type { FilmWatermarkPayload } from "../../../data/queries/useFilmPlaybackSession";
+
+/**
+ * The dynamic viewer overlay: this renter's name, email and rental reference,
+ * drawn over the player for a few seconds at a time in a moving position.
+ *
+ * ## What this layer does, and what it does not
+ *
+ * It deters the screen-record-and-share leak by NAMING the leaker. It stops
+ * nobody from recording, and it is the one protection layer a custom player can
+ * simply omit - which is why it ships as a droppable component rather than as
+ * something welded into a styled block. Keeping the layer costs one component;
+ * dropping it costs per-viewer traceability, and a leaked recording is then
+ * still traceable to the film (the platform watermark is burned into the pixels
+ * by the transcoder) but no longer to the person.
+ *
+ * ## Why it moves
+ *
+ * Constant placement invites cropping: a fixed corner is one rectangle to cut
+ * off, and a recording cropped once is clean for ever. Randomised position and
+ * timing contaminate the WHOLE recording instead, so there is no single edit
+ * that removes it.
+ *
+ * ## Why it watches itself
+ *
+ * A viewer with dev tools open can delete the node or set `display: none` on it.
+ * The overlay observes its own subtree and re-asserts the style it was given, so
+ * removing it takes more than one click. This is a speed bump, not a control: it
+ * is a client-side layer and everything client-side is ultimately editable. The
+ * layers that actually hold are on the server.
+ *
+ * Mount it INSIDE the element that has the video, positioned, so it shares the
+ * player surface. A sibling div is trivially hidden and, worse, is not captured
+ * by a screen recording of the video element alone.
+ */
+export interface FilmWatermarkProps extends Partial<FilmWatermarkPayload> {
+  /** How often a new placement appears, in ms. Default 45s, jittered. */
+  intervalMs?: number;
+  /** How long each placement stays up, in ms. Default 6s. */
+  visibleMs?: number;
+  /** 0..1. Default 0.42 - readable in a recording, unobtrusive while watching. */
+  opacity?: number;
+  className?: string;
+  /** Merged over the computed placement. Does not survive the tamper check. */
+  style?: CSSProperties;
+}
+
+/** The nine placements, as percentages of the player surface. Corners are avoided: they crop first. */
+const PLACEMENTS: { top: string; left: string }[] = [
+  { top: "12%", left: "8%" },
+  { top: "12%", left: "52%" },
+  { top: "38%", left: "18%" },
+  { top: "38%", left: "58%" },
+  { top: "62%", left: "10%" },
+  { top: "62%", left: "48%" },
+  { top: "80%", left: "22%" },
+  { top: "80%", left: "60%" },
+  { top: "50%", left: "34%" },
+];
+
+const pick = <T,>(items: T[]): T => items[Math.floor(Math.random() * items.length)] ?? items[0]!;
+
+export function FilmWatermark({
+  name,
+  email,
+  rentalRef,
+  intervalMs = 45_000,
+  visibleMs = 6_000,
+  opacity = 0.42,
+  className,
+  style,
+}: FilmWatermarkProps) {
+  const [visible, setVisible] = useState(false);
+  const [placement, setPlacement] = useState(() => PLACEMENTS[0]!);
+  /** Bumped by the tamper check to force React to re-apply the style it owns. */
+  const [assertion, setAssertion] = useState(0);
+  const nodeRef = useRef<HTMLDivElement | null>(null);
+
+  // Identify with whatever we were given. An empty overlay is worse than none:
+  // it draws attention to the mechanism while carrying no evidence.
+  const label = useMemo(
+    () =>
+      [name, email, rentalRef]
+        .map((part) => (part ?? "").trim())
+        .filter(Boolean)
+        .join("  ·  "),
+    [name, email, rentalRef],
+  );
+
+  // The show/hide cycle. Jittered so the interval itself is not a pattern
+  // somebody can cut around.
+  useEffect(() => {
+    if (!label) return;
+    let showTimer: ReturnType<typeof setTimeout>;
+    let hideTimer: ReturnType<typeof setTimeout>;
+
+    const cycle = () => {
+      setPlacement(pick(PLACEMENTS));
+      setVisible(true);
+      hideTimer = setTimeout(() => {
+        setVisible(false);
+        // 0.6x to 1.4x of the nominal interval.
+        showTimer = setTimeout(cycle, intervalMs * (0.6 + Math.random() * 0.8));
+      }, visibleMs);
+    };
+
+    // First appearance lands early, so a viewer who stops recording after 30
+    // seconds still has it, then settles into the cycle.
+    showTimer = setTimeout(cycle, 3_000 + Math.random() * 4_000);
+    return () => {
+      clearTimeout(showTimer);
+      clearTimeout(hideTimer);
+    };
+  }, [label, intervalMs, visibleMs]);
+
+  // The tamper check. Watches the node's own attributes and its parent's child
+  // list, and re-asserts by bumping state - React then rewrites the style it
+  // owns, whatever was done to it.
+  useEffect(() => {
+    if (!label || typeof MutationObserver === "undefined") return;
+    const node = nodeRef.current;
+    const parent = node?.parentElement;
+    if (!node || !parent) return;
+
+    const observer = new MutationObserver((records) => {
+      const touched = records.some(
+        (record) =>
+          (record.type === "attributes" && record.target === node) ||
+          (record.type === "childList" && [...record.removedNodes].includes(node)),
+      );
+      if (touched) setAssertion((n) => n + 1);
+    });
+    observer.observe(parent, { childList: true });
+    observer.observe(node, { attributes: true, attributeFilter: ["style", "class", "hidden"] });
+    return () => observer.disconnect();
+  }, [label, assertion]);
+
+  if (!label) return null;
+
+  return (
+    <div
+      ref={nodeRef}
+      key={assertion}
+      aria-hidden="true"
+      data-testid="film-watermark"
+      style={{
+        position: "absolute",
+        top: placement.top,
+        left: placement.left,
+        maxWidth: "70%",
+        // Never intercepts a click: the play/pause surface underneath has to
+        // keep working, and a viewer fighting an invisible box is a support
+        // ticket that reads as "the player is broken".
+        pointerEvents: "none",
+        userSelect: "none",
+        zIndex: 20,
+        opacity: visible ? opacity : 0,
+        transition: "opacity 900ms ease-in-out",
+        // Deliberate literals: this sits over video frames of unknown colour, so
+        // it cannot be a theme token. White text with a dark shadow is the only
+        // pair that stays readable over both a night scene and a snowfield.
+        color: "#ffffff",
+        textShadow: "0 1px 3px rgba(0,0,0,0.85)",
+        fontSize: "clamp(10px, 1.4vw, 14px)",
+        letterSpacing: "0.02em",
+        lineHeight: 1.4,
+        whiteSpace: "nowrap",
+        overflow: "hidden",
+        textOverflow: "ellipsis",
+        ...style,
+      }}
+      className={className}
+    >
+      {label}
+    </div>
+  );
+}
+
+export default FilmWatermark;