@hyperframes/studio 0.4.24 → 0.5.0-alpha.2

package/src/components/editor/colorValue.test.ts

@@ -0,0 +1,82 @@
+import { describe, expect, it } from "vitest";
+import {
+  formatCssColor,
+  hsvToRgb,
+  mergeColorWithExistingAlpha,
+  parseCssColor,
+  rgbToHsv,
+  toColorPickerValue,
+  toHexColor,
+} from "./colorValue";
+
+describe("parseCssColor", () => {
+  it("parses rgb values", () => {
+    expect(parseCssColor("rgb(12, 34, 56)")).toEqual({
+      red: 12,
+      green: 34,
+      blue: 56,
+      alpha: 1,
+    });
+  });
+
+  it("parses rgba values", () => {
+    expect(parseCssColor("rgba(15, 23, 42, 0.64)")).toEqual({
+      red: 15,
+      green: 23,
+      blue: 42,
+      alpha: 0.64,
+    });
+  });
+
+  it("parses transparent", () => {
+    expect(parseCssColor("transparent")).toEqual({
+      red: 0,
+      green: 0,
+      blue: 0,
+      alpha: 0,
+    });
+  });
+});
+
+describe("toColorPickerValue", () => {
+  it("converts css color to hex", () => {
+    expect(toColorPickerValue("rgba(15, 23, 42, 0.64)")).toBe("#0f172a");
+  });
+});
+
+describe("toHexColor", () => {
+  it("formats rgb channels as hex", () => {
+    expect(toHexColor({ red: 15, green: 23, blue: 42 })).toBe("#0f172a");
+  });
+});
+
+describe("formatCssColor", () => {
+  it("formats opaque colors as rgb", () => {
+    expect(formatCssColor({ red: 18, green: 52, blue: 86, alpha: 1 })).toBe("rgb(18, 52, 86)");
+  });
+
+  it("formats translucent colors as rgba", () => {
+    expect(formatCssColor({ red: 18, green: 52, blue: 86, alpha: 0.64 })).toBe(
+      "rgba(18, 52, 86, 0.64)",
+    );
+  });
+});
+
+describe("rgb hsv conversion", () => {
+  it("round-trips primary color values", () => {
+    const hsv = rgbToHsv({ red: 47, green: 198, blue: 127 });
+    expect(hsvToRgb(hsv)).toEqual({ red: 47, green: 198, blue: 127 });
+  });
+});
+
+describe("mergeColorWithExistingAlpha", () => {
+  it("preserves alpha when the previous color was translucent", () => {
+    expect(mergeColorWithExistingAlpha("#123456", "rgba(15, 23, 42, 0.64)")).toBe(
+      "rgba(18, 52, 86, 0.64)",
+    );
+  });
+
+  it("returns rgb when the previous color was opaque", () => {
+    expect(mergeColorWithExistingAlpha("#123456", "rgb(15, 23, 42)")).toBe("rgb(18, 52, 86)");
+  });
+});

package/src/components/editor/colorValue.ts

