Skip to content

Write HTML. Render video. Built for agents.

14.8 KB
Raw Blame
import { useCallback, useEffect, useRef } from "react";
import {
  LAYER_REVEAL_PRIOR_POSITION_ATTR,
  LAYER_REVEAL_PRIOR_Z_ATTR,
} from "../../player/lib/timelineElementHelpers";
import { readEffectiveZIndex } from "./canvasContextMenuZOrder";

/** The lifted paint order — far above any authored z. Only the RENDERER sees
 *  it: every studio z reader is reveal-transparent (readLayerRevealPriorZ). */
export const LAYER_REVEAL_LIFT_Z = "2147483000";
export const LAYER_REVEAL_PENDING_COMMIT_ATTR = "data-hf-studio-reveal-pending-commit";

interface RevealedNode {
  element: HTMLElement;
  priors: { display: string; visibility: string; opacity: string };
  /** Values THIS override wrote — restore only while they are still in place. */
  applied: { display?: string; visibility?: string; opacity?: string };
}

interface RevealLift {
  priors: { zIndex: string; position: string };
  positionLifted: boolean;
}

type PendingRevealCommit = {
  token: string;
  releasedPriors?: RevealLift["priors"];
};

export type LayerRevealCommitOwnership = {
  token: string;
  priorZ: string;
  priorPosition: string | null;
  activeLiftStyles: RevealLift["priors"];
};

let revealCommitSequence = 0;
const zPersistCounts = new WeakMap<HTMLElement, number>();
const REVEAL_RETRY_MS = 16;

/** Prevent delayed reveals from capturing an optimistic z as authored state. */
export function beginLayerZPersist(element: HTMLElement): () => void {
  zPersistCounts.set(element, (zPersistCounts.get(element) ?? 0) + 1);
  let released = false;
  return () => {
    if (released) return;
    released = true;
    const remaining = (zPersistCounts.get(element) ?? 1) - 1;
    if (remaining > 0) zPersistCounts.set(element, remaining);
    else zPersistCounts.delete(element);
  };
}

interface RevealState {
  /** The layer element the reveal was applied for (deselect detection). */
  base: HTMLElement;
  nodes: RevealedNode[];
  lift: RevealLift | null;
}

function restoreInline(el: HTMLElement, property: string, prior: string): void {
  if (prior) el.style.setProperty(property, prior);
  else el.style.removeProperty(property);
}

// This decoder owns the complete serialized reveal-commit schema. Splitting
// field checks across helpers would create multiple authorities for validity.
// fallow-ignore-next-line complexity
function readPendingRevealCommit(element: HTMLElement): PendingRevealCommit | null {
  const raw = element.getAttribute(LAYER_REVEAL_PENDING_COMMIT_ATTR);
  if (!raw) return null;
  try {
    const value: unknown = JSON.parse(raw);
    if (typeof value !== "object" || value === null || !("token" in value)) return null;
    const token = value.token;
    if (typeof token !== "string") return null;
    if (!("releasedPriors" in value) || value.releasedPriors === undefined) return { token };
    const releasedPriors = value.releasedPriors;
    if (
      typeof releasedPriors !== "object" ||
      releasedPriors === null ||
      !("zIndex" in releasedPriors) ||
      !("position" in releasedPriors)
    ) {
      return null;
    }
    const { zIndex, position } = releasedPriors;
    return typeof zIndex === "string" && typeof position === "string"
      ? { token, releasedPriors: { zIndex, position } }
      : null;
  } catch {
    return null;
  }
}

function writePendingRevealCommit(element: HTMLElement, state: PendingRevealCommit): void {
  element.setAttribute(LAYER_REVEAL_PENDING_COMMIT_ATTR, JSON.stringify(state));
}

