Step 5: Make it a list

A created-at timestamp gives every peer the same order, for free — and a delete button, to match.

Right now new notes land in whatever order the map happens to iterate — not wrong, exactly, but not a list either. The fix is data, not coordination: store a creation time on every note, and let each peer compute the same order from it. This step touches both halves of the pane — the // src/codec.ts and // src/tool.tsx comment lines mark where each file begins; on disk they're two separate files. (The merged import block at the top splits the same way: defineStateCodec and field belong to src/codec.ts; everything else — including module-level helpers like newId — belongs to src/tool.tsx.)

First, in src/codec.ts, give Note a creation time:

src/codec.ts

export type Note = {
  text: string
  /** Creation time — a stable sort key every peer agrees on. */
  at: number
}

Then, in src/tool.tsx, sort the entries by it inside Board, and stamp it when a note is created:

src/tool.tsx

const notes = useMemo(
  () => Object.entries(data.notes).sort((a, b) => a[1].at - b[1].at),
  [data.notes],
)
const addNote = () =>
  actions.map("notes").set(newId(), { text: "", at: Date.now() })

The useMemo isn't ceremony: sorting builds a brand-new array, and doing it inline would hand React a fresh array on every render. Memoized on data.notes, it only recomputes when a note actually changes.

Finally — still in src/tool.tsx — add a Delete button next to each textarea, inside the notes.map(…) loop, wired to actions.map("notes").delete(id). That's a new method on the hand-written actions type too: delete(key: string): void joins set in what map(name: "notes") returns — the answer shows the full type.

Order and delete

src/codec.ts + src/tool.tsx

import { useMemo } from "react"

import {

DocumentGate,

type ToolRenderProps,

defineStateCodec,

defineTool,

field,

useDocument,

} from "@vvd/sdk"

// src/codec.ts

/** One note on the board. */

export type Note = {

text: string

}

export const codec = defineStateCodec({

// A per-KEY map: two people adding or editing different notes at once BOTH land.

notes: field.map<Note>(),

})

// src/tool.tsx

const newId = () => crypto.randomUUID()

function Board({

data,

actions,

}: {

data: { notes: Readonly<Record<string, Note>> }

actions: {

map(name: "notes"): { set(key: string, value: Note): void }

}

}) {

const notes = Object.entries(data.notes)

const addNote = () => actions.map("notes").set(newId(), { text: "" })

return (

<h1 style={{ margin: 0, fontSize: 20 }}>bestiary</h1>

Add a note

</button>

</div>

{notes.map(([id, note]) => (

<textarea

key={id}

value={note.text}

placeholder="Write something…"

onChange={(e) =>

actions.map("notes").set(id, { ...note, text: e.target.value })

}

style={{ minHeight: 64, padding: 10 }}

))}

{notes.length === 0 && <p style={{ opacity: 0.6 }}>No notes yet.</p>}

</div>

)

}

export function BestiaryView({ document }: ToolRenderProps) {

const coords = useMemo(

() => ({ worldId: document.worldId, documentId: document.id }),

[document.worldId, document.id],

)

const { data, status, actions, retry } = useDocument(coords, codec)

return (

{data && actions && <Board data={data} actions={actions} />}

</DocumentGate>

)

}

export default defineTool({

id: "bestiary",

name: "bestiary",

documentTypes: ["bestiary"],

needs: [],

render: BestiaryView,

})

import { useMemo } from "react"

import {
DocumentGate,
type ToolRenderProps,
defineStateCodec,
defineTool,
field,
useDocument,
} from "@vvd/sdk"

// src/codec.ts
/** One note on the board. */
export type Note = {
text: string
}

export const codec = defineStateCodec({
// A per-KEY map: two people adding or editing different notes at once BOTH land.
notes: field.map<Note>(),
})

// src/tool.tsx
const newId = () => crypto.randomUUID()

function Board({
data,
actions,
}: {
data: { notes: Readonly<Record<string, Note>> }
actions: {
  map(name: "notes"): { set(key: string, value: Note): void }
}
}) {
const notes = Object.entries(data.notes)
const addNote = () => actions.map("notes").set(newId(), { text: "" })
return (
  <div style={{ maxWidth: 640, margin: "0 auto", padding: 24 }}>
    <div style={{ display: "flex", alignItems: "center", gap: 12 }}>
      <h1 style={{ margin: 0, fontSize: 20 }}>bestiary</h1>
      <button type="button" onClick={addNote} style={{ marginLeft: "auto" }}>
        Add a note
      </button>
    </div>
    <div style={{ marginTop: 16, display: "grid", gap: 12 }}>
      {notes.map(([id, note]) => (
        <textarea
          key={id}
          value={note.text}
          placeholder="Write something…"
          onChange={(e) =>
            actions.map("notes").set(id, { ...note, text: e.target.value })
          }
          style={{ minHeight: 64, padding: 10 }}
        />
      ))}
      {notes.length === 0 && <p style={{ opacity: 0.6 }}>No notes yet.</p>}
    </div>
  </div>
)
}

export function BestiaryView({ document }: ToolRenderProps) {
const coords = useMemo(
  () => ({ worldId: document.worldId, documentId: document.id }),
  [document.worldId, document.id],
)
const { data, status, actions, retry } = useDocument(coords, codec)
return (
  <DocumentGate status={status} onRetry={retry}>
    {data && actions && <Board data={data} actions={actions} />}
  </DocumentGate>
)
}

export default defineTool({
id: "bestiary",
name: "bestiary",
documentTypes: ["bestiary"],
needs: [],
render: BestiaryView,
})

Edit and the example re-runs. Tab indents; press Escape to leave the editor.

Running · your edits, live

Starting the example…

You should see: add three or four notes, delete one from the middle — the rest keep their order. Every peer computes that order from the same at, so nobody has to agree on it over the network; it's just a read.

Why not field.list? A list merges by position — great when the sequence itself is the meaning (a timeline, a set of steps), but two people inserting at the same index at the same moment land in a defined-but-arbitrary order. A field.map keyed by id has no positions to disagree about; sorting by at gets you order back as a plain read. The Hello World starter kit has the full case for it.

Next steps

Step 6 — Two people at onceThe moment this stops being a demo.