I recommend reviewing this file by looking into it without the diff.

Just double-checking for my own understanding: is there any real difference between the mock function returning the base MockTemplateVersion value, versus it returning the updated version?

Yes, because we are going to use this version to optimistically update the UI.

Just making sure: this is for making the UX nicer, right? It just makes sure that if the page needs to load in new version data, the UI doesn't unload while that's happening?

Exactly!

I don't know the full set of problems that this component is trying to solve, but my gut feeling is that it might make sense to combine tarFile and fileTree into one single useState call. Something like this:

type TarInfo = {
  reader: TarReader;
  tree: FileTree;
};

// Type (TarInfo | undefined)
const [tarState, setTarState] = useState<TarInfo>();

const initializeFileTree = async (file: ArrayBuffer) => {
  const tarReader = new TarReader();
  await tarReader.readFile(file);
  const fileTree = await createTemplateVersionFileTree(tarReader);

  setTarState({ reader: tarReader, file: fileTree });
};

• Right now, it looks like they're always supposed to be used together. Combining them would make sure that it's impossible to have one without the other.
• tarFile is set up with useRef right now, even though the inner value is referenced directly in render logic. My worry is that if the logic gets more complicated later, someone might update tarFileRef when they want a re-render, but not realize why the screen isn't changing
• There is the tarFileRef.current write before createTemplateVersionFileTree gets called, but it doesn't seem that delaying the state change until after initializeFileTree resolves would affect anything?

Awesome points.

1 - I think makes sense
2, 3 - This initialization should happen only once

Moved it to a single state call!

Should there be some error handling in the off chance tarReader.getTextFile returns undefined?

For this specific use case, we can just ignore it for now.

Could some of this functionality be done via useMutation's onMutate and onSuccess callbacks? onMutate also lets you return out a cleanup function

I don't think so because this is not related to a specific mutation.