/** Hand an active reveal lift to one pending durable z commit. */
export function beginLayerRevealCommit(element: HTMLElement): LayerRevealCommitOwnership | null {
  const priorZ = element.getAttribute(LAYER_REVEAL_PRIOR_Z_ATTR);
  if (priorZ == null) return null;
  const ownership = {
    token: `reveal-z-${revealCommitSequence++}`,
    priorZ,
    priorPosition: element.getAttribute(LAYER_REVEAL_PRIOR_POSITION_ATTR),
    activeLiftStyles: { zIndex: element.style.zIndex, position: element.style.position },
  };
  writePendingRevealCommit(element, { token: ownership.token });
  element.removeAttribute(LAYER_REVEAL_PRIOR_Z_ATTR);
  element.removeAttribute(LAYER_REVEAL_PRIOR_POSITION_ATTR);
  return ownership;
}

/** Durable success consumes the reveal regardless of whether selection released it meanwhile. */
export function completeLayerRevealCommit(
  element: HTMLElement,
  ownership: LayerRevealCommitOwnership,
): void {
  if (readPendingRevealCommit(element)?.token === ownership.token) {
    element.removeAttribute(LAYER_REVEAL_PENDING_COMMIT_ATTR);
  }
}

/**
 * Roll back only the reveal transaction this commit owns. An active reveal gets
 * its temporary lift back; a reveal released while persistence was pending gets
 * its exact authored inline styles back, with no resurrected metadata.
 */
export function rollbackLayerRevealCommit(
  element: HTMLElement,
  ownership: LayerRevealCommitOwnership,
): void {
  const pending = readPendingRevealCommit(element);
  if (pending?.token !== ownership.token) return;
  element.removeAttribute(LAYER_REVEAL_PENDING_COMMIT_ATTR);
  element.removeAttribute(LAYER_REVEAL_PRIOR_Z_ATTR);
  element.removeAttribute(LAYER_REVEAL_PRIOR_POSITION_ATTR);
  if (pending.releasedPriors) {
    restoreInline(element, "z-index", pending.releasedPriors.zIndex);
    restoreInline(element, "position", pending.releasedPriors.position);
    return;
  }
  restoreInline(element, "z-index", ownership.activeLiftStyles.zIndex);
  restoreInline(element, "position", ownership.activeLiftStyles.position);
  element.setAttribute(LAYER_REVEAL_PRIOR_Z_ATTR, ownership.priorZ);
  if (ownership.priorPosition != null) {
    element.setAttribute(LAYER_REVEAL_PRIOR_POSITION_ATTR, ownership.priorPosition);
  }
}

/** Restore a property ONLY when its current inline value is still the one this
 *  override wrote — a later real edit (commit, animation seek) is the new
 *  truth and must not be clobbered. */
function restoreIfOurs(
  el: HTMLElement,
  property: "display" | "visibility" | "opacity",
  applied: string | undefined,
  prior: string,
): void {
  if (applied == null) return;
  if (el.style.getPropertyValue(property) !== applied) return;
  restoreInline(el, property, prior);
}

/** What hides this node at the current frame, per computed style. */
function readHideSignals(el: HTMLElement, win: Window) {
  const computed = win.getComputedStyle(el);
  const opacity = Number.parseFloat(computed.opacity);
  return {
    display: computed.display === "none",
    visibility: computed.visibility === "hidden" || computed.visibility === "collapse",
    opacity: Number.isFinite(opacity) && opacity <= 0.01,
  };
}

/** Force one hidden node visible with inline styles; returns priors + applied. */
function revealNode(
  el: HTMLElement,
  win: Window,
  needs: ReturnType<typeof readHideSignals>,
): RevealedNode {
  const priors = {
    display: el.style.display,
    visibility: el.style.visibility,
    opacity: el.style.opacity,
  };
  const applied: RevealedNode["applied"] = {};
  if (needs.display) {
    // Prefer whatever the stylesheet says once the inline hide is lifted;
    // only force block when the sheet itself hides it.
    el.style.removeProperty("display");
    if (win.getComputedStyle(el).display === "none") el.style.display = "block";
    applied.display = el.style.display;
  }
  if (needs.visibility) {
    el.style.visibility = "visible";
    applied.visibility = "visible";
  }
  if (needs.opacity) {
    el.style.opacity = "1";
    applied.opacity = "1";
  }
  return { element: el, priors, applied };
}

