watershed Collaborative data structures for Gleam

← watershed · Foundations

Before you
build anything.

The build guide walks a working board through every step. These sheets cover the model underneath it: how you declare and lay out a document, and how you bring its channels online.

Building a screen users can assemble for themselves? That optional layer now has its own section: the component model.

Foundations

Core · every watershed app

3 sheets. Read in order — each one leans on the last.

  1. 01 Schemas and fields Declare the shape of a map once, at compile time, with a phantom tag the runtime never sees: a plain field, a handle to a nested map, or a handle to another channel entirely. Field · ChildField · ChannelField · FieldError
  2. 02 Documents and handles A watershed document is not one tree — it's a root map plus whatever channels its values point to, each one independently addressed, attached, and resolved. root_typed · handle_of · create_map · resolve
  3. 03 Starting a document Every client runs the same bootstrap: get a handle, wait for the catch-up, ensure the channels it needs exist, and only render once they've all reported in. got_document · connected · ensure_* · subscribe

Once a channel exists, the field atlas covers what it does when two clients touch it at once, and runtime covers what happens while it's live: optimistic edits, reconnect, and the rest. Ready to see it running? Start the survey procedure at step one.