Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
420 changes: 420 additions & 0 deletions documentation/plans/optimism-seam-spike-brief.md

Large diffs are not rendered by default.

374 changes: 374 additions & 0 deletions packages/signals/docs/INTERNALS-ASYNC-STATE.md

Large diffs are not rendered by default.

206 changes: 58 additions & 148 deletions packages/signals/docs/RULES-DERIVED.md

Large diffs are not rendered by default.

8 changes: 6 additions & 2 deletions packages/signals/docs/RULES-FUNDAMENTALS.md
Original file line number Diff line number Diff line change
Expand Up @@ -29,9 +29,13 @@ These are the only words the fundamentals use. Internal names (transaction, stag
- **Action.** `action(fn)`: the explicit hold — its writes are held until the body has returned and everything they put in flight has landed.
- **Boundary.** `<Loading>` (`createLoadingBoundary`). A boundary is **armed** until it has shown content (a _fresh_ boundary), and armed again by `on`; a boundary showing content is **disarmed** (a _shown_ boundary). Armed, it catches what is pending under it; disarmed, it forwards — it holds like any reader. `<Errored>` is the error boundary.
- **Fallback.** What a boundary displays instead of its content. Content behind a fallback is kept alive but is not on screen. An armed boundary with something pending under it _enters_ its fallback with the frame that armed it — the mount, or the `on` change — and the fallback is on screen when that frame is (F-4).
- **First load.** The wait before a source has its first answer. A first load is _loading_, not a change: there is no previous content to keep. A memo created during a hold that reads the held change (_born held_, D-2) is loading in the same sense: it has no value the screen can show until that hold commits. A read of something loading suspends — to a boundary, or into the hold (F-2, F-4) — and `isPending` of it gives no verdict, because there is nothing shown to be stale (F-9).
- **First load.** The wait before a source has its first answer. A first load is _loading_, not a change: there is no previous content to keep. A memo created during a hold that reads the held change (_born held_, D-2) — including a first pass that reads this flush's staging when the flush then parks — is loading in the same sense: it has no value the screen can show until that hold commits. A read of something loading suspends — to a boundary, or into the hold (F-2, F-4) — and `isPending` of it gives no verdict, because there is nothing shown to be stale (F-9).
- **Question / re-ask.** A source's inputs are its question. An input changing asks a new question; `refresh()`, polling, an action's confirming refetch re-ask the same one.
- **Display-ahead reader.** `latest(x)`, `isPending(x)`, an optimistic value: a reader that shows a held change (or the verdict about it) before the hold reveals it.
- **Display-ahead read.** A single read — `latest(x)`, `isPending(x)`, or a read of a slot showing a guess — that shows the held change, or the verdict about it, now, without joining the hold. It is a read, not a kind of reader: a plain read beside it in the same pass is still a plain read, and a pass has reads, not a posture (D-25).
- **Answer.** A value a source has for its question: its committed value, its own async landed — into a hold or not — or a declared first paint (`loadingValue`). `latest` shows the newest answer; `isPending` judges whether a newer question has none yet (D-22, D-23).
- **Produced.** Said of a node that has an answer, and of a derivation that has computed a value from held inputs (born held): what `latest` can return. A first load has produced nothing.
- **The hold's work.** Every pass that read a value the hold holds plainly, and what those passes created: it computes now and shows at the commit, never before (D-1, D-2).
- **Guess.** An optimistic write: an edit over the answers to the question it was written over, and the value of its slot for the whole screen from its flush until the hold it was made over commits or its own source answers differently (F-11, D-34). A guess with nothing held under it is void.
- **Declared lag.** `createDeferred(fn)`: a source whose author has declared that its previous answer is an acceptable answer while the next one loads. After its first answer, its own re-asks hold nothing and its readers keep the answer they show until the new one lands (D-40). It is the counterpart of a display-ahead reader: that one shows a held change early, this one shows a change's consequence late, and neither is a hold.
- **Lane.** The world a display-ahead read opens: the screen plus what it shows ahead. What is rendered from a display-ahead read — derived from its value — lives in its lane, and the lane holds _itself_ on its own async — a hold of its own, separate from the hold it reads ahead of (F-6). A branch a display-ahead read merely _gates_ is not derived from it: it is a mainline mount whose plain reads are the screen's (D-27).
- **Flush.** The unit of visibility. Writes become visible at the flush that carries them; a manual `flush()` ends a tick.
Expand Down
851 changes: 492 additions & 359 deletions packages/signals/docs/RULES-INDEX.md

Large diffs are not rendered by default.

Loading
Loading