/** Walk `element` → body, force-revealing every hiding node; returns the touched nodes. */
function revealHiddenChain(element: HTMLElement): RevealedNode[] {
  const doc = element.ownerDocument;
  const win = doc.defaultView;
  if (!win) return [];
  const nodes: RevealedNode[] = [];
  let el: HTMLElement | null = element;
  while (el && el !== doc.body && el !== doc.documentElement) {
    let needs: ReturnType<typeof readHideSignals>;
    try {
      needs = readHideSignals(el, win);
    } catch {
      break; // detached / cross-realm — leave the rest alone
    }
    if (needs.display || needs.visibility || needs.opacity) nodes.push(revealNode(el, win, needs));
    el = el.parentElement;
  }
  return nodes;
}

/**
 * Lift the selected element to the TOP of the paint order while selected —
 * regardless of its authored z or panel position. The true z is parked in
 * LAYER_REVEAL_PRIOR_Z_ATTR so every studio z reader keeps reporting it (the
 * lift is invisible to menus, badges, the lane mirror, and the panel sort);
 * only the renderer sees the lifted inline value. A static element gets a
 * temporary position:relative (layout-preserving) so the z applies, with the
 * prior position parked in LAYER_REVEAL_PRIOR_POSITION_ATTR for the z-commit's
 * static check. Exported for direct unit testing.
 */
export function liftElementToTop(element: HTMLElement): RevealLift | null {
  const win = element.ownerDocument.defaultView;
  if (!win) return null;
  const priors = { zIndex: element.style.zIndex, position: element.style.position };
  let positionLifted = false;
  try {
    element.setAttribute(LAYER_REVEAL_PRIOR_Z_ATTR, String(readEffectiveZIndex(element)));
    if (win.getComputedStyle(element).position === "static") {
      element.setAttribute(LAYER_REVEAL_PRIOR_POSITION_ATTR, "static");
      element.style.position = "relative";
      positionLifted = true;
    }
  } catch {
    element.removeAttribute(LAYER_REVEAL_PRIOR_Z_ATTR);
    return null; // detached / cross-realm — no lift
  }
  element.style.zIndex = LAYER_REVEAL_LIFT_Z;
  return { priors, positionLifted };
}

/**
 * Undo an active lift. Skipped entirely when the prior-z attribute is gone —
 * a z-reorder commit consumed the lift (handleDomZIndexReorderCommit removes
 * the attributes and writes the new real z), and that commit is the truth.
 * Exported for direct unit testing.
 */
export function restoreLiftedElement(element: HTMLElement, lift: RevealLift): void {
  if (!element.hasAttribute(LAYER_REVEAL_PRIOR_Z_ATTR)) {
    const pending = readPendingRevealCommit(element);
    if (pending && !pending.releasedPriors) {
      // Persistence temporarily owns the live z. Hand it the exact authored
      // priors so a later rejection can restore them after this hook lets go.
      writePendingRevealCommit(element, { ...pending, releasedPriors: lift.priors });
    }
    return;
  }
  const positionStillLifted = element.hasAttribute(LAYER_REVEAL_PRIOR_POSITION_ATTR);
  element.removeAttribute(LAYER_REVEAL_PRIOR_Z_ATTR);
  element.removeAttribute(LAYER_REVEAL_PRIOR_POSITION_ATTR);
  if (element.style.zIndex === LAYER_REVEAL_LIFT_Z) {
    restoreInline(element, "z-index", lift.priors.zIndex);
  }
  if (lift.positionLifted && positionStillLifted && element.style.position === "relative") {
    restoreInline(element, "position", lift.priors.position);
  }
}

