fix(figma): read the branch key from a Figma branch URL

packages/core/src/figma/parseFigmaRef.test.ts

@@ -17,6 +17,21 @@ describe("parseFigmaRef", () => {
     expect(ref.nodeId).toBeUndefined();
   });
 
+  it("uses the branch key of a branch URL, which is the key the REST API serves the branch under", () => {
+    expect(
+      parseFigmaRef("https://www.figma.com/design/MainKey123/branch/BranchKey456/Name?node-id=1-2"),
+    ).toEqual({ fileKey: "BranchKey456", nodeId: "1:2" });
+    expect(parseFigmaRef("https://www.figma.com/file/MainKey123/branch/BranchKey456")).toEqual({
+      fileKey: "BranchKey456",
+    });
+  });
+
+  it("does not read a file named branch as a branch key", () => {
+    expect(parseFigmaRef("https://www.figma.com/design/MainKey123/branch")).toEqual({
+      fileKey: "MainKey123",
+    });
+  });
+
   it("accepts fileKey:nodeId shorthand", () => {
     expect(parseFigmaRef("ABC123:1-2")).toEqual({ fileKey: "ABC123", nodeId: "1:2" });
   });

packages/core/src/figma/parseFigmaRef.ts

@@ -1,6 +1,6 @@
 import type { FigmaRef } from "./types";
 
-const FILE_KEY_RE = /\/(?:design|file|proto)\/([A-Za-z0-9]+)/;
+const FILE_KEY_RE = /\/(?:design|file|proto)\/([A-Za-z0-9]+)(?:\/branch\/([A-Za-z0-9]+))?/;
 
 function normalizeNodeId(raw: string): string {
   return raw.replaceAll("-", ":");
@@ -20,7 +20,7 @@ export function parseFigmaRef(input: string): FigmaRef {
   }
 
   const keyMatch = trimmed.match(FILE_KEY_RE);
-  const fileKey = keyMatch?.[1];
+  const fileKey = keyMatch?.[2] ?? keyMatch?.[1];
   if (fileKey === undefined) throw new Error(`parseFigmaRef: no fileKey in "${input}"`);
 
   const q = trimmed.indexOf("?");