@@ -0,0 +1,175 @@
+export interface ParsedColor {
+  red: number;
+  green: number;
+  blue: number;
+  alpha: number;
+}
+
+export interface HsvColor {
+  hue: number;
+  saturation: number;
+  value: number;
+}
+
+function clampChannel(value: number): number {
+  return Math.max(0, Math.min(255, Math.round(value)));
+}
+
+function clampAlpha(value: number): number {
+  return Math.max(0, Math.min(1, value));
+}
+
+function toHex(value: number): string {
+  return clampChannel(value).toString(16).padStart(2, "0");
+}
+
+function formatAlpha(value: number): string {
+  return `${Math.round(clampAlpha(value) * 100) / 100}`;
+}
+
+export function parseCssColor(value: string): ParsedColor | null {
+  const trimmed = value.trim().toLowerCase();
+  if (!trimmed) return null;
+  if (trimmed === "transparent") {
+    return { red: 0, green: 0, blue: 0, alpha: 0 };
+  }
+
+  const shortHex = trimmed.match(/^#([0-9a-f]{3})$/i);
+  if (shortHex) {
+    const [r, g, b] = shortHex[1].split("");
+    return {
+      red: Number.parseInt(r + r, 16),
+      green: Number.parseInt(g + g, 16),
+      blue: Number.parseInt(b + b, 16),
+      alpha: 1,
+    };
+  }
+
+  const hex = trimmed.match(/^#([0-9a-f]{6})$/i);
+  if (hex) {
+    return {
+      red: Number.parseInt(hex[1].slice(0, 2), 16),
+      green: Number.parseInt(hex[1].slice(2, 4), 16),
+      blue: Number.parseInt(hex[1].slice(4, 6), 16),
+      alpha: 1,
+    };
+  }
+
+  const rgba = trimmed.match(
+    /^rgba?\(\s*([0-9.]+)\s*,\s*([0-9.]+)\s*,\s*([0-9.]+)(?:\s*,\s*([0-9.]+))?\s*\)$/i,
+  );
+  if (rgba) {
+    return {
+      red: clampChannel(Number.parseFloat(rgba[1])),
+      green: clampChannel(Number.parseFloat(rgba[2])),
+      blue: clampChannel(Number.parseFloat(rgba[3])),
+      alpha: clampAlpha(rgba[4] != null ? Number.parseFloat(rgba[4]) : 1),
+    };
+  }
+
+  return null;
+}
+
+export function toColorPickerValue(value: string): string {
+  const parsed = parseCssColor(value);
+  if (!parsed) return "#000000";
+  return toHexColor(parsed);
+}
+
+export function toHexColor(color: Pick<ParsedColor, "red" | "green" | "blue">): string {
+  return `#${toHex(color.red)}${toHex(color.green)}${toHex(color.blue)}`;
+}
+
+export function formatCssColor(color: ParsedColor): string {
+  const red = clampChannel(color.red);
+  const green = clampChannel(color.green);
+  const blue = clampChannel(color.blue);
+  const alpha = clampAlpha(color.alpha);
+
+  if (alpha >= 1) {
+    return `rgb(${red}, ${green}, ${blue})`;
+  }
+
+  return `rgba(${red}, ${green}, ${blue}, ${formatAlpha(alpha)})`;
+}
+
+export function rgbToHsv(color: Pick<ParsedColor, "red" | "green" | "blue">): HsvColor {
+  const red = clampChannel(color.red) / 255;
+  const green = clampChannel(color.green) / 255;
+  const blue = clampChannel(color.blue) / 255;
+  const max = Math.max(red, green, blue);
+  const min = Math.min(red, green, blue);
+  const delta = max - min;
+
+  let hue = 0;
+  if (delta !== 0) {
+    if (max === red) {
+      hue = 60 * (((green - blue) / delta) % 6);
+    } else if (max === green) {
+      hue = 60 * ((blue - red) / delta + 2);
+    } else {
+      hue = 60 * ((red - green) / delta + 4);
+    }
+  }
+
+  if (hue < 0) hue += 360;
+
+  return {
+    hue,
+    saturation: max === 0 ? 0 : delta / max,
+    value: max,
+  };
+}
+
+export function hsvToRgb(color: HsvColor): Pick<ParsedColor, "red" | "green" | "blue"> {
+  const hue = (((color.hue % 360) + 360) % 360) / 60;
+  const saturation = Math.max(0, Math.min(1, color.saturation));
+  const value = Math.max(0, Math.min(1, color.value));
+  const chroma = value * saturation;
+  const x = chroma * (1 - Math.abs((hue % 2) - 1));
+  const m = value - chroma;
+
+  let red = 0;
+  let green = 0;
+  let blue = 0;
+
+  if (hue >= 0 && hue < 1) {
+    red = chroma;
+    green = x;
+  } else if (hue >= 1 && hue < 2) {
+    red = x;
+    green = chroma;
+  } else if (hue >= 2 && hue < 3) {
+    green = chroma;
+    blue = x;
+  } else if (hue >= 3 && hue < 4) {
+    green = x;
+    blue = chroma;
+  } else if (hue >= 4 && hue < 5) {
+    red = x;
+    blue = chroma;
+  } else {
+    red = chroma;
+    blue = x;
+  }
+
+  return {
+    red: clampChannel((red + m) * 255),
+    green: clampChannel((green + m) * 255),
+    blue: clampChannel((blue + m) * 255),
+  };
+}
+
+export function mergeColorWithExistingAlpha(nextHex: string, previousValue: string): string {
+  const hex = nextHex.trim();
+  const match = hex.match(/^#([0-9a-f]{6})$/i);
+  if (!match) return previousValue;
+
+  const previous = parseCssColor(previousValue);
+  const red = Number.parseInt(match[1].slice(0, 2), 16);
+  const green = Number.parseInt(match[1].slice(2, 4), 16);
+  const blue = Number.parseInt(match[1].slice(4, 6), 16);
+  const alpha = previous?.alpha ?? 1;
+
+  return formatCssColor({ red, green, blue, alpha });
+}

package/src/components/editor/domEditing.test.ts

@@ -0,0 +1,427 @@
+import { describe, expect, it } from "vitest";
+import { Window } from "happy-dom";
+import {
+  buildDomEditMovePatchOperations,
+  buildDomEditResizePatchOperations,
+  buildDomEditStylePatchOperation,
+  buildElementAgentPrompt,
+  findElementForSelection,
+  isTextEditableSelection,
+  serializeDomEditTextFields,
+  type DomEditSelection,
+  resolveDomEditCapabilities,
+  resolveDomEditSelection,
+} from "./domEditing";
+
+function createDocument(markup: string): Document {
+  const window = new Window();
+  Object.assign(window, { SyntaxError });
+  window.document.body.innerHTML = markup;
+  return window.document;
+}
+
+describe("resolveDomEditCapabilities", () => {
+  it("marks absolute px-positioned layers as movable and resizable", () => {
+    expect(
+      resolveDomEditCapabilities({
+        selector: "#card",
+        inlineStyles: {
+          left: "120px",
+          top: "80px",
+          width: "240px",
+          height: "140px",
+        },
+        computedStyles: {
+          position: "absolute",
+          left: "120px",
+          top: "80px",
+          width: "240px",
+          height: "140px",
+          transform: "none",
+        },
+        isCompositionHost: false,
+        isMasterView: false,
+      }),
+    ).toEqual({
+      canSelect: true,
+      canEditStyles: true,
+      canMove: true,
+      canResize: true,
+      canDetachFromLayout: false,
+      reasonIfDisabled: undefined,
+    });
+  });
+
+  it("rejects flex/grid children for move and resize", () => {
+    expect(
+      resolveDomEditCapabilities({
+        selector: "#chip",
+        tagName: "div",
+        inlineStyles: {},
+        computedStyles: {
+          position: "static",
+          display: "block",
+          left: "auto",
+          top: "auto",
+          width: "180px",
+          height: "64px",
+          transform: "none",
+        },
+        isCompositionHost: false,
+        isMasterView: false,
+      }),
+    ).toMatchObject({
+      canSelect: true,
+      canEditStyles: true,
+      canMove: false,
+      canResize: false,
+      canDetachFromLayout: true,
+      reasonIfDisabled: "This layer is controlled by layout.",
+    });
+  });
+
+  it("rejects transform-driven geometry", () => {
+    expect(
+      resolveDomEditCapabilities({
+        selector: "#card",
+        inlineStyles: {
+          left: "120px",
+          top: "80px",
+          width: "240px",
+          height: "140px",
+        },
+        computedStyles: {
+          position: "absolute",
+          left: "120px",
+          top: "80px",
+          width: "240px",
+          height: "140px",
+          transform: "matrix(1, 0, 0, 1, 12, 0)",
+        },
+        isCompositionHost: false,
+        isMasterView: false,
+      }),
+    ).toMatchObject({
+      canMove: false,
+      canResize: false,
+      canDetachFromLayout: false,
+    });
+  });
+
+  it("allows imported absolute media to resize from computed px geometry", () => {
+    expect(
+      resolveDomEditCapabilities({
+        selector: "#photo",
+        inlineStyles: {
+          inset: "0",
+          width: "100%",
+          height: "100%",
+        },
+        computedStyles: {
+          position: "absolute",
+          left: "0px",
+          top: "0px",
+          width: "330px",
+          height: "228px",
+          transform: "none",
+        },
+        isCompositionHost: false,
+        isMasterView: false,
+      }),
+    ).toMatchObject({
+      canMove: true,
+      canResize: true,
+    });
+  });
+});
+
+describe("resolveDomEditSelection", () => {
+  it("allows moving composition hosts in master view while keeping contents drill-down only", () => {
+    expect(
+      resolveDomEditCapabilities({
+        selector: "#detail-host",
+        inlineStyles: {
+          left: "80px",
+          top: "60px",
+          width: "320px",
+          height: "220px",
+        },
+        computedStyles: {
+          position: "absolute",
+          left: "80px",
+          top: "60px",
+          width: "320px",
+          height: "220px",
+          transform: "none",
+        },
+        isCompositionHost: true,
+        isMasterView: true,
+      }),
+    ).toEqual({
+      canSelect: true,
+      canEditStyles: false,
+      canMove: true,
+      canResize: true,
+      canDetachFromLayout: false,
+      reasonIfDisabled: undefined,
+    });
+  });
+
+  it("resolves child clicks inside a composition host back to the host in master view", () => {
+    const document = createDocument(`
+      <div data-composition-id="main">
+        <div id="detail-host" data-composition-src="compositions/detail-card.html">
+          <span id="inner-copy">Nested scene</span>
+        </div>
+      </div>
+    `);
+
+    const child = document.getElementById("inner-copy") as HTMLElement;
+    const selection = resolveDomEditSelection(child, {
+      activeCompositionPath: null,
+      isMasterView: true,
+    });
+
+    expect(selection?.id).toBe("detail-host");
+    expect(selection?.isCompositionHost).toBe(true);
+    expect(selection?.capabilities.canMove).toBe(false);
+    expect(selection?.capabilities.canEditStyles).toBe(false);
+  });
+
+  it("scopes class selector indexing to the same source file", () => {
+    const document = createDocument(`
+      <div data-composition-id="main">
+        <div class="chip">Root chip</div>
+        <div data-composition-id="nested" data-composition-file="compositions/nested.html">
+          <div class="chip">Nested chip</div>
+        </div>
+      </div>
+    `);
+
+    const rootChip = document.getElementsByClassName("chip")[0] as HTMLElement;
+    const selection = resolveDomEditSelection(rootChip, {
+      activeCompositionPath: null,
+      isMasterView: true,
+    });
+
+    expect(selection?.sourceFile).toBe("index.html");
+    expect(selection?.selector).toBe(".chip");
+    expect(selection?.selectorIndex).toBe(0);
+    expect(findElementForSelection(document, selection!, null)).toBe(rootChip);
+  });
+
+  it("prefers the nearest clip ancestor on single-click style selection", () => {
+    const document = createDocument(`
+      <section id="card" class="clip" style="left: 10px; top: 20px; width: 200px; height: 100px; position: absolute;">
+        <p id="copy">Hello</p>
+      </section>
+    `);
+
+    const child = document.getElementById("copy") as HTMLElement;
+    const selection = resolveDomEditSelection(child, {
+      activeCompositionPath: null,
+      isMasterView: false,
+      preferClipAncestor: true,
+    });
+
+    expect(selection?.id).toBe("card");
+    expect(selection?.selector).toBe("#card");
+  });
+
+  it("collects simple child text blocks as separate editable fields", () => {
+    const document = createDocument(`
+      <section id="card" class="clip" style="left: 10px; top: 20px; width: 200px; height: 100px; position: absolute;">
+        <strong>Headline</strong>
+        <span>Supporting copy</span>
+      </section>
+    `);
+
+    const selection = resolveDomEditSelection(document.getElementById("card") as HTMLElement, {
+      activeCompositionPath: null,
+      isMasterView: false,
+    });
+
+    expect(selection?.textFields.map((field) => field.label)).toEqual(["Text 1", "Text 2"]);
+    expect(selection?.textFields.map((field) => field.value)).toEqual([
+      "Headline",
+      "Supporting copy",
+    ]);
+  });
+
+  it("preserves user-entered text spacing in editable text fields", () => {
+    const document = createDocument(`
+      <section id="card" class="clip" style="position: absolute;">
+        <strong>Headline with trailing space </strong>
+      </section>
+    `);
+
+    const selection = resolveDomEditSelection(document.getElementById("card") as HTMLElement, {
+      activeCompositionPath: null,
+      isMasterView: false,
+    });
+
+    expect(selection?.textFields[0]?.value).toBe("Headline with trailing space ");
+  });
+
+  it("keeps an emptied text layer editable so users can type into it again", () => {
+    const document = createDocument(`
+      <div id="card" class="clip" style="position: absolute;"></div>
+    `);
+
+    const selection = resolveDomEditSelection(document.getElementById("card") as HTMLElement, {
+      activeCompositionPath: null,
+      isMasterView: false,
+    });
+
+    expect(selection?.textFields).toMatchObject([
+      {
+        key: "self:0:div",
+        label: "Content",
+        value: "",
+        source: "self",
+      },
+    ]);
+    expect(selection ? isTextEditableSelection(selection) : false).toBe(true);
+  });
+
+  it("keeps emptied child text layers editable after their content is cleared", () => {
+    const document = createDocument(`
+      <div id="card" class="clip" style="position: absolute;">
+        <strong></strong>
+        <span></span>
+      </div>
+    `);
+
+    const selection = resolveDomEditSelection(document.getElementById("card") as HTMLElement, {
+      activeCompositionPath: null,
+      isMasterView: false,
+    });
+
+    expect(selection?.textFields.map((field) => field.tagName)).toEqual(["strong", "span"]);
+    expect(selection?.textFields.map((field) => field.value)).toEqual(["", ""]);
+  });
+});
+
+describe("patch builders and prompt builder", () => {
+  it("builds move patch operations for left/top", () => {
+    expect(buildDomEditMovePatchOperations(140.4, 82.1)).toEqual([
+      { type: "inline-style", property: "left", value: "140px" },
+      { type: "inline-style", property: "top", value: "82px" },
+    ]);
+  });
+
+  it("builds resize patch operations for width/height", () => {
+    expect(buildDomEditResizePatchOperations(301.6, 210.1)).toEqual([
+      { type: "inline-style", property: "width", value: "302px" },
+      { type: "inline-style", property: "height", value: "210px" },
+    ]);
+  });
+
+  it("builds style patch operations", () => {
+    expect(buildDomEditStylePatchOperation("background-color", "rgb(15, 23, 42)")).toEqual({
+      type: "inline-style",
+      property: "background-color",
+      value: "rgb(15, 23, 42)",
+    });
+  });
+
+  it("builds an agent prompt with source and selector context", () => {
+    const selection = {
+      element: {} as HTMLElement,
+      id: "editable-card",
+      selector: "#editable-card",
+      selectorIndex: undefined,
+      sourceFile: "index.html",
+      compositionPath: "index.html",
+      compositionSrc: undefined,
+      isCompositionHost: false,
+      label: "Drag me first",
+      tagName: "div",
+      boundingBox: { x: 108, y: 112, width: 380, height: 196 },
+      textContent: "Drag me first",
+      dataAttributes: {},
+      inlineStyles: {
+        left: "108px",
+        top: "112px",
+        width: "380px",
+        height: "196px",
+      },
+      computedStyles: {
+        position: "absolute",
+        left: "108px",
+        top: "112px",
+        width: "380px",
+        height: "196px",
+        color: "rgb(248, 250, 252)",
+      },
+      textFields: [
+        {
+          key: "self:0:div",
+          label: "Content",
+          value: "Drag me first",
+          tagName: "div",
+          attributes: [],
+          inlineStyles: {},
+          computedStyles: {},
+          source: "self",
+        },
+      ],
+      capabilities: {
+        canSelect: true,
+        canEditStyles: true,
+        canMove: true,
+        canResize: true,
+      },
+    } satisfies DomEditSelection;
+
+    const prompt = buildElementAgentPrompt({
+      selection,
+      currentTime: 1.25,
+      tagSnippet: `<div id="editable-card" style="position:absolute; left: 108px; top: 112px; width: 380px; height: 196px; color: rgb(248, 250, 252)"`,
+    });
+
+    expect(prompt).toContain("## HyperFrames element edit request v1");
+    expect(prompt).toContain("Schema version: 1");
+    expect(prompt).toContain("Source file: index.html");
+    expect(prompt).toContain("Selector: #editable-card");
+    expect(prompt).toContain("Playback time:");
+    expect(prompt).toContain("Text fields:");
+    expect(prompt).toContain('key=self:0:div; tag=<div>; source=self; text="Drag me first"');
+    expect(prompt).toContain("Inline styles:");
+    expect(prompt).toContain("Computed styles (browser-resolved):");
+    expect(prompt).toContain("Target HTML:");
+    expect(prompt).toContain("Guardrails:");
+    expect(prompt).toContain("Do not modify other elements' data-* attributes or positioning.");
+  });
+
+  it("serializes child text fields back into HTML", () => {
+    expect(
+      serializeDomEditTextFields([
+        {
+          key: "child:0:strong",
+          label: "Text 1",
+          value: "Headline <1>",
+          tagName: "strong",
+          attributes: [],
+          inlineStyles: {
+            "font-size": "22px",
+          },
+          computedStyles: {},
+          source: "child",
+        },
+        {
+          key: "child:1:span",
+          label: "Text 2",
+          value: "Details & more",
+          tagName: "span",
+          attributes: [],
+          inlineStyles: {},
+          computedStyles: {},
+          source: "child",
+        },
+      ]),
+    ).toBe(
+      '<strong data-hf-text-key="child:0:strong" style="font-size: 22px">Headline &lt;1&gt;</strong><span data-hf-text-key="child:1:span">Details &amp; more</span>',
+    );
+  });
+});