feat(studio): disable manual positioning JSON by default, add toggle

Manual edits were always stored in `.hyperframes/studio-manual-edits.json`,
making it hard to share source without the sidecar file and easy to
accidentally reposition elements via drag.

Changes:
- `enabled` field added to `StudioManualEditManifest` (defaults to `false`
  when absent — existing projects are unaffected until they opt in)
- Drag handles, resize, and rotation handles are hidden when disabled
- Layout X/Y/W/H/R fields in the Design panel are read-only when disabled
- "Manual positioning" toggle added at the bottom of the Design panel,
  visible whether or not an element is selected
- Toggle state is persisted to `.hyperframes/studio-manual-edits.json`
  so each project can opt in independently
- `STUDIO_PREVIEW_MANUAL_EDITING_ENABLED` env flag still acts as a hard
  cap (env off → feature off regardless of project setting)

Author: miguel-heygen

packages/studio/src/App.tsx

@@ -192,6 +192,8 @@ export function StudioApp() {
     syncPreviewHistoryHotkey: appHotkeys.syncPreviewHistoryHotkey,
     reloadPreview,
     setRefreshKey,
+    manualEditsEnabled: manifestPersistence.manualEditsEnabled,
+    setManualEditsEnabled: manifestPersistence.setManualEditsEnabled,
   });
 
   domEditSelectionBridgeRef.current = domEditSession.domEditSelection;

packages/studio/src/components/StudioPreviewArea.tsx

