@hyperframes/studio 0.7.28 → 0.7.30

package/src/components/editor/persistSeam.integration.test.ts

@@ -0,0 +1,264 @@
+// @vitest-environment jsdom
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+  patchElementInHtml,
+  type PatchOperation,
+  type SourceMutationTarget,
+} from "@hyperframes/studio-server/source-mutation";
+import { describe, expect, it } from "vitest";
+import {
+  collectDomEditTextFields,
+  buildDomEditPatchTarget,
+  buildDomEditStylePatchOperation,
+  buildDomEditTextPatchOperation,
+} from "./domEditingLayers";
+import { buildPathOffsetPatches } from "./manualEditsDomPatches";
+import { STUDIO_OFFSET_X_PROP, STUDIO_PATH_OFFSET_ATTR } from "./manualEditsTypes";
+import { makeSelection } from "../../hooks/domSelectionTestHarness";
+import { buildTextFieldChildOperations } from "../../hooks/domEditTextFieldCommitOps";
+
+const testDir = dirname(fileURLToPath(import.meta.url));
+const fixtureDir = join(testDir, "../../../tests/e2e/fixtures/design-panel-qa");
+
+function readFixture(relativePath: string): string {
+  return readFileSync(join(fixtureDir, relativePath), "utf-8");
+}
+
+function createSelection(input: {
+  id: string;
+  hfId: string;
+  tagName: string;
+}): ReturnType<typeof makeSelection> {
+  const element = document.createElement(input.tagName);
+  element.id = input.id;
+  element.setAttribute("data-hf-id", input.hfId);
+  return {
+    ...makeSelection(input.id, element),
+    hfId: input.hfId,
+  };
+}
+
+function clientTarget(input: { id: string; hfId: string; tagName: string }): SourceMutationTarget {
+  return buildDomEditPatchTarget(createSelection(input));
+}
+
+function patchAndExpectChange(
+  sourceHtml: string,
+  target: SourceMutationTarget,
+  operations: PatchOperation[],
+): string {
+  const result = patchElementInHtml(sourceHtml, target, operations);
+  expect(result.matched).toBe(true);
+  expect(result.html).not.toBe(sourceHtml);
+  return result.html;
+}
+
+function parseHtml(html: string): Document {
+  return new DOMParser().parseFromString(html, "text/html");
+}
+
+function findElementInHtml(html: string, selector: string): Element {
+  const document = parseHtml(html);
+  const directMatch = document.querySelector(selector);
+  if (directMatch) return directMatch;
+
+  for (const template of Array.from(document.querySelectorAll("template"))) {
+    const templateMatch = template.content.querySelector(selector);
+    if (templateMatch) return templateMatch;
+  }
+
+  throw new Error(`Expected selector ${selector} to match`);
+}
+
+function findByHfId(html: string, hfId: string): Element {
+  return findElementInHtml(html, `[data-hf-id="${hfId}"]`);
+}
+
+function countOccurrences(value: string, needle: string): number {
+  return value.split(needle).length - 1;
+}
+
+describe("persist seam source mutation", () => {
+  const indexHtml = readFixture("index.html");
+  const subHtml = readFixture("compositions/qa-sub.html");
+
+  it("persists qa-headline text font-size style operation", () => {
+    const html = patchAndExpectChange(
+      indexHtml,
+      clientTarget({ id: "qa-headline", hfId: "qa-headline", tagName: "h1" }),
+      [buildDomEditStylePatchOperation("font-size", "64px")],
+    );
+
+    expect(findByHfId(html, "qa-headline").getAttribute("style")).toContain("font-size: 64px");
+  });
+
+  it("persists qa-shape fill style operation", () => {
+    const html = patchAndExpectChange(
+      indexHtml,
+      clientTarget({ id: "qa-shape", hfId: "qa-shape", tagName: "div" }),
+      [buildDomEditStylePatchOperation("background-color", "#ff0000")],
+    );
+
+    expect(findByHfId(html, "qa-shape").getAttribute("style")).toContain(
+      "background-color: #ff0000",
+    );
+  });
+
+  it("persists qa-multi text color style operation", () => {
+    const html = patchAndExpectChange(
+      indexHtml,
+      clientTarget({ id: "qa-multi", hfId: "qa-multi", tagName: "div" }),
+      [buildDomEditStylePatchOperation("color", "#00ff00")],
+    );
+
+    expect(findByHfId(html, "qa-multi").getAttribute("style")).toContain("color: #00ff00");
+  });
+
+  it("persists qa-image opacity style operation", () => {
+    const html = patchAndExpectChange(
+      indexHtml,
+      clientTarget({ id: "qa-image", hfId: "qa-image", tagName: "img" }),
+      [buildDomEditStylePatchOperation("opacity", "0.4")],
+    );
+
+    expect(findByHfId(html, "qa-image").getAttribute("style")).toContain("opacity: 0.4");
+  });
+
+  it("persists detached jsdom path offset operations", () => {
+    const element = document.createElement("div");
+    element.style.setProperty(STUDIO_OFFSET_X_PROP, "24px");
+
+    const html = patchAndExpectChange(
+      indexHtml,
+      clientTarget({ id: "qa-shape", hfId: "qa-shape", tagName: "div" }),
+      buildPathOffsetPatches(element),
+    );
+    const shape = findByHfId(html, "qa-shape");
+
+    expect(shape.getAttribute("style")).toContain(`${STUDIO_OFFSET_X_PROP}: 24px`);
+    expect(shape.getAttribute("style")).toContain("translate: var(--hf-studio-offset-x, 0px)");
+    expect(shape.getAttribute(STUDIO_PATH_OFFSET_ATTR)).toBe("true");
+  });
+
+  it("persists timeline data-start attribute operation", () => {
+    const html = patchAndExpectChange(
+      indexHtml,
+      clientTarget({ id: "qa-zone-headline", hfId: "qa-zone-headline", tagName: "div" }),
+      [{ type: "attribute", property: "start", value: "2.5" }],
+    );
+
+    expect(findByHfId(html, "qa-zone-headline").getAttribute("data-start")).toBe("2.5");
+    expect(countOccurrences(html, 'data-start="2.5"')).toBe(1);
+  });
+
+  it("persists media volume data attribute operation", () => {
+    const html = patchAndExpectChange(
+      indexHtml,
+      clientTarget({ id: "qa-video", hfId: "qa-video", tagName: "video" }),
+      [{ type: "attribute", property: "volume", value: "0.75" }],
+    );
+
+    expect(findByHfId(html, "qa-video").getAttribute("data-volume")).toBe("0.75");
+    expect(html).not.toContain('data-volume="0.5"');
+  });
+
+  it("returns matched false and unchanged html for a missing hfId target", () => {
+    const result = patchElementInHtml(indexHtml, { hfId: "qa-does-not-exist" }, [
+      buildDomEditStylePatchOperation("font-size", "64px"),
+    ]);
+
+    expect(result.matched).toBe(false);
+    expect(result.html).toBe(indexHtml);
+  });
+
+  it("persists sub-composition child style operation inside a template", () => {
+    const html = patchAndExpectChange(
+      subHtml,
+      clientTarget({ id: "qa-sub-title", hfId: "qa-sub-title", tagName: "h2" }),
+      [buildDomEditStylePatchOperation("font-size", "50px")],
+    );
+
+    expect(findByHfId(html, "qa-sub-title").getAttribute("style")).toContain("font-size: 50px");
+  });
+
+  it("returns matched false for runtime-generated caption words absent from static source", () => {
+    const result = patchElementInHtml(
+      indexHtml,
+      { selector: "#qa-caption-host span", selectorIndex: 0 },
+      [buildDomEditStylePatchOperation("color", "#ffffff")],
+    );
+
+    expect(result.matched).toBe(false);
+    expect(result.html).toBe(indexHtml);
+  });
+
+  it("fixes U4: child text-field style persists as an inline style on the correct child span", () => {
+    const html = patchAndExpectChange(indexHtml, { hfId: "qa-multi" }, [
+      buildDomEditStylePatchOperation("color", "#0000ff", {
+        childSelector: ":scope > span",
+        childIndex: 0,
+      }),
+    ]);
+
+    const lineA = findElementInHtml(html, ".qa-line-a");
+    const lineB = findElementInHtml(html, ".qa-line-b");
+    expect(lineA.getAttribute("style")).toContain("color: #0000ff");
+    expect(lineB.getAttribute("style")).toBeNull();
+    expect(lineB.textContent).toBe("Second styled line");
+    expect(html).not.toContain("&lt;span");
+  });
+
+  it("targets the second direct child when siblings share the same tag and class", () => {
+    const source = `<div data-hf-id="dups"><span class="dup">First</span><span class="dup">Second</span></div>`;
+    const html = patchAndExpectChange(source, { hfId: "dups" }, [
+      buildDomEditStylePatchOperation("color", "#0000ff", {
+        childSelector: ":scope > span",
+        childIndex: 1,
+      }),
+    ]);
+
+    const document = parseHtml(html);
+    const spans = Array.from(document.querySelectorAll(".dup"));
+    expect(spans[0]?.getAttribute("style")).toBeNull();
+    expect(spans[1]?.getAttribute("style")).toContain("color: #0000ff");
+  });
+
+  it("persists a child text-field content edit as plain text", () => {
+    const value = "A < B & C";
+    const html = patchAndExpectChange(indexHtml, { hfId: "qa-multi" }, [
+      buildDomEditTextPatchOperation(value, {
+        childSelector: ":scope > span",
+        childIndex: 0,
+      }),
+    ]);
+
+    expect(findElementInHtml(html, ".qa-line-a").textContent).toBe(value);
+    expect(findElementInHtml(html, ".qa-line-b").textContent).toBe("Second styled line");
+    expect(html).not.toContain("&lt;span");
+  });
+
+  it("uses same-tag source child indexes when a non-leaf sibling sits between fields", () => {
+    const source = `<div data-hf-id="mixed"><span class="leaf-a">First</span><span class="wrapper"><b>Wrapper</b></span><span class="leaf-b">Second</span></div>`;
+    const previewHost = document.createElement("div");
+    previewHost.innerHTML = source;
+    const previewTarget = previewHost.querySelector('[data-hf-id="mixed"]');
+    if (!(previewTarget instanceof HTMLElement)) throw new Error("Expected preview target");
+
+    const originalFields = collectDomEditTextFields(previewTarget);
+    const secondField = originalFields.find((field) => field.value === "Second");
+    if (!secondField) throw new Error("Expected second text field");
+    const nextFields = originalFields.map((field) =>
+      field.key === secondField.key ? { ...field, value: "Second updated" } : field,
+    );
+    const operations = buildTextFieldChildOperations(originalFields, nextFields);
+    if (!operations) throw new Error("Expected child operations");
+
+    const html = patchAndExpectChange(source, { hfId: "mixed" }, operations);
+
+    expect(findElementInHtml(html, ".leaf-a").textContent).toBe("First");
+    expect(findElementInHtml(html, ".wrapper").textContent).toBe("Wrapper");
+    expect(findElementInHtml(html, ".leaf-b").textContent).toBe("Second updated");
+  });
+});

