prototype: basic Upwelling-style branches, using forks

[geoffreylitt]

This branch is a tech spike exploring an implementation of upwelling-style branches (explicitly created in advance of editing) using the existing fork capability. (Because it's a spike, not planning to merge to main, although perhaps we might want to if we want to start using some of this functionality?)

For now I've prototyped all this in standalone-TEE just to be able to make rapid progress and avoid making things too generic yet. But nearly all this stuff isn't TEE-specific and should be lifted out into a broader TR environment.

The basic design, so far:

• We have a few commands for users to create a fork and merge it back to the original doc
• pointers are stored in both directions, from parent -> child and child -> parent.
  • To ensure privacy, when a new fork is created a parent -> child link isn't populated. It's only created once an explicit share action happens.
  • The child -> parent link stores a doc URL, as well as heads.
• There's a diff view, which currently shows a diff from the time the doc was forked to the current state.
  • Currently we never rebase on changes to the original doc that happened post-fork; that's probably desirable to add somehow.
  • I'm diffing on every keystroke, not doing any incremental maintenance yet. Seems fine on small docs with small histories.
• There's not yet a nice way to browse forks from the parent; we should probably have something like a list that shows little diffs for each one or something.

Alongside that basic forking logic, I also used this as a chance to explore two related threads which were tangentially relevant:

• A desktop-style menu bar, because I needed a place to put more commands. I think this is the right UI metaphor to use for commands in TEE short term. I also think it's a reasonable default for medium term TEE/TR UI unless we have better ideas. It's much better than stuffing a ton of buttons into a header.
• A tiny bit schema validation stub using effect/schema -- because I was evolving the TEE doc schema and hitting problems with missing fields in old docs. I define the doc schema in effect/schema, autogen a typescript type, and check at runtime if the doc can parse into the right schema. (Much more to explore here but it was already useful)

A list of issues that have come up during this work so far:

• Obviously the UI here is very immature; you don't get a good sense of visibility into the structure of parent doc vs forks, more work needed.
• When to rebase the fork against the parent? Upwelling's design is to show "pending changes" on the fork when the parent has changes, and the user manually triggers a rebase.
• Terminology: There are lots of words that need to be considered more: "fork" vs "branch" vs "layer", "clone", "child" / "parent", "merge"... we should think carefully about what Automerge terms are user-facing and which ones should be hidden/reworded.
• How to think about opening a new document in an existing editor? Both in standalone TEE and TEE/TR. Do we just update the url hash and re-mount from scratch? Do we update the url passed in thru mount...?
• Persistent UI state: the "show changes" toggle is currently React state but it should be persistent, it's very annoying to have it reset on reload. This suggests storing UI state in an Automerge doc somewhere.
• Automerge-repo timing: if I make a fork and then immediately try to open it in a new tab, it's not ready yet when the new tab opens. This is odd since the doc should be in my local repo? And I don't think I've missed an await. For now, just did a hardcoded delay...
• Forking metadata is a very generic thing; it should be stored in some kind of generic place that we can expect most/all docs to have. (Perhaps eventually repo should manage this?)