Files
hyperframes/packages/studio-server/src/helpers/sourceMutation.ts
T

804 lines
31 KiB
TypeScript

import { replacementTimelineAssetId } from "@hyperframes/core/timeline-asset-id";
import { parseHTML } from "linkedom";
import { removeElementWithGsapCascade } from "@hyperframes/parsers";
import { readMediaOffsetSeconds, readPlaybackRate } from "@hyperframes/parsers/media-duration";
import postcss from "postcss";
import selectorParser from "postcss-selector-parser";
import { isAllowedHtmlAttribute, isSafeAttributeValue } from "@hyperframes/core/html-attr-safety";
import { sanitizeRichTextChildren } from "@hyperframes/core/rich-text-sanitize";
import {
EXCLUDED_TAGS,
ensureHfIds,
mintHfId,
walkCompositionDescendants,
} from "@hyperframes/parsers/hf-ids";
import { readClipTiming, writeClipTiming } from "@hyperframes/core/composition-contract";
import { relinkSplitHalves } from "@hyperframes/core/media-link";
import { parseStyleDecls, patchStyleAttrString } from "./sourceStyleMutation.js";
export interface SourceMutationTarget {
id?: string | null;
hfId?: string;
selector?: string;
selectorIndex?: number;
}
const pinnedInSource = new WeakMap<Document, ReadonlySet<string>>();
export function parseSourceDocument(raw: string): {
document: Document;
wrappedFragment: boolean;
} {
const source = ensureHfIds(raw);
const hasDocumentShell = /<!doctype|<html[\s>]/i.test(source);
const document = hasDocumentShell
? parseHTML(source).document
: parseHTML(`<!DOCTYPE html><html><head></head><body>${source}</body></html>`).document;
pinnedInSource.set(
document,
new Set(Array.from(raw.matchAll(/\bdata-hf-id\s*=\s*["']?([^"'\s>]+)/gi), (m) => m[1]!)),
);
return { document, wrappedFragment: !hasDocumentShell };
}
function duplicateCssRulesForId(document: Document, originalId: string, newId: string): void {
const idToken = `#${originalId}`;
const transform = selectorParser((selectors) => {
selectors.walkIds((node) => {
if (node.value === originalId) node.value = newId;
});
});
for (const styleEl of document.querySelectorAll("style")) {
const css = styleEl.textContent ?? "";
let root: postcss.Root;
try {
root = postcss.parse(css);
} catch {
continue;
}
const clones: postcss.Rule[] = [];
root.walkRules((rule) => {
if (!rule.selector.includes(idToken)) return;
const newSelector = transform.processSync(rule.selector);
if (newSelector === rule.selector) return;
const clone = rule.clone({ selector: newSelector });
clones.push(clone);
});
if (clones.length > 0) {
for (const c of clones) root.append(c);
styleEl.textContent = root.toString();
}
}
}
function querySelectorAllWithTemplates(root: Document | Element, selector: string): Element[] {
const matches = Array.from(root.querySelectorAll(selector));
if (matches.length > 0) return matches;
// querySelectorAll doesn't traverse <template> content in linkedom.
// Search directly on each template element (NOT .content — removing from
// .content's DocumentFragment doesn't update the serialized output).
// Recurse so NESTED templates resolve too — ensureHfIds and the SDK's
// querySelectorAllDeep descend nested composition templates, so ids exist at
// any template depth; a one-level search here would silently no-op
// server-side ops on those ids while the SDK resolves them.
const templates = Array.from(root.querySelectorAll("template"));
for (const tmpl of templates) {
const inner = querySelectorAllWithTemplates(tmpl, selector);
if (inner.length > 0) return inner;
}
return [];
}
// Prevent CSS attribute-selector injection via a crafted hfId: escape
// backslashes first, then double-quotes. Keeps a malformed/hostile value from
// breaking out of the `[data-hf-id="…"]` selector once callers beyond the
// internal mint contract (R2+ user flows) pass values here.
function escapeCssAttrValue(value: string): string {
return value.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
}
function findByHfId(document: Document, hfId: string): Element | null {
try {
const matches = querySelectorAllWithTemplates(
document,
`[data-hf-id="${escapeCssAttrValue(hfId)}"]`,
);
if (matches.length > 1) {
// The mint contract guarantees uniqueness; a duplicate means upstream
// id drift. Don't silently patch an arbitrary one — surface it.
// eslint-disable-next-line no-console
console.warn(
`sourceMutation: data-hf-id "${hfId}" matched ${matches.length} elements; using the first. ids must be unique per document.`,
);
}
return matches[0] ?? null;
} catch {
// Malformed selector despite escaping — let the caller fall back.
return null;
}
}
export function findTargetElement(
document: Document,
target: SourceMutationTarget,
): Element | null {
if (target.hfId) {
const el = findByHfId(document, target.hfId);
if (el) return el;
}
const pinned = pinnedInSource.get(document);
const unlessPinnedElsewhere = (el: Element | null | undefined) =>
el && !(target.hfId && pinned?.has(el.getAttribute("data-hf-id") ?? "")) ? el : null;
if (target.id) {
const byId = unlessPinnedElsewhere(document.getElementById(target.id));
if (byId) return byId;
}
if (!target.selector) return null;
try {
const matches = querySelectorAllWithTemplates(document, target.selector);
return unlessPinnedElsewhere(matches[target.selectorIndex ?? 0]);
} catch {
return null;
}
}
/**
* Removes every target in one parse and one serialization. A target nested inside one already
* removed no longer matches, which is a normal outcome rather than a failure.
*/
export function removeElementsFromHtml(
source: string,
targets: readonly SourceMutationTarget[],
): string {
const { document, wrappedFragment } = parseSourceDocument(source);
let removed = false;
for (const target of targets) {
const element = findTargetElement(document, target);
if (!element) continue;
removeElementWithGsapCascade(document, element);
removed = true;
}
if (!removed) return source;
return wrappedFragment ? document.body.innerHTML || "" : document.toString();
}
export function removeElementFromHtml(source: string, target: SourceMutationTarget): string {
return removeElementsFromHtml(source, [target]);
}
export function isHTMLElement(el: Node): el is HTMLElement {
const HTMLEl = el.ownerDocument?.defaultView?.HTMLElement;
return HTMLEl ? el instanceof HTMLEl : el.nodeType === 1 && "style" in el;
}
// A mount's id names the root it mounts; the runtime numbers repeated mounts (id__hf1, id__hf2).
function mountsComposition(document: Document, host: Element, compositionId: string): boolean {
if (host.hasAttribute("data-composition-src")) return true;
return (
host.children.length === 0 &&
querySelectorAllWithTemplates(document, "template").some(
(template) => template.id === `${compositionId}-template`,
)
);
}
export function dedupeClonedCompositionId(document: Document, clone: Element): void {
const compositionId = clone.getAttribute("data-composition-id");
if (!compositionId || mountsComposition(document, clone, compositionId)) return;
const usedCompositionIds = new Set(
querySelectorAllWithTemplates(document, "[data-composition-id]").map((node) =>
node.getAttribute("data-composition-id"),
),
);
const base = `${compositionId}-split`;
let nextCompositionId = base;
let suffix = 2;
while (usedCompositionIds.has(nextCompositionId)) nextCompositionId = `${base}-${suffix++}`;
clone.setAttribute("data-composition-id", nextCompositionId);
}
export interface PatchOperation {
/** `ensure-id` keeps the element's id, else writes `value` made unique in this file and `takenIds`. */
type:
| "inline-style"
| "attribute"
| "html-attribute"
| "text-content"
| "rich-text"
| "ensure-id";
property: string;
value: string | null;
childSelector?: string;
childIndex?: number;
}
interface ResolvedPatchOperation {
op: PatchOperation;
target: HTMLElement;
}
function resolveOperationTarget(parent: HTMLElement, op: PatchOperation): HTMLElement | null {
if (op.childSelector === undefined) return parent;
try {
const child = parent.querySelectorAll(op.childSelector)[op.childIndex ?? 0] ?? null;
return child && isHTMLElement(child) ? child : null;
} catch {
return null;
}
}
/**
* Give the elements a rich-text patch just introduced their stable ids, here,
* in the bytes about to be written and handed back.
*
* Otherwise the next preview request mints them and writes the file a second
* time, after Studio has already recorded the edit in its history. The recorded
* "after" stops matching disk, the content check refuses, and undo reports the
* file as changed outside Studio — for every colour applied to a run of
* characters and every text layer added. The clip split stamps its own clone
* for exactly this reason.
*
* Minted one element at a time with the same function `ensureHfIds` uses, so
* these ids are the ones the next pass would have assigned. Not `ensureHfIds`
* itself: it takes a whole document, and handing it this element's markup would
* put the markup back as one.
*/
function stampNewChildIds(parent: Element): void {
const assigned = new Set<string>();
const root = parent.ownerDocument?.body ?? parent;
walkCompositionDescendants(root, (el) => {
const id = el.getAttribute("data-hf-id");
if (id) assigned.add(id);
});
for (const el of parent.querySelectorAll("*")) {
if (el.getAttribute("data-hf-id")) continue;
if (EXCLUDED_TAGS.has(el.tagName.toLowerCase())) continue;
el.setAttribute("data-hf-id", mintHfId(el, assigned));
}
}
// fallow-ignore-next-line complexity
export function patchElementInHtml(
source: string,
target: SourceMutationTarget,
operations: PatchOperation[],
takenIds?: ReadonlySet<string>,
): { html: string; matched: boolean; elementId?: string | null } {
const { document, wrappedFragment } = parseSourceDocument(source);
const el = findTargetElement(document, target);
if (!el || !isHTMLElement(el)) return { html: source, matched: false };
const htmlEl = el;
const originalHtml = wrappedFragment ? document.body.innerHTML || "" : document.toString();
const resolved: ResolvedPatchOperation[] = [];
for (const op of operations) {
const opTarget = resolveOperationTarget(htmlEl, op);
if (!opTarget) return { html: source, matched: false };
resolved.push({ op, target: opTarget });
}
for (const { op, target: opTarget } of resolved) {
switch (op.type) {
case "inline-style":
// linkedom's CSSStyleDeclaration does not support CSS custom properties
// (--foo) or newer individual transform properties (translate, rotate,
// scale) via style.setProperty(). Manipulate the style attribute string
// directly so all property names survive the round-trip.
{
const raw = opTarget.getAttribute("style") ?? "";
const patched = patchStyleAttrString(raw, op.property, op.value);
opTarget.setAttribute("style", patched);
}
break;
case "attribute":
{
const fullAttr = op.property.startsWith("data-") ? op.property : `data-${op.property}`;
if (op.value != null) {
opTarget.setAttribute(fullAttr, op.value);
} else {
opTarget.removeAttribute(fullAttr);
}
}
break;
case "html-attribute":
if (!isAllowedHtmlAttribute(op.property)) break;
if (op.value != null) {
if (!isSafeAttributeValue(op.property, op.value)) break;
const replacementId =
op.property === "src" ? replacementTimelineAssetId(document, opTarget, op.value) : null;
if (replacementId !== null) opTarget.setAttribute("id", replacementId);
opTarget.setAttribute(op.property, op.value);
} else {
opTarget.removeAttribute(op.property);
}
break;
case "ensure-id":
if (opTarget.getAttribute("id") || !op.value) break;
opTarget.setAttribute("id", nextUniqueId(document, op.value, takenIds));
break;
case "text-content":
if (op.value != null) {
const inner = opTarget.children.length === 1 ? opTarget.firstElementChild : null;
const textTarget = inner && isHTMLElement(inner) ? inner : opTarget;
textTarget.textContent = op.value;
}
break;
// The one operation that can write markup, so the one that has to check
// it. Assigned first and sanitised after, rather than sanitising a
// string: parsing is what turns a payload into the tree the allowlist
// can actually judge, and linkedom never runs anything it parses.
case "rich-text":
if (op.value != null) {
opTarget.innerHTML = op.value;
sanitizeRichTextChildren(opTarget);
stampNewChildIds(opTarget);
}
break;
}
}
const html = wrappedFragment ? document.body.innerHTML || "" : document.toString();
const elementId = htmlEl.getAttribute("id");
if (html === originalHtml) return { html: source, matched: true, elementId };
return { html: ensureHfIds(html), matched: true, elementId };
}
export function nextUniqueId(
document: Document,
base: string,
takenIds?: ReadonlySet<string>,
): string {
let id = base;
let suffix = 2;
while (document.getElementById(id) || takenIds?.has(id)) id = `${base}-${suffix++}`;
return id;
}
/** Whether each target exists in `source`; the document is parsed once however many targets ask. */
export function probeElementsInSource(
source: string,
targets: readonly SourceMutationTarget[],
): boolean[] {
const { document } = parseSourceDocument(source);
return targets.map((target) => {
if (!target.id && !target.hfId && !target.selector) return false;
const el = findTargetElement(document, target);
return el != null && isHTMLElement(el);
});
}
export function probeElementInSource(source: string, target: SourceMutationTarget): boolean {
return probeElementsInSource(source, [target])[0] ?? false;
}
export interface SplitElementResult {
html: string;
matched: boolean;
newId: string | null;
}
function resolveElementTiming(el: Element): {
start: number;
duration: number;
} {
const timing = readClipTiming(el);
return { start: timing.start ?? 0, duration: timing.duration ?? 0 };
}
function setElementDuration(
el: Element,
start: number,
duration: number,
trackIndex?: number,
): void {
writeClipTiming(el, {
start: Math.round(start * 1000) / 1000,
duration: Math.round(duration * 1000) / 1000,
...(trackIndex != null ? { trackIndex } : {}),
});
}
/** True when the media has an authored window and the row's range (if given) is that window. */
function isWindowOf(
media: { start: number; duration: number },
row?: { start: number; duration: number },
): boolean {
if (media.duration <= 0) return false;
const near = (a: number, b: number) => Math.abs(a - b) < 0.001;
return !row || (near(media.start, row.start) && near(media.duration, row.duration));
}
// fallow-ignore-next-line complexity
export function splitElementInHtml(
source: string,
target: SourceMutationTarget,
splitTime: number,
newId: string,
fallbackTiming?: {
start: number;
duration: number;
playbackStart?: number;
playbackRate?: number;
// The element's current resolved track (authored, or the runtime's
// positional-index fallback when unauthored). Stamped onto both halves so
// inserting the clone can't shift either one to a different row — see
// parseAuthoredTrack's fallback in core/runtime/timeline.ts.
track?: number;
},
): SplitElementResult {
const { document, wrappedFragment } = parseSourceDocument(source);
const el = findTargetElement(document, target);
if (!el || !isHTMLElement(el)) return { html: source, matched: false, newId: null };
// An untimed wrapper whose row is its timed media's own window is a view of that
// media: cut the media and leave the wrappers untimed. A GSAP scene keeps its own window.
const timedMediaSelector = "video[data-start], audio[data-start]";
const innerMedia =
el.hasAttribute("data-start") ||
resolveElementTiming(el).duration > 0 ||
el.matches("[data-composition-src], [data-composition-id]")
? null
: el.querySelector(timedMediaSelector);
const timedMedia =
innerMedia && isWindowOf(resolveElementTiming(innerMedia), fallbackTiming) ? innerMedia : null;
const timed = timedMedia ?? el;
const timing = resolveElementTiming(timed);
let { start, duration } = timing;
// GSAP-animated elements carry their timing in the script, not in data-* attrs,
// so the source has no authored duration. Fall back to the store's (GSAP-derived)
// range — the runtime windows visibility off data-start/data-duration regardless
// of class, so stamping both halves below makes each half show only in its window.
if (duration <= 0 && fallbackTiming && fallbackTiming.duration > 0) {
start = fallbackTiming.start;
duration = fallbackTiming.duration;
}
if (duration <= 0 || splitTime <= start || splitTime >= start + duration) {
return { html: source, matched: false, newId: null };
}
newId = nextUniqueId(document, newId);
const firstDuration = splitTime - start;
const secondDuration = duration - firstDuration;
const clone = el.cloneNode(true);
if (!isHTMLElement(clone)) return { html: source, matched: false, newId: null };
clone.setAttribute("id", newId);
dedupeClonedCompositionId(document, clone);
clone.removeAttribute("data-hf-id");
// Descendants carry their own data-hf-id; leaving them duplicates the id of
// every nested node (e.g. an inner <span>), so strip them on the clone too.
for (const node of clone.querySelectorAll("[data-hf-id]")) node.removeAttribute("data-hf-id");
const clonedTimed = timedMedia ? clone.querySelector(timedMediaSelector)! : clone;
if (timedMedia?.id) {
const mediaId = nextUniqueId(document, `${timedMedia.id}-split`, new Set([newId]));
duplicateCssRulesForId(document, timedMedia.id, mediaId);
clonedTimed.setAttribute("id", mediaId);
}
setElementDuration(clonedTimed, splitTime, secondDuration, fallbackTiming?.track);
// Keep the "clip" class — the runtime uses it to control visibility
// based on data-start/data-duration timing.
// A split creates two views over the same media source or sub-composition.
// Even an untrimmed one needs an explicit zero in-point stamped on the first
// half so the second half can advance from it instead of restarting at zero.
const playbackStartAttr = timed.hasAttribute("data-playback-start")
? "data-playback-start"
: timed.hasAttribute("data-media-start")
? "data-media-start"
: timed.matches("[data-composition-src], [data-composition-id]")
? "data-playback-start"
: timed.matches("audio, video")
? "data-media-start"
: null;
if (playbackStartAttr) {
const readAttr = (name: string) => timed.getAttribute(name);
const authoredTrim = timed.getAttribute(playbackStartAttr);
const currentTrim =
authoredTrim !== null
? readMediaOffsetSeconds(readAttr)
: (fallbackTiming?.playbackStart ?? 0);
const rate = readPlaybackRate(readAttr, fallbackTiming?.playbackRate);
if (authoredTrim === null || Number(authoredTrim) !== currentTrim)
timed.setAttribute(playbackStartAttr, String(Math.round(currentTrim * 1000) / 1000));
clonedTimed.setAttribute(
playbackStartAttr,
String(Math.round((currentTrim + firstDuration * rate) * 1000) / 1000),
);
}
// Duplicate CSS rules targeting the original ID so the clone inherits the same styles.
const originalId = el.getAttribute("id");
if (originalId) {
duplicateCssRulesForId(document, originalId, newId);
}
// Trim the original element's duration. A GSAP element had no data-start; stamp
// it so the runtime windows the first half (visibility selects on [data-start]).
setElementDuration(timed, start, firstDuration, fallbackTiming?.track);
// Insert clone after original
if (el.nextSibling) {
el.parentElement!.insertBefore(clone, el.nextSibling);
} else {
el.parentElement!.appendChild(clone);
}
const html = wrappedFragment ? document.body.innerHTML || "" : document.toString();
return {
// The split owns its new nodes' stable ids. Leaving the clone unstamped makes
// the next preview request persist different bytes after history is recorded.
html: ensureHfIds(html),
matched: true,
newId,
};
}
// --- Element grouping -------------------------------------------------------
// A group is a real `<div data-hf-group="…">` wrapping its members in the DOM.
// Wrapping rebases each member's left/top so its absolute position is unchanged:
// the wrapper sits at the selection bbox top-left, and each child's new left/top
// is its old left/top minus the wrapper origin (computed client-side, where live
// layout is available, and passed in via `rebases`). GSAP x/y, CSS translate and
// --hf-studio-offset vars are deltas relative to flow position and stay untouched.
export interface WrapElementsResult {
html: string;
matched: boolean;
groupId: string | null;
error?: string;
}
export interface UnwrapElementsResult {
html: string;
unwrapped: boolean;
/** The unwrapped wrapper's id, so callers can strip GSAP that targeted it
* (the wrapper is gone; a leftover `gsap.set("#id")` would throw at runtime). */
unwrappedGroupId?: string;
/** Members (id'd children) with their absolute layout centres (post un-rebase),
* so the caller can BAKE the group's GSAP transform into each member before
* stripping it — otherwise the group's moves are lost on ungroup. */
members?: Array<{ id: string; cx: number; cy: number }>;
/** The wrapper's layout centre — the pivot for baking the group's rotation/scale. */
groupCenter?: { cx: number; cy: number };
}
export interface ElementRebase {
target: SourceMutationTarget;
left: number;
top: number;
/** The member's current resolved track (authored, or the runtime's
* positional-index fallback). Stamped explicitly so moving it into the
* wrapper can't shift its computed row — same hazard split closes. */
track?: number;
}
function getInlineStylePx(el: Element, property: string): number {
const style = (isHTMLElement(el) ? el.getAttribute("style") : null) ?? "";
const { props } = parseStyleDecls(style);
const raw = props.get(property);
if (!raw) return 0;
const n = parseFloat(raw);
return Number.isFinite(n) ? n : 0;
}
function setInlineLeftTop(el: HTMLElement, left: number, top: number): void {
let style = el.getAttribute("style") ?? "";
style = patchStyleAttrString(style, "left", `${left}px`);
style = patchStyleAttrString(style, "top", `${top}px`);
el.setAttribute("style", style);
}
// Slug the group name ("Group 1" → "group-1") into a unique, valid element id.
function uniqueGroupDomId(document: Document, groupId: string): string {
const base =
groupId
.trim()
.toLowerCase()
.replace(/[^a-z0-9]+/g, "-")
// Normalization above leaves at most one hyphen at either edge.
.replace(/^-|-$/g, "") || "group";
return nextUniqueId(document, base);
}
// fallow-ignore-next-line complexity
export function wrapElementsInHtml(
source: string,
targets: SourceMutationTarget[],
groupId: string,
bbox: { left: number; top: number; width: number; height: number },
rebases: ElementRebase[],
): WrapElementsResult {
const { document, wrappedFragment } = parseSourceDocument(source);
if (targets.length === 0) {
return { html: source, matched: false, groupId: null, error: "no targets" };
}
// Resolve + dedupe by element ref (two targets may point at the same node).
const els: HTMLElement[] = [];
const seen = new Set<Element>();
for (const target of targets) {
const el = findTargetElement(document, target);
if (!el || !isHTMLElement(el) || seen.has(el)) continue;
seen.add(el);
els.push(el);
}
if (els.length === 0) {
return { html: source, matched: false, groupId: null, error: "no targets matched" };
}
// P1: require a single common parent (LCA multi-parent wrapping is P2).
const parent = els[0]?.parentElement;
if (!parent || els.some((el) => el.parentElement !== parent)) {
return {
html: source,
matched: false,
groupId: null,
error: "grouped elements must share a single parent",
};
}
// Order members by their position in the parent (= z-order / stacking order).
const memberSet = new Set<Element>(els);
const ordered = Array.from(parent.children).filter((c): c is HTMLElement => memberSet.has(c));
// Map each member to its rebased left/top and track (resolved against the same document).
const rebaseByEl = new Map<Element, { left: number; top: number; track?: number }>();
for (const rebase of rebases) {
const el = findTargetElement(document, rebase.target);
if (el) rebaseByEl.set(el, { left: rebase.left, top: rebase.top, track: rebase.track });
}
const wrapper = document.createElement("div");
wrapper.setAttribute("data-hf-group", groupId);
// A real `id` (slug of the group name) makes the wrapper a first-class node in the
// clip manifest / timeline parent-map (both keyed by id) and a clean GSAP target —
// without it the wrapper is invisible to the timeline and breaks child enumeration.
wrapper.setAttribute("id", uniqueGroupDomId(document, groupId));
// Adopt the topmost member's stacking level. A group is one stacking unit, so a
// non-member interleaved between two selected members can't stay "between" them
// once they unify. Matching Figma/Sketch, the group lifts to the topmost selected
// layer: the wrapper goes at the LAST member's slot and carries the max member
// z-index — so an interleaved non-member falls below the group instead of hoisting
// above it, and explicit member z-indexes are honored.
const memberZIndexes = ordered
.map((el) =>
Number.parseInt(
parseStyleDecls(el.getAttribute("style") ?? "").props.get("z-index") ?? "",
10,
),
)
.filter((z) => Number.isFinite(z));
const maxZ = memberZIndexes.length > 0 ? Math.max(...memberZIndexes) : null;
wrapper.setAttribute(
"style",
`position: absolute; left: ${bbox.left}px; top: ${bbox.top}px; width: ${bbox.width}px; height: ${bbox.height}px` +
(maxZ !== null ? `; z-index: ${maxZ}` : ""),
);
// Insert the wrapper at the topmost member's slot, then move members into it.
parent.insertBefore(wrapper, ordered[ordered.length - 1] ?? null);
for (const el of ordered) {
const rebase = rebaseByEl.get(el);
if (rebase) setInlineLeftTop(el, rebase.left, rebase.top);
if (rebase?.track != null) writeClipTiming(el, { trackIndex: Math.round(rebase.track) });
wrapper.appendChild(el); // appendChild moves the node, preserving order
}
return {
html: wrappedFragment ? document.body.innerHTML || "" : document.toString(),
matched: true,
groupId,
};
}
export interface UnwrapChildTrack {
target: SourceMutationTarget;
/** The child's current resolved track, same hazard and fix as wrap's members. */
track?: number;
}
// Only children actually inside the group and given a resolved track qualify —
// same hazard and fix as wrap's members, scoped to this group's own children.
function buildChildTrackMap(
document: Document,
group: Element,
childTracks: UnwrapChildTrack[],
): Map<Element, number> {
const trackByEl = new Map<Element, number>();
for (const entry of childTracks) {
const el = findTargetElement(document, entry.target);
if (el && group.contains(el) && entry.track != null) trackByEl.set(el, entry.track);
}
return trackByEl;
}
// Undoes the wrap-side rebase (child absolute = child rebased + wrapper
// origin), stamps each child's resolved track where one was given, and moves
// every child back into the parent ahead of the wrapper — preserving order.
function relocateGroupChildren(
group: Element,
parent: Element,
wLeft: number,
wTop: number,
trackByEl: Map<Element, number>,
): Array<{ id: string; cx: number; cy: number }> {
const members: Array<{ id: string; cx: number; cy: number }> = [];
for (const child of Array.from(group.children)) {
if (isHTMLElement(child)) {
const newLeft = getInlineStylePx(child, "left") + wLeft;
const newTop = getInlineStylePx(child, "top") + wTop;
setInlineLeftTop(child, newLeft, newTop);
const track = trackByEl.get(child);
if (track != null) writeClipTiming(child, { trackIndex: Math.round(track) });
if (child.id) {
members.push({
id: child.id,
cx: newLeft + getInlineStylePx(child, "width") / 2,
cy: newTop + getInlineStylePx(child, "height") / 2,
});
}
}
parent.insertBefore(child, group);
}
return members;
}
export function unwrapElementsFromHtml(
source: string,
groupTarget: SourceMutationTarget,
childTracks: UnwrapChildTrack[] = [],
): UnwrapElementsResult {
const { document, wrappedFragment } = parseSourceDocument(source);
const group = findTargetElement(document, groupTarget);
if (!group || !isHTMLElement(group)) return { html: source, unwrapped: false };
// Shape guard mirroring the wrap-side contract: only ever dissolve an actual
// group wrapper. A stale/desynced selection that resolves to a plain <div>
// would otherwise be unwrapped — rebasing its children by the parent's origin
// (silent corruption). Wrap enforces invariants; unwrap must too.
if (!group.hasAttribute("data-hf-group")) return { html: source, unwrapped: false };
const parent = group.parentElement;
if (!parent) return { html: source, unwrapped: false };
const trackByEl = buildChildTrackMap(document, group, childTracks);
// Undo the rebase: child absolute position = child (rebased) + wrapper origin.
const wLeft = getInlineStylePx(group, "left");
const wTop = getInlineStylePx(group, "top");
const groupCenter = {
cx: wLeft + getInlineStylePx(group, "width") / 2,
cy: wTop + getInlineStylePx(group, "height") / 2,
};
const members = relocateGroupChildren(group, parent, wLeft, wTop, trackByEl);
const groupId = group.id || undefined;
group.remove();
return {
html: wrappedFragment ? document.body.innerHTML || "" : document.toString(),
unwrapped: true,
unwrappedGroupId: groupId,
members,
groupCenter,
};
}
/** After a cut, give each linked group's right halves their own `data-link` and `data-sync-origin`. */
export function relinkSplitHalvesInHtml(source: string, rightHalfIds: readonly string[]): string {
const { document, wrappedFragment } = parseSourceDocument(source);
const carriesPairing = (id: string) => {
const el = document.getElementById(id);
return Boolean(el?.hasAttribute("data-link") || el?.hasAttribute("data-sync-origin"));
};
if (!rightHalfIds.some(carriesPairing)) {
return source;
}
relinkSplitHalves(document, rightHalfIds);
return wrappedFragment ? document.body.innerHTML || "" : document.toString();
}