package/src/components/editor/propertyPanelPrimitives.tsx

@@ -371,7 +371,10 @@ export function Section({
   );
 
   return (
-    <section className="min-w-0 border-t border-panel-border">
+    <section
+      className="min-w-0 border-t border-panel-border"
+      data-panel-section={slugifyPanelSectionTitle(title)}
+    >
       <div className="flex w-full items-center gap-2 px-4 py-2.5">
         <button
           type="button"
@@ -387,3 +390,14 @@ export function Section({
     </section>
   );
 }
+
+// Stable hook for e2e/automation to locate a section without depending on the
+// display copy (h3 textContent matching breaks on wording tweaks or, if this
+// panel is ever localized, on translation).
+function slugifyPanelSectionTitle(title: string): string {
+  return title
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/(^-|-$)/g, "");
+}

package/src/components/editor/useDomEditOverlayGestures.ts

@@ -369,6 +369,7 @@ export function createDomEditOverlayGestureHandlers(opts: UseDomEditOverlayGestu
       opts.suppressNextBoxClickRef.current = true;
       opts.onCanvasMouseDown(e as unknown as React.MouseEvent<HTMLDivElement>, {
         preferClipAncestor: false,
+        hoverSelection: opts.hoverSelectionRef.current,
       });
       return;
     }

package/src/hooks/domEditCommitRunner.ts

@@ -0,0 +1,46 @@
+interface DomEditCommitRunnerConfig {
+  capture: () => void;
+  apply: () => void;
+  persist: () => Promise<void>;
+  shouldRevert: (error: unknown) => boolean;
+  revert: () => void;
+  onError: (error: unknown) => void;
+  shouldResync: () => boolean;
+  resync: () => void | Promise<void>;
+}
+
+interface CommitVersionRef {
+  current: number;
+}
+
+export function bumpDomEditCommitVersion(versionRef: CommitVersionRef): () => boolean {
+  const commitVersion = versionRef.current + 1;
+  versionRef.current = commitVersion;
+  return () => versionRef.current === commitVersion;
+}
+
+export function bumpDomEditCommitMapVersion<TKey>(
+  versionMap: Map<TKey, number>,
+  versionKey: TKey,
+): () => boolean {
+  const commitVersion = (versionMap.get(versionKey) ?? 0) + 1;
+  versionMap.set(versionKey, commitVersion);
+  return () => versionMap.get(versionKey) === commitVersion;
+}
+
+export async function runDomEditCommit(config: DomEditCommitRunnerConfig): Promise<void> {
+  config.capture();
+  config.apply();
+
+  try {
+    await config.persist();
+  } catch (error) {
+    if (config.shouldRevert(error)) {
+      config.revert();
+    }
+    config.onError(error);
+  }
+
+  if (!config.shouldResync()) return;
+  await config.resync();
+}

package/src/hooks/domEditPersistFailure.test.ts

@@ -0,0 +1,123 @@
+import { describe, expect, it, vi } from "vitest";
+import type { PatchOperation } from "../utils/sourcePatcher";
+import { StudioSaveHttpError } from "../utils/studioSaveDiagnostics";
+import {
+  DomEditPersistUnsafeValueError,
+  reportDomEditPersistFailure,
+  warnDomEditPersistNoOp,
+} from "./domEditPersistFailure";
+
+const selection = {
+  label: "Hero title",
+  hfId: "hf-hero",
+  id: "hero",
+  selector: ".hero",
+  selectorIndex: 0,
+  sourceFile: "index.html",
+};
+
+const operations: PatchOperation[] = [{ type: "inline-style", property: "color", value: "red" }];
+
+describe("reportDomEditPersistFailure", () => {
+  it("toasts with the selected label and underlying error detail", () => {
+    const showToast = vi.fn<(message: string, tone?: "error" | "info") => void>();
+    const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+
+    reportDomEditPersistFailure(selection, operations, new Error("network down"), showToast);
+
+    expect(showToast).toHaveBeenCalledWith('Couldn\'t save "Hero title": network down', "error");
+    expect(warnSpy).toHaveBeenCalledWith(
+      "[Studio] DOM edit persist failed",
+      expect.objectContaining({
+        target: {
+          hfId: "hf-hero",
+          id: "hero",
+          selector: ".hero",
+          selectorIndex: 0,
+          sourceFile: "index.html",
+        },
+        operations: "inline-style:color",
+        error: "network down",
+      }),
+    );
+
+    warnSpy.mockRestore();
+  });
+
+  it("toasts StudioSaveHttpError and unmarked unsafe errors", () => {
+    const showToast = vi.fn<(message: string, tone?: "error" | "info") => void>();
+    const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+
+    reportDomEditPersistFailure(
+      selection,
+      operations,
+      new StudioSaveHttpError("Failed to patch index.html (500)", 500),
+      showToast,
+    );
+    reportDomEditPersistFailure(
+      selection,
+      operations,
+      new DomEditPersistUnsafeValueError("DOM patch contains unsafe values: style.width"),
+      showToast,
+    );
+
+    expect(showToast).toHaveBeenCalledTimes(2);
+    expect(showToast).toHaveBeenCalledWith(
+      expect.stringContaining("Failed to patch index.html"),
+      "error",
+    );
+    expect(showToast).toHaveBeenCalledWith(
+      expect.stringContaining("DOM patch contains unsafe values: style.width"),
+      "error",
+    );
+    expect(warnSpy).toHaveBeenCalledTimes(2);
+
+    warnSpy.mockRestore();
+  });
+
+  it("does not toast errors explicitly marked as already toasted", () => {
+    const showToast = vi.fn<(message: string, tone?: "error" | "info") => void>();
+    const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+    const error = new DomEditPersistUnsafeValueError(
+      "DOM patch contains unsafe values: style.width",
+    );
+    Object.defineProperty(error, "alreadyToasted", { value: true });
+
+    reportDomEditPersistFailure(selection, operations, error, showToast);
+
+    expect(showToast).not.toHaveBeenCalled();
+    expect(warnSpy).toHaveBeenCalledTimes(1);
+    expect(warnSpy).toHaveBeenCalledWith(
+      "[Studio] DOM edit persist failed",
+      expect.objectContaining({
+        target: expect.objectContaining({ hfId: "hf-hero", sourceFile: "index.html" }),
+      }),
+    );
+
+    warnSpy.mockRestore();
+  });
+});
+
+describe("warnDomEditPersistNoOp", () => {
+  it("logs a structured breadcrumb without requiring a toast callback", () => {
+    const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+
+    warnDomEditPersistNoOp(selection, operations);
+
+    expect(warnSpy).toHaveBeenCalledWith(
+      "[Studio] DOM edit persist no-op",
+      expect.objectContaining({
+        target: {
+          hfId: "hf-hero",
+          id: "hero",
+          selector: ".hero",
+          selectorIndex: 0,
+          sourceFile: "index.html",
+        },
+        operations: "inline-style:color",
+      }),
+    );
+
+    warnSpy.mockRestore();
+  });
+});

package/src/hooks/domEditPersistFailure.ts

@@ -0,0 +1,89 @@
+import type { DomEditSelection } from "../components/editor/domEditing";
+import { StudioSaveHttpError } from "../utils/studioSaveDiagnostics";
+import type { PatchOperation } from "../utils/sourcePatcher";
+
+export class DomEditPersistUnresolvableError extends Error {
+  constructor(targetPath: string) {
+    super(`Couldn't find this element in the source file (${targetPath})`);
+    this.name = "DomEditPersistUnresolvableError";
+  }
+}
+
+export class DomEditPersistUnsafeValueError extends Error {
+  readonly alreadyToasted: boolean;
+
+  constructor(message: string, options: { alreadyToasted?: boolean } = {}) {
+    super(message);
+    this.name = "DomEditPersistUnsafeValueError";
+    this.alreadyToasted = options.alreadyToasted ?? false;
+  }
+}
+
+export class DomEditPersistUnsupportedTextStructureError extends Error {
+  constructor() {
+    super("Couldn't save this text structure change");
+    this.name = "DomEditPersistUnsupportedTextStructureError";
+  }
+}
+
+export type DomEditPersistFailureSelection = Pick<
+  DomEditSelection,
+  "label" | "hfId" | "id" | "selector" | "selectorIndex" | "sourceFile"
+>;
+
+function summarizeOperations(operations: PatchOperation[]): string {
+  return operations.map((op) => `${op.type}:${op.property}`).join(", ");
+}
+
+function getTargetTuple(selection: DomEditPersistFailureSelection) {
+  return {
+    hfId: selection.hfId,
+    id: selection.id,
+    selector: selection.selector,
+    selectorIndex: selection.selectorIndex,
+    sourceFile: selection.sourceFile,
+  };
+}
+
+function getErrorDetail(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+function getSelectionLabel(selection: DomEditPersistFailureSelection): string {
+  return selection.label || selection.selector || selection.id || "this element";
+}
+
+export function reportDomEditPersistFailure(
+  selection: DomEditPersistFailureSelection,
+  operations: PatchOperation[],
+  error: unknown,
+  showToast: (message: string, tone?: "error" | "info") => void,
+): void {
+  const detail = getErrorDetail(error);
+  console.warn("[Studio] DOM edit persist failed", {
+    target: getTargetTuple(selection),
+    operations: summarizeOperations(operations),
+    error: detail,
+  });
+
+  const wasAlreadyToasted =
+    (error instanceof DomEditPersistUnsafeValueError || error instanceof StudioSaveHttpError) &&
+    error.alreadyToasted;
+  if (wasAlreadyToasted) {
+    return;
+  }
+
+  showToast(`Couldn't save "${getSelectionLabel(selection)}": ${detail}`, "error");
+}
+
+export function warnDomEditPersistNoOp(
+  selection: DomEditPersistFailureSelection,
+  operations: PatchOperation[],
+): void {
+  console.warn("[Studio] DOM edit persist no-op", {
+    target: getTargetTuple(selection),
+    operations: summarizeOperations(operations),
+    detail:
+      "Server matched the target but reported no change even though the client believed the value changed.",
+  });
+}

package/src/hooks/domEditTextFieldCommitOps.test.ts

@@ -0,0 +1,111 @@
+import { describe, expect, it } from "vitest";
+import type { DomEditTextField } from "../components/editor/domEditing";
+import { buildTextFieldChildOperations } from "./domEditTextFieldCommitOps";
+
+function textField(input: {
+  key: string;
+  value: string;
+  tagName?: string;
+  inlineStyles?: Record<string, string>;
+  source?: DomEditTextField["source"];
+  sourceChildIndex?: number;
+}): DomEditTextField {
+  return {
+    key: input.key,
+    label: input.key,
+    value: input.value,
+    tagName: input.tagName ?? "span",
+    attributes: [],
+    inlineStyles: input.inlineStyles ?? {},
+    computedStyles: {},
+    source: input.source ?? "child",
+    ...(input.sourceChildIndex == null ? {} : { sourceChildIndex: input.sourceChildIndex }),
+  };
+}
+
+describe("buildTextFieldChildOperations", () => {
+  it("builds child-scoped text and style operations for changed child fields", () => {
+    const originalFields = [
+      textField({
+        key: "first",
+        value: "First",
+        inlineStyles: { color: "red" },
+        sourceChildIndex: 0,
+      }),
+      textField({
+        key: "second",
+        value: "Second",
+        inlineStyles: { "font-size": "24px" },
+        sourceChildIndex: 1,
+      }),
+    ];
+    const nextFields = [
+      originalFields[0],
+      textField({
+        key: "second",
+        value: "Second < &",
+        inlineStyles: { "font-size": "24px", color: "#0000ff" },
+        sourceChildIndex: 1,
+      }),
+    ];
+
+    expect(buildTextFieldChildOperations(originalFields, nextFields)).toEqual([
+      {
+        type: "text-content",
+        property: "text",
+        value: "Second < &",
+        childSelector: ":scope > span",
+        childIndex: 1,
+      },
+      {
+        type: "inline-style",
+        property: "color",
+        value: "#0000ff",
+        childSelector: ":scope > span",
+        childIndex: 1,
+      },
+    ]);
+  });
+
+  it("emits null for a removed inline style", () => {
+    const originalFields = [
+      textField({
+        key: "first",
+        value: "First",
+        inlineStyles: { color: "red" },
+        sourceChildIndex: 0,
+      }),
+    ];
+    const nextFields = [
+      textField({ key: "first", value: "First", inlineStyles: {}, sourceChildIndex: 0 }),
+    ];
+
+    expect(buildTextFieldChildOperations(originalFields, nextFields)).toEqual([
+      {
+        type: "inline-style",
+        property: "color",
+        value: null,
+        childSelector: ":scope > span",
+        childIndex: 0,
+      },
+    ]);
+  });
+
+  it("returns null for structural changes, reordered fields, and text nodes", () => {
+    const originalFields = [
+      textField({ key: "first", value: "First" }),
+      textField({ key: "second", value: "Second" }),
+    ];
+
+    expect(buildTextFieldChildOperations(originalFields, [originalFields[0]])).toBeNull();
+    expect(
+      buildTextFieldChildOperations(originalFields, [originalFields[1], originalFields[0]]),
+    ).toBeNull();
+    expect(
+      buildTextFieldChildOperations(originalFields, [
+        originalFields[0],
+        textField({ key: "second", value: "Second", tagName: "#text", source: "text-node" }),
+      ]),
+    ).toBeNull();
+  });
+});