@hyperframes/studio 0.7.58 → 0.7.59

package/src/components/editor/PropertyPanelFlatFooter.tsx

@@ -0,0 +1,73 @@
+import { useTrackDesignInput } from "../../contexts/DesignPanelInputContext";
+
+export function PropertyPanelFlatFooter({
+  onAskAgent,
+  recordingState,
+  recordingDuration,
+  onToggleRecording,
+}: {
+  onAskAgent?: () => void;
+  recordingState?: "idle" | "recording" | "preview";
+  recordingDuration?: number;
+  onToggleRecording?: () => void;
+}) {
+  const track = useTrackDesignInput();
+  const recording = recordingState === "recording";
+  const recordTitle = recording
+    ? `Stop recording ${(recordingDuration ?? 0).toFixed(1)}s`
+    : "Record gesture (R)";
+
+  return (
+    // No border-t here: every possible element immediately above this footer
+    // in the new fixed-headers + scrollable-open-section layout (a collapsed
+    // FlatGroupHeader, or the open group's scrollable body wrapper) already
+    // draws its own border-b in normal document flow — nothing here is
+    // `position: sticky` anymore, so there's no rounding seam to seal (see
+    // p11-scrollable-open-section-report.md).
+    <div className="flex items-center justify-between bg-panel-bg px-4 py-[11px]">
+      <button
+        type="button"
+        data-flat-footer-ask="true"
+        onClick={() => {
+          track("button", "Ask agent");
+          onAskAgent?.();
+        }}
+        disabled={!onAskAgent}
+        className="flex items-center gap-[7px] text-[11px] font-medium text-panel-text-2 disabled:cursor-not-allowed"
+      >
+        <svg
+          width="13"
+          height="13"
+          viewBox="0 0 16 16"
+          fill="currentColor"
+          className="text-panel-accent"
+        >
+          <path d="M8 1l1.4 4.6L14 7l-4.6 1.4L8 13l-1.4-4.6L2 7l4.6-1.4z" />
+        </svg>
+        Ask agent about this element
+      </button>
+      {onToggleRecording && (
+        <button
+          type="button"
+          data-flat-footer-record="true"
+          aria-label={recordTitle}
+          title={recordTitle}
+          onMouseDown={(e) => e.preventDefault()}
+          onClick={() => {
+            track("button", "Gesture recording");
+            onToggleRecording();
+          }}
+          className={recording ? "text-panel-danger animate-pulse" : "text-panel-danger"}
+        >
+          <svg width="14" height="14" viewBox="0 0 14 14" fill="currentColor">
+            {recording ? (
+              <rect x="2" y="2" width="10" height="10" rx="1.5" />
+            ) : (
+              <circle cx="7" cy="7" r="6" />
+            )}
+          </svg>
+        </button>
+      )}
+    </div>
+  );
+}

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

