feat(studio): revamps Studio + improves code quality (#2291)

* feat(studio): glue API coexistence layer for the NLE swap What: extends 21 glue files so the OLD timeline/canvas engine and the NEW NLE components type-check side by side: playerStore (multi-select setters, zoom pin, snap toggle, non-reactive scale scratch), drag-state types gain optional NLE fields, timelineLayout/timelineAssetDrop/timelineEditingHelpers/ timelineEditing/timelineElementHelpers/studioHelpers/assetHelpers gain the NLE exports, DomEditOverlay + gestures + AssetContextMenu + Timeline props gain optional callbacks/params, contexts gain *Optional hooks, and TimelineEditCallbacks.onMoveElements becomes a bivariant method accepting both engines' change shapes. patchDocumentRootDuration's test rides along. Why: this is the keystone that dissolves the old "welded glue" problem — every symbol the NLE components need is ADDED next to what the old engine still uses, so the engine components and the swaps can land as separate reviewable PRs. How: 15 authored intermediate files (main content + additive symbols; no behavior changes — new fields optional, new callbacks unused until wired) plus 6 files whose final content is already purely additive. New exports without consumers yet carry TEMP(studio-dnd) ignoreExports entries, removed by the app-shell swap. Test plan: tsc --noEmit in studio + studio-server (verifies BOTH engines compile); bunx vitest run (full suite green incl. the 6 new patchDocumentRootDuration tests); fallow audit clean. * feat(studio): timeline interaction hooks and lanes component (unwired) What: the timeline-side wiring layer, unwired: TimelineLanes (the lane renderer driving drag/resize/marquee), timelineMarquee (+tests), useTimelineStackingSync, useTimelineGeometry, useTimelineEditPinning, useTimelineEditingDrops. Why: everything between the pure drag math and <Timeline> itself; the timeline-glue swap PR then only rewires Timeline/TimelineCanvas onto these. How: new files, tsc-clean against the coexistence layer. Unwired components carry TEMP(studio-dnd) entry registrations, removed at the app-shell swap. Test plan: bunx vitest run timelineMarquee.test.ts; tsc --noEmit; fallow audit clean. * feat(studio): NLE shell assembly (unwired) What: EditorShell (the full editor layout replacing NLELayout + StudioPreviewArea), TimelinePane (timeline host with sub-comp rebasing) and useTimelineEditCallbacks (the callback bag bridging store edits to the timeline), all unwired. Why: the shell that App swaps to in the final step; reviewing it standalone keeps that swap PR small. How: new files against the coexistence layer; TEMP(studio-dnd) entries until App mounts EditorShell in the app-shell swap. Test plan: tsc --noEmit; bunx vitest run (suite unchanged); fallow audit clean. * feat(studio): timeline glue swap — Timeline/TimelineCanvas onto the NLE engine What: flips the timeline glue to its final form (23 files): Timeline and TimelineCanvas rebuilt on TimelineLanes/TimelineOverlays, useTimelineClipDrag drives preview/commit through the new drag engine, range selection goes multi-select, playback loop moves to useTimelinePlayerLoop. Deletes the 9 old-engine files this orphans (group drag, marquee selection, snap targets, layer gutter, selection overlays + their suites) — each is compile- or gate-forced by this swap, verified by probe. Why: second swap step; timeline-only, canvas and App untouched. How: modified files to final content + forced deletions. playerStore/timelineEditing/timelineCallbacks stay at their coexistence form until the app swap (the old App still runs on them). Test plan: tsc --noEmit; bunx vitest run (full suite); fallow audit clean. * feat(studio): clip thumbnail modules What: ImageThumbnail (+tests) and thumbnailUtils (+tests) — frame decode with SVG/AVIF format fallbacks and rounded-corner clipping — plus VideoThumbnail updates. Why: the decode layer for timeline clip thumbnails, ahead of the visual refresh that renders them. How: new modules + one modified file; purely presentational. Test plan: bunx vitest run on both test files; tsc --noEmit; fallow audit clean. * feat(studio): assets/blocks panel behaviors + preview helpers What: blocks tab install flow, right-panel and global drag-overlay polish, music beat analysis and clip-content rendering hooks, and the preview-helper utilities backing asset preview. Why: completes the studio NLE stack on top of the visual refresh. How: modified files only (kept as one PR: splitting further would produce sub-150-LOC fragments of interdependent panel glue). Test plan: bunx vitest run studioPreviewHelpers/studioUrlState suites; tsc --noEmit; fallow audit clean. * fix(studio): restore timeline playback loop * fix(studio): restore missing GSAP helpers module * refactor(studio): split timeline GSAP helpers * style(studio): keep timeline helper under size limit * fix(studio): restore timeline overlays module * fix(studio): remove stale GSAP import * fix(studio): restore canonical timeline dependencies * style(studio): format restored timeline helpers * style(studio): satisfy helper line limit * fix(studio): repair rebuilt timeline integration * feat(studio): complete rebuilt NLE cutover * fix(studio): guard project and timeline race boundaries * fix(studio): preserve graded resize and crop geometry * fix(studio): log resize/rotate commit failures, move anchor accumulator to resize-local * fix(studio): treat duration-0 tweens as static holds and settle resize position before persist Instant holds (to()/fromTo() with duration 0) were classified as animated tweens by every commit route, so resizing or rotating them converted the hold into a corrupt duration-0 keyframes tween (new value at 0%, old at 100%) that GSAP drops; panel edits appended a losing set. A shared isInstantHold() now routes them through the static replace-in-place path, and percentage math guards zero-duration windows. Separately, anchored-corner resizes painted 3-5 frames at the new size but old position while the offset persist round-tripped the server. The commit path now applies the corrected GSAP position synchronously before awaiting the offset persist, mirroring the scale route's settle. * feat(studio): gesture-transaction seam with commit observability Introduce runGestureTransaction — one owner for a gesture commit's settle -> persist -> record lifecycle. It settles the live DOM synchronously before any async persist, folds every mutation into one undo entry via a per-transaction coalesceKey, restores pre-gesture state exactly once on failure, and asserts (dev console) + reports (PostHog: commit_transaction / commit_invariant_violation / commit_transaction_failed) that a persist never changes pixels. The box-size resize path is migrated onto it; the ad hoc per-route coalesceKey/reload handling is removed. Extract the resize draft-rect math into resizeDraft.ts to keep the gesture-handler file under the size cap. Also: keep url_hash telemetry to the route slug only (drop the query string, which carried the user's selected element id/selector), and gate the [hf-resize] diagnostics behind localStorage hf-resize-debug so they ship as opt-in tracing rather than console noise. * fix(studio): transaction owns the undo label The coalesced history entry took the last sub-mutation's label, so a resize surfaced as "Move layer" (the offset persist) in undo/redo. The seam now stamps tx.label on every wrapped mutation, so the folded entry reads as the gesture. * fix(studio): atomic static size/position commits (no data loss) Static resize/position holds updated an existing set via delete+add — two undo entries, and a delete that succeeded before a failed add lost the hold on disk. Use one in-place update-properties mutation when a set exists (one undo entry, no partial-failure window). The keyframed-hold heal that can't be expressed as a property update now adds before it deletes, so any single failure leaves a recoverable duplicate, never a lost hold. Transaction-owned commits are tracked via a WeakSet so the heal path never double-wraps an already-wrapped gesture. * fix(core): restore timed-clip visibility after a forced timeline rebind __hfForceTimelineRebind force-rendered the re-registered timeline but never re-ran the per-[data-start] visibility pass, so after undo or soft reload every clip rendered regardless of its time window until a full page reload. Extract the visibility loop into syncTimedElementVisibility and call it from both syncMediaForCurrentState (unchanged) and the rebind. * fix(studio): atomic z-order/keyframe/split commits, one undo entry each Three edit-commit paths hardened onto the one-transaction invariant: - Z-order reorder (useElementLifecycleOps): N per-element writes now fold into one undo entry (coalesceMs Infinity) and, on a failed persist, restore already-written files to disk so no partial reorder survives. - Enable-keyframes (useEnableKeyframes/useGsapKeyframeOps): the intermediate convert phase no longer full-reloads the preview (skipReload), killing the black-flash remount; convert + edit share one coalesce key = one undo entry. - Razor split-all (useRazorSplit): snapshot before the batch and restore on any failure, so a mid-batch error never leaves un-revertable partial splits. Shared file-history helpers (RecordEditInput, DomEditCommitBaseParams, readProjectFileContent, restoreFilesToOriginal) dedupe the rollback/commit logic across these paths. Commit options thread as one partial object rather than field-by-field. Test setup extracted into colocated helpers. * fix(studio): fold multi-step edits into one undo entry; guard text revert - Gesture recording (useGestureCommit): the per-property-group commits now share one coalesce key and only the last reloads, so a recording is one undo entry and one preview reload instead of up to four. - Delete selected keyframes (deleteSelectedKeyframes, split out of timelineEditingHelpers): N removals fold into one coalesced undo entry with a single reload. - Text-field commit (useDomEditTextCommits): commitDomTextFields now uses the same version-guarded revert as handleDomTextCommit, so a stale failed commit can no longer stomp a newer successful one. * feat(studio): batch a gesture's mutations into one atomic server write A transaction that emits N mutations previously did N sequential POSTs, each rewriting the file and soft-reloading — the root of the multi-phase persist window. Add a gsap-mutations-batch endpoint that validates every mutation up front, applies them in one in-memory rewrite chain, and writes the file once (all-or-nothing: an invalid entry rejects the whole batch, no partial write). The seam buffers a transaction's commits and, when more than one targets the same file, dispatches a single batch — one write, one history entry, one reload. The batch capability rides on the existing commit-function reference; no option fields are threaded through callers. * fix(studio): soften off-canvas indicator outline to 30% opacity The dashed off-canvas selection outline at 60% was noisy with many protruding elements on screen; drop the resting opacity to 30% (hover still restores full opacity so it stays discoverable). * fix(studio): drop off-canvas indicator outline to 10% opacity Follow-up to the 30% softening — 10% resting opacity reads much calmer with many protruding elements; hover still restores full opacity. * fix(studio): gate [hf-commit] console traces to dev only The start/settled/persisted/restore lifecycle traces logged on every gesture commit in all environments — console noise for end users. Route them through a dev-only traceCommit helper (matching the pixel-violation error's existing DEV gate). The commit_* PostHog events stay always on; they are the production observability, the console lines are a dev aid. * fix(studio): count actual reloads, not softReload requests, in commit telemetry A resize's size and offset persists both request softReload; the seam counted each request, so a batched gesture reported reload_count 2 even though the batch is one write and one reload. Compute the count from what dispatchBufferedCommits actually did — one for a batch, the request count for the sequential fallback. * fix(studio): rotate hover + off-canvas overlays with the element; flicker-free crop - Hover overlay applied the element's rotation only to the selection chrome, not the hover box; it now rotates about center like the selection, via a shared orientedGroupAwareOverlayRect router (one owner for rotation-aware overlay geometry across hover/selection/off-canvas). - Off-canvas indicator was axis-aligned; it now rotates with the element and inverse-rotates the canvas-exclusion clip into the element's local frame, so the protruding-sliver clip stays correct for rotated elements. - Crop commit re-lifted the element only in the commit's .then(), so one frame painted the cropped state (the flicker). Re-lift synchronously right after onStyleCommit (which applies the clip before its first await), so the cropped state never paints; the persisted file value is unchanged. * fix(studio): address code-review findings across the commit-hardening campaign Correctness (would ship green, bite under latency): - Enable-keyframes phase 2 now carries coalesceMs: Infinity, so the convert folds into one undo entry instead of splitting past the 300ms default. - The SDK keyframe persist path forwards coalesceMs (CutoverOptions gains the field); multi-keyframe delete and convert coalesce correctly when SDK-routed. - Razor split-all's rollback is guarded so a failing restore can't swallow the error toast that tells the user the split failed. Simplification (single source of truth / no dead flexibility): - Decompose resolveResizeDraftRect (drops a fallow-ignore suppression). - Delegate the third readProjectFileContent copy to the shared helper. - Inline setPatchFromUpdateProperties (its only caller passes one mutation). - One toSdkPersistOptions translates gesture overrides to SDK options. - Bundle the reorder-rollback deps into one object (was 7-9 positional args). - Dedupe the 'last group reloads' ternary; type gesture options as CommitMutationOptions; drop a Map+array wrapper around a single write. * feat(studio): atomic z-order reorder via batch patch-element endpoint Z-order reorder issued N per-element inline-style patches (one server write each), so a mid-chain failure could leave a partial reorder on disk. Add a patch-elements-batch endpoint that validates every patch, folds them over the file in one in-memory rewrite, and writes once (all-or-nothing; unsafe input rejects with no write). The reorder now sends one batch per source file and records one undo entry. Because a failed atomic write persists nothing, the interim disk-write-back rollback (restoreReorderedFile / restoreFulfilledReorderFiles / ReorderRollbackDeps) is deleted — failure rolls back only live DOM/store state. Closes the last disk-atomicity gap. * fix(studio): razor-split undo no longer silently no-ops The split clone was written to disk without a data-hf-id, so the split endpoint recorded that unstamped HTML as the undo entry's afterHash. The next reloadPreview() ran the preview route's ensureHfIds write-back, which minted a fresh id and persisted DIFFERENT bytes — so at undo time the disk hash no longer matched afterHash and editHistory's content-mismatch guard silently refused the undo (no write, no network, no error). Stamp the split output via ensureHfIds in splitElementInHtml before it is written/returned, so the preview write-back is a no-op and the recorded afterHash always equals the final on-disk bytes. Fixes at the source rather than relaxing the mismatch guard. Corrects the stale comment that credited forceReloadSdkSession. * feat(studio): closed-hand grab cursor on the rotate handle The rotate handle used the default arrow cursor; show a grabbing (closed-hand) cursor on hover to signal it's grabbed and dragged to rotate. * fix(studio): dropping a dragged element over another no longer selects it A moved drag's release fired the box click, which re-selected whatever now sat under the pointer via the hover cache — so dropping an element over a higher-z one selected the drop target instead of keeping the dragged element selected. The drag-move branch now suppresses the next box click, mirroring the resize branch. * fix(studio): group drag is one undo entry, not one per element Dragging a multi-selected group committed each member's position write as its own undo entry, so reverting took N Cmd+Z presses. Force a shared coalesceKey (infinite window) across every member's commit so they fold into a single undo entry, like the other multi-step commit paths. * fix(studio): undo of a split no longer leaves a ghost clip in the timeline The file and the composition iframe revert correctly on undo, but the timeline panel kept a ghost node for the split clone. The element-merge that repopulates the timeline preserves elements the fresh scan dropped — intended for enriched sub-composition children a bare DOM re-scan misses, but it also preserved a genuinely-removed TOP-LEVEL element (the split clone after undo), leaving a phantom clip. Restrict the preserve to elements with a compositionSrc (the enriched sub-comp children); a top-level element missing from the fresh scan was truly removed. --------- Co-authored-by: ukimsanov <ular.kimsanov@heygen.com>
2026-09-11 23:00:03 +00:00 · 2026-07-13 02:55:36 -04:00
parent 9940503102
commit df29fa7a5e
228 changed files with 18774 additions and 7332 deletions
@@ -9,6 +9,14 @@ export interface OverlayRect {
  height: number;
  editScaleX: number;
  editScaleY: number;
+  /**
+   * The element's live transform rotation in DEGREES (screen/CSS convention, CW
+   * positive), decomposed from its computed transform matrix. Present so the
+   * selection chrome can render as an oriented bounding box (OBB) that co-rotates
+   * with the element. Omitted (treated as 0) for group/union rects and when the
+   * transform is unmeasurable — those render axis-aligned exactly as before.
+   */
+  angle?: number;
 }

 export interface GroupOverlayItem {
@@ -98,31 +106,115 @@ export function toVisibleOverlayRect(
  return rect ? { ...rect, ...hugRectForElement(rect, element) } : null;
 }

-export function toOverlayRect(
+/**
+ * getComputedStyle(element).transform decomposed into a DOMMatrix, read ONCE.
+ * Shared by orientedOverlayRect's rotation gate and elementCornerOverlayPoints
+ * so a single measurement pass serves both — constructing this twice per frame
+ * (one read per consumer) was redundant work; see orientedOverlayRect below.
+ */
+interface ElementTransformSnapshot {
+  matrix: DOMMatrix;
+  cs: CSSStyleDeclaration;
+}
+
+function readElementTransformSnapshot(
+  win: Window,
+  element: HTMLElement,
+): ElementTransformSnapshot | null {
+  const DOMMatrixCtor = (win as Window & typeof globalThis).DOMMatrix;
+  if (!DOMMatrixCtor) return null;
+  const cs = win.getComputedStyle(element);
+  try {
+    const matrix = new DOMMatrixCtor(cs.transform === "none" ? "" : cs.transform);
+    return { matrix, cs };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The element's live transform rotation, in DEGREES (screen/CSS convention, CW
+ * positive), decomposed from its transform matrix (rotation = atan2(b, a)).
+ * GSAP folds rotation and scale into the same matrix; this reads rotation only.
+ * Skew is ignored (does not affect atan2(b, a)).
+ */
+function rotationDegreesFromMatrix(matrix: DOMMatrix): number {
+  const a = Number.isFinite(matrix.a) ? matrix.a : 1;
+  const b = Number.isFinite(matrix.b) ? matrix.b : 0;
+  const deg = (Math.atan2(b, a) * 180) / Math.PI;
+  return Number.isFinite(deg) ? deg : 0;
+}
+
+/** Below this, orientedOverlayRect treats the element as unrotated and returns
+ *  the AABB directly (see its doc comment) — tight enough to only swallow
+ *  matrix-decomposition floating-point noise, never an actual rotation. */
+const ROTATION_GATE_EPSILON_DEG = 1e-4;
+
+/** iframe→overlay mapping basis shared by every overlay-geometry function. */
+interface OverlayRootScale {
+  iframeRect: DOMRect;
+  overlayRect: DOMRect;
+  rootScaleX: number;
+  rootScaleY: number;
+}
+
+/** The composition root element inside the preview doc (or null when absent). */
+function findOverlayRootElement(doc: Document | null): HTMLElement | null {
+  return doc?.querySelector<HTMLElement>("[data-composition-id]") ?? doc?.documentElement ?? null;
+}
+
+/**
+ * The root's effective width/height for scaling: prefer the composition's
+ * declared dimensions (data-width/data-height), which stay fixed while GSAP
+ * transforms mutate the measured rect; fall back to the measured rect. Null when
+ * unmeasurable.
+ */
+function resolveRootDimensions(root: HTMLElement | null): { width: number; height: number } | null {
+  if (!root) return null;
+  const rootRect = root.getBoundingClientRect();
+  const width = readPositiveDimension(root.getAttribute("data-width")) ?? rootRect.width;
+  const height = readPositiveDimension(root.getAttribute("data-height")) ?? rootRect.height;
+  if (!width || !height) return null;
+  return { width, height };
+}
+
+/**
+ * The iframe/overlay client rects and the iframe→root scale factors. Uses the
+ * composition's declared dimensions (data-width/data-height) for the scale
+ * instead of rootRect.width/height: when GSAP applies transforms (scale,
+ * translate) to the root, rootRect dimensions change but the composition's
+ * canonical size stays fixed, and using rootRect misaligns the overlay during
+ * animated playback. Returns null when the geometry is unmeasurable.
+ */
+function computeOverlayRootScale(
+  overlayEl: HTMLDivElement,
+  iframe: HTMLIFrameElement,
+  doc: Document | null,
+): OverlayRootScale | null {
+  const iframeRect = iframe.getBoundingClientRect();
+  const overlayRect = overlayEl.getBoundingClientRect();
+  const dims = resolveRootDimensions(findOverlayRootElement(doc));
+  if (!dims) return null;
+  return {
+    iframeRect,
+    overlayRect,
+    rootScaleX: iframeRect.width / dims.width,
+    rootScaleY: iframeRect.height / dims.height,
+  };
+}
+
+function toOverlayRect(
  overlayEl: HTMLDivElement,
  iframe: HTMLIFrameElement,
  element: HTMLElement,
+  precomputedScale?: OverlayRootScale | null,
 ): OverlayRect | null {
-  const iframeRect = iframe.getBoundingClientRect();
-  const overlayRect = overlayEl.getBoundingClientRect();
-  const doc = iframe.contentDocument;
-  const root =
-    doc?.querySelector<HTMLElement>("[data-composition-id]") ?? doc?.documentElement ?? null;
-  const rootRect = root?.getBoundingClientRect();
-  // Use the composition's declared dimensions (data-width/data-height) for scale
-  // calculation instead of rootRect.width/height. When GSAP applies transforms
-  // (scale, translate) to the root element, rootRect dimensions change but the
-  // composition's canonical size stays the same. Using rootRect causes overlay
-  // misalignment during animated playback.
-  const declaredWidth = readPositiveDimension(root?.getAttribute("data-width") ?? null);
-  const declaredHeight = readPositiveDimension(root?.getAttribute("data-height") ?? null);
-  const rootWidth = declaredWidth ?? rootRect?.width;
-  const rootHeight = declaredHeight ?? rootRect?.height;
-  if (!rootWidth || !rootHeight || !rootRect) return null;
+  const scale =
+    precomputedScale ?? computeOverlayRootScale(overlayEl, iframe, iframe.contentDocument);
+  if (!scale) return null;
+  const { iframeRect, overlayRect, rootScaleX, rootScaleY } = scale;

  const elementRect = element.getBoundingClientRect();
-  const rootScaleX = iframeRect.width / rootWidth;
-  const rootScaleY = iframeRect.height / rootHeight;
  const sourceBoundary = findSourceBoundary(element);
  const sourceBoundaryRect = sourceBoundary?.getBoundingClientRect();
  const editScale = resolveDomEditCoordinateScale({
@@ -144,7 +236,163 @@ export function toOverlayRect(
  };
 }

+/** Which physical corner of the (possibly rotated) element a resize handle keeps
+ *  fixed: NW grabs the top-left, so the bottom-right (se) is the anchor, etc. */
+export type FixedCorner = "nw" | "ne" | "sw" | "se";
+
+/** Distance between two overlay-px corner points — the edge-length math
+ *  orientedOverlayRect uses to turn corners into a width/height. Exported so a
+ *  caller already holding raw corners (e.g. a resize gesture mid-measurement)
+ *  can derive the same dimensions without a second orientedOverlayRect call. */
+export function cornerEdgeLength(a: { x: number; y: number }, b: { x: number; y: number }): number {
+  return Math.hypot(b.x - a.x, b.y - a.y);
+}
+
+/**
+ * The centroid (rendered center) of the four transformed corners from
+ * `elementCornerOverlayPoints`, in overlay px. This is the element's true rotation
+ * center — the point a center-anchored resize keeps planted.
+ */
+export function overlayCornersCentroid(corners: Record<FixedCorner, { x: number; y: number }>): {
+  x: number;
+  y: number;
+} {
+  return {
+    x: (corners.nw.x + corners.ne.x + corners.se.x + corners.sw.x) / 4,
+    y: (corners.nw.y + corners.ne.y + corners.se.y + corners.sw.y) / 4,
+  };
+}
+
+/**
+ * The element's border-box corners in OVERLAY coordinates, honoring its live
+ * transform (rotation/skew/scale) — NOT the axis-aligned getBoundingClientRect.
+ * A rotated element's four visual corners are the transformed local box corners.
+ * Uses the same iframe→overlay root scale as toOverlayRect so the returned
+ * points share that function's coordinate space. Returns null when the
+ * geometry is unmeasurable.
+ */
+export function elementCornerOverlayPoints(
+  overlayEl: HTMLDivElement,
+  iframe: HTMLIFrameElement,
+  element: HTMLElement,
+  precomputedScale?: OverlayRootScale | null,
+  precomputedTransform?: ElementTransformSnapshot | null,
+): Record<FixedCorner, { x: number; y: number }> | null {
+  const win = iframe.contentWindow;
+  const doc = iframe.contentDocument;
+  if (!win || !doc) return null;
+  const DOMPointCtor = (win as Window & typeof globalThis).DOMPoint;
+  if (!DOMPointCtor) return null;
+
+  const scale = precomputedScale ?? computeOverlayRootScale(overlayEl, iframe, doc);
+  if (!scale) return null;
+  const { iframeRect, overlayRect, rootScaleX, rootScaleY } = scale;
+
+  // The element's local border box maps to viewport coords by the SAME transform
+  // matrix the browser used for its BCR. We recover the transform's screen-space
+  // action from the BCR: transformPoint(localCorner - origin) gives a corner
+  // RELATIVE to the transformed origin. We anchor those relative corners to the
+  // BCR by matching the AABB of the transformed corners to the real BCR — the
+  // constant offset cancels in the before/after difference the caller takes, but
+  // we resolve it fully here so callers can also read absolute overlay positions.
+  const transform = precomputedTransform ?? readElementTransformSnapshot(win, element);
+  if (!transform) return null;
+  const { matrix, cs } = transform;
+  const w = element.offsetWidth;
+  const h = element.offsetHeight;
+  const originParts = cs.transformOrigin.split(" ").map((p) => Number.parseFloat(p));
+  const ox = Number.isFinite(originParts[0]!) ? originParts[0]! : w / 2;
+  const oy = Number.isFinite(originParts[1]!) ? originParts[1]! : h / 2;
+  const rel = (lx: number, ly: number): { x: number; y: number } => {
+    const p = matrix.transformPoint(new DOMPointCtor(lx - ox, ly - oy));
+    return { x: p.x, y: p.y };
+  };
+  const relCorners = {
+    nw: rel(0, 0),
+    ne: rel(w, 0),
+    se: rel(w, h),
+    sw: rel(0, h),
+  };
+  // Recover the absolute viewport position by matching to the element's BCR:
+  // the relative corners' AABB min corresponds to the BCR's top-left.
+  const xs = [relCorners.nw.x, relCorners.ne.x, relCorners.se.x, relCorners.sw.x];
+  const ys = [relCorners.nw.y, relCorners.ne.y, relCorners.se.y, relCorners.sw.y];
+  const bcr = element.getBoundingClientRect();
+  const dx = bcr.left - Math.min(...xs);
+  const dy = bcr.top - Math.min(...ys);
+  const toOverlay = (pt: { x: number; y: number }): { x: number; y: number } => ({
+    x: iframeRect.left - overlayRect.left + (pt.x + dx) * rootScaleX,
+    y: iframeRect.top - overlayRect.top + (pt.y + dy) * rootScaleY,
+  });
+  return {
+    nw: toOverlay(relCorners.nw),
+    ne: toOverlay(relCorners.ne),
+    se: toOverlay(relCorners.se),
+    sw: toOverlay(relCorners.sw),
+  };
+}
+
+/**
+ * The selection chrome's ORIENTED bounding box: the element's UNROTATED border box
+ * expressed in overlay coordinates (center-anchored left/top/width/height) plus the
+ * live rotation angle. Rendering that rect with `transform: rotate(angle)` about its
+ * center reproduces the element's real transformed corners exactly, so the border,
+ * corner dots, rotate handle, and crop pills all co-rotate with the object.
+ *
+ * Built from `elementCornerOverlayPoints` (the real transformed corners): the OBB
+ * center is the corner centroid, the unrotated width/height are the edge lengths, and
+ * left/top place the unrotated box so that rotating it about its center lands the
+ * corners back on the measured points. At angle 0 this equals `toOverlayRect` (the
+ * AABB and OBB coincide), so unrotated chrome is pixel-identical to today.
+ *
+ * Returns the plain AABB rect (angle 0) when the corner geometry can't be measured.
+ *
+ * Rotation gate: an unrotated element's OBB is numerically identical to its AABB
+ * (the comment above), so a cheap rotation read decides up front whether the
+ * (much pricier) corner-transform pass runs at all — for the overwhelming
+ * majority of selections, which aren't rotated, this call is just `toOverlayRect`
+ * plus one getComputedStyle/DOMMatrix read. The root scale and the transform
+ * snapshot are each computed once per call and threaded into both the rotation
+ * read and the corner math, instead of every helper re-measuring independently.
+ */
+export function orientedOverlayRect(
+  overlayEl: HTMLDivElement,
+  iframe: HTMLIFrameElement,
+  element: HTMLElement,
+): OverlayRect | null {
+  const scale = computeOverlayRootScale(overlayEl, iframe, iframe.contentDocument);
+  if (!scale) return null;
+  const base = toOverlayRect(overlayEl, iframe, element, scale);
+  if (!base) return null;
+
+  const win = iframe.contentWindow;
+  const transform = win ? readElementTransformSnapshot(win, element) : null;
+  const angle = transform ? rotationDegreesFromMatrix(transform.matrix) : 0;
+  if (Math.abs(angle) < ROTATION_GATE_EPSILON_DEG) return base;
+
+  const corners = elementCornerOverlayPoints(overlayEl, iframe, element, scale, transform);
+  if (!corners) return base;
+  // Unrotated edge lengths (in overlay px): nw→ne is the width, nw→sw the height.
+  const width = cornerEdgeLength(corners.nw, corners.ne);
+  const height = cornerEdgeLength(corners.nw, corners.sw);
+  const centerX = (corners.nw.x + corners.se.x) / 2;
+  const centerY = (corners.nw.y + corners.se.y) / 2;
+  if (!Number.isFinite(width) || !Number.isFinite(height) || width <= 0 || height <= 0) {
+    return base;
+  }
+  return {
+    left: centerX - width / 2,
+    top: centerY - height / 2,
+    width,
+    height,
+    editScaleX: base.editScaleX,
+    editScaleY: base.editScaleY,
+    angle,
+  };
+}
+
 const OVERLAY_RECT_EPSILON_PX = 0.5;
+const OVERLAY_RECT_ANGLE_EPSILON_DEG = 0.1;

 export function rectsEqual(a: OverlayRect | null, b: OverlayRect | null): boolean {
  if (a === b) return true;
@@ -155,7 +403,8 @@ export function rectsEqual(a: OverlayRect | null, b: OverlayRect | null): boolea
    Math.abs(a.width - b.width) < OVERLAY_RECT_EPSILON_PX &&
    Math.abs(a.height - b.height) < OVERLAY_RECT_EPSILON_PX &&
    Math.abs(a.editScaleX - b.editScaleX) < 0.001 &&
-    Math.abs(a.editScaleY - b.editScaleY) < 0.001
+    Math.abs(a.editScaleY - b.editScaleY) < 0.001 &&
+    Math.abs((a.angle ?? 0) - (b.angle ?? 0)) < OVERLAY_RECT_ANGLE_EPSILON_DEG
  );
 }

@@ -228,6 +477,17 @@ export function groupAwareOverlayRect(
  return { ...union, editScaleX: rect.editScaleX, editScaleY: rect.editScaleY };
 }

+/** Groups stay axis-aligned unions; ordinary elements keep their oriented box. */
+export function orientedGroupAwareOverlayRect(
+  overlayEl: HTMLDivElement,
+  iframe: HTMLIFrameElement,
+  el: HTMLElement,
+): OverlayRect | null {
+  return el.hasAttribute("data-hf-group")
+    ? groupAwareOverlayRect(overlayEl, iframe, el)
+    : orientedOverlayRect(overlayEl, iframe, el);
+}
+
 export function filterNestedDomEditGroupItems<T extends { element: HTMLElement }>(items: T[]): T[] {
  return items.filter(
    (item) => !items.some((other) => other !== item && other.element.contains(item.element)),