@hyperframes/studio 0.8.108 → 0.8.109

package/dist/ui.js

@@ -30,7 +30,7 @@ import {
   fieldBase,
   fieldText,
   popupSurface
-} from "./chunk-NCUBAVGK.js";
+} from "./chunk-5VSXRGIX.js";
 import "./chunk-PZ5AY32C.js";
 export {
   Button,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/studio",
-  "version": "0.8.108",
+  "version": "0.8.109",
   "description": "",
   "repository": {
     "type": "git",
@@ -60,12 +60,12 @@
     "dockview-react": "8.3.1",
     "gsap": "^3.13.0",
     "mediabunny": "^1.45.3",
-    "@hyperframes/core": "0.8.108",
-    "@hyperframes/parsers": "0.8.108",
-    "@hyperframes/player": "0.8.108",
-    "@hyperframes/sdk": "0.8.108",
-    "@hyperframes/studio-server": "0.8.108",
-    "@hyperframes/shader-transitions": "0.8.108"
+    "@hyperframes/core": "0.8.109",
+    "@hyperframes/parsers": "0.8.109",
+    "@hyperframes/sdk": "0.8.109",
+    "@hyperframes/shader-transitions": "0.8.109",
+    "@hyperframes/player": "0.8.109",
+    "@hyperframes/studio-server": "0.8.109"
   },
   "devDependencies": {
     "@tailwindcss/vite": "^4.3.3",
@@ -81,7 +81,7 @@
     "vite": "^6.4.2",
     "vitest": "^4.1.11",
     "zustand": "^5.0.0",
-    "@hyperframes/producer": "0.8.108"
+    "@hyperframes/producer": "0.8.109"
   },
   "peerDependencies": {
     "react": "19",

package/src/App.tsx

@@ -17,11 +17,7 @@ import { useFileManager } from "./hooks/useFileManager";
 import { usePreviewPersistence } from "./hooks/usePreviewPersistence";
 import { usePreviewDocumentVersion } from "./hooks/usePreviewDocumentVersion";
 import { useTimelineEditing } from "./hooks/useTimelineEditing";
-import {
-  persistTimelineMoveEditsAtomically,
-  type TimelineMoveEditsHandler,
-  type TimelineMoveOperation,
-} from "./hooks/timelineMoveAdapter";
+import { useTimelineMoveEditsHandler } from "./hooks/timelineMoveAdapter";
 import type { TimelineZIndexReorderCommit } from "./hooks/useTimelineEditingTypes";
 import type { BlockPreviewInfo } from "./components/sidebar/BlocksTab";
 import { useDomEditSession } from "./hooks/useDomEditSession";
@@ -179,12 +175,8 @@ export function StudioApp({ readOnlyPreview = false, readOnlyPreviewReason }: St
     invalidateGsapCache,
     handleDomZIndexReorderCommitRef,
   });
-  const handleTimelineElementsMove: TimelineMoveEditsHandler = useCallback(
-    async (edits, coalesceKey, operation: TimelineMoveOperation = "timing", coalesceMs) => {
-      const deps = { handleTimelineGroupMove: timelineEditing.handleTimelineGroupMove };
-      await persistTimelineMoveEditsAtomically(edits, coalesceKey, operation, deps, coalesceMs);
-    },
-    [timelineEditing.handleTimelineGroupMove],
+  const handleTimelineElementsMove = useTimelineMoveEditsHandler(
+    timelineEditing.handleTimelineGroupMove,
   );
   const {
     addAssetAtPlayhead: handleAddAssetAtPlayhead,
@@ -246,6 +238,8 @@ export function StudioApp({ readOnlyPreview = false, readOnlyPreviewReason }: St
   });
   const appHotkeys = useAppHotkeys({
     handleTimelineElementsDelete: timelineEditing.handleTimelineElementsDelete,
+    handleLinkEdit: timelineEditing.handleLinkEdit,
+    handleTimelineElementDeleteOnly: timelineEditing.handleTimelineElementDeleteOnly,
     handleTimelineElementSplit: timelineEditing.handleTimelineElementSplit,
     handleDomEditElementDelete: domEditDeleteBridge,
     domEditSelectionRef: domEditSelectionBridgeRef,
@@ -553,6 +547,8 @@ export function StudioApp({ readOnlyPreview = false, readOnlyPreviewReason }: St
                   handleRazorSplit={timelineEditing.handleRazorSplit}
                   handleRazorSplitAll={timelineEditing.handleRazorSplitAll}
                   handleFreezeFrame={timelineEditing.handleFreezeFrame}
+                  handleLinkEdit={timelineEditing.handleLinkEdit}
+                  handleTimelineElementDeleteOnly={timelineEditing.handleTimelineElementDeleteOnly}
                   onCopyClip={handleCopy}
                   onPasteClip={handlePaste}
                   onDuplicateClip={handleDuplicate}

package/src/components/EditorShell.tsx

@@ -104,6 +104,8 @@ export function EditorShell({
   handleRazorSplit,
   handleRazorSplitAll,
   handleFreezeFrame,
+  handleLinkEdit,
+  handleTimelineElementDeleteOnly,
   onCopyClip,
   onPasteClip,
   onDuplicateClip,
@@ -165,6 +167,8 @@ export function EditorShell({
     handleRazorSplit,
     handleRazorSplitAll,
     handleFreezeFrame,
+    handleLinkEdit,
+    handleTimelineElementDeleteOnly,
   });
 
   return (

package/src/components/LinkedSelectionToggle.tsx

@@ -0,0 +1,73 @@
+import { useCallback, useState } from "react";
+import { createPortal } from "react-dom";
+import { LinkSimple } from "@phosphor-icons/react";
+import { useContextMenuDismiss } from "../hooks/useContextMenuDismiss";
+import { useMenuKeyboardNav } from "../player/components/menuKeyboardNav";
+import { useLinkedClipPreferences } from "../utils/linkedClipPreferences";
+import { Tooltip } from "./ui";
+import { flatActive, flatIdle } from "./timelineToolbarStyles";
+
+function SyncIndicatorMenu({ x, y, onClose }: { x: number; y: number; onClose: () => void }) {
+  const menuRef = useContextMenuDismiss(onClose);
+  useMenuKeyboardNav(menuRef);
+  const visible = useLinkedClipPreferences((s) => s.syncIndicatorsVisible);
+  const setVisible = useLinkedClipPreferences((s) => s.setSyncIndicatorsVisible);
+  return createPortal(
+    <div
+      ref={menuRef}
+      role="menu"
+      aria-label="Linked clips"
+      className="fixed z-200 min-w-[200px] rounded-sm border border-neutral-700 bg-neutral-900 py-1 shadow-lg"
+      style={{ left: x, top: y }}
+    >
+      <button
+        type="button"
+        role="menuitemcheckbox"
+        aria-checked={visible}
+        className="flex w-full items-center gap-2 px-3 py-1.5 text-left text-xs text-neutral-300 outline-hidden hover:bg-neutral-800 focus-visible:bg-neutral-800"
+        onClick={() => {
+          setVisible(!visible);
+          onClose();
+        }}
+      >
+        <span className="w-3 text-studio-accent">{visible ? "✓" : ""}</span>
+        Show out-of-sync indicators
+      </button>
+    </div>,
+    document.body,
+  );
+}
+
+/** Premiere's Linked Selection; right-click holds the out-of-sync indicator preference. */
+export function LinkedSelectionToggle() {
+  const linkedSelection = useLinkedClipPreferences((s) => s.linkedSelection);
+  const setLinkedSelection = useLinkedClipPreferences((s) => s.setLinkedSelection);
+  const [menuAt, setMenuAt] = useState<{ x: number; y: number } | null>(null);
+  const closeMenu = useCallback(() => setMenuAt(null), []);
+  return (
+    <>
+      <Tooltip
+        label={
+          linkedSelection
+            ? "Linked Selection on — a click selects both halves (⌥-click for one)"
+            : "Linked Selection off — a click selects one clip"
+        }
+      >
+        <button
+          type="button"
+          onClick={() => setLinkedSelection(!linkedSelection)}
+          onContextMenu={(e) => {
+            e.preventDefault();
+            setMenuAt({ x: e.clientX, y: e.clientY });
+          }}
+          aria-label="Linked Selection"
+          aria-pressed={linkedSelection}
+          className={linkedSelection ? flatActive : flatIdle}
+        >
+          <LinkSimple size={16} weight="bold" aria-hidden="true" />
+        </button>
+      </Tooltip>
+      {menuAt && <SyncIndicatorMenu x={menuAt.x} y={menuAt.y} onClose={closeMenu} />}
+    </>
+  );
+}

package/src/components/TimelineToolbar.test.tsx

@@ -391,3 +391,34 @@ describe("TimelineToolbar add beat", () => {
     act(() => root.unmount());
   });
 });
+
+describe("TimelineToolbar Linked Selection", () => {
+  it("is on by default, first among the editing toggles, and persists a click", async () => {
+    const { useLinkedClipPreferences } = await import("../utils/linkedClipPreferences");
+    const { host } = renderToolbar();
+    const button = host.querySelector<HTMLButtonElement>('button[aria-label="Linked Selection"]');
+    expect(button?.getAttribute("aria-pressed")).toBe("true");
+    const snapping = host.querySelector('button[aria-label="Toggle timeline snapping"]');
+    expect(snapping && button?.compareDocumentPosition(snapping)).toBe(
+      Node.DOCUMENT_POSITION_FOLLOWING,
+    );
+    act(() => button?.dispatchEvent(new MouseEvent("click", { bubbles: true })));
+    expect(button?.getAttribute("aria-pressed")).toBe("false");
+    expect(readStudioUiPreferences().linkedSelectionEnabled).toBe(false);
+    act(() => useLinkedClipPreferences.getState().setLinkedSelection(true));
+  });
+
+  it("right-click toggles the out-of-sync indicator preference", async () => {
+    const { useLinkedClipPreferences } = await import("../utils/linkedClipPreferences");
+    const { host } = renderToolbar();
+    const button = host.querySelector('button[aria-label="Linked Selection"]');
+    act(() => button?.dispatchEvent(new MouseEvent("contextmenu", { bubbles: true })));
+    const item = document.querySelector<HTMLButtonElement>('[role="menuitemcheckbox"]');
+    expect(item?.textContent).toContain("Show out-of-sync indicators");
+    expect(item?.getAttribute("aria-checked")).toBe("true");
+    act(() => item?.click());
+    expect(useLinkedClipPreferences.getState().syncIndicatorsVisible).toBe(false);
+    expect(readStudioUiPreferences().syncIndicatorsVisible).toBe(false);
+    act(() => useLinkedClipPreferences.getState().setSyncIndicatorsVisible(true));
+  });
+});

package/src/components/TimelineToolbar.tsx

@@ -31,6 +31,7 @@ import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
 import type { DomEditSelection } from "./editor/domEditingTypes";
 import { canSplitElement } from "../utils/timelineElementSplit";
 import { useAudioMetersVisible } from "../utils/audioMeterVisibility";
+import { LinkedSelectionToggle } from "./LinkedSelectionToggle";
 import { useProjectHasAudio } from "../utils/audioMeterMath";
 import { canAddBeatAt, addBeatAtCompositionTime } from "../utils/beatEditActions";
 import { isTypingTarget } from "../utils/typingTarget";
@@ -218,6 +219,7 @@ export function TimelineToolbar({
           <TimelineToolPicker showSelectAroundPlayhead={showSelectAroundPlayhead} />
           {/* Divider: tool-mode | editing-actions */}
           <div aria-hidden="true" className="mx-1 h-4 w-px bg-neutral-800" />
+          <LinkedSelectionToggle />
           <Tooltip label={timelineSnapEnabled ? "Snapping on (N)" : "Snapping off (N)"}>
             <button
               type="button"

package/src/components/editor/InlineTextCaret.test.tsx

@@ -0,0 +1,150 @@
+// @vitest-environment happy-dom
+
+import React, { act } from "react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { cleanupMounted, trackedRoot } from "../ui/mountHost.testHelpers";
+import { CARET_PX, InlineTextCaret } from "./InlineTextCaret";
+import type { InlineTextEditSession } from "../../hooks/useInlineTextEdit";
+
+(globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+afterEach(() => {
+  // Unmount before clearing the body: the caret is portaled there, so clearing first orphans React's node.
+  cleanupMounted();
+  document.body.innerHTML = "";
+  vi.restoreAllMocks();
+});
+
+/** A frame showing the composition at a quarter of its width, from 100,50 on Studio's screen. */
+function fakeFrame() {
+  const iframe = document.body.appendChild(document.createElement("iframe"));
+  iframe.getBoundingClientRect = () =>
+    ({ left: 100, top: 50, width: window.innerWidth / 4 }) as DOMRect;
+  return iframe;
+}
+
+/** A text open for editing in a fake frame shown at a quarter of the composition's width, its caret after "Ti". */
+function scene() {
+  document.body.innerHTML = `<h1 contenteditable="true" style="color: rgb(250, 250, 250)">Title</h1>`;
+  const element = document.body.firstElementChild as HTMLElement;
+  const iframe = fakeFrame();
+  vi.spyOn(Range.prototype, "getClientRects").mockReturnValue([
+    { left: 400, top: 200, height: 120 },
+  ] as unknown as DOMRectList);
+  element.focus();
+  const text = element.firstChild as Text;
+  window.getSelection()!.collapse(text, 2);
+  const session: InlineTextEditSession = {
+    element,
+    original: "Title",
+    outline: "",
+    outlineOffset: "",
+  };
+  return { element, iframe, session, text };
+}
+
+function render(session: InlineTextEditSession | null, iframe: HTMLIFrameElement | null) {
+  const root = trackedRoot(document.body.appendChild(document.createElement("div")));
+  act(() => root.render(<InlineTextCaret session={session} iframe={iframe} />));
+  return { root, caret: () => document.querySelector<HTMLElement>("[data-inline-text-caret]") };
+}
+
+const fire = (target: EventTarget, type: string) =>
+  act(() => void target.dispatchEvent(new Event(type)));
+
+describe("InlineTextCaret", () => {
+  it("draws a 2 px caret on Studio's screen where the composition's caret stands, in the text's colour", () => {
+    const { iframe, session } = scene();
+    const caret = render(session, iframe).caret();
+    expect(caret).not.toBeNull();
+    expect(caret!.style.left).toBe(`${100 + 400 / 4 - CARET_PX / 2}px`);
+    expect(caret!.style.top).toBe(`${50 + 200 / 4}px`);
+    expect(caret!.style.height).toBe(`${120 / 4}px`);
+    expect(caret!.style.width).toBe(`${CARET_PX}px`);
+    expect(caret!.style.background).toBe("rgb(250, 250, 250)");
+  });
+
+  it("follows a pan or zoom of the preview, which moves the iframe with no event", async () => {
+    const { iframe, session } = scene();
+    const caret = render(session, iframe).caret;
+    iframe.getBoundingClientRect = () =>
+      ({ left: 140, top: 50, width: window.innerWidth / 4 }) as DOMRect;
+    await act(() => new Promise((done) => requestAnimationFrame(() => done(undefined))));
+    expect(caret()!.style.left).toBe(`${140 + 400 / 4 - CARET_PX / 2}px`);
+  });
+
+  it("after End at a soft wrap the caret stands at the earlier line's end; after Home, at the next line's start", () => {
+    const { element, iframe, session } = scene();
+    // A collapsed range at a wrap point has the next line's box; the character before it ends the earlier line.
+    vi.spyOn(Range.prototype, "getClientRects").mockImplementation(function (this: Range) {
+      return (this.collapsed
+        ? [{ left: 0, top: 320, height: 120 }]
+        : [{ left: 300, right: 400, top: 200, height: 120 }]) as unknown as DOMRectList;
+    });
+    const caret = render(session, iframe).caret;
+    const press = (key: string) => {
+      act(() => void element.dispatchEvent(new KeyboardEvent("keydown", { key })));
+      fire(document, "selectionchange");
+    };
+    press("End");
+    expect([caret()!.style.left, caret()!.style.top]).toEqual([
+      `${100 + 400 / 4 - CARET_PX / 2}px`,
+      `${50 + 200 / 4}px`,
+    ]);
+    press("Shift");
+    expect(caret()!.style.top, "a modifier alone keeps the side").toBe(`${50 + 200 / 4}px`);
+    press("Home");
+    expect([caret()!.style.left, caret()!.style.top]).toEqual([
+      `${100 - CARET_PX / 2}px`,
+      `${50 + 320 / 4}px`,
+    ]);
+  });
+
+  it("shows no caret while a range is selected, and again once the selection collapses", () => {
+    const { iframe, session, text } = scene();
+    const { caret } = render(session, iframe);
+    act(() => window.getSelection()!.setBaseAndExtent(text, 0, text, 3));
+    fire(document, "selectionchange");
+    expect(caret()).toBeNull();
+    act(() => window.getSelection()!.collapse(text, 3));
+    fire(document, "selectionchange");
+    expect(caret()).not.toBeNull();
+  });
+
+  it("shows no caret while an input method composes, nor once the text loses focus", () => {
+    const { element, iframe, session } = scene();
+    const { caret } = render(session, iframe);
+    fire(element, "compositionstart");
+    expect(caret()).toBeNull();
+    fire(element, "compositionend");
+    expect(caret()).not.toBeNull();
+    act(() => element.blur());
+    fire(element, "blur");
+    expect(caret()).toBeNull();
+  });
+
+  it("hides the browser's own caret while it draws one, and gives it back after", () => {
+    const { element, iframe, session } = scene();
+    element.style.caretColor = "red";
+    const { root } = render(session, iframe);
+    expect(element.style.caretColor).toBe("transparent");
+    act(() => root.render(<InlineTextCaret session={null} iframe={iframe} />));
+    expect(element.style.caretColor).toBe("red");
+  });
+
+  it("stands at the end of a bold word when the caret is past it, where no box of its own is drawn", () => {
+    document.body.innerHTML = `<h1 contenteditable="true">Go <strong>bold</strong></h1>`;
+    const element = document.body.firstElementChild as HTMLElement;
+    const iframe = fakeFrame();
+    vi.spyOn(Range.prototype, "getClientRects").mockImplementation(function (this: Range) {
+      const rects = this.collapsed ? [] : [{ left: 300, right: 500, top: 200, height: 120 }];
+      return rects as unknown as DOMRectList;
+    });
+    element.focus();
+    window.getSelection()!.collapse(element, element.childNodes.length);
+    const session = { element, original: "", outline: "", outlineOffset: "" };
+    const caret = render(session, iframe).caret();
+    expect(caret!.style.left).toBe(`${100 + 500 / 4 - CARET_PX / 2}px`);
+    expect(caret!.style.top).toBe(`${50 + 200 / 4}px`);
+  });
+});

package/src/components/editor/InlineTextCaret.tsx

@@ -0,0 +1,211 @@
+import { useEffect, useState } from "react";
+import { createPortal } from "react-dom";
+import type { InlineTextEditSession } from "../../hooks/useInlineTextEdit";
+
+/** The drawn caret's width on screen, whatever the preview's scale. */
+export const CARET_PX = 2;
+
+interface CaretPlacement {
+  left: number;
+  top: number;
+  height: number;
+  color: string;
+}
+
+/**
+ * The caret of a text edited in place, drawn at screen size: the preview is scaled, so the browser's 1 px caret
+ * shrinks below a pixel. This one follows the real selection; the browser's own is transparent meanwhile.
+ */
+export function InlineTextCaret({
+  session,
+  iframe,
+}: {
+  session: InlineTextEditSession | null;
+  iframe: HTMLIFrameElement | null;
+}) {
+  const [placement, setPlacement] = useState<CaretPlacement | null>(null);
+  const element = session?.element ?? null;
+
+  useEffect(() => {
+    if (!element || !iframe) {
+      setPlacement(null);
+      return;
+    }
+    const doc = element.ownerDocument;
+    const view = doc.defaultView;
+    const studio = iframe.ownerDocument.defaultView;
+    const color = caretColorOf(element);
+    const ownCaret = element.style.caretColor;
+    element.style.caretColor = "transparent";
+    let composing = false;
+    let side: CaretSide = "after";
+    const update = () =>
+      setPlacement(composing ? null : placeAtCaret(element, iframe, color, side));
+    // The DOM has no side for a soft-wrap point (one line's end is the next one's start): the key that moved there
+    // says which, as CodeMirror and ProseMirror keep it.
+    const onKey = ({ key }: KeyboardEvent) => {
+      if (!MODIFIERS.has(key)) side = SIDE_OF_KEY[key] ?? "after";
+    };
+    const onPress = () => void (side = "after");
+    const composition = (on: boolean) => () => {
+      composing = on;
+      update();
+    };
+    const start = composition(true);
+    const end = composition(false);
+    // The preview moves by transforms (the player's scale, a pan or zoom of the stage) that fire no event: the iframe's
+    // box is checked each frame and a move re-places the caret.
+    let box = "";
+    let frame = 0;
+    const follow = () => {
+      const { left, top, width, height } = iframe.getBoundingClientRect();
+      const now = `${left},${top},${width},${height}`;
+      if (now !== box) {
+        box = now;
+        update();
+      }
+      frame = studio?.requestAnimationFrame(follow) ?? 0;
+    };
+    doc.addEventListener("selectionchange", update);
+    element.addEventListener("keydown", onKey);
+    element.addEventListener("pointerdown", onPress);
+    element.addEventListener("input", update);
+    element.addEventListener("focus", update);
+    element.addEventListener("blur", update);
+    element.addEventListener("compositionstart", start);
+    element.addEventListener("compositionend", end);
+    view?.addEventListener("resize", update);
+    view?.addEventListener("scroll", update, true);
+    follow();
+    return () => {
+      studio?.cancelAnimationFrame(frame);
+      doc.removeEventListener("selectionchange", update);
+      element.removeEventListener("keydown", onKey);
+      element.removeEventListener("pointerdown", onPress);
+      element.removeEventListener("input", update);
+      element.removeEventListener("focus", update);
+      element.removeEventListener("blur", update);
+      element.removeEventListener("compositionstart", start);
+      element.removeEventListener("compositionend", end);
+      view?.removeEventListener("resize", update);
+      view?.removeEventListener("scroll", update, true);
+      element.style.caretColor = ownCaret;
+    };
+  }, [element, iframe]);
+
+  if (!placement || !iframe) return null;
+  // On Studio's body: a transformed ancestor in the canvas would make `fixed` relative to itself, not the viewport.
+  return createPortal(
+    <div
+      // Keyed on where it stands, so each move starts the blink lit, as the system caret does.
+      key={`${placement.left},${placement.top}`}
+      data-inline-text-caret="true"
+      aria-hidden="true"
+      className="hf-inline-text-caret pointer-events-none fixed z-200"
+      style={{
+        left: placement.left,
+        top: placement.top,
+        width: CARET_PX,
+        height: placement.height,
+        background: placement.color,
+      }}
+    />,
+    iframe.ownerDocument.body,
+  );
+}
+
+/** The colour the browser would draw its caret in: `caret-color`, or the text's colour when that is `auto`. */
+function caretColorOf(element: HTMLElement): string {
+  const style = element.ownerDocument.defaultView?.getComputedStyle(element);
+  if (!style) return "currentColor";
+  return style.caretColor && style.caretColor !== "auto" ? style.caretColor : style.color;
+}
+
+type CaretSide = "before" | "after";
+const MODIFIERS = new Set(["Shift", "Control", "Alt", "Meta"]);
+// Only End leaves Chrome's own caret at the earlier line's end; an arrow onto a wrap point lands on the next line.
+const SIDE_OF_KEY: Record<string, CaretSide> = { End: "before" };
+
+/** Where the caret stands on Studio's screen, or null when there is none to draw: a range selected, the text not
+ * focused, or the selection outside it. */
+
+function placeAtCaret(
+  element: HTMLElement,
+  iframe: HTMLIFrameElement,
+  color: string,
+  side: CaretSide,
+): CaretPlacement | null {
+  const view = element.ownerDocument.defaultView;
+  const range = view ? caretRange(element, view) : null;
+  if (!view || !range) return null;
+  const rect = (side === "before" && endOfCharBefore(range)) || caretRect(range, element, view);
+  const box = iframe.getBoundingClientRect();
+  const scale = view.innerWidth ? box.width / view.innerWidth : 1;
+  return {
+    left: box.left + rect.left * scale - CARET_PX / 2,
+    top: box.top + rect.top * scale,
+    height: rect.height * scale,
+    color,
+  };
+}
+
+/** The collapsed range's box on its line. A caret between two nodes has none, so it stands beside them; an empty
+ * text has neither, so it stands at the text's start, one line tall. */
+function caretRect(range: Range, element: HTMLElement, view: Window) {
+  const last = [...range.getClientRects()].reverse().find((rect) => rect.height > 0);
+  if (last) return { left: last.left, top: last.top, height: last.height };
+  const beside = besideNode(range);
+  if (beside) return beside;
+  const style = view.getComputedStyle(element);
+  const box = element.getBoundingClientRect();
+  const fontSize = Number.parseFloat(style.fontSize) || 16;
+  const line = Number.parseFloat(style.lineHeight) || fontSize * 1.2;
+  return {
+    left: box.left + (Number.parseFloat(style.paddingLeft) || 0),
+    top: box.top + (Number.parseFloat(style.paddingTop) || 0),
+    height: line,
+  };
+}
+
+function caretRange(element: HTMLElement, view: Window): Range | null {
+  const doc = element.ownerDocument;
+  const selection = view.getSelection();
+  if (!selection || selection.rangeCount === 0 || !selection.isCollapsed) return null;
+  if (!doc.hasFocus() || !element.contains(doc.activeElement)) return null;
+  const range = selection.getRangeAt(0);
+  return element.contains(range.startContainer) ? range : null;
+}
+
+/** The right edge of the character just before a collapsed range in a text node: where a caret that came from
+ * before a soft-wrap point stands, at the end of the earlier line. */
+function endOfCharBefore({ startContainer: at, startOffset: offset }: Range) {
+  if (at.nodeType !== Node.TEXT_NODE || offset === 0) return null;
+  const char = at.ownerDocument!.createRange();
+  // An emoji's second half alone has no box: take the whole pair.
+  const low = /[\uDC00-\uDFFF]/.test((at as Text).data[offset - 1] ?? "");
+  char.setStart(at, offset - (low && offset > 1 ? 2 : 1));
+  char.setEnd(at, offset);
+  // A trailing space at a wrap has a box on each line; the earlier line's comes first.
+  const rect = [...char.getClientRects()].find((each) => each.height > 0);
+  return rect ? { left: rect.right, top: rect.top, height: rect.height } : null;
+}
+
+/** At an element boundary: the end of the node before, or the start of the node after (a line break's own line). */
+function besideNode(range: Range) {
+  const [before, after] = neighbours(range);
+  const node = before && before.nodeName !== "BR" ? before : (after ?? before);
+  if (!node) return null;
+  const around = range.cloneRange();
+  around.selectNode(node);
+  const rects = [...around.getClientRects()].filter((rect) => rect.height > 0);
+  const end = node === before;
+  const rect = end ? rects.at(-1) : rects[0];
+  return rect ? { left: end ? rect.right : rect.left, top: rect.top, height: rect.height } : null;
+}
+
+/** The nodes either side of a collapsed range; an empty text node is a boundary too, between its siblings. */
+function neighbours({ startContainer: at, startOffset: offset }: Range) {
+  return at.nodeType === Node.TEXT_NODE
+    ? [at.previousSibling, at.nextSibling]
+    : [at.childNodes[offset - 1] ?? null, at.childNodes[offset] ?? null];
+}