@hyperframes/studio 0.6.0 → 0.6.2

package/src/components/editor/domEditingAgentPrompt.ts

@@ -0,0 +1,97 @@
+/**
+ * Agent prompt builder for HyperFrames element edit requests.
+ */
+import { formatTime } from "../../player/lib/time";
+import type { DomEditSelection, DomEditTextField } from "./domEditingTypes";
+
+function formatBoundingBox(bounds: DomEditSelection["boundingBox"]): string {
+  return `x=${Math.round(bounds.x)}, y=${Math.round(bounds.y)}, width=${Math.round(bounds.width)}, height=${Math.round(bounds.height)}`;
+}
+
+function formatStyleBlock(styles: Record<string, string>): string {
+  return Object.entries(styles)
+    .filter(([, value]) => value && value !== "initial")
+    .map(([key, value]) => `${key}: ${value}`)
+    .join("\n");
+}
+
+function formatTextFields(fields: DomEditTextField[]): string {
+  return fields
+    .map(
+      (field) =>
+        `- key=${field.key}; tag=<${field.tagName}>; source=${field.source}; text=${JSON.stringify(field.value)}`,
+    )
+    .join("\n");
+}
+
+export function buildElementAgentPrompt({
+  selection,
+  currentTime,
+  tagSnippet,
+  selectionContext,
+  userInstruction,
+  sourceFilePath,
+}: {
+  selection: DomEditSelection;
+  currentTime: number;
+  tagSnippet?: string;
+  selectionContext?: string;
+  userInstruction?: string;
+  sourceFilePath?: string;
+}): string {
+  const displayedSourceFile = sourceFilePath?.trim() || selection.sourceFile;
+  const lines = [
+    "## HyperFrames element edit request v1",
+    "Schema version: 1",
+    "",
+    userInstruction?.trim() || "Edit this selected HyperFrames element.",
+    "",
+    `Composition: ${selection.compositionPath}`,
+    `Playback time: ${formatTime(currentTime)}`,
+    `Source file: ${displayedSourceFile}`,
+    `DOM id: ${selection.id ?? "(none)"}`,
+    `Selector: ${selection.selector ?? "(none)"}`,
+    `Selector index: ${selection.selectorIndex ?? 0}`,
+    `Tag: <${selection.tagName}>`,
+    `Bounds: ${formatBoundingBox(selection.boundingBox)}`,
+  ];
+
+  if (selection.textContent) {
+    lines.push(`Text: ${selection.textContent}`);
+  }
+
+  const trimmedSelectionContext = selectionContext?.trim();
+  if (trimmedSelectionContext) {
+    lines.push("", "Selection context:", trimmedSelectionContext);
+  }
+
+  const textFieldsBlock = formatTextFields(selection.textFields);
+  if (textFieldsBlock) {
+    lines.push("", "Text fields:", textFieldsBlock);
+  }
+
+  const inlineStyleBlock = formatStyleBlock(selection.inlineStyles);
+  if (inlineStyleBlock) {
+    lines.push("", "Inline styles:", inlineStyleBlock);
+  }
+
+  const computedStyleBlock = formatStyleBlock(selection.computedStyles);
+  if (computedStyleBlock) {
+    lines.push("", "Computed styles (browser-resolved):", computedStyleBlock);
+  }
+
+  if (tagSnippet) {
+    lines.push("", "Target HTML:", tagSnippet);
+  }
+
+  lines.push(
+    "",
+    "Guardrails:",
+    "- Make a targeted change to this element only.",
+    "- Preserve the rest of the composition and its timing.",
+    "- Do not modify other elements' data-* attributes or positioning.",
+    "- Prefer existing inline styles or existing CSS rules for this element over adding unrelated selectors.",
+  );
+
+  return lines.join("\n");
+}

package/src/components/editor/domEditingDom.ts