@@ -0,0 +1,79 @@
+// @vitest-environment happy-dom
+
+import React, { act } from "react";
+import { createRoot } from "react-dom/client";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { PropertyPanelFlatHeader } from "./PropertyPanelFlatHeader";
+
+(globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+afterEach(() => {
+  document.body.innerHTML = "";
+});
+
+function renderHeader(overrides: Partial<Parameters<typeof PropertyPanelFlatHeader>[0]> = {}) {
+  const host = document.createElement("div");
+  document.body.append(host);
+  const root = createRoot(host);
+  const props = {
+    name: "Mono Label",
+    meta: ".mono-label · div",
+    elementKind: "text" as const,
+    hidden: false,
+    copied: false,
+    onCopy: vi.fn(),
+    onClear: vi.fn(),
+    showUngroup: false,
+    ...overrides,
+  };
+  act(() => {
+    root.render(<PropertyPanelFlatHeader {...props} />);
+  });
+  return { host, root, props };
+}
+
+describe("PropertyPanelFlatHeader", () => {
+  it("renders name, meta, and the mint text-type icon", () => {
+    const { host, root } = renderHeader();
+    expect(host.textContent).toContain("Mono Label");
+    expect(host.textContent).toContain(".mono-label · div");
+    const icon = host.querySelector('[data-flat-header-icon="true"]');
+    expect(icon?.className).toContain("text-panel-accent");
+    act(() => root.unmount());
+  });
+
+  it("colors the media icon cyan and the other icon amber", () => {
+    const { host: mediaHost, root: mediaRoot } = renderHeader({ elementKind: "media" });
+    expect(mediaHost.querySelector('[data-flat-header-icon="true"]')?.className).toContain(
+      "text-panel-media",
+    );
+    act(() => mediaRoot.unmount());
+
+    const { host: otherHost, root: otherRoot } = renderHeader({ elementKind: "other" });
+    expect(otherHost.querySelector('[data-flat-header-icon="true"]')?.className).toContain(
+      "text-panel-container",
+    );
+    act(() => otherRoot.unmount());
+  });
+
+  it("fires onCopy and onClear from their action buttons", () => {
+    const { host, root, props } = renderHeader();
+    const copy = host.querySelector<HTMLButtonElement>(
+      '[aria-label="Copy element info to clipboard"]',
+    );
+    const clear = host.querySelector<HTMLButtonElement>('[aria-label="Clear selection"]');
+    act(() => copy?.dispatchEvent(new MouseEvent("click", { bubbles: true })));
+    act(() => clear?.dispatchEvent(new MouseEvent("click", { bubbles: true })));
+    expect(props.onCopy).toHaveBeenCalledTimes(1);
+    expect(props.onClear).toHaveBeenCalledTimes(1);
+    act(() => root.unmount());
+  });
+
+  it("only renders Ungroup when showUngroup is true", () => {
+    const { host: without } = renderHeader({ showUngroup: false });
+    expect(without.querySelector('[aria-label="Ungroup"]')).toBeNull();
+
+    const { host: withUngroup } = renderHeader({ showUngroup: true, onUngroup: vi.fn() });
+    expect(withUngroup.querySelector('[aria-label="Ungroup"]')).not.toBeNull();
+  });
+});

package/src/components/editor/PropertyPanelFlatHeader.tsx

@@ -0,0 +1,112 @@
+import { Eye, EyeSlash } from "@phosphor-icons/react";
+import { useTrackDesignInput } from "../../contexts/DesignPanelInputContext";
+import { ClipboardList, Film, Square, Type, X } from "../../icons/SystemIcons";
+
+const ICON_BY_KIND = { text: Type, media: Film, other: Square } as const;
+const ICON_COLOR_BY_KIND = {
+  text: "text-panel-accent",
+  media: "text-panel-media",
+  other: "text-panel-container",
+} as const;
+
+export function PropertyPanelFlatHeader({
+  name,
+  meta,
+  elementKind,
+  hidden,
+  onToggleHidden,
+  copied,
+  onCopy,
+  onClear,
+  onUngroup,
+  showUngroup,
+}: {
+  name: string;
+  meta: string;
+  elementKind: "text" | "media" | "other";
+  hidden: boolean;
+  onToggleHidden?: () => void;
+  copied: boolean;
+  onCopy: () => void;
+  onClear: () => void;
+  onUngroup?: () => void;
+  showUngroup: boolean;
+}) {
+  const track = useTrackDesignInput();
+  const Icon = ICON_BY_KIND[elementKind];
+  const visibilityLabel = hidden ? "Show element" : "Hide element";
+
+  return (
+    <div className="flex items-center gap-2.5 border-b border-panel-hairline px-4 py-3">
+      <Icon
+        size={15}
+        data-flat-header-icon="true"
+        className={`flex-shrink-0 ${ICON_COLOR_BY_KIND[elementKind]}`}
+      />
+      <div className="flex min-w-0 flex-1 items-baseline gap-2">
+        <span className="truncate text-[13px] font-semibold text-panel-text-0">{name}</span>
+        <span className="truncate font-mono text-[10px] text-panel-text-4">{meta}</span>
+      </div>
+      <div className="flex flex-shrink-0 items-center gap-2.5 text-panel-text-3">
+        {showUngroup && (
+          <button
+            type="button"
+            aria-label="Ungroup"
+            title="Ungroup (⌘⇧G)"
+            onClick={() => {
+              track("button", "Ungroup");
+              onUngroup?.();
+            }}
+          >
+            <svg
+              width="13"
+              height="13"
+              viewBox="0 0 16 16"
+              fill="none"
+              stroke="currentColor"
+              strokeWidth="1.5"
+            >
+              <rect x="1.5" y="1.5" width="7" height="7" rx="1" />
+              <rect x="7.5" y="7.5" width="7" height="7" rx="1" />
+            </svg>
+          </button>
+        )}
+        {onToggleHidden && (
+          <button
+            type="button"
+            aria-label={visibilityLabel}
+            title={visibilityLabel}
+            onClick={() => {
+              track("toggle", "Element visibility");
+              onToggleHidden();
+            }}
+          >
+            {hidden ? <EyeSlash size={13} weight="bold" /> : <Eye size={13} weight="bold" />}
+          </button>
+        )}
+        <button
+          type="button"
+          aria-label="Copy element info to clipboard"
+          title={copied ? "Copied!" : "Copy element info for any AI agent"}
+          onClick={() => {
+            track("button", "Copy element info");
+            onCopy();
+          }}
+          className={copied ? "text-panel-accent" : undefined}
+        >
+          <ClipboardList size={13} />
+        </button>
+        <button
+          type="button"
+          aria-label="Clear selection"
+          onClick={() => {
+            track("button", "Clear selection");
+            onClear();
+          }}
+        >
+          <X size={13} />
+        </button>
+      </div>
+    </div>
+  );
+}

package/src/components/editor/gsapAnimationCallbacks.ts

@@ -34,3 +34,30 @@ export interface GsapAnimationEditCallbacks {
   /** Unroll a computed (helper/loop) tween into literal tweens so it edits directly. */
   onUnroll?: (animationId: string) => void;
 }
+
+// User-facing control label for each animation-meta field. The ease control is
+// labelled "Speed" in the card UI, so ease/easeEach map there.
+const ANIMATION_META_LABELS: Record<string, { control: string; name: string }> = {
+  duration: { control: "metric", name: "Length" },
+  position: { control: "metric", name: "Starts at" },
+  ease: { control: "select", name: "Speed" },
+  easeEach: { control: "select", name: "Speed" },
+};
+
+/**
+ * Emit design-input telemetry for an `onUpdateMeta` payload, attributing each
+ * changed field to the control the user actually touched. Iterates the real keys
+ * present rather than falling through to a single placeholder — so a meta field
+ * added later is attributed honestly by its own key instead of poisoning another
+ * control's usage count.
+ */
+export function trackAnimationMetaUpdate(
+  track: (control: string, name: string) => void,
+  updates: Record<string, unknown>,
+): void {
+  for (const key of Object.keys(updates)) {
+    const mapped = ANIMATION_META_LABELS[key];
+    if (mapped) track(mapped.control, mapped.name);
+    else track("select", key);
+  }
+}

package/src/components/editor/gsapLivePreview.ts

@@ -0,0 +1,34 @@
+import type { DomEditSelection } from "./domEditingTypes";
+
+/**
+ * Build the "live preview" callback the 3D-transform sub-view fires while a
+ * value is being dragged: apply a gsap.set() to the matching node inside the
+ * preview iframe so the edit is reflected immediately, before it's committed.
+ *
+ * Extracted so the identical closure exists once — shared by the legacy
+ * PropertyPanel Layout section and the flat Layout group (PropertyPanelFlat).
+ */
+// Resolve by id when unique, otherwise by selector + selectorIndex — a bare
+// querySelector(selector) always hits the FIRST match, so dragging on the
+// second of two same-selector siblings would animate the wrong element.
+function resolvePreviewNode(
+  doc: Document | null | undefined,
+  el: DomEditSelection,
+): Element | null {
+  if (!doc) return null;
+  if (el.id) return doc.querySelector(`#${el.id}`);
+  if (!el.selector) return null;
+  return doc.querySelectorAll(el.selector)[el.selectorIndex ?? 0] ?? null;
+}
+
+export function createGsapLivePreview(iframeRef: { readonly current: HTMLIFrameElement | null }) {
+  return (el: DomEditSelection, props: Record<string, number>) => {
+    const iframe = iframeRef.current;
+    const win = iframe?.contentWindow as
+      | { gsap?: { set: (t: Element, v: Record<string, number>) => void } }
+      | null
+      | undefined;
+    const node = resolvePreviewNode(iframe?.contentDocument, el);
+    if (win?.gsap && node) win.gsap.set(node, props);
+  };
+}

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

@@ -105,4 +105,14 @@ describe("manual editing availability", () => {
     expect(resolveStudioBooleanEnvFlag({ EMPTY: "" }, ["EMPTY"], true)).toBe(true);
     expect(resolveStudioBooleanEnvFlag({ UNKNOWN: "maybe" }, ["UNKNOWN"], false)).toBe(false);
   });
+
+  it("defaults the flat inspector flag to false and honors an explicit override", async () => {
+    const off = await loadAvailabilityWithEnv({});
+    expect(off.STUDIO_FLAT_INSPECTOR_ENABLED).toBe(false);
+
+    const on = await loadAvailabilityWithEnv({
+      VITE_STUDIO_FLAT_INSPECTOR_ENABLED: "true",
+    });
+    expect(on.STUDIO_FLAT_INSPECTOR_ENABLED).toBe(true);
+  });
 });

