@hyperframes/studio 0.7.55 → 0.7.57

package/src/components/editor/canvasContextMenuZOrder.ts

@@ -7,8 +7,23 @@
  * the computed value. Treat missing / "auto" as 0 for comparison purposes.
  *
  * "Overlapping siblings" = siblings whose bounding rects intersect the
- * target's bounding rect. Forward/backward operate within that set;
- * front/back operate across all siblings.
+ * target's bounding rect AND are actually visible at the current frame.
+ * Forward/backward operate within that set; front/back operate across all
+ * siblings (full painting family, visible or not — unchanged semantics).
+ *
+ * ── Visibility ───────────────────────────────────────────────────────────────
+ * In HyperFrames compositions the nearest z-neighbor is often INVISIBLE at the
+ * paused frame: the runtime hides time-inactive clips with inline
+ * `visibility:hidden` / `display:none` (see core runtime
+ * syncTimedElementVisibility), and GSAP timelines park elements at `opacity:0`.
+ * Stepping "forward" over such a sibling looks like a silent no-op. The
+ * forward/backward comparison set therefore keeps only siblings whose
+ * element-level computed style is visible (display ≠ none, visibility ≠
+ * hidden, opacity > 0.01) — all runtime hiding signals are inline styles, so
+ * computed style covers them. Ancestor-chain checks are unnecessary here:
+ * siblings share the target's ancestors. The probe is injectable
+ * (ZOrderResolveOptions.isVisible) so the pure-module tests stay meaningful
+ * without a real style engine, mirroring how tests stub rect reading.
  *
  * ── Tie-awareness ────────────────────────────────────────────────────────────
  * CSS paint order for elements that share a z-index is DOM document order:
@@ -26,6 +41,8 @@
  * (project convention clamps z ≥ 0).
  */
 
+import { COLOR_GRADING_SOURCE_HIDDEN_ATTR } from "@hyperframes/core/color-grading";
+
 export type ZOrderAction = "bring-forward" | "send-backward" | "bring-to-front" | "send-to-back";
 
 /** A resolved change: set `element`'s z-index to `zIndex`. */
@@ -34,6 +51,48 @@ export interface ZOrderPatch {
   zIndex: number;
 }
 
