@hyperframes/studio 0.7.16 → 0.7.18

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/studio",
-  "version": "0.7.16",
+  "version": "0.7.18",
   "description": "",
   "repository": {
     "type": "git",
@@ -45,11 +45,11 @@
     "dompurify": "^3.2.4",
     "marked": "^14.1.4",
     "mediabunny": "^1.45.3",
-    "@hyperframes/core": "0.7.16",
-    "@hyperframes/player": "0.7.16",
-    "@hyperframes/parsers": "0.7.16",
-    "@hyperframes/studio-server": "0.7.16",
-    "@hyperframes/sdk": "0.7.16"
+    "@hyperframes/parsers": "0.7.18",
+    "@hyperframes/player": "0.7.18",
+    "@hyperframes/sdk": "0.7.18",
+    "@hyperframes/studio-server": "0.7.18",
+    "@hyperframes/core": "0.7.18"
   },
   "devDependencies": {
     "@types/react": "19",
@@ -64,7 +64,7 @@
     "vite": "^6.4.2",
     "vitest": "^3.2.4",
     "zustand": "^5.0.0",
-    "@hyperframes/producer": "0.7.16"
+    "@hyperframes/producer": "0.7.18"
   },
   "peerDependencies": {
     "react": "19",

package/src/App.tsx

@@ -83,7 +83,7 @@ export function StudioApp() {
   const [previewIframe, setPreviewIframe] = useState<HTMLIFrameElement | null>(null);
   const [compositionLoading, setCompositionLoading] = useState(true);
   const [refreshKey, setRefreshKey] = useState(0);
-  const [, setPreviewDocumentVersion] = useState(0);
+  const [previewDocumentVersion, setPreviewDocumentVersion] = useState(0);
   const [blockPreview, setBlockPreview] = useState<BlockPreviewInfo | null>(null);
   const previewIframeRef = useRef<HTMLIFrameElement | null>(null);
   const activeCompPathRef = useRef(activeCompPath);
@@ -296,6 +296,7 @@ export function StudioApp() {
     projectIdRef: fileManager.projectIdRef,
     previewIframe,
     refreshKey,
+    previewDocumentVersion,
     rightPanelTab: panelLayout.rightPanelTab,
     applyStudioManualEditsToPreviewRef: previewPersistence.applyStudioManualEditsToPreviewRef,
     syncPreviewHistoryHotkey: appHotkeys.syncPreviewHistoryHotkey,

package/src/hooks/useDomEditSession.ts

@@ -18,6 +18,7 @@ import { useGsapScriptCommits } from "./useGsapScriptCommits";
 import { useGsapCacheVersion } from "./useGsapTweenCache";
 import { useDomEditWiring } from "./useDomEditWiring";
 import { useGsapAwareEditing } from "./useGsapAwareEditing";
+import { useStudioSelectionPublisher } from "./useStudioSelectionPublisher";
 
 // ── Types ──
 
@@ -54,6 +55,7 @@ export interface UseDomEditSessionParams {
   projectIdRef: React.MutableRefObject<string | null>;
   previewIframe: HTMLIFrameElement | null;
   refreshKey: number;
+  previewDocumentVersion: number;
   rightPanelTab: RightPanelTab;
   applyStudioManualEditsToPreviewRef: React.MutableRefObject<
     (iframe: HTMLIFrameElement) => Promise<void>
@@ -96,6 +98,7 @@ export function useDomEditSession({
   projectIdRef,
   previewIframe,
   refreshKey,
+  previewDocumentVersion,
   rightPanelTab,
   applyStudioManualEditsToPreviewRef,
   syncPreviewHistoryHotkey,
@@ -168,6 +171,15 @@ export function useDomEditSession({
     domEditSelection,
   });
 
+  useStudioSelectionPublisher({
+    projectId,
+    domEditSelection,
+    domEditSelectionRef,
+    refreshKey,
+    previewDocumentVersion,
+    refreshDomEditSelectionFromPreview,
+  });
+
   // ── GSAP cache (hoisted so both useGsapScriptCommits and useDomEditWiring share the same instance) ──
 
   const { version: gsapCacheVersion, bump: bumpGsapCache } = useGsapCacheVersion();

package/src/hooks/useDomSelection.ts

@@ -381,7 +381,10 @@ export function useDomSelection({
       if (!doc) return;
 
       const element = findElementForSelection(doc, selection, activeCompPath);
-      if (!element) return;
+      if (!element) {
+        applyDomSelection(null, { revealPanel: false });
+        return;
+      }
 
       const nextSelection = await buildDomSelectionFromTarget(element);
       if (nextSelection) {

package/src/hooks/useStudioSelectionPublisher.ts

@@ -0,0 +1,102 @@
+import { useEffect, useRef, type MutableRefObject } from "react";
+import type { DomEditSelection } from "../components/editor/domEditing";
+import { usePlayerStore } from "../player";
+import { buildStudioSelectionSnapshot } from "../utils/studioSelectionSnapshot";
+import { trackStudioEvent } from "../utils/studioTelemetry";
+
+interface UseStudioSelectionPublisherParams {
+  projectId: string | null;
+  domEditSelection: DomEditSelection | null;
+  domEditSelectionRef: MutableRefObject<DomEditSelection | null>;
+  refreshKey: number;
+  previewDocumentVersion: number;
+  refreshDomEditSelectionFromPreview: (selection: DomEditSelection) => Promise<void>;
+}
+
+function reportSelectionPublishError(error: unknown): void {
+  if (error instanceof Error && error.name === "AbortError") return;
+  const errorName = error instanceof Error ? error.name : typeof error;
+  const errorMessage = error instanceof Error ? error.message : String(error);
+  trackStudioEvent("studio_selection_publish_failed", {
+    error_name: errorName,
+    error_message: errorMessage.slice(0, 500),
+  });
+  // eslint-disable-next-line no-console
+  console.warn("[Studio] Failed to update agent selection context", error);
+}
+
+function putSelection(projectId: string, selection: unknown, signal?: AbortSignal): Promise<void> {
+  return fetch(`/api/projects/${encodeURIComponent(projectId)}/selection`, {
+    method: "PUT",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ selection }),
+    signal,
+  }).then(() => undefined);
+}
+
+export function useStudioSelectionPublisher({
+  projectId,
+  domEditSelection,
+  domEditSelectionRef,
+  refreshKey,
+  previewDocumentVersion,
+  refreshDomEditSelectionFromPreview,
+}: UseStudioSelectionPublisherParams): void {
+  const lastSelectionRefreshKeyRef = useRef(refreshKey);
+  const pendingSelectionRefreshKeyRef = useRef<number | null>(null);
+
+  // eslint-disable-next-line no-restricted-syntax
+  useEffect(() => {
+    if (!projectId) return;
+    const selection = domEditSelection?.element.isConnected
+      ? buildStudioSelectionSnapshot({
+          projectId,
+          selection: domEditSelection,
+          currentTime: usePlayerStore.getState().currentTime,
+        })
+      : null;
+    const controller = new AbortController();
+    void putSelection(projectId, selection, controller.signal).catch(reportSelectionPublishError);
+    return () => controller.abort();
+  }, [domEditSelection, projectId]);
+
+  // Clear server-side agent context when Studio leaves a project. Without this,
+  // a long-running multi-project preview server can keep serving the last
+  // selected element for a project after its tab/session unmounts.
+  // eslint-disable-next-line no-restricted-syntax
+  useEffect(() => {
+    if (!projectId) return;
+    return () => {
+      void putSelection(projectId, null).catch(reportSelectionPublishError);
+    };
+  }, [projectId]);
+
+  // On external file edits, the iframe reloads while React keeps the previous
+  // DOM selection object alive. Clear the agent-facing snapshot immediately so
+  // `preview --context` never serves a detached or stale target, then let the
+  // post-load preview document refresh below re-resolve the selection if it
+  // still exists in the new document.
+  // eslint-disable-next-line no-restricted-syntax
+  useEffect(() => {
+    if (lastSelectionRefreshKeyRef.current === refreshKey) return;
+    lastSelectionRefreshKeyRef.current = refreshKey;
+    pendingSelectionRefreshKeyRef.current = domEditSelectionRef.current ? refreshKey : null;
+    if (!projectId || !domEditSelectionRef.current) return;
+    const controller = new AbortController();
+    void putSelection(projectId, null, controller.signal).catch(reportSelectionPublishError);
+    return () => controller.abort();
+  }, [domEditSelectionRef, projectId, refreshKey]);
+
+  // `refreshPreviewDocumentVersion` ticks after iframe load and shortly after.
+  // Consume one pending refresh per external reload: enough to re-resolve the
+  // selected element once the new document is queryable, without republishing
+  // the same snapshot on every follow-up 80/300ms tick.
+  // eslint-disable-next-line no-restricted-syntax
+  useEffect(() => {
+    if (pendingSelectionRefreshKeyRef.current === null) return;
+    pendingSelectionRefreshKeyRef.current = null;
+    const selection = domEditSelectionRef.current;
+    if (!selection) return;
+    void refreshDomEditSelectionFromPreview(selection);
+  }, [domEditSelectionRef, previewDocumentVersion, refreshDomEditSelectionFromPreview]);
+}

package/src/utils/studioSelectionSnapshot.test.ts

@@ -0,0 +1,47 @@
+import { describe, expect, it } from "vitest";
+import { buildStudioSelectionSnapshot } from "./studioSelectionSnapshot";
+import type { DomEditSelection } from "../components/editor/domEditing";
+
+describe("buildStudioSelectionSnapshot", () => {
+  it("serializes a DOM edit selection without the live HTMLElement", () => {
+    const selection = {
+      element: { tagName: "H1" } as HTMLElement,
+      id: null,
+      hfId: "hero-title",
+      selector: ".title",
+      selectorIndex: 0,
+      label: "Hero title",
+      tagName: "h1",
+      sourceFile: "index.html",
+      compositionPath: "index.html",
+      isCompositionHost: false,
+      isInsideLockedComposition: false,
+      boundingBox: { x: 10, y: 20, width: 300, height: 64 },
+      textContent: "Launch faster",
+      dataAttributes: { "data-hf-id": "hero-title" },
+      inlineStyles: { color: "white" },
+      computedStyles: { "font-size": "48px" },
+      textFields: [],
+      capabilities: { canSelect: true, canEditStyles: true },
+    } as DomEditSelection;
+
+    const snapshot = buildStudioSelectionSnapshot({
+      projectId: "demo",
+      selection,
+      currentTime: 1.25,
+    });
+
+    expect(snapshot).toMatchObject({
+      schemaVersion: 1,
+      projectId: "demo",
+      compositionPath: "index.html",
+      sourceFile: "index.html",
+      currentTime: 1.25,
+      target: { hfId: "hero-title", selector: ".title", selectorIndex: 0 },
+      thumbnailUrl:
+        "/api/projects/demo/thumbnail/index.html?t=1.25&format=png&selector=.title&selectorIndex=0",
+    });
+    expect(JSON.stringify(snapshot)).not.toContain("HTMLElement");
+    expect(snapshot).not.toHaveProperty("element");
+  });
+});

package/src/utils/studioSelectionSnapshot.ts

@@ -0,0 +1,72 @@
+import type { StudioSelectionSnapshot } from "@hyperframes/studio-server";
+import type { DomEditSelection } from "../components/editor/domEditing";
+
+function round3(value: number): number {
+  return Math.round(value * 1000) / 1000;
+}
+
+function thumbnailUrl({
+  projectId,
+  selection,
+  currentTime,
+}: {
+  projectId: string;
+  selection: DomEditSelection;
+  currentTime: number;
+}): string {
+  const compPath = encodeURIComponent(
+    selection.compositionPath || selection.sourceFile || "index.html",
+  );
+  const params = new URLSearchParams({
+    t: String(round3(currentTime)),
+    format: "png",
+  });
+  if (selection.selector) params.set("selector", selection.selector);
+  if (selection.selectorIndex != null) params.set("selectorIndex", String(selection.selectorIndex));
+  return `/api/projects/${encodeURIComponent(projectId)}/thumbnail/${compPath}?${params.toString()}`;
+}
+
+export function buildStudioSelectionSnapshot({
+  projectId,
+  selection,
+  currentTime,
+}: {
+  projectId: string;
+  selection: DomEditSelection;
+  currentTime: number;
+}): StudioSelectionSnapshot {
+  return {
+    schemaVersion: 1,
+    projectId,
+    compositionPath: selection.compositionPath,
+    sourceFile: selection.sourceFile,
+    currentTime: round3(currentTime),
+    target: {
+      id: selection.id,
+      hfId: selection.hfId,
+      selector: selection.selector,
+      selectorIndex: selection.selectorIndex,
+    },
+    label: selection.label,
+    tagName: selection.tagName,
+    boundingBox: {
+      x: round3(selection.boundingBox.x),
+      y: round3(selection.boundingBox.y),
+      width: round3(selection.boundingBox.width),
+      height: round3(selection.boundingBox.height),
+    },
+    textContent: selection.textContent,
+    dataAttributes: { ...selection.dataAttributes },
+    inlineStyles: { ...selection.inlineStyles },
+    computedStyles: { ...selection.computedStyles },
+    textFields: selection.textFields.map((field) => ({
+      key: field.key,
+      label: field.label,
+      value: field.value,
+      tagName: field.tagName,
+      source: field.source,
+    })),
+    capabilities: { ...selection.capabilities },
+    thumbnailUrl: thumbnailUrl({ projectId, selection, currentTime }),
+  };
+}