package/src/components/editor/manualEditingAvailability.ts

@@ -97,4 +97,13 @@ export const STUDIO_SDK_RESOLVER_SHADOW_ENABLED = resolveStudioBooleanEnvFlag(
   true,
 );
 
+// Studio inspector redesign ("Ledger, flat" — design_handoff_studio_inspector):
+// flat identity header/footer/groups behind a flag for incremental review.
+// Default false; enable via VITE_STUDIO_FLAT_INSPECTOR_ENABLED=true.
+export const STUDIO_FLAT_INSPECTOR_ENABLED = resolveStudioBooleanEnvFlag(
+  env,
+  ["VITE_STUDIO_ENABLE_FLAT_INSPECTOR", "VITE_STUDIO_FLAT_INSPECTOR_ENABLED"],
+  false,
+);
+
 export const STUDIO_MANUAL_EDITING_DISABLED_TITLE = "Manual editing is temporarily disabled";

package/src/components/editor/propertyPanel3dTransform.tsx

@@ -5,6 +5,7 @@ import { MetricField } from "./propertyPanelPrimitives";
 import { KeyframeNavigation } from "./KeyframeNavigation";
 import { formatPxMetricValue, parsePxMetricValue, RESPONSIVE_GRID } from "./propertyPanelHelpers";
 import { Transform3DCube, type CubePose } from "./Transform3DCube";