+/** Injectable knobs for the pure resolver (kept mockable like rect reading). */
+export interface ZOrderResolveOptions {
+  /**
+   * Element-level visibility probe used to scope the forward/backward
+   * comparison set. Defaults to `isElementVisibleForZOrder` (computed-style
+   * display/visibility/opacity). Injectable so tests can run without a real
+   * style engine.
+   */
+  isVisible?: (el: HTMLElement) => boolean;
+}
+
+/**
+ * Default visibility probe: is this element itself visible at the current
+ * frame? Element-level only (siblings share the target's ancestor chain).
+ * Covers the runtime's inactive-clip hiding (inline `visibility:hidden` /
+ * `display:none`) and animation-parked `opacity:0`, all of which surface
+ * through computed style. A color-grading source (hidden at opacity:0 while
+ * its canvas paints in its place) still counts as visible, matching
+ * isElementVisibleThroughAncestors in domEditingDom.
+ */
+export function isElementVisibleForZOrder(el: HTMLElement): boolean {
+  try {
+    const win = el.ownerDocument?.defaultView;
+    if (!win) return true;
+    const computed = win.getComputedStyle(el);
+    if (computed.display === "none") return false;
+    if (computed.visibility === "hidden" || computed.visibility === "collapse") return false;
+    const opacity = Number.parseFloat(computed.opacity);
+    if (
+      Number.isFinite(opacity) &&
+      opacity <= 0.01 &&
+      !el.hasAttribute(COLOR_GRADING_SOURCE_HIDDEN_ATTR)
+    ) {
+      return false;
+    }
+    return true;
+  } catch {
+    /* cross-origin / detached — assume visible (fail open, matches rect fallback) */
+    return true;
+  }
+}
+
 interface RenderEntry {
   element: HTMLElement;
   zIndex: number;
@@ -81,8 +140,18 @@ function isElementNode(node: Node): node is HTMLElement {
  * z-index onto the qa-clean audio element, and counting it as a sibling skews the
  * renumber for the visible elements. `<script>/<style>/<link>/<meta>` are also
  * non-painting and could otherwise pad the family / eat a z slot.
+ * `<template>/<noscript>` never paint either — letting them in meant renumber
+ * fallbacks wrote z-index/position into template source markup.
  */
-const NON_PAINTING_TAGS = new Set(["AUDIO", "SCRIPT", "STYLE", "LINK", "META"]);
+const NON_PAINTING_TAGS = new Set([
+  "AUDIO",
+  "SCRIPT",
+  "STYLE",
+  "LINK",
+  "META",
+  "TEMPLATE",
+  "NOSCRIPT",
+]);
 
 /** A painting element: an element node whose tag actually renders pixels. */
 function isPaintingElement(node: Node): node is HTMLElement {
@@ -112,7 +181,7 @@ function getFamily(target: HTMLElement): { entries: RenderEntry[]; targetIndex:
   return { entries, targetIndex };
 }
 
-/** True if two DOM bounding rects intersect (even if touching). */
+/** True if two DOM bounding rects strictly overlap (rects that merely touch do NOT intersect). */
 function rectsIntersect(
   a: { left: number; top: number; right: number; bottom: number },
   b: { left: number; top: number; right: number; bottom: number },
@@ -121,26 +190,35 @@ function rectsIntersect(
 }
 
 /**
- * Restrict a family to the target plus siblings whose bounding rect overlaps
- * the target's rect. The target is always retained. If the target's rect is
- * unavailable or empty (headless / happy-dom returns 0×0), all entries are
- * kept — matching the prior behavior.
+ * Restrict a family to the target plus siblings that are VISIBLE and whose
+ * bounding rect overlaps the target's rect. The target is always retained
+ * (even when itself hidden at the current frame — it is the user's explicit
+ * selection). If the target's rect is unavailable or empty (headless /
+ * happy-dom returns 0×0), the overlap filter is skipped and all VISIBLE
+ * entries are kept — matching the prior rect-fallback behavior.
  */
-function getOverlappingFamily(target: HTMLElement, entries: RenderEntry[]): RenderEntry[] {
+function getOverlappingFamily(
+  target: HTMLElement,
+  entries: RenderEntry[],
+  isVisible: (el: HTMLElement) => boolean,
+): RenderEntry[] {
+  const visibleEntries = entries.filter(
+    (entry) => entry.element === target || isVisible(entry.element),
+  );
   let targetRect: DOMRect;
   try {
     targetRect = target.getBoundingClientRect();
   } catch {
-    return entries;
+    return visibleEntries;
   }
-  if (targetRect.width === 0 && targetRect.height === 0) return entries;
+  if (targetRect.width === 0 && targetRect.height === 0) return visibleEntries;
   const tr = {
     left: targetRect.left,
     top: targetRect.top,
     right: targetRect.right,
     bottom: targetRect.bottom,
   };
-  return entries.filter((entry) => {
+  return visibleEntries.filter((entry) => {
     if (entry.element === target) return true;
     try {
       const r = entry.element.getBoundingClientRect();
@@ -296,28 +374,46 @@ function buildGlobalOrder(
 }
 
 /**
- * Resolve the z-order patches for an action.
- *
- * Returns null when the action is a no-op (target already at the relevant
- * end of its set), otherwise the minimal list of {element, zIndex} changes.
+ * The shared scoping pipeline: full painting family for front/back, visible
+ * overlapping siblings for forward/backward, sorted into render order with the
+ * target's position. Null when the family/scope is too small to act on.
  */
-export function resolveZOrderChange(
+function resolveScopedRenderOrder(
   target: HTMLElement,
   action: ZOrderAction,
-): ZOrderPatch[] | null {
+  options?: ZOrderResolveOptions,
+): { entries: RenderEntry[]; order: RenderEntry[]; pos: number } | null {
   const { entries } = getFamily(target);
   // Family always includes the target; fewer than 2 means no siblings at all.
   if (entries.length < 2) return null;
 
+  const isVisible = options?.isVisible ?? isElementVisibleForZOrder;
   const scoped =
     action === "bring-to-front" || action === "send-to-back"
       ? entries
-      : getOverlappingFamily(target, entries);
+      : getOverlappingFamily(target, entries, isVisible);
   if (scoped.length < 2) return null;
 
   const order = toRenderOrder(scoped);
   const pos = order.findIndex((e) => e.element === target);
   if (pos === -1) return null;
+  return { entries, order, pos };
+}
+
+/**
+ * Resolve the z-order patches for an action.
+ *
+ * Returns null when the action is a no-op (target already at the relevant
+ * end of its set), otherwise the minimal list of {element, zIndex} changes.
+ */
+export function resolveZOrderChange(
+  target: HTMLElement,
+  action: ZOrderAction,
+  options?: ZOrderResolveOptions,
+): ZOrderPatch[] | null {
+  const resolved = resolveScopedRenderOrder(target, action, options);
+  if (!resolved) return null;
+  const { entries, order, pos } = resolved;
 
   const desired = [...order];
   const [moved] = desired.splice(pos, 1);
@@ -343,10 +439,36 @@ export function resolveZOrderChange(
   return realizeOrder(order, desired, target, entries);
 }
 
+/**
+ * The sibling a forward/backward step crosses: the visible overlapping
+ * neighbor directly above (bring-forward) or below (send-backward) the target
+ * in render order. Null for front/back, for a no-op step, or when the scope is
+ * too small. Uses the SAME scoping as resolveZOrderChange, so call it with the
+ * same options BEFORE any live styles are applied.
+ */
+export function resolveCrossedNeighbor(
+  target: HTMLElement,
+  action: ZOrderAction,
+  options?: ZOrderResolveOptions,
+): HTMLElement | null {
+  if (action !== "bring-forward" && action !== "send-backward") return null;
+  const resolved = resolveScopedRenderOrder(target, action, options);
+  if (!resolved) return null;
+  const { order, pos } = resolved;
+  const neighbor = action === "bring-forward" ? order[pos + 1] : order[pos - 1];
+  return neighbor?.element ?? null;
+}
+
 /**
  * Whether a z-order action is available for the target.
- * "disabled" = the element is already at that limit.
+ * "disabled" = the element is already at that limit. Shares the resolver (and
+ * its visibility scoping), so enable/disable always matches what the action
+ * would actually do.
  */
-export function isZOrderActionEnabled(target: HTMLElement, action: ZOrderAction): boolean {
-  return resolveZOrderChange(target, action) !== null;
+export function isZOrderActionEnabled(
+  target: HTMLElement,
+  action: ZOrderAction,
+  options?: ZOrderResolveOptions,
+): boolean {
+  return resolveZOrderChange(target, action, options) !== null;
 }

package/src/components/editor/domEditNudge.test.ts

@@ -0,0 +1,80 @@
+import { describe, expect, it } from "vitest";
+import {
+  CANVAS_NUDGE_SHIFT_STEP_PX,
+  CANVAS_NUDGE_STEP_PX,
+  canCanvasNudgeTargets,
+  resolveCanvasNudgeDelta,
+} from "./domEditNudge";
+
+function mockKeyboardEvent(
+  key: string,
+  overrides: Partial<Pick<KeyboardEvent, "altKey" | "ctrlKey" | "metaKey" | "shiftKey">> = {},
+): Pick<KeyboardEvent, "altKey" | "ctrlKey" | "metaKey" | "shiftKey" | "key"> {
+  return {
+    altKey: false,
+    ctrlKey: false,
+    metaKey: false,
+    shiftKey: false,
+    key,
+    ...overrides,
+  };
+}
+
+describe("resolveCanvasNudgeDelta", () => {
+  it("maps plain arrows to 1px composition deltas", () => {
+    expect(resolveCanvasNudgeDelta(mockKeyboardEvent("ArrowLeft"))).toEqual({
+      dx: -CANVAS_NUDGE_STEP_PX,
+      dy: 0,
+    });
+    expect(resolveCanvasNudgeDelta(mockKeyboardEvent("ArrowRight"))).toEqual({
+      dx: CANVAS_NUDGE_STEP_PX,
+      dy: 0,
+    });
+    expect(resolveCanvasNudgeDelta(mockKeyboardEvent("ArrowUp"))).toEqual({
+      dx: 0,
+      dy: -CANVAS_NUDGE_STEP_PX,
+    });
+    expect(resolveCanvasNudgeDelta(mockKeyboardEvent("ArrowDown"))).toEqual({
+      dx: 0,
+      dy: CANVAS_NUDGE_STEP_PX,
+    });
+  });
+
+  it("maps Shift+arrow to 10px deltas", () => {
+    expect(resolveCanvasNudgeDelta(mockKeyboardEvent("ArrowRight", { shiftKey: true }))).toEqual({
+      dx: CANVAS_NUDGE_SHIFT_STEP_PX,
+      dy: 0,
+    });
+    expect(resolveCanvasNudgeDelta(mockKeyboardEvent("ArrowUp", { shiftKey: true }))).toEqual({
+      dx: 0,
+      dy: -CANVAS_NUDGE_SHIFT_STEP_PX,
+    });
+  });
+
+  it("ignores browser and app shortcut chords", () => {
+    expect(resolveCanvasNudgeDelta(mockKeyboardEvent("ArrowLeft", { altKey: true }))).toBeNull();
+    expect(resolveCanvasNudgeDelta(mockKeyboardEvent("ArrowLeft", { ctrlKey: true }))).toBeNull();
+    expect(resolveCanvasNudgeDelta(mockKeyboardEvent("ArrowLeft", { metaKey: true }))).toBeNull();
+  });
+
+  it("ignores non-arrow keys", () => {
+    expect(resolveCanvasNudgeDelta(mockKeyboardEvent("Escape"))).toBeNull();
+    expect(resolveCanvasNudgeDelta(mockKeyboardEvent("a"))).toBeNull();
+  });
+});
+
+describe("canCanvasNudgeTargets", () => {
+  const movable = { capabilities: { canApplyManualOffset: true } };
+  const locked = { capabilities: { canApplyManualOffset: false } };
+
+  it("requires at least one target", () => {
+    expect(canCanvasNudgeTargets([])).toBe(false);
+  });
+
+  it("allows only when every target accepts a manual offset", () => {
+    expect(canCanvasNudgeTargets([movable])).toBe(true);
+    expect(canCanvasNudgeTargets([movable, movable])).toBe(true);
+    expect(canCanvasNudgeTargets([locked])).toBe(false);
+    expect(canCanvasNudgeTargets([movable, locked])).toBe(false);
+  });
+});

package/src/components/editor/domEditNudge.ts

@@ -0,0 +1,44 @@
+/**
+ * Pure helpers for the canvas arrow-key nudge (DomEditOverlay).
+ *
+ * Mirrors captions/keyboard.ts conventions; the two nudge surfaces can't
+ * double-fire because PreviewOverlays mounts CaptionOverlay and DomEditOverlay
+ * mutually exclusively (caption edit mode returns before the DOM overlay).
+ */
+
+const CANVAS_NUDGE_KEYS = new Set(["ArrowUp", "ArrowDown", "ArrowLeft", "ArrowRight"]);
+
+export const CANVAS_NUDGE_STEP_PX = 1;
+export const CANVAS_NUDGE_SHIFT_STEP_PX = 10;
+/** One undo entry per key burst: the commit fires after this idle gap. */
+export const CANVAS_NUDGE_COMMIT_DEBOUNCE_MS = 400;
+
+type CanvasNudgeKeyEvent = Pick<
+  KeyboardEvent,
+  "altKey" | "ctrlKey" | "metaKey" | "shiftKey" | "key"
+>;
+
+/**
+ * Arrow key → composition-px delta (Shift = 10). Null when the key is not a
+ * plain/Shift arrow, so browser and app shortcut chords pass through.
+ */
+export function resolveCanvasNudgeDelta(
+  event: CanvasNudgeKeyEvent,
+): { dx: number; dy: number } | null {
+  if (event.metaKey || event.ctrlKey || event.altKey) return null;
+  if (!CANVAS_NUDGE_KEYS.has(event.key)) return null;
+  const step = event.shiftKey ? CANVAS_NUDGE_SHIFT_STEP_PX : CANVAS_NUDGE_STEP_PX;
+  return {
+    dx: event.key === "ArrowLeft" ? -step : event.key === "ArrowRight" ? step : 0,
+    dy: event.key === "ArrowUp" ? -step : event.key === "ArrowDown" ? step : 0,
+  };
+}
+
+export interface CanvasNudgeTarget {
+  capabilities: { canApplyManualOffset: boolean };
+}
+
+/** A nudge needs at least one target and every target must accept manual offsets. */
+export function canCanvasNudgeTargets(targets: ReadonlyArray<CanvasNudgeTarget>): boolean {
+  return targets.length > 0 && targets.every((t) => t.capabilities.canApplyManualOffset);
+}

package/src/components/editor/domEditOverlayGeometry.test.ts

@@ -1,6 +1,37 @@
 // @vitest-environment jsdom
 import { describe, expect, it } from "vitest";
-import { selectionCacheKey } from "./domEditOverlayGeometry";
+import {
+  orientedOverlayRect,
+  orientedGroupAwareOverlayRect,
+  overlayCornersCentroid,
+  selectionCacheKey,
+} from "./domEditOverlayGeometry";
+
+describe("overlayCornersCentroid", () => {
+  it("averages the four corners (the rendered rotation center)", () => {
+    expect(
+      overlayCornersCentroid({
+        nw: { x: 10, y: 20 },
+        ne: { x: 110, y: 20 },
+        se: { x: 110, y: 80 },
+        sw: { x: 10, y: 80 },
+      }),
+    ).toEqual({ x: 60, y: 50 });
+  });
+
+  it("is unchanged by rotation — a rotated square's corners average to its center", () => {
+    // Unit square centered at (5,5), rotated 45deg about its center: corners land
+    // on the axis midpoints, whose average is still the center.
+    const c = overlayCornersCentroid({
+      nw: { x: 5, y: 5 - Math.SQRT2 / 2 },
+      ne: { x: 5 + Math.SQRT2 / 2, y: 5 },
+      se: { x: 5, y: 5 + Math.SQRT2 / 2 },
+      sw: { x: 5 - Math.SQRT2 / 2, y: 5 },
+    });
+    expect(c.x).toBeCloseTo(5, 9);
+    expect(c.y).toBeCloseTo(5, 9);
+  });
+});
 
 describe("selectionCacheKey — hfId collision (R7)", () => {
   it("produces distinct keys for two elements that differ only by hfId", () => {
@@ -11,3 +42,138 @@ describe("selectionCacheKey — hfId collision (R7)", () => {
     expect(a).not.toBe(b);
   });
 });
+
+describe("orientedOverlayRect — rotation gate (perf fix, V15 18a/18b)", () => {
+  // jsdom has no DOMMatrix/DOMPoint; a minimal stand-in is enough to exercise the
+  // real (unmocked) orientedOverlayRect, unlike DomEditOverlay.test.ts and
+  // anchoredResizeCommitFeedsOffset.test.ts, which mock this module entirely.
+  class FakeDOMMatrix {
+    a = 1;
+    b = 0;
+    c = 0;
+    d = 1;
+    e = 0;
+    f = 0;
+    constructor(init?: string) {
+      const m = init ? /matrix\(([^)]+)\)/.exec(init) : null;
+      if (!m) return;
+      const parts = m[1]!.split(",").map((s) => Number.parseFloat(s.trim()));
+      [this.a, this.b, this.c, this.d, this.e, this.f] = parts as [
+        number,
+        number,
+        number,
+        number,
+        number,
+        number,
+      ];
+    }
+    transformPoint(pt: { x: number; y: number }) {
+      return {
+        x: this.a * pt.x + this.c * pt.y + this.e,
+        y: this.b * pt.x + this.d * pt.y + this.f,
+      };
+    }
+  }
+  class FakeDOMPoint {
+    constructor(
+      public x: number,
+      public y: number,
+    ) {}
+  }
+  // matrix() form of rotate(30deg), so the module's `new DOMMatrix(cs.transform)`
+  // parse (which expects "matrix(...)", not "rotate(...)") resolves correctly.
+  const ROTATE_30DEG_MATRIX =
+    "matrix(0.8660254037844387, 0.49999999999999994, -0.49999999999999994, 0.8660254037844387, 0, 0)";
+
+  function stubRect(
+    el: Element,
+    rect: { left: number; top: number; width: number; height: number },
+  ) {
+    (el as unknown as { getBoundingClientRect: () => DOMRect }).getBoundingClientRect = () =>
+      ({
+        left: rect.left,
+        top: rect.top,
+        width: rect.width,
+        height: rect.height,
+        right: rect.left + rect.width,
+        bottom: rect.top + rect.height,
+        x: rect.left,
+        y: rect.top,
+        toJSON() {
+          return this;
+        },
+      }) as DOMRect;
+  }
+
+  function buildHarness() {
+    const overlayEl = document.createElement("div");
+    document.body.appendChild(overlayEl);
+    stubRect(overlayEl, { left: 0, top: 0, width: 1000, height: 1000 });
+
+    const iframe = document.createElement("iframe");
+    document.body.appendChild(iframe);
+    stubRect(iframe, { left: 0, top: 0, width: 1000, height: 1000 });
+
+    const doc = iframe.contentDocument!;
+    const root = doc.createElement("div");
+    root.setAttribute("data-composition-id", "root");
+    root.setAttribute("data-width", "1000");
+    root.setAttribute("data-height", "1000");
+    doc.body.appendChild(root);
+
+    const el = doc.createElement("div");
+    root.appendChild(el);
+    stubRect(el, { left: 400, top: 450, width: 200, height: 100 });
+    Object.defineProperty(el, "offsetWidth", { value: 200, configurable: true });
+    Object.defineProperty(el, "offsetHeight", { value: 100, configurable: true });
+
+    const win = iframe.contentWindow as unknown as Window & {
+      DOMMatrix: unknown;
+      DOMPoint: unknown;
+    };
+    win.DOMMatrix = FakeDOMMatrix;
+    win.DOMPoint = FakeDOMPoint;
+
+    return { overlayEl, iframe, el };
+  }
+
+  it("unrotated element takes the cheap AABB path — matches the raw bounding rect, angle 0", () => {
+    const { overlayEl, iframe, el } = buildHarness();
+    const rect = orientedOverlayRect(overlayEl, iframe, el);
+    expect(rect).not.toBeNull();
+    expect(rect!.left).toBeCloseTo(400, 5);
+    expect(rect!.top).toBeCloseTo(450, 5);
+    expect(rect!.width).toBeCloseTo(200, 5);
+    expect(rect!.height).toBeCloseTo(100, 5);
+    expect(rect!.angle ?? 0).toBe(0);
+  });
+
+  it("rotated element takes the corner-geometry path — reports the live angle", () => {
+    const { overlayEl, iframe, el } = buildHarness();
+    el.style.transform = ROTATE_30DEG_MATRIX;
+    const rect = orientedOverlayRect(overlayEl, iframe, el);
+    expect(rect).not.toBeNull();
+    expect(rect!.angle).toBeCloseTo(30, 3);
+  });
+
+  it("preserves an ordinary element's rotation through the group-aware entry point", () => {
+    const { overlayEl, iframe, el } = buildHarness();
+    el.style.transform = ROTATE_30DEG_MATRIX;
+    const rect = orientedGroupAwareOverlayRect(overlayEl, iframe, el);
+    expect(rect!.angle).toBeCloseTo(30, 3);
+  });
+
+  it("gate re-evaluates every call — editing an element to rotated mid-session flips the path immediately", () => {
+    const { overlayEl, iframe, el } = buildHarness();
+    const before = orientedOverlayRect(overlayEl, iframe, el);
+    expect(before?.angle ?? 0).toBe(0);
+
+    el.style.transform = ROTATE_30DEG_MATRIX;
+    const after = orientedOverlayRect(overlayEl, iframe, el);
+    expect(after!.angle).toBeCloseTo(30, 3);
+
+    el.style.transform = "";
+    const restored = orientedOverlayRect(overlayEl, iframe, el);
+    expect(restored?.angle ?? 0).toBe(0);
+  });
+});