@hyperframes/studio 0.6.6 → 0.6.7

package/src/utils/projectRouting.ts

@@ -1,24 +1,61 @@
 const PROJECT_HASH_PREFIX = "#project/";
 
+export interface ProjectHashRoute {
+  projectId: string;
+  params: URLSearchParams;
+}
+
+function decodeHashProjectId(value: string): string {
+  try {
+    return decodeURIComponent(value);
+  } catch {
+    return value;
+  }
+}
+
+function normalizeHashParams(
+  params?: URLSearchParams | Record<string, string | null | undefined>,
+): URLSearchParams {
+  if (!params) return new URLSearchParams();
+  if (params instanceof URLSearchParams) return params;
+
+  const next = new URLSearchParams();
+  for (const [key, value] of Object.entries(params)) {
+    if (!key || value == null || value === "") continue;
+    next.set(key, value);
+  }
+  return next;
+}
+
 export function encodeProjectId(projectId: string): string {
   return encodeURIComponent(projectId);
 }
 
-export function buildProjectHash(projectId: string): string {
-  return `${PROJECT_HASH_PREFIX}${encodeProjectId(projectId)}`;
+export function buildProjectHash(
+  projectId: string,
+  params?: URLSearchParams | Record<string, string | null | undefined>,
+): string {
+  const search = normalizeHashParams(params).toString();
+  return `${PROJECT_HASH_PREFIX}${encodeProjectId(projectId)}${search ? `?${search}` : ""}`;
 }
 
-export function parseProjectIdFromHash(hash: string): string | null {
+export function parseProjectHashRoute(hash: string): ProjectHashRoute | null {
   if (!hash.startsWith(PROJECT_HASH_PREFIX)) return null;
 
-  const encodedProjectId = hash.slice(PROJECT_HASH_PREFIX.length);
+  const route = hash.slice(PROJECT_HASH_PREFIX.length);
+  const queryIndex = route.indexOf("?");
+  const encodedProjectId = queryIndex >= 0 ? route.slice(0, queryIndex) : route;
   if (!encodedProjectId || encodedProjectId.includes("/")) return null;
 
-  try {
-    return decodeURIComponent(encodedProjectId);
-  } catch {
-    return encodedProjectId;
-  }
+  const rawParams = queryIndex >= 0 ? route.slice(queryIndex + 1) : "";
+  return {
+    projectId: decodeHashProjectId(encodedProjectId),
+    params: new URLSearchParams(rawParams),
+  };
+}
+
+export function parseProjectIdFromHash(hash: string): string | null {
+  return parseProjectHashRoute(hash)?.projectId ?? null;
 }
 
 export function buildProjectApiPath(projectId: string, suffix = ""): string {

package/src/utils/sourcePatcher.ts

@@ -71,7 +71,7 @@ function splitInlineStyleDeclarations(style: string): string[] {
 export interface PatchOperation {
   type: "inline-style" | "attribute" | "text-content";
   property: string;
-  value: string;
+  value: string | null;
 }
 
 export interface PatchTarget {
@@ -133,7 +133,12 @@ export function resolveSourceFile(
 /**
  * Apply a style property change to an element's inline style in the HTML source.
  */
-function patchInlineStyle(html: string, elementId: string, prop: string, value: string): string {
+function patchInlineStyle(
+  html: string,
+  elementId: string,
+  prop: string,
+  value: string | null,
+): string {
   // Find the element tag with this id
   const idPattern = new RegExp(`(<[^>]*\\bid=(["'])${escapeRegex(elementId)}\\2[^>]*)>`, "i");
   const match = idPattern.exec(html);
@@ -143,7 +148,12 @@ function patchInlineStyle(html: string, elementId: string, prop: string, value:
   return patchInlineStyleInTag(html, tag, prop, value);
 }
 
-function patchInlineStyleInTag(html: string, tag: string, prop: string, value: string): string {
+function patchInlineStyleInTag(
+  html: string,
+  tag: string,
+  prop: string,
+  value: string | null,
+): string {
   if (!tag) return html;
 
   // Check if there's an existing style attribute
@@ -160,16 +170,22 @@ function patchInlineStyleInTag(html: string, tag: string, prop: string, value: s
       const val = part.slice(colon + 1).trim();
       if (key) props.set(key, val);
     }
-    // Update/add the property
-    props.set(prop, value);
-    // Rebuild style string
+    // Update/add or remove the property
+    if (value === null) {
+      props.delete(prop);
+    } else {
+      props.set(prop, value);
+    }
+    // Rebuild style string; keep style="" if empty (harmless)
     const newStyle = Array.from(props.entries())
       .map(([k, v]) => `${k}: ${escapeStyleAttributeValue(v, quote)}`)
       .join("; ");
     const newTag = tag.replace(styleMatch[0], `style=${quote}${newStyle}${quote}`);
     return html.replace(tag, newTag);
   } else {
-    // No existing style — add one
+    // No existing style attribute
+    if (value === null) return html; // nothing to remove
+    // Add one
     const newTag =
       tag.replace(/>$/, "") + ` style="${prop}: ${escapeStyleAttributeValue(value, '"')}"`;
     return html.replace(tag, newTag);
@@ -180,7 +196,7 @@ function patchInlineStyleByTarget(
   html: string,
   target: PatchTarget,
   prop: string,
-  value: string,
+  value: string | null,
 ): string {
   const match = findTagByTarget(html, target);
   if (!match) return html;
@@ -277,15 +293,23 @@ function patchAttributeByTarget(
   html: string,
   target: PatchTarget,
   attr: string,
-  value: string,
+  value: string | null,
 ): string {
   const match = findTagByTarget(html, target);
   if (!match) return html;
 
   const fullAttr = attr.startsWith("data-") ? attr : `data-${attr}`;
-  const attrPattern = new RegExp(`\\b${fullAttr}=(["'])([^"']*)\\1`);
+  const attrPattern = new RegExp(`\\b${escapeRegex(fullAttr)}=(["'])([^"']*)\\1`);
   const tag = match.tag;
 
+  if (value === null) {
+    // Remove the attribute if present
+    if (!attrPattern.test(tag)) return html;
+    const removePattern = new RegExp(`\\s+${escapeRegex(fullAttr)}=(["'])[^"']*\\1`);
+    const newTag = tag.replace(removePattern, "");
+    return replaceTagAtMatch(html, match, newTag);
+  }
+
   if (attrPattern.test(tag)) {
     const newTag = tag.replace(attrPattern, `${fullAttr}="${value}"`);
     return replaceTagAtMatch(html, match, newTag);
@@ -298,14 +322,26 @@ function patchAttributeByTarget(
 /**
  * Apply an attribute change to an element in the HTML source.
  */
-function patchAttribute(html: string, elementId: string, attr: string, value: string): string {
+function patchAttribute(
+  html: string,
+  elementId: string,
+  attr: string,
+  value: string | null,
+): string {
   const idPattern = new RegExp(`(<[^>]*\\bid=(["'])${escapeRegex(elementId)}\\2[^>]*)>`, "i");
   const match = idPattern.exec(html);
   if (!match) return html;
 
   const tag = match[1];
   const fullAttr = attr.startsWith("data-") ? attr : `data-${attr}`;
-  const attrPattern = new RegExp(`\\b${fullAttr}=(["'])([^"']*)\\1`);
+  const attrPattern = new RegExp(`\\b${escapeRegex(fullAttr)}=(["'])([^"']*)\\1`);
+
+  if (value === null) {
+    if (!attrPattern.test(tag)) return html;
+    const removePattern = new RegExp(`\\s+${escapeRegex(fullAttr)}=(["'])[^"']*\\1`);
+    const newTag = tag.replace(removePattern, "");
+    return html.replace(tag, newTag);
+  }
 
   if (attrPattern.test(tag)) {
     // Update existing attribute
@@ -381,7 +417,7 @@ export function applyPatch(html: string, elementId: string, op: PatchOperation):
     case "attribute":
       return patchAttribute(html, elementId, op.property, op.value);
     case "text-content":
-      return patchTextContent(html, elementId, op.value);
+      return op.value !== null ? patchTextContent(html, elementId, op.value) : html;
     default:
       return html;
   }
@@ -401,7 +437,7 @@ export function applyPatchByTarget(html: string, target: PatchTarget, op: PatchO
     case "attribute":
       return patchAttributeByTarget(html, target, op.property, op.value);
     case "text-content":
-      return patchTextContentByTarget(html, target, op.value);
+      return op.value !== null ? patchTextContentByTarget(html, target, op.value) : html;
     default:
       return html;
   }

package/src/utils/studioPreviewHelpers.test.ts

@@ -0,0 +1,56 @@
+import { describe, expect, it, vi } from "vitest";
+import { pauseStudioPreviewPlayback } from "./studioPreviewHelpers";
+
+describe("pauseStudioPreviewPlayback", () => {
+  it("pauses through __player without pausing sibling timelines directly", () => {
+    const playerPause = vi.fn();
+    const timelinePause = vi.fn();
+    const siblingPause = vi.fn();
+
+    const iframe = {
+      contentWindow: {
+        __player: {
+          getTime: () => 4.25,
+          pause: playerPause,
+        },
+        __timeline: {
+          time: () => 4.25,
+          pause: timelinePause,
+        },
+        __timelines: {
+          root: {
+            pause: siblingPause,
+          },
+        },
+      },
+    } as unknown as HTMLIFrameElement;
+
+    expect(pauseStudioPreviewPlayback(iframe)).toBe(4.25);
+    expect(playerPause).toHaveBeenCalledTimes(1);
+    expect(timelinePause).not.toHaveBeenCalled();
+    expect(siblingPause).not.toHaveBeenCalled();
+  });
+
+  it("falls back to pausing timelines directly when __player is unavailable", () => {
+    const timelinePause = vi.fn();
+    const siblingPause = vi.fn();
+
+    const iframe = {
+      contentWindow: {
+        __timeline: {
+          time: () => 2.5,
+          pause: timelinePause,
+        },
+        __timelines: {
+          root: {
+            pause: siblingPause,
+          },
+        },
+      },
+    } as unknown as HTMLIFrameElement;
+
+    expect(pauseStudioPreviewPlayback(iframe)).toBe(2.5);
+    expect(timelinePause).toHaveBeenCalledTimes(1);
+    expect(siblingPause).toHaveBeenCalledTimes(1);
+  });
+});

package/src/utils/studioPreviewHelpers.ts

@@ -1,5 +1,9 @@
 import type { DomEditViewport, DomEditSelection } from "../components/editor/domEditing";
 import { resolveVisualDomEditSelectionTarget } from "../components/editor/domEditing";
+import {
+  getDomLayerPatchTarget,
+  isElementComputedVisible,
+} from "../components/editor/domEditingElement";
 import { usePlayerStore, liveTime } from "../player";
 import { getEventTargetElement } from "./studioHelpers";
 
@@ -56,6 +60,28 @@ export function getPreviewLocalPointer(
   return resolvePreviewLocalPointer(iframe, doc, win, clientX, clientY);
 }
 
+const POINTER_EVENTS_OVERRIDE_ID = "__hf_studio_pointer_events_override__";
+
+function forcePointerEventsAuto(doc: Document): HTMLStyleElement | null {
+  try {
+    const style = doc.createElement("style");
+    style.id = POINTER_EVENTS_OVERRIDE_ID;
+    style.textContent = "* { pointer-events: auto !important; }";
+    doc.head.appendChild(style);
+    return style;
+  } catch {
+    return null;
+  }
+}
+
+function removePointerEventsOverride(style: HTMLStyleElement | null): void {
+  try {
+    style?.remove();
+  } catch {
+    // cross-origin or detached doc
+  }
+}
+
 export function getPreviewTargetFromPointer(
   iframe: HTMLIFrameElement,
   clientX: number,
@@ -75,17 +101,25 @@ export function getPreviewTargetFromPointer(
   const localPointer = resolvePreviewLocalPointer(iframe, doc, win, clientX, clientY);
   if (!localPointer) return null;
 
-  if (typeof doc.elementsFromPoint === "function") {
-    const visualTarget = resolveVisualDomEditSelectionTarget(
-      doc.elementsFromPoint(localPointer.x, localPointer.y),
-      {
-        activeCompositionPath,
-      },
-    );
-    if (visualTarget) return visualTarget;
-  }
+  const overrideStyle = forcePointerEventsAuto(doc);
+  try {
+    if (typeof doc.elementsFromPoint === "function") {
+      const visualTarget = resolveVisualDomEditSelectionTarget(
+        doc.elementsFromPoint(localPointer.x, localPointer.y),
+        {
+          activeCompositionPath,
+        },
+      );
+      if (visualTarget) return visualTarget;
+    }
 
-  return getEventTargetElement(doc.elementFromPoint(localPointer.x, localPointer.y));
+    const fallback = getEventTargetElement(doc.elementFromPoint(localPointer.x, localPointer.y));
+    if (!fallback || !getDomLayerPatchTarget(fallback, activeCompositionPath)) return null;
+    if (!isElementComputedVisible(fallback)) return null;
+    return fallback;
+  } finally {
+    removePointerEventsOverride(overrideStyle);
+  }
 }
 
 export function buildRasterClickSelectionContext(
@@ -160,11 +194,15 @@ export function pauseStudioPreviewPlayback(iframe: HTMLIFrameElement | null): nu
   if (!win) return null;
 
   try {
-    let pausedTime: number | null = null;
     const player = objectLike(Reflect.get(win, "__player"));
-    pausedTime = readPlaybackTime(player, "getTime") ?? pausedTime;
-    callPlaybackMethod(player, "pause");
+    const playerPausedTime = readPlaybackTime(player, "getTime");
+    const playerPause = player ? Reflect.get(player, "pause") : null;
+    if (typeof playerPause === "function") {
+      callPlaybackMethod(player, "pause");
+      return playerPausedTime;
+    }
 
+    let pausedTime: number | null = null;
     const timeline = objectLike(Reflect.get(win, "__timeline"));
     pausedTime = pausedTime ?? readPlaybackTime(timeline, "time");
     callPlaybackMethod(timeline, "pause");

package/src/utils/studioUiPreferences.test.ts

@@ -21,11 +21,13 @@ describe("studio UI preferences", () => {
 
     writeStudioUiPreferences({ timelineVisible: false }, storage);
     writeStudioUiPreferences({ playbackRate: 1.5 }, storage);
+    writeStudioUiPreferences({ audioMuted: true }, storage);
     writeStudioUiPreferences({ previewZoom: { zoomPercent: 160, panX: -20, panY: 12 } }, storage);
 
     expect(readStudioUiPreferences(storage)).toEqual({
       timelineVisible: false,
       playbackRate: 1.5,
+      audioMuted: true,
       previewZoom: { zoomPercent: 160, panX: -20, panY: 12 },
     });
   });
@@ -38,6 +40,7 @@ describe("studio UI preferences", () => {
         leftCollapsed: "yes",
         timelineVisible: true,
         playbackRate: Number.NaN,
+        audioMuted: "false",
         previewZoom: { zoomPercent: 150, panX: 0, panY: "bad" },
       }),
     );

package/src/utils/studioUiPreferences.ts

@@ -8,6 +8,7 @@ export interface StudioUiPreferences {
   leftCollapsed?: boolean;
   timelineVisible?: boolean;
   playbackRate?: number;
+  audioMuted?: boolean;
   previewZoom?: StoredPreviewZoomState;
 }
 
@@ -44,6 +45,9 @@ function readStorage(storage: Storage | null): StudioUiPreferences {
     if (typeof parsed.playbackRate === "number" && Number.isFinite(parsed.playbackRate)) {
       preferences.playbackRate = parsed.playbackRate;
     }
+    if (typeof parsed.audioMuted === "boolean") {
+      preferences.audioMuted = parsed.audioMuted;
+    }
     if (isRecord(parsed.previewZoom)) {
       const { zoomPercent, panX, panY } = parsed.previewZoom;
       if (

package/src/utils/studioUrlState.test.ts

@@ -0,0 +1,249 @@
+// @vitest-environment happy-dom
+
+import React, { act } from "react";
+import { createRoot } from "react-dom/client";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import {
+  buildStudioHash,
+  normalizeStudioCompositionPath,
+  normalizeStudioUrlPanelTab,
+  parseStudioUrlStateFromHash,
+} from "./studioUrlState";
+import { useStudioUrlState } from "../hooks/useStudioUrlState";
+import { usePlayerStore } from "../player";
+
+globalThis.IS_REACT_ACT_ENVIRONMENT = true;
+
+function resetPlayerStore() {
+  usePlayerStore.setState({
+    isPlaying: false,
+    currentTime: 0,
+    duration: 0,
+    timelineReady: false,
+    elements: [],
+    selectedElementId: null,
+    requestedSeekTime: null,
+  });
+}
+
+afterEach(() => {
+  vi.useRealTimers();
+  document.body.innerHTML = "";
+  window.history.replaceState(null, "", "/");
+  resetPlayerStore();
+});
+
+function renderStudioUrlStateHarness(
+  props: Partial<React.ComponentProps<typeof StudioUrlStateHarness>> = {},
+) {
+  const host = document.createElement("div");
+  document.body.append(host);
+  const root = createRoot(host);
+  const baseProps: React.ComponentProps<typeof StudioUrlStateHarness> = {
+    projectId: "demo",
+    activeCompPath: null,
+    currentTime: 0,
+    duration: 30,
+    isPlaying: false,
+    compositionLoading: false,
+    refreshKey: 0,
+    previewIframeRef: { current: null },
+    rightPanelTab: "renders",
+    rightCollapsed: true,
+    timelineVisible: true,
+    activeCompPathHydrated: true,
+    domEditSelection: null,
+    buildDomSelectionFromTarget: () => null,
+    applyDomSelection: () => {},
+    initialState: {
+      activeCompPath: null,
+      currentTime: 4.2,
+      rightPanelTab: null,
+      rightCollapsed: null,
+      timelineVisible: null,
+      selection: null,
+    },
+  };
+
+  const render = (nextProps: Partial<React.ComponentProps<typeof StudioUrlStateHarness>> = {}) => {
+    act(() => {
+      root.render(
+        React.createElement(StudioUrlStateHarness, {
+          ...baseProps,
+          ...props,
+          ...nextProps,
+        }),
+      );
+    });
+  };
+
+  render();
+  return {
+    rerender: render,
+    unmount: () =>
+      act(() => {
+        root.unmount();
+      }),
+  };
+}
+
+function StudioUrlStateHarness(props: Parameters<typeof useStudioUrlState>[0]) {
+  useStudioUrlState(props);
+  return null;
+}
+
+describe("studio url state", () => {
+  it("parses persisted studio state from project hash", () => {
+    const state = parseStudioUrlStateFromHash(
+      "#project/demo?v=1&comp=compositions%2Ftitle.html&t=4.25&tab=design&rc=0&tv=1&selFile=index.html&selId=hero",
+    );
+
+    expect(state.activeCompPath).toBe("compositions/title.html");
+    expect(state.currentTime).toBe(4.25);
+    expect(state.rightPanelTab).toBe("design");
+    expect(state.rightCollapsed).toBe(false);
+    expect(state.timelineVisible).toBe(true);
+    expect(state.selection).toEqual({
+      sourceFile: "index.html",
+      id: "hero",
+      selector: undefined,
+      selectorIndex: undefined,
+    });
+  });
+
+  it("builds a project hash with persisted studio state", () => {
+    expect(
+      buildStudioHash("demo", {
+        activeCompPath: "compositions/title.html",
+        currentTime: 4.2571,
+        rightPanelTab: "layers",
+        rightCollapsed: true,
+        timelineVisible: false,
+        selection: {
+          sourceFile: "index.html",
+          selector: ".card",
+          selectorIndex: 2,
+        },
+      }),
+    ).toBe(
+      "#project/demo?v=1&comp=compositions%2Ftitle.html&t=4.257&tab=layers&rc=1&tv=0&selFile=index.html&selSelector=.card&selIndex=2",
+    );
+  });
+
+  it("falls back cleanly on invalid values", () => {
+    const state = parseStudioUrlStateFromHash("#project/demo?tab=nope&t=abc&rc=9&tv=7");
+
+    expect(state.activeCompPath).toBeNull();
+    expect(state.currentTime).toBeNull();
+    expect(state.rightPanelTab).toBeNull();
+    expect(state.rightCollapsed).toBeNull();
+    expect(state.timelineVisible).toBeNull();
+    expect(state.selection).toBeNull();
+  });
+
+  it("normalizes stale composition paths to the master composition", () => {
+    expect(
+      normalizeStudioCompositionPath("compositions/missing.html", [
+        "index.html",
+        "compositions/title.html",
+      ]),
+    ).toBeNull();
+    expect(
+      normalizeStudioCompositionPath("compositions/title.html", [
+        "index.html",
+        "compositions/title.html",
+      ]),
+    ).toBe("compositions/title.html");
+  });
+
+  it("normalizes url tabs against feature flags", () => {
+    expect(normalizeStudioUrlPanelTab("renders")).toBe("renders");
+    expect(normalizeStudioUrlPanelTab("layers", { inspectorPanelsEnabled: false })).toBe("renders");
+    expect(normalizeStudioUrlPanelTab("motion", { motionPanelEnabled: false })).toBe("design");
+  });
+
+  it("hydrates seek first, preserves the initial url state, then restores selection", () => {
+    vi.useFakeTimers();
+    window.history.replaceState(null, "", "#project/demo?t=4.2&tab=design&selId=hero");
+    const requestSeek = vi.fn();
+    usePlayerStore.setState({ requestSeek });
+    const selectedElement = document.createElement("div");
+    selectedElement.id = "hero";
+    document.body.append(selectedElement);
+    const previewDoc = document.implementation.createHTMLDocument("preview");
+    previewDoc.body.append(selectedElement);
+    const applyDomSelection = vi.fn();
+    const restoredSelection = {
+      element: selectedElement,
+      id: "hero",
+      selector: "#hero",
+      selectorIndex: 0,
+      sourceFile: "index.html",
+      tagName: "div",
+      label: "Hero",
+      textContent: "",
+      textFields: [],
+      capabilities: {
+        canEditText: false,
+        canEditLayout: true,
+        canApplyManualOffset: true,
+        canApplyManualSize: true,
+        canApplyManualRotation: true,
+        canAdjustOpacity: true,
+        canAdjustFill: true,
+        canAdjustBorderRadius: true,
+        canAdjustStroke: true,
+        canAdjustShadow: true,
+        canAdjustZIndex: true,
+      },
+      computedStyle: {
+        display: "block",
+        position: "absolute",
+      },
+    };
+
+    const harness = renderStudioUrlStateHarness({
+      previewIframeRef: {
+        current: { contentDocument: previewDoc } as HTMLIFrameElement,
+      },
+      rightPanelTab: "design",
+      rightCollapsed: false,
+      applyDomSelection,
+      buildDomSelectionFromTarget: () => restoredSelection,
+      initialState: {
+        activeCompPath: null,
+        currentTime: 4.2,
+        rightPanelTab: "design",
+        rightCollapsed: false,
+        timelineVisible: true,
+        selection: { id: "hero" },
+      },
+    });
+
+    expect(requestSeek).toHaveBeenCalledWith(4.2);
+    expect(applyDomSelection).not.toHaveBeenCalled();
+    expect(window.location.hash).toContain("t=4.2");
+    expect(window.location.hash).toContain("tab=design");
+
+    act(() => {
+      vi.advanceTimersByTime(250);
+    });
+    expect(window.location.hash).toContain("t=4.2");
+    expect(applyDomSelection).not.toHaveBeenCalled();
+
+    harness.rerender({ currentTime: 4.2 });
+    act(() => {
+      vi.advanceTimersByTime(250);
+    });
+    expect(applyDomSelection).toHaveBeenCalledWith(restoredSelection, { revealPanel: false });
+
+    harness.rerender({ currentTime: 4.2, domEditSelection: restoredSelection });
+    act(() => {
+      vi.advanceTimersByTime(250);
+    });
+    expect(window.location.hash).toContain("t=4.2");
+    expect(window.location.hash).toContain("selId=hero");
+
+    harness.unmount();
+  });
+});