+import { useTrackDesignInput } from "../../contexts/DesignPanelInputContext";
 
 // translateZ only foreshortens under a perspective lens. Rather than hardcode one
 // (an arbitrary px value reads wrong at different canvas sizes), derive it from the
@@ -71,6 +72,7 @@ function Cube3dControl({
   onKeyframe?: () => void;
   keyframed?: boolean;
 }) {
+  const track = useTrackDesignInput();
   const pose: CubePose = {
     rotationX: gsapRuntimeValues.rotationX ?? 0,
     rotationY: gsapRuntimeValues.rotationY ?? 0,
@@ -96,6 +98,7 @@ function Cube3dControl({
     }
     const axes = Object.keys(changedProps);
     if (axes.length === 0) return;
+    track("slider", "3D rotation pose");
     // ONE keyframe for the whole pose change — avoids per-axis commits racing into
     // adjacent duplicate keyframes.
     void onCommitAnimatedProperties(element, changedProps);
@@ -111,6 +114,7 @@ function Cube3dControl({
       scale: 1,
       transformPerspective: 0,
     };
+    track("button", "Reset 3D transform");
     void onCommitAnimatedProperties(element, identity);
   };
   // Immediate element feedback while dragging — set the live transform without a
@@ -168,6 +172,7 @@ function Cube3dControl({
             }
             // One commit for all props so the writes can't race read-modify-write on
             // the same script (which dropped a prop and reverted after a seek).
+            track("slider", "3D depth");
             void onCommitAnimatedProperties(element, props);
           }}
           onRecenter={recenter}

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

@@ -0,0 +1,28 @@
+// @vitest-environment happy-dom
+
+import React, { act } from "react";
+import { createRoot } from "react-dom/client";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { ColorField } from "./propertyPanelColor";
+
+(globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+afterEach(() => {
+  document.body.innerHTML = "";
+});
+
+describe("ColorField flat trigger", () => {
+  it("renders label and value inline with a small swatch, no boxed border", () => {
+    const host = document.createElement("div");
+    document.body.append(host);
+    const root = createRoot(host);
+    act(() => {
+      root.render(<ColorField flat label="Color" value="rgb(255, 176, 32)" onCommit={vi.fn()} />);
+    });
+    const trigger = host.querySelector<HTMLButtonElement>('[data-flat-color-trigger="true"]');
+    expect(trigger).not.toBeNull();
+    expect(trigger?.className).not.toContain("border-neutral-800");
+    expect(host.textContent).toContain("Color");
+    act(() => root.unmount());
+  });
+});

package/src/components/editor/propertyPanelColor.tsx

@@ -11,6 +11,7 @@ import {
 } from "./colorValue";
 import { resolveFloatingPanelPosition, type FloatingPosition } from "./floatingPanel";
 import { colorFromCss, FIELD, LABEL } from "./propertyPanelHelpers";
+import { useTrackDesignInput } from "../../contexts/DesignPanelInputContext";
 
 const COLOR_PICKER_SIZE = { width: 292, height: 386 };
 
@@ -121,13 +122,16 @@ export function ColorField({
   label,
   value,
   disabled,
+  flat,
   onCommit,
 }: {
   label: string;
   value: string;
   disabled?: boolean;
+  flat?: boolean;
   onCommit: (nextValue: string) => void;
 }) {
+  const track = useTrackDesignInput();
   const buttonRef = useRef<HTMLButtonElement | null>(null);
   const panelRef = useRef<HTMLDivElement | null>(null);
   const [open, setOpen] = useState(false);
@@ -201,7 +205,9 @@ export function ColorField({
   const commitColor = (nextColor: ParsedColor) => {
     setDraftColor(nextColor);
     setHexDraft(toHexColor(nextColor).toUpperCase());
-    onCommit(formatCssColor(nextColor));
+    const nextValue = formatCssColor(nextColor);
+    if (nextValue !== value) track("color", label);
+    onCommit(nextValue);
   };
 
   const commitHsv = (nextHsv: { hue?: number; saturation?: number; value?: number }) => {
@@ -349,6 +355,30 @@ export function ColorField({
     }
   };
 
+  if (flat) {
+    return (
+      <div className="flex min-h-[30px] items-center justify-between">
+        <span className="text-[11px] text-panel-text-2">{label}</span>
+        <button
+          type="button"
+          data-flat-color-trigger="true"
+          disabled={disabled}
+          aria-label={`Pick ${label.toLowerCase()} color`}
+          ref={buttonRef}
+          onClick={openPicker}
+          className="flex items-center gap-2 disabled:cursor-not-allowed"
+        >
+          <span
+            className="h-4 w-4 flex-shrink-0 rounded-[4px]"
+            style={{ backgroundColor: value || "transparent" }}
+          />
+          <span className="font-mono text-[11px] text-panel-text-0">{value}</span>
+        </button>
+        {picker}
+      </div>
+    );
+  }
+
   return (
     <div className="grid min-w-0 gap-1.5">
       <span className={LABEL}>{label}</span>

package/src/components/editor/propertyPanelColorGradingControls.tsx

@@ -11,6 +11,7 @@ import { ChevronDown, ChevronRight, Plus, X } from "../../icons/SystemIcons";
 import { LUT_EXT } from "../../utils/mediaTypes";
 import { LABEL } from "./propertyPanelHelpers";
 import { ColorGradingSliderControl } from "./propertyPanelColorGradingSlider";
+import { useTrackDesignInput } from "../../contexts/DesignPanelInputContext";
 
 const LUT_UPLOAD_DIR = "assets/luts";
 
@@ -175,6 +176,7 @@ export function ColorGradingControls({
   onImportAssets?: (files: FileList, dir?: string) => Promise<string[]>;
   onCommitColorGrading: (nextGrading: NormalizedHfColorGrading) => void;
 }) {
+  const track = useTrackDesignInput();
   const lutInputRef = useRef<HTMLInputElement>(null);
   const [lutOpen, setLutOpen] = useState(false);
   const [detailSettings, setDetailSettings] = useState<"vignette" | "grain" | null>(null);
@@ -195,7 +197,10 @@ export function ColorGradingControls({
 
   const applyPreset = (preset: string) => {
     const next = normalizeHfColorGrading({ preset, intensity: 1, lut: grading.lut });
-    if (next) onCommitColorGrading(next);
+    if (next) {
+      track("select", "Preset");
+      onCommitColorGrading(next);
+    }
   };
   const updateFilterIntensity = (value: number) => {
     onCommitColorGrading({
@@ -218,7 +223,10 @@ export function ColorGradingControls({
     if (!files?.length || !onImportAssets) return;
     const uploaded = await onImportAssets(files, LUT_UPLOAD_DIR);
     const firstLut = uploaded.find((asset) => LUT_EXT.test(asset));
-    if (firstLut) applyLut(firstLut, 1);
+    if (firstLut) {
+      track("button", "Import LUT");
+      applyLut(firstLut, 1);
+    }
   };
   const commitDetailSlider = (slider: DetailSlider, next: number) => {
     onCommitColorGrading({
@@ -313,6 +321,7 @@ export function ColorGradingControls({
                 value={selectedLut}
                 onChange={(event) => {
                   const nextSrc = event.target.value;
+                  track("select", "Custom LUT");
                   applyLut(
                     nextSrc || null,
                     nextSrc && grading.lut?.src === nextSrc ? grading.lut.intensity : 1,