/**
 * Temporary "show me this element" override for the Layers panel
 * (Webflow-navigator style): clicking a layer forces it (and every hiding
 * ancestor up to the body) visible with LIVE inline styles, and paints it on
 * TOP of the stack while selected (see liftElementToTop).
 *
 * Strictly ephemeral by construction:
 * - Exact prior inline values are recorded per touched node and restored on
 *   every exit path — reveal of a different layer, deselect, playback start,
 *   unmount. Nothing is ever sent to a persist path, and each property is
 *   restored only while it still holds the value this override wrote.
 * - A post-edit iframe reload replaces the DOM; detached nodes are skipped on
 *   restore (the fresh document never had the override).
 * - Scrubbing/playing lets the runtime and GSAP rewrite these same inline
 *   styles — that is the animation showing reality, and the override is
 *   dropped on play for exactly that reason.
 */
export function useLayerRevealOverride({
  isPlaying,
  selectedElement,
}: {
  isPlaying: boolean;
  selectedElement: HTMLElement | null;
}): {
  scheduleReveal: (element: HTMLElement, delayMs: number) => void;
} {
  const stateRef = useRef<RevealState | null>(null);
  const pendingRevealRef = useRef<{ timer: number; element: HTMLElement } | null>(null);
  const currentRef = useRef({ isPlaying, selectedElement });
  currentRef.current = { isPlaying, selectedElement };

  const restoreReveal = useCallback(() => {
    const state = stateRef.current;
    stateRef.current = null;
    if (!state) return;
    for (const { element, priors, applied } of state.nodes) {
      if (!element.isConnected) continue;
      restoreIfOurs(element, "display", applied.display, priors.display);
      restoreIfOurs(element, "visibility", applied.visibility, priors.visibility);
      restoreIfOurs(element, "opacity", applied.opacity, priors.opacity);
    }
    if (state.lift && state.base.isConnected) restoreLiftedElement(state.base, state.lift);
  }, []);

  const reveal = useCallback(
    (element: HTMLElement) => {
      restoreReveal();
      const nodes = revealHiddenChain(element);
      const lift = liftElementToTop(element);
      if (nodes.length > 0 || lift) stateRef.current = { base: element, nodes, lift };
    },
    [restoreReveal],
  );

  const cancelScheduledReveal = useCallback(() => {
    const pending = pendingRevealRef.current;
    pendingRevealRef.current = null;
    if (pending) window.clearTimeout(pending.timer);
  }, []);

  const scheduleReveal = useCallback(
    (element: HTMLElement, delayMs: number) => {
      cancelScheduledReveal();
      const current = currentRef.current;
      if (current.isPlaying) return;
      const attemptReveal = () => {
        const latest = currentRef.current;
        if (latest.isPlaying || latest.selectedElement !== element || !element.isConnected) {
          pendingRevealRef.current = null;
          return;
        }
        if (zPersistCounts.has(element)) {
          const timer = window.setTimeout(attemptReveal, REVEAL_RETRY_MS);
          pendingRevealRef.current = { timer, element };
          return;
        }
        pendingRevealRef.current = null;
        reveal(element);
      };
      const timer = window.setTimeout(attemptReveal, delayMs);
      pendingRevealRef.current = { timer, element };
    },
    [cancelScheduledReveal, reveal],
  );

  // Selection and playback jointly own eligibility for both pending and active
  // reveals. Cancel first; playback or a different selection then restores the
  // animation/authored styles.
  useEffect(() => {
    const pending = pendingRevealRef.current;
    if (isPlaying || (pending && pending.element !== selectedElement)) cancelScheduledReveal();
    const base = stateRef.current?.base;
    if (isPlaying || (base && selectedElement !== base)) restoreReveal();
  }, [cancelScheduledReveal, isPlaying, restoreReveal, selectedElement]);

  // Unmount: never leave a timer or override behind.
  useEffect(
    () => () => {
      cancelScheduledReveal();
      restoreReveal();
    },
    [cancelScheduledReveal, restoreReveal],
  );

  return { scheduleReveal };
}