heddle

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.

thrd.it ply.it Trading sandbox

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
mountHistory in 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_MODEL and 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 .plyx document, with the meme under artifacts.poster
Parts
one: layer, a layer of the poster
Saved
autosave to localStorage, 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 revert or undoCheckout. 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.

How Heddle compares with the alternatives