Case studies · version 0.8.0
Where it is used
Two apps keep their history in Heddle today. Each has an abridged, working version here. A third, a trading sandbox, shows the stream beside a history. The two app studies were read from each app's source in November 2026: the calls, the state shape and the storage keys are theirs. Both apps are on Heddle 0.2, two versions behind this page, so neither uses heddle/sync or heddle/stream yet.
Whiteboard · Wired in
thrd.it: every engine edit is a commit
A whiteboard with a History panel: timeline, branches, merge, and restore of a board, a layer or one object. A small whiteboard written for this page, with the state shape and the Heddle calls thrd.it uses: a graph history, the board regrouped by layer, a commit when an edit is finished, and the parts board, layer and node. It runs on this page's Heddle, not on the 0.2 the app vendors, and none of it is thrd.it's code.
This figure is live. It needs JavaScript, which has not run.
Move things, then open Details and restore one layer, or the selected object, from an earlier commit. The rest of the board stays as it is.
- Model
graph, chosen in one constant- A commit is
- one engine commit that changed the board, with the engine's commands as its op log and the actor as provenance
- The state
- the whole board, regrouped as
{ board, layers: { id: { at, nodes } } } - Parts
board,layer,node, and the current selection- Saved
- per board in
localStorage, 300 ms after the last change - UI
mountHistoryin a sidebar, with its actions routed through the engine- Heddle version
- 0.2
What it uses
commit checkout undoCheckout branch merge revert restore diff verify exportBundle importBundle
What it had to work around
- Arrays merge as one value. A layer's list of children would conflict on every concurrent add, so the app passes its own merge strategy that takes the union.
- Text edits cannot be replayed from ops. Those commits are stored as snapshots, without an op log.
- A branched history does not open as linear. The app catches
E_MODELand starts an in-memory history. - Restore choices were fixed at mount. The panel remounts when the layers change.
setParts()removed the need in 0.3.
Its regrouped state keeps nodes under their layer instead of in one board-wide list, the direction the Performance section recommends.
Meme editor · Wired in
ply.it: a meme with a history
Every edit to a meme is a commit, and one layer can be brought back from any earlier version. A small meme editor written for this page, with the state shape and the Heddle calls ply.it uses: a graph history, the whole document with the meme under artifacts.poster, a commit when an edit is finished, and one part, layer. The pictures are drawn from shapes. It runs on this page's Heddle, and none of it is ply.it's code.
This figure is live. It needs JavaScript, which has not run.
Type a caption and watch it preview. It becomes a commit when you leave the field. Then restore one layer, such as the picture, from an earlier commit.
- Model
graph- A commit is
- one finished edit: a drag that ended, a field that changed, a text edit, a template load. A drag in progress only previews
- The state
- the whole
.plyxdocument, with the meme underartifacts.poster - Parts
- one:
layer, a layer of the poster - Saved
autosavetolocalStorage, under one key- UI
mountHistory: timeline, branches, merge, graph and restore of one layer- Heddle version
- 0.2
What it uses
commit revert undoCheckout state subscribe autosave loadHistory
What it had to work around
- A state the editor cannot draw. A checkout or merge can produce a document the meme editor rejects. It takes the move back with
revertorundoCheckout. The host hook of 0.3 lets an app veto the move first. - Unchanged documents. The app skips a commit when the document did not change.
- One history for every meme. It saves under a single key, not one per document.
Commit when the gesture ends and preview while it runs: the rule the sync notes give, arrived at here first.
Sandbox · stream and history together
A trading desk in two models
Prices are ticks. Orders are decisions. Each goes where it belongs. The price feed is a stream: about twenty ticks a second, capped, with candles from buckets(). Every order is a commit on a linear history, so the account has undo, redo and a scrubber. Drag the history back and the chart, the position and the profit are those of that moment: the history gives the book, and stream.at("px", commit.time) gives the price that was current then.
This figure is live. It needs JavaScript, which has not run.
The feed is a stream
Nothing is hashed. Old ticks fall off. Twenty prices a second would be twenty commits a second, each hashing the whole state. A stream push is an array append. The capacity keeps memory flat however long the feed runs.
The book is a history
Every order can be undone and replayed. An order is a decision someone made, and there are few of them. Each is a commit with a message and the time of the tick it was filled at, so the account can be stepped through, saved and checked.
Time joins them
One clock stamps both. A commit carries a time, and a stream is read by time. That is the whole link: no foreign key, no join table. The same link puts the cursors back in the whiteboard's replay.
The prices are a seeded random walk. Nothing is real and nothing is traded.
What they have not used yet
Live sync
heddle/sync is new in 0.4. Neither app syncs between people yet.
The stream
heddle/stream is new in 0.4. Cursors and selections are still each app's own.
The lab
thrd.it has its own test lab, which this one was modelled on. Neither replays Heddle recordings yet.