@@ -75,6 +75,7 @@ export function StudioPreviewArea({
     domEditHoverSelection,
     domEditSelection,
     domEditGroupSelections,
+    manualEditsEnabled,
     handleTimelineElementSelect,
     handlePreviewCanvasMouseDown,
     handlePreviewCanvasPointerMove,
@@ -133,7 +134,7 @@ export function StudioPreviewArea({
               }
               selection={shouldShowSelectedDomBounds ? domEditSelection : null}
               groupSelections={shouldShowSelectedDomBounds ? domEditGroupSelections : []}
-              allowCanvasMovement={STUDIO_PREVIEW_MANUAL_EDITING_ENABLED}
+              allowCanvasMovement={STUDIO_PREVIEW_MANUAL_EDITING_ENABLED && manualEditsEnabled}
               onCanvasMouseDown={handlePreviewCanvasMouseDown}
               onCanvasPointerMove={handlePreviewCanvasPointerMove}
               onCanvasPointerLeave={handlePreviewCanvasPointerLeave}

packages/studio/src/components/StudioRightPanel.tsx

@@ -64,6 +64,8 @@ export function StudioRightPanel({
     handleDomMotionCommit,
     handleDomMotionClear,
     applyDomSelection,
+    manualEditsEnabled,
+    setManualEditsEnabled,
   } = useDomEditContext();
 
   const { assets, fontAssets, handleImportFiles, handleImportFonts } = useFileManagerContext();
@@ -180,6 +182,8 @@ export function StudioRightPanel({
                   onImportFonts={handleImportFonts}
                   activeCompositionPath={activeCompPath}
                   onSelectLayer={handleSelectLayer}
+                  manualEditsEnabled={manualEditsEnabled}
+                  onSetManualEditsEnabled={setManualEditsEnabled}
                 />
               ) : motionPanelActive ? (
                 <MotionPanel

packages/studio/src/components/editor/PropertyPanel.tsx

@@ -53,6 +53,8 @@ interface PropertyPanelProps {
   onImportFonts?: (files: FileList | File[]) => Promise<ImportedFontAsset[]>;
   activeCompositionPath?: string | null;
   onSelectLayer?: (layer: DomEditLayerItem) => void;
+  manualEditsEnabled?: boolean;
+  onSetManualEditsEnabled?: (enabled: boolean) => void;
 }
 
 /* ------------------------------------------------------------------ */
@@ -115,6 +117,42 @@ function LayerTree({
   );
 }
 
+/* ------------------------------------------------------------------ */
+/*  ManualPositioningToggle                                            */
+/* ------------------------------------------------------------------ */
+
+function ManualPositioningToggle({
+  enabled,
+  onToggle,
+}: {
+  enabled: boolean;
+  onToggle: (enabled: boolean) => void;
+}) {
+  return (
+    <div className="flex-shrink-0 border-t border-neutral-800 px-4 py-3">
+      <div className="flex items-center justify-between">
+        <span className="text-[11px] text-neutral-400">Manual positioning</span>
+        <button
+          type="button"
+          role="switch"
+          aria-checked={enabled}
+          onClick={() => onToggle(!enabled)}
+          title={enabled ? "Disable drag-to-reposition" : "Enable drag-to-reposition"}
+          className={`relative inline-flex h-5 w-9 flex-shrink-0 rounded-full transition-colors focus-visible:outline-none ${
+            enabled ? "bg-studio-accent" : "bg-neutral-700"
+          }`}
+        >
+          <span
+            className={`pointer-events-none mt-0.5 inline-block h-4 w-4 transform rounded-full bg-white shadow-sm transition-transform ${
+              enabled ? "translate-x-[18px]" : "translate-x-[2px]"
+            }`}
+          />
+        </button>
+      </div>
+    </div>
+  );
+}
+
 /* ------------------------------------------------------------------ */
 /*  PropertyPanel                                                      */
 /* ------------------------------------------------------------------ */
@@ -141,41 +179,52 @@ export const PropertyPanel = memo(function PropertyPanel({
   onImportFonts,
   activeCompositionPath = null,
   onSelectLayer,
+  manualEditsEnabled = true,
+  onSetManualEditsEnabled,
 }: PropertyPanelProps) {
   const styles = element?.computedStyles ?? EMPTY_STYLES;
 
   if (!element) {
     return (
-      <div className="flex h-full flex-col items-center justify-center bg-neutral-900 px-6 text-center">
-        {multiSelectCount > 1 ? (
-          <>
-            <Layers size={18} className="mb-3 text-neutral-600" />
-            <p className="text-sm font-medium text-neutral-200">
-              {multiSelectCount} elements selected
-            </p>
-            <p className="mt-2 max-w-[260px] text-xs leading-5 text-neutral-500">
-              Select a single element to edit its properties. Click an element in the preview or use
-              the timeline layer panel.
-            </p>
-          </>
-        ) : (
-          <>
-            <Eye size={18} className="mb-3 text-neutral-600" />
-            <p className="text-sm font-medium text-neutral-200">
-              Select an element in the preview.
-            </p>
-            <p className="mt-2 max-w-[260px] text-xs leading-5 text-neutral-500">
-              The inspector is tuned for element edits with safer geometry controls, color picking,
-              and cleaner grouped layer controls.
-            </p>
-          </>
+      <div className="flex h-full flex-col bg-neutral-900">
+        <div className="flex flex-1 flex-col items-center justify-center px-6 text-center">
+          {multiSelectCount > 1 ? (
+            <>
+              <Layers size={18} className="mb-3 text-neutral-600" />
+              <p className="text-sm font-medium text-neutral-200">
+                {multiSelectCount} elements selected
+              </p>
+              <p className="mt-2 max-w-[260px] text-xs leading-5 text-neutral-500">
+                Select a single element to edit its properties. Click an element in the preview or
+                use the timeline layer panel.
+              </p>
+            </>
+          ) : (
+            <>
+              <Eye size={18} className="mb-3 text-neutral-600" />
+              <p className="text-sm font-medium text-neutral-200">
+                Select an element in the preview.
+              </p>
+              <p className="mt-2 max-w-[260px] text-xs leading-5 text-neutral-500">
+                The inspector is tuned for element edits with safer geometry controls, color
+                picking, and cleaner grouped layer controls.
+              </p>
+            </>
+          )}
+        </div>
+        {onSetManualEditsEnabled && (
+          <ManualPositioningToggle
+            enabled={manualEditsEnabled}
+            onToggle={onSetManualEditsEnabled}
+          />
         )}
       </div>
     );
   }
 
-  const manualOffsetEditingDisabled = !element.capabilities.canApplyManualOffset;
-  const manualSizeEditingDisabled = !element.capabilities.canApplyManualSize;
+  const manualOffsetEditingDisabled =
+    !element.capabilities.canApplyManualOffset || !manualEditsEnabled;
+  const manualSizeEditingDisabled = !element.capabilities.canApplyManualSize || !manualEditsEnabled;
   const sourceLabel = element.id ? `#${element.id}` : element.selector;
   const showEditableSections = element.capabilities.canEditStyles;
   const manualOffset = readStudioPathOffset(element.element);
@@ -318,6 +367,7 @@ export const PropertyPanel = memo(function PropertyPanel({
             <MetricField
               label="R"
               value={`${manualRotation.angle}°`}
+              disabled={!manualEditsEnabled}
               onCommit={(next) => commitManualRotation(next.replace("°", ""))}
             />
           </div>
@@ -342,6 +392,9 @@ export const PropertyPanel = memo(function PropertyPanel({
           />
         )}
       </div>
+      {onSetManualEditsEnabled && (
+        <ManualPositioningToggle enabled={manualEditsEnabled} onToggle={onSetManualEditsEnabled} />
+      )}
     </div>
   );
 });

packages/studio/src/components/editor/manualEditsParsing.ts

@@ -126,8 +126,10 @@ export function parseStudioManualEditManifest(content: string): StudioManualEdit
     if (!parsed || typeof parsed !== "object") return emptyStudioManualEditManifest();
     const edits = (parsed as { edits?: unknown }).edits;
     if (!Array.isArray(edits)) return emptyStudioManualEditManifest();
+    const record = parsed as Record<string, unknown>;
     return {
       version: 1,
+      enabled: record.enabled === true,
       edits: edits.map(parseManualEdit).filter((edit): edit is StudioManualEdit => edit !== null),
     };
   } catch {

packages/studio/src/components/editor/manualEditsTypes.ts

@@ -75,6 +75,7 @@ export type StudioManualEdit = StudioPathOffsetEdit | StudioBoxSizeEdit | Studio
 
 export interface StudioManualEditManifest {
   version: 1;
+  enabled?: boolean;
   edits: StudioManualEdit[];
 }
 

packages/studio/src/contexts/DomEditContext.tsx

@@ -50,6 +50,8 @@ export function DomEditProvider({
     setAgentModalOpen,
     setAgentPromptSelectionContext,
     setAgentModalAnchorPoint,
+    manualEditsEnabled,
+    setManualEditsEnabled,
   },
   children,
 }: {
@@ -95,6 +97,8 @@ export function DomEditProvider({
       setAgentModalOpen,
       setAgentPromptSelectionContext,
       setAgentModalAnchorPoint,
+      manualEditsEnabled,
+      setManualEditsEnabled,
     }),
     [
       domEditSelection,
@@ -134,6 +138,8 @@ export function DomEditProvider({
       setAgentModalOpen,
       setAgentPromptSelectionContext,
       setAgentModalAnchorPoint,
+      manualEditsEnabled,
+      setManualEditsEnabled,
     ],
   );
   return <DomEditContext value={stable}>{children}</DomEditContext>;

packages/studio/src/hooks/useDomEditSession.ts

@@ -66,6 +66,8 @@ export interface UseDomEditSessionParams {
   syncPreviewHistoryHotkey: (iframe: HTMLIFrameElement | null) => void;
   reloadPreview: () => void;
   setRefreshKey: React.Dispatch<React.SetStateAction<number>>;
+  manualEditsEnabled: boolean;
+  setManualEditsEnabled: (enabled: boolean) => void;
 }
 
 // ── Hook ──
@@ -105,6 +107,8 @@ export function useDomEditSession({
   syncPreviewHistoryHotkey,
   reloadPreview,
   setRefreshKey: _setRefreshKey,
+  manualEditsEnabled,
+  setManualEditsEnabled,
 }: UseDomEditSessionParams) {
   void _setRefreshKey;
   // ── Selection (delegated to useDomSelection) ──
@@ -339,5 +343,7 @@ export function useDomEditSession({
     setAgentModalOpen,
     setAgentPromptSelectionContext,
     setAgentModalAnchorPoint,
+    manualEditsEnabled,
+    setManualEditsEnabled,
   };
 }

packages/studio/src/hooks/useManifestPersistence.ts

@@ -55,6 +55,7 @@ export function useManifestPersistence({
   activeCompPathRef,
 }: UseManifestPersistenceParams) {
   const [, setStudioMotionRevision] = useState(0);
+  const [manualEditsEnabled, setManualEditsEnabledState] = useState(false);
 
   const domEditSaveTimestampRef = useRef(0);
   const domTextCommitVersionRef = useRef(0);
@@ -169,7 +170,9 @@ export function useManifestPersistence({
         return;
       }
       if (options?.forceFromDisk || readRevision === studioManualEditRevisionRef.current) {
-        studioManualEditManifestRef.current = parseStudioManualEditManifest(content);
+        const parsed = parseStudioManualEditManifest(content);
+        studioManualEditManifestRef.current = parsed;
+        setManualEditsEnabledState(parsed.enabled ?? false);
         if (options?.forceFromDisk) studioManualEditRevisionRef.current += 1;
       }
       applyCurrentStudioManualEditsToPreview(iframe);
@@ -435,6 +438,7 @@ export function useManifestPersistence({
     studioManualEditProjectRef.current = projectId;
     if (!previousProjectId || previousProjectId === projectId) return;
     studioManualEditManifestRef.current = emptyStudioManualEditManifest();
+    setManualEditsEnabledState(false);
     studioManualEditRevisionRef.current += 1;
     studioMotionManifestRef.current = emptyStudioMotionManifest();
     studioMotionRevisionRef.current += 1;
@@ -481,6 +485,55 @@ export function useManifestPersistence({
     return () => es.close();
   });
 
+  const setManualEditsEnabled = useCallback(
+    (enabled: boolean) => {
+      const previousManifest = studioManualEditManifestRef.current;
+      const nextManifest = { ...previousManifest, enabled };
+      studioManualEditManifestRef.current = nextManifest;
+      studioManualEditRevisionRef.current += 1;
+      setManualEditsEnabledState(enabled);
+
+      const save = async () => {
+        const originalContent = await readOptionalProjectFile(STUDIO_MANUAL_EDITS_PATH);
+        const diskManifest = parseStudioManualEditManifest(originalContent);
+        const nextDiskManifest = { ...diskManifest, enabled };
+        const nextDiskContent = serializeStudioManualEditManifest(nextDiskManifest);
+        if (nextDiskContent === originalContent) return;
+
+        const pid = projectIdRef.current;
+        if (!pid) throw new Error("No active project");
+        domEditSaveTimestampRef.current = Date.now();
+        await saveProjectFilesWithHistory({
+          projectId: pid,
+          label: enabled ? "Enable manual positioning" : "Disable manual positioning",
+          kind: "manual",
+          coalesceKey: "manual-edits-enabled",
+          files: { [STUDIO_MANUAL_EDITS_PATH]: nextDiskContent },
+          readFile: async () => originalContent,
+          writeFile: writeProjectFile,
+          recordEdit,
+        });
+        domEditSaveTimestampRef.current = Date.now();
+      };
+
+      void queueDomEditSave(save).catch((error) => {
+        studioManualEditManifestRef.current = previousManifest;
+        studioManualEditRevisionRef.current += 1;
+        setManualEditsEnabledState(previousManifest.enabled ?? false);
+        const message = error instanceof Error ? error.message : "Failed to save setting";
+        showToast(message);
+      });
+    },
+    [
+      queueDomEditSave,
+      readOptionalProjectFile,
+      writeProjectFile,
+      recordEdit,
+      showToast,
+      domEditSaveTimestampRef,
+    ],
+  );
+
   return {
     domEditSaveTimestampRef,
     domTextCommitVersionRef,
@@ -501,5 +554,7 @@ export function useManifestPersistence({
     commitStudioManualEditManifestOptimistically,
     commitStudioMotionManifestOptimistically,
     syncHistoryPreviewAfterApply,
+    manualEditsEnabled,
+    setManualEditsEnabled,
   };
 }