foldkit-remote 0.14.1 → 0.16.0

package/README.md

@@ -887,6 +887,32 @@ rendering it loading. A read the server leaves unanswered settles as missing,
 so it ends the loop; what runs out the passes is a chain whose every read
 reveals one more.
 
+### Preloading a destination from `update`
+
+`prefetch` and `satisfy` return a Model, which suits a render that has none
+yet. A running application has one, and it moves on while a read is out, so
+writing the returned Model back would undo what happened meanwhile.
+`Data.preload` is `satisfy` as a Command: it reads what `actives` would read
+in the Model you give it (the live one with the route set to where the reader
+may go) and yields one `Preloaded`, carrying the Messages that wrote it,
+which `update` reduces into the Model as it is by then:
+
+```ts
+const project = Surface.at(ProjectPage, model =>
+  model.route._tag === 'project' ? Option.some({ projectId: model.route.projectId }) : Option.none(),
+)
+// The reader is over the link to p2: read its page before they arrive.
+const preload = Data.preload({ ...model, route: { _tag: 'project', projectId: 'p2' } }, { project })
+// update returns { model, commands: [preload] }; under Remote.fold, foldData.preload(...)
+```
+
+It never fails: a read that fails, or a client that dies, ends it with what
+was read before, and the destination reads the rest when the reader arrives.
+A Surface of another application is refused when the Command is made. What it
+reads is kept like any other read until what is retained next changes, so
+preload close to the navigation you expect (a hover, a focus), not far ahead
+of it.
+
 ### Refreshing from `update`
 
 To revalidate what a screen already declares — a refresh button, a focus
@@ -2127,4 +2153,7 @@ Remote does **not** own:
 - [`examples/remote`](../../examples/remote) — an asserted trace through plan,
   prefetch, refresh, query, render, mutation, retention, and decode failure.
 - [`examples/kitchen-sink`](../../examples/kitchen-sink) — the same architecture
-  using the real server packages.
+  using the real server packages.
+- [Site, Remote and SSR together](../../docs/site-remote-ssr.md) — routes that
+  activate reads, rendered on the server with their data and taken over without
+  fetching again.