@@ -0,0 +1,266 @@
+/**
+ * Low-level DOM primitives: type guards, style getters, CSS escaping,
+ * selector utilities, and composition source resolution.
+ * No imports from other domEditing* modules — safe to import from anywhere.
+ */
+import { CURATED_STYLE_PROPERTIES } from "./domEditingTypes";
+
+// ─── Type guard ───────────────────────────────────────────────────────────────
+
+export function isHtmlElement(value: unknown): value is HTMLElement {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "nodeType" in value &&
+    typeof (value as { nodeType?: unknown }).nodeType === "number" &&
+    (value as { nodeType: number }).nodeType === 1
+  );
+}
+
+// ─── Style parsing ────────────────────────────────────────────────────────────
+
+export function parsePx(value: string | undefined): number | null {
+  if (!value) return null;
+  const trimmed = value.trim();
+  if (!trimmed.endsWith("px")) return null;
+  const parsed = parseFloat(trimmed);
+  return Number.isFinite(parsed) ? parsed : null;
+}
+
+export function isIdentityTransform(value: string | undefined): boolean {
+  const transform = (value ?? "none").trim();
+  if (!transform || transform === "none") return true;
+
+  const matrix = transform.match(/^matrix\(([^)]+)\)$/i);
+  if (matrix) {
+    const values = matrix[1].split(",").map((part) => Number.parseFloat(part.trim()));
+    if (values.length !== 6 || values.some((part) => !Number.isFinite(part))) return false;
+    return (
+      Math.abs(values[0] - 1) < 0.0001 &&
+      Math.abs(values[1]) < 0.0001 &&
+      Math.abs(values[2]) < 0.0001 &&
+      Math.abs(values[3] - 1) < 0.0001 &&
+      Math.abs(values[4]) < 0.0001 &&
+      Math.abs(values[5]) < 0.0001
+    );
+  }
+
+  const matrix3d = transform.match(/^matrix3d\(([^)]+)\)$/i);
+  if (!matrix3d) return false;
+  const values = matrix3d[1].split(",").map((part) => Number.parseFloat(part.trim()));
+  if (values.length !== 16 || values.some((part) => !Number.isFinite(part))) return false;
+  const identity = [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1];
+  return values.every((part, index) => Math.abs(part - identity[index]) < 0.0001);
+}
+
+export function isTextBearingTag(tagName: string): boolean {
+  return ["div", "span", "p", "strong", "h1", "h2", "h3", "h4", "h5", "h6"].includes(tagName);
+}
+
+// ─── Style accessors ──────────────────────────────────────────────────────────
+
+export function getCuratedComputedStyles(el: HTMLElement): Record<string, string> {
+  const styles: Record<string, string> = {};
+  const computed = el.ownerDocument.defaultView?.getComputedStyle(el);
+  if (!computed) return styles;
+
+  for (const prop of CURATED_STYLE_PROPERTIES) {
+    const value = computed.getPropertyValue(prop);
+    if (value) styles[prop] = value;
+  }
+
+  return styles;
+}
+
+export function getInlineStyles(el: HTMLElement): Record<string, string> {
+  const styles: Record<string, string> = {};
+  for (const property of CURATED_STYLE_PROPERTIES) {
+    const value = el.style.getPropertyValue(property);
+    if (value) styles[property] = value;
+  }
+  return styles;
+}
+
+export function getDataAttributes(el: HTMLElement): Record<string, string> {
+  const attrs: Record<string, string> = {};
+  for (const attr of el.attributes) {
+    if (attr.name.startsWith("data-")) {
+      attrs[attr.name.slice(5)] = attr.value;
+    }
+  }
+  return attrs;
+}
+
+// ─── DOM traversal ────────────────────────────────────────────────────────────
+
+export function findClosestByAttribute(
+  el: HTMLElement,
+  attributeNames: string[],
+): HTMLElement | null {
+  let current: HTMLElement | null = el;
+  while (current) {
+    const candidate = current;
+    if (attributeNames.some((attribute) => candidate.hasAttribute(attribute))) {
+      return candidate;
+    }
+    current = current.parentElement;
+  }
+  return null;
+}
+
+export function getElementDepth(el: HTMLElement): number {
+  let depth = 0;
+  let current = el.parentElement;
+  while (current) {
+    depth += 1;
+    current = current.parentElement;
+  }
+  return depth;
+}
+
+// ─── Composition source resolution ───────────────────────────────────────────
+
+export function getSourceFileForElement(
+  el: HTMLElement,
+  activeCompositionPath: string | null,
+): { sourceFile: string; compositionPath: string } {
+  const sourceHost = findClosestByAttribute(el, ["data-composition-file", "data-composition-src"]);
+  const ownerRoot = findClosestByAttribute(el, ["data-composition-id"]);
+  const sourceFile =
+    sourceHost?.getAttribute("data-composition-file") ??
+    sourceHost?.getAttribute("data-composition-src") ??
+    ownerRoot?.getAttribute("data-composition-file") ??
+    ownerRoot?.getAttribute("data-composition-src") ??
+    activeCompositionPath ??
+    "index.html";
+
+  return {
+    sourceFile,
+    compositionPath: sourceFile,
+  };
+}
+
+export function normalizeTimelineCompositionSource(value: string | undefined): string | undefined {
+  const trimmed = value?.trim();
+  if (!trimmed) return undefined;
+
+  let pathname = trimmed;
+  try {
+    pathname = new URL(trimmed, "http://studio.local").pathname;
+  } catch {
+    pathname = trimmed;
+  }
+
+  for (const marker of ["/preview/comp/", "/preview/"]) {
+    const markerIndex = pathname.indexOf(marker);
+    if (markerIndex < 0) continue;
+    const sourcePath = pathname.slice(markerIndex + marker.length).replace(/^\/+/, "");
+    return sourcePath || trimmed;
+  }
+
+  return trimmed;
+}
+
+// ─── CSS escaping ─────────────────────────────────────────────────────────────
+
+export function escapeCssIdentifier(value: string): string {
+  const css = globalThis.CSS as { escape?: (input: string) => string } | undefined;
+  if (typeof css?.escape === "function") return css.escape(value);
+
+  if (value === "-") return "\\-";
+
+  let escaped = "";
+  for (let index = 0; index < value.length; index += 1) {
+    const char = value[index] ?? "";
+    const code = char.charCodeAt(0);
+    if (code === 0) {
+      escaped += "�";
+      continue;
+    }
+
+    const isDigit = code >= 48 && code <= 57;
+    const isUpperAlpha = code >= 65 && code <= 90;
+    const isLowerAlpha = code >= 97 && code <= 122;
+    const isControl = (code >= 1 && code <= 31) || code === 127;
+    const isLeadingDigit = index === 0 && isDigit;
+    const isSecondDigitAfterDash = index === 1 && value.startsWith("-") && isDigit;
+    if (isControl || isLeadingDigit || isSecondDigitAfterDash) {
+      escaped += `\\${code.toString(16)} `;
+      continue;
+    }
+    if (isUpperAlpha || isLowerAlpha || isDigit || char === "-" || char === "_" || code >= 128) {
+      escaped += char;
+      continue;
+    }
+    escaped += `\\${char}`;
+  }
+  return escaped;
+}
+
+export function escapeCssString(value: string): string {
+  return value
+    .replace(/\\/g, "\\\\")
+    .replace(/"/g, '\\"')
+    .replace(/\n/g, "\\a ")
+    .replace(/\r/g, "\\d ")
+    .replace(/\f/g, "\\c ");
+}
+
+export function querySelectorAllSafely(doc: Document, selector: string): Element[] {
+  try {
+    return Array.from(doc.querySelectorAll(selector));
+  } catch {
+    return [];
+  }
+}
+
+export function humanizeIdentifier(value: string): string {
+  return (
+    value
+      .replace(/\.html$/i, "")
+      .replace(/^compositions\//i, "")
+      .split("/")
+      .at(-1)
+      ?.replace(/[-_]+/g, " ")
+      .replace(/\b\w/g, (char) => char.toUpperCase()) ?? value
+  );
+}
+
+// ─── CSS selector building ────────────────────────────────────────────────────
+
+export function buildStableSelector(el: HTMLElement): string | undefined {
+  if (el.id) return `#${escapeCssIdentifier(el.id)}`;
+
+  const compositionId = el.getAttribute("data-composition-id");
+  if (compositionId) return `[data-composition-id="${escapeCssString(compositionId)}"]`;
+
+  return getPreferredClassSelector(el);
+}
+
+export function getPreferredClassSelector(el: HTMLElement): string | undefined {
+  const classes = Array.from(el.classList)
+    .map((value) => value.trim())
+    .filter(Boolean);
+  if (classes.length === 0) return undefined;
+  const preferred =
+    classes.find((value) => value !== "clip" && !value.startsWith("__hf-")) ?? classes[0];
+  return preferred ? `.${escapeCssIdentifier(preferred)}` : undefined;
+}
+
+export function getSelectorIndex(
+  doc: Document,
+  el: HTMLElement,
+  selector: string | undefined,
+  sourceFile: string,
+  activeCompositionPath: string | null,
+): number | undefined {
+  if (!selector?.startsWith(".")) return undefined;
+
+  const candidates = querySelectorAllSafely(doc, selector).filter(
+    (candidate): candidate is HTMLElement =>
+      isHtmlElement(candidate) &&
+      getSourceFileForElement(candidate, activeCompositionPath).sourceFile === sourceFile,
+  );
+  const index = candidates.indexOf(el);
+  return index >= 0 ? index : undefined;
+}

package/src/components/editor/domEditingElement.ts

@@ -0,0 +1,329 @@
+/**
+ * Element visibility, visual scoring, layer patch targets, element finders,
+ * and the `findElementForSelection` / `findElementForTimelineElement` lookups.
+ */
+import type {
+  DomEditContextOptions,
+  DomEditSelection,
+  DomEditViewport,
+  TimelineElementDomTarget,
+  TimelineElementDomTargetOptions,
+} from "./domEditingTypes";
+import {
+  buildStableSelector,
+  escapeCssString,
+  findClosestByAttribute,
+  getElementDepth,
+  getPreferredClassSelector,
+  getSelectorIndex,
+  getSourceFileForElement,
+  isHtmlElement,
+  isTextBearingTag,
+  normalizeTimelineCompositionSource,
+  querySelectorAllSafely,
+} from "./domEditingDom";
+
+// ─── Visibility ──────────────────────────────────────────────────────────────
+
+export function isElementComputedVisible(el: HTMLElement): boolean {
+  const win = el.ownerDocument.defaultView;
+  if (!win) return true;
+  let current: HTMLElement | null = el;
+  while (current) {
+    const computed = win.getComputedStyle(current);
+    if (computed.display === "none" || computed.visibility === "hidden") return false;
+    const opacity = Number.parseFloat(computed.opacity);
+    if (Number.isFinite(opacity) && opacity <= 0.01) return false;
+    current = current.parentElement;
+  }
+  return true;
+}
+
+const VISUAL_LEAF_TAGS = new Set(["img", "video", "canvas", "svg", "audio"]);
+
+function isEmptyVisualContainer(el: HTMLElement): boolean {
+  const tag = el.tagName.toLowerCase();
+  if (VISUAL_LEAF_TAGS.has(tag)) return false;
+
+  const { children } = el;
+  if (children.length === 0) {
+    return (el.textContent ?? "").trim().length === 0;
+  }
+
+  for (let i = 0; i < children.length; i += 1) {
+    const child = children[i];
+    if (!isHtmlElement(child)) continue;
+    if (VISUAL_LEAF_TAGS.has(child.tagName.toLowerCase())) return false;
+    if (isElementComputedVisible(child)) return false;
+  }
+
+  return true;
+}
+
+export function hasRenderedBox(el: HTMLElement): boolean {
+  const rect = el.getBoundingClientRect();
+  if (rect.width <= 1 || rect.height <= 1) return false;
+  if (!isElementComputedVisible(el)) return false;
+  if (isEmptyVisualContainer(el)) return false;
+  return true;
+}
+
+// ─── Visual scoring ──────────────────────────────────────────────────────────
+
+function isEditableTextLeafForScoring(el: HTMLElement): boolean {
+  return isTextBearingTag(el.tagName.toLowerCase()) && el.children.length === 0;
+}
+
+function getVisualElementScore(el: HTMLElement, pointerStackIndex: number): number {
+  const tagName = el.tagName.toLowerCase();
+  const rect = el.getBoundingClientRect();
+  const area = Math.max(1, rect.width * rect.height);
+  const smallerElementBonus = Math.max(0, 1_000_000 - Math.min(area, 1_000_000)) / 1_000;
+  const visualLeafBonus =
+    isEditableTextLeafForScoring(el) || ["img", "video", "canvas", "svg"].includes(tagName)
+      ? 2_000
+      : 0;
+
+  return getElementDepth(el) * 10_000 + visualLeafBonus + smallerElementBonus - pointerStackIndex;
+}
+
+// ─── Layer patch target ──────────────────────────────────────────────────────
+
+const DOM_LAYER_IGNORED_TAGS = new Set([
+  "base",
+  "br",
+  "canvas",
+  "link",
+  "meta",
+  "script",
+  "source",
+  "style",
+  "template",
+  "track",
+  "wbr",
+]);
+
+function isInspectableLayerElement(el: HTMLElement): boolean {
+  const tagName = el.tagName.toLowerCase();
+  if (DOM_LAYER_IGNORED_TAGS.has(tagName)) return false;
+
+  const computed = el.ownerDocument.defaultView?.getComputedStyle(el);
+  if (computed?.display === "none" || computed?.visibility === "hidden") return false;
+
+  return true;
+}
+
+export function getDomLayerPatchTarget(
+  el: HTMLElement,
+  activeCompositionPath: string | null,
+): Pick<DomEditSelection, "id" | "selector" | "selectorIndex" | "sourceFile"> | null {
+  if (!isInspectableLayerElement(el)) return null;
+
+  const selector = buildStableSelector(el);
+  if (!selector) return null;
+
+  const { sourceFile } = getSourceFileForElement(el, activeCompositionPath);
+  return {
+    id: el.id || undefined,
+    selector,
+    selectorIndex: getSelectorIndex(
+      el.ownerDocument,
+      el,
+      selector,
+      sourceFile,
+      activeCompositionPath,
+    ),
+    sourceFile,
+  };
+}
+
+// ─── Clip ancestor / selection candidate ─────────────────────────────────────
+
+function getPreferredClipAncestor(startEl: HTMLElement): HTMLElement | null {
+  let current: HTMLElement | null = startEl;
+  while (current) {
+    if (current.classList.contains("clip")) {
+      const isCompositionHost =
+        current.hasAttribute("data-composition-src") ||
+        current.hasAttribute("data-composition-file");
+      if (!isCompositionHost || current === startEl) return current;
+    }
+    current = current.parentElement;
+  }
+  return null;
+}
+
+export function getSelectionCandidate(
+  startEl: HTMLElement,
+  options: DomEditContextOptions,
+): HTMLElement {
+  if (options.preferClipAncestor) {
+    const clipAncestor = getPreferredClipAncestor(startEl);
+    if (clipAncestor) {
+      return clipAncestor;
+    }
+  }
+
+  return startEl;
+}
+
+// ─── Visual target resolution ─────────────────────────────────────────────────
+
+export function resolveVisualDomEditSelectionTarget(
+  elementsFromPoint: Iterable<Element | null | undefined>,
+  options: Pick<DomEditContextOptions, "activeCompositionPath">,
+): HTMLElement | null {
+  let best: { element: HTMLElement; score: number } | null = null;
+  let pointerStackIndex = 0;
+
+  for (const entry of elementsFromPoint) {
+    if (!isHtmlElement(entry)) {
+      pointerStackIndex += 1;
+      continue;
+    }
+
+    if (hasRenderedBox(entry) && getDomLayerPatchTarget(entry, options.activeCompositionPath)) {
+      const score = getVisualElementScore(entry, pointerStackIndex);
+      if (!best || score > best.score) {
+        best = { element: entry, score };
+      }
+    }
+    pointerStackIndex += 1;
+  }
+
+  return best?.element ?? null;
+}
+
+// ─── Raster detection ────────────────────────────────────────────────────────
+
+function hasRasterBackground(selection: Pick<DomEditSelection, "computedStyles">): boolean {
+  const backgroundImage = selection.computedStyles["background-image"]?.trim();
+  return Boolean(backgroundImage && backgroundImage !== "none");
+}
+
+export function isLargeRasterDomEditSelection(
+  selection: Pick<DomEditSelection, "boundingBox" | "computedStyles" | "tagName">,
+  viewport?: DomEditViewport | null,
+): boolean {
+  const tagName = selection.tagName.toLowerCase();
+  const isRasterLike = tagName === "img" || hasRasterBackground(selection);
+  if (!isRasterLike) return false;
+
+  const { width, height } = selection.boundingBox;
+  if (width <= 1 || height <= 1) return false;
+  if (!viewport || viewport.width <= 1 || viewport.height <= 1) {
+    return width >= 960 && height >= 540;
+  }
+
+  const areaRatio = (width * height) / (viewport.width * viewport.height);
+  const widthRatio = width / viewport.width;
+  const heightRatio = height / viewport.height;
+  return areaRatio >= 0.4 || (widthRatio >= 0.7 && heightRatio >= 0.5);
+}
+
+// ─── Element finders ──────────────────────────────────────────────────────────
+
+export function findElementForSelection(
+  doc: Document,
+  selection: Pick<DomEditSelection, "id" | "selector" | "selectorIndex" | "sourceFile">,
+  activeCompositionPath: string | null = null,
+): HTMLElement | null {
+  if (selection.id) {
+    const byId = doc.getElementById(selection.id);
+    if (
+      isHtmlElement(byId) &&
+      (!selection.sourceFile ||
+        getSourceFileForElement(byId, activeCompositionPath).sourceFile === selection.sourceFile)
+    ) {
+      return byId;
+    }
+  }
+
+  if (!selection.selector) return null;
+
+  if (selection.selector.startsWith(".") && selection.selectorIndex != null) {
+    const matches = querySelectorAllSafely(doc, selection.selector).filter(
+      (candidate): candidate is HTMLElement =>
+        isHtmlElement(candidate) &&
+        (!selection.sourceFile ||
+          getSourceFileForElement(candidate, activeCompositionPath).sourceFile ===
+            selection.sourceFile),
+    );
+    return matches[selection.selectorIndex] ?? null;
+  }
+
+  const matches = querySelectorAllSafely(doc, selection.selector).filter(
+    (candidate): candidate is HTMLElement =>
+      isHtmlElement(candidate) &&
+      (!selection.sourceFile ||
+        getSourceFileForElement(candidate, activeCompositionPath).sourceFile ===
+          selection.sourceFile),
+  );
+  return matches[0] ?? null;
+}
+
+export function findElementForTimelineElement(
+  doc: Document,
+  element: TimelineElementDomTarget,
+  options: TimelineElementDomTargetOptions,
+): HTMLElement | null {
+  const elementId = typeof element.id === "string" ? element.id : "";
+  const compositionSource =
+    normalizeTimelineCompositionSource(element.compositionSrc) ??
+    options.compIdToSrc?.get(elementId);
+  const sourceFile =
+    compositionSource ??
+    normalizeTimelineCompositionSource(element.sourceFile) ??
+    options.activeCompositionPath ??
+    "index.html";
+  const escapedElementId = escapeCssString(elementId);
+  const escapedCompositionSource = compositionSource ? escapeCssString(compositionSource) : null;
+  const selector =
+    element.selector ??
+    (compositionSource
+      ? `[data-composition-src="${escapedCompositionSource}"],[data-composition-file="${escapedCompositionSource}"],[data-composition-id="${escapedElementId}"]`
+      : escapedElementId
+        ? `[data-composition-id="${escapedElementId}"]`
+        : undefined);
+
+  if (selector || element.domId) {
+    const targetElement = findElementForSelection(
+      doc,
+      {
+        id: element.domId ?? undefined,
+        selector,
+        selectorIndex: element.selectorIndex,
+        sourceFile,
+      },
+      options.activeCompositionPath,
+    );
+    if (targetElement) return targetElement;
+  }
+
+  const hasExplicitDomTarget = Boolean(element.domId || element.selector || compositionSource);
+  if (options.isMasterView || hasExplicitDomTarget || !options.activeCompositionPath) {
+    return null;
+  }
+
+  const root = doc.querySelector("[data-composition-id]");
+  if (!isHtmlElement(root)) return null;
+  return getSourceFileForElement(root, options.activeCompositionPath).sourceFile === sourceFile
+    ? root
+    : null;
+}
+
+// ─── Layer children ───────────────────────────────────────────────────────────
+
+export function getDirectLayerChildren(
+  el: HTMLElement,
+  options: DomEditContextOptions,
+): HTMLElement[] {
+  return Array.from(el.children).filter(
+    (child): child is HTMLElement =>
+      isHtmlElement(child) && getDomLayerPatchTarget(child, options.activeCompositionPath) !== null,
+  );
+}
+
+// ─── Composition source helpers ───────────────────────────────────────────────
+
+export { findClosestByAttribute, getPreferredClassSelector, getSourceFileForElement };