feat: SyncClient hydration, fix ref doc creation, defer incomplete refs

Three fixes to sanity-rooms:

1. SyncClient hydration: initialState is now optional. Client connects
   immediately, hydrates from the server room's first state message.
   ready promise, isHydrated getter, mutation guards before hydration.
   Editor no longer needs an HTTP pre-fetch for initial config.

2. Ref doc creation: editDocument fails on non-existent docs (SDK
   learnings were wrong — proved with throwaway script). Bridge now
   uses createDocument + editDocument for new ref docs, tracks known
   docs via markRefDocKnown to avoid duplicate creates. Mock updated
   to enforce real SDK constraints.

3. Defer incomplete refs: handleSanityChange now skips mapping when
   ref bridges haven't loaded yet, preventing broadcast of state with
   stripped custom resources. Ref bridge onChange re-triggers mapping
   once loaded.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: snorrees

sanity-sdk-learnings.md

@@ -55,9 +55,10 @@ When you subscribe to a doc via `getDocumentState`, the SDK creates an entry in
 ### `editDocument` vs `createDocument`
 
 - `createDocument` throws if a draft already exists (`"A draft version already exists"`)
-- `editDocument` with `{ set: fields }` works as an **upsert** — it creates the draft if it doesn't exist, updates it if it does. This is the correct choice for ref documents (custom fonts, palettes, backgrounds) where the doc may or may not exist.
+- `editDocument` **requires the doc to exist** in draft or published form — it throws `"Cannot edit document because it does not exist in draft or published form"` otherwise. It is NOT an upsert.
+- `createDocument` + `editDocument` in the same `applyDocumentActions` batch WORKS — the create runs first, then the edit sees the newly created draft.
 
-**Use `editDocument` for ref docs, not `createDocument`.** Using `createDocument` in a batch with the main doc edit causes the entire batch to fail if the ref doc draft already exists — silently dropping the main doc write too.
+**For ref docs that may or may not exist:** batch `createDocument(handle)` before `editDocument(handle, { set: ... })`. If the doc already exists, skip the `createDocument`. The bridge must track which ref docs have been created to choose the right action.
 
 ## Server-side reference integrity
 

src/__tests__/sanity-bridge.test.ts

@@ -83,7 +83,7 @@ describe('SanityBridge', () => {
     bridge.dispose()
   })
 
-  it('write with refDocs uses editDocument not createDocument (Bug #3)', async () => {
+  it('write with existing ref doc edits without creating', async () => {
     const mock = createMockSanity({ 'doc-1': { value: 1 }, 'ref-1': { name: 'existing' } })
     const bridge = new SanityBridge({
       instance: mock.instance,
@@ -94,16 +94,94 @@ describe('SanityBridge', () => {
     })
     await flushMicrotasks()
 
-    // Write main doc + ref doc (ref doc already exists as draft)
+    // Tell the bridge ref-1 already exists in Sanity
+    bridge.markRefDocKnown('ref-1')
+
     bridge.write(
       { value: 2 },
       [{ docId: 'ref-1', documentType: 'customFont', content: { name: 'updated' } }],
     )
     await flushMicrotasks()
 
-    // Main doc should be updated
     expect(mock.getDoc('doc-1')?.value).toBe(2)
-    // Ref doc should be updated (not fail because it already exists)
+    expect(mock.getDoc('ref-1')?.name).toBe('updated')
+    bridge.dispose()
+  })
+
+  it('write with new ref doc creates then edits transparently', async () => {
+    const mock = createMockSanity({ 'doc-1': { value: 1 } })
+    const bridge = new SanityBridge({
+      instance: mock.instance,
+      resource: mock.resource,
+      docId: 'doc-1',
+      documentType: 'test',
+      onChange: () => {},
+    })
+    await flushMicrotasks()
+
+    // ref doc doesn't exist — bridge should create + edit automatically
+    bridge.write(
+      { value: 2 },
+      [{ docId: 'new-ref', documentType: 'customBackground', content: { name: 'new bg' } }],
+    )
+    await flushMicrotasks()
+
+    expect(mock.getDoc('doc-1')?.value).toBe(2)
+    expect(mock.getDoc('new-ref')?.name).toBe('new bg')
+    expect(mock.getDoc('new-ref')?._id).toBe('new-ref')
+    bridge.dispose()
+  })
+
+  it('second write to same ref doc skips create', async () => {
+    const mock = createMockSanity({ 'doc-1': { value: 1 } })
+    const bridge = new SanityBridge({
+      instance: mock.instance,
+      resource: mock.resource,
+      docId: 'doc-1',
+      documentType: 'test',
+      onChange: () => {},
+    })
+    await flushMicrotasks()
+
+    // First write — creates the ref doc
+    bridge.write(
+      { value: 2 },
+      [{ docId: 'new-ref', documentType: 'customBackground', content: { name: 'v1' } }],
+    )
+    await flushMicrotasks()
+    expect(mock.getDoc('new-ref')?.name).toBe('v1')
+
+    // Second write — should NOT try createDocument again (would throw "already exists")
+    bridge.write(
+      { value: 3 },
+      [{ docId: 'new-ref', documentType: 'customBackground', content: { name: 'v2' } }],
+    )
+    await flushMicrotasks()
+    expect(mock.getDoc('new-ref')?.name).toBe('v2')
+    bridge.dispose()
+  })
+
+  it('markRefDocKnown prevents unnecessary create on existing docs', async () => {
+    const mock = createMockSanity({ 'doc-1': { value: 1 }, 'ref-1': { name: 'existing' } })
+    const bridge = new SanityBridge({
+      instance: mock.instance,
+      resource: mock.resource,
+      docId: 'doc-1',
+      documentType: 'test',
+      onChange: () => {},
+    })
+    await flushMicrotasks()
+
+    // Without markRefDocKnown, writing would try createDocument on an existing doc → fail
+    // With it, the bridge knows to skip createDocument
+    bridge.markRefDocKnown('ref-1')
+
+    bridge.write(
+      { value: 2 },
+      [{ docId: 'ref-1', documentType: 'customFont', content: { name: 'updated' } }],
+    )
+    await flushMicrotasks()
+
     expect(mock.getDoc('ref-1')?.name).toBe('updated')
     bridge.dispose()
   })

src/__tests__/sync-client.test.ts

@@ -455,3 +455,126 @@ describe('SyncClient diff-at-flush', () => {
     syncClient.dispose()
   })
 })
+
+// ── Hydration tests ───────────────────────────────────────────────────────
+
+function makeUnhydratedClient() {
+  const { client: transport, server } = createMemoryTransportPair()
+  const syncClient = new SyncClient({
+    transport,
+    documents: {
+      main: { applyMutation: replaceApply },
+    },
+    sendDebounce: { ms: 0, maxWaitMs: 0 },
+  })
+  return { syncClient, server, transport }
+}
+
+describe('SyncClient hydration', () => {
+  it('ready resolves immediately when all docs have initialState', async () => {
+    const { syncClient } = makeClient({ count: 0 })
+    await syncClient.ready // should not hang
+    expect(syncClient.isHydrated).toBe(true)
+    syncClient.dispose()
+  })
+
+  it('ready resolves after server sends state for unhydrated doc', async () => {
+    const { syncClient, server } = makeUnhydratedClient()
+    expect(syncClient.isHydrated).toBe(false)
+
+    let resolved = false
+    syncClient.ready.then(() => { resolved = true })
+    await flushMicrotasks()
+    expect(resolved).toBe(false)
+
+    server.send({ channel: 'doc:main', type: 'state', state: { count: 42 } } satisfies ServerMsg)
+    await flushMicrotasks()
+
+    expect(resolved).toBe(true)
+    expect(syncClient.isHydrated).toBe(true)
+    syncClient.dispose()
+  })
+
+  it('getDocState throws before hydration', () => {
+    const { syncClient } = makeUnhydratedClient()
+    expect(() => syncClient.getDocState('main')).toThrow('not hydrated')
+    syncClient.dispose()
+  })
+
+  it('mutate throws before hydration', () => {
+    const { syncClient } = makeUnhydratedClient()
+    expect(() => syncClient.mutate('main', { kind: 'replace', state: { count: 1 } })).toThrow('before hydration')
+    syncClient.dispose()
+  })
+
+  it('getDocState works after hydration', async () => {
+    const { syncClient, server } = makeUnhydratedClient()
+    server.send({ channel: 'doc:main', type: 'state', state: { count: 99 } } satisfies ServerMsg)
+    await flushMicrotasks()
+
+    expect(syncClient.getDocState('main')).toEqual({ count: 99 })
+    syncClient.dispose()
+  })
+
+  it('subscribers notified on hydration', async () => {
+    const { syncClient, server } = makeUnhydratedClient()
+    const listener = vi.fn()
+    syncClient.subscribeDoc('main', listener)
+
+    server.send({ channel: 'doc:main', type: 'state', state: { count: 1 } } satisfies ServerMsg)
+    await flushMicrotasks()
+
+    expect(listener).toHaveBeenCalledTimes(1)
+    syncClient.dispose()
+  })
+
+  it('mixed docs: ready waits for all unhydrated docs', async () => {
+    const { client: transport, server } = createMemoryTransportPair()
+    const syncClient = new SyncClient({
+      transport,
+      documents: {
+        hydrated: { initialState: 'ready', applyMutation: replaceApply },
+        pending: { applyMutation: replaceApply },
+      },
+      sendDebounce: { ms: 0, maxWaitMs: 0 },
+    })
+
+    expect(syncClient.isHydrated).toBe(false)
+    expect(syncClient.isDocHydrated('hydrated')).toBe(true)
+    expect(syncClient.isDocHydrated('pending')).toBe(false)
+
+    let resolved = false
+    syncClient.ready.then(() => { resolved = true })
+    await flushMicrotasks()
+    expect(resolved).toBe(false)
+
+    server.send({ channel: 'doc:pending', type: 'state', state: 'loaded' } satisfies ServerMsg)
+    await flushMicrotasks()
+
+    expect(resolved).toBe(true)
+    expect(syncClient.isHydrated).toBe(true)
+    expect(syncClient.getDocState('pending')).toBe('loaded')
+    expect(syncClient.getDocState('hydrated')).toBe('ready')
+    syncClient.dispose()
+  })
+
+  it('mutations work normally after hydration', async () => {
+    vi.useFakeTimers()
+    const { syncClient, server } = makeUnhydratedClient()
+
+    server.send({ channel: 'doc:main', type: 'state', state: { count: 10 } } satisfies ServerMsg)
+    await vi.advanceTimersByTimeAsync(0)
+
+    syncClient.mutate('main', { kind: 'replace', state: { count: 20 } })
+    expect(syncClient.getDocState('main')).toEqual({ count: 20 })
+
+    // Flush should produce a sanityPatch
+    const received: unknown[] = []
+    server.onMessage((m) => received.push(m))
+    await vi.advanceTimersByTimeAsync(0)
+
+    expect(received).toHaveLength(1)
+    expect(asMutateMsg(received[0]).mutation.kind).toBe('sanityPatch')
+    syncClient.dispose()
+  })
+})

src/client/sync-client.ts

@@ -8,6 +8,10 @@
  *
  * Named mutations (intent-based, e.g. AI tool calls) still go through the
  * traditional mutation queue with ack/reject handling.
+ *
+ * Hydration: when `initialState` is omitted, the doc starts unhydrated.
+ * The `ready` promise resolves once all docs receive their first `state`
+ * message from the server. Mutations are blocked until hydration completes.
  */
 
 import { diffValue } from '@sanity/diff-patch'
@@ -20,8 +24,11 @@ import { docChannel, parseChannel } from '../channel'
 import { type DebouncedFlusher, createFlusher, clearFlusher, scheduleFlusher } from '../debounce'
 import { MutationQueue } from './mutation-queue'
 
+const UNHYDRATED = Symbol('unhydrated')
+
 export interface DocConfig {
-  initialState: unknown
+  /** Initial state. Omit to wait for the server's first `state` message. */
+  initialState?: unknown
   applyMutation: (state: unknown, mutation: Mutation) => unknown | null
   reconcile?: (prev: unknown, next: unknown) => unknown
 }
@@ -43,6 +50,8 @@ interface DocState {
   listeners: Set<() => void>
   /** Whether localState has unsent changes (replace mutations not yet flushed). */
   dirty: boolean
+  /** Whether this doc has received its initial state (from constructor or server). */
+  hydrated: boolean
 }
 
 type StatusListener = (status: 'connected' | 'disconnected') => void
@@ -67,24 +76,36 @@ export class SyncClient {
   private debounceMs: number
   private maxWaitMs: number
   private disposed = false
+  private _resolveReady: (() => void) | null = null
+
+  /** Resolves when all docs have received their initial state. */
+  readonly ready: Promise<void>
 
   constructor(options: SyncClientOptions) {
     this.transport = options.transport
     this.debounceMs = options.sendDebounce?.ms ?? 500
     this.maxWaitMs = options.sendDebounce?.maxWaitMs ?? 1000
 
     for (const [docId, config] of Object.entries(options.documents)) {
+      const hasInitial = config.initialState !== undefined
       this.docs.set(docId, {
-        serverState: config.initialState,
-        localState: config.initialState,
-        lastSentState: config.initialState,
+        serverState: hasInitial ? config.initialState : UNHYDRATED,
+        localState: hasInitial ? config.initialState : UNHYDRATED,
+        lastSentState: hasInitial ? config.initialState : UNHYDRATED,
         queue: new MutationQueue(),
         config,
         listeners: new Set(),
         dirty: false,
+        hydrated: hasInitial,
       })
     }
 
+    if ([...this.docs.values()].every(d => d.hydrated)) {
+      this.ready = Promise.resolve()
+    } else {
+      this.ready = new Promise(resolve => { this._resolveReady = resolve })
+    }
+
     this.unsubMessage = this.transport.onMessage((raw) => {
       if (isServerMsg(raw)) this.handleServerMsg(raw)
     })
@@ -99,6 +120,7 @@ export class SyncClient {
   getDocState<T = unknown>(docId: string): T {
     const doc = this.docs.get(docId)
     if (!doc) throw new Error(`Unknown document: ${docId}`)
+    if (!doc.hydrated) throw new Error(`Document "${docId}" not hydrated — await client.ready`)
     return doc.localState as T
   }
 
@@ -109,11 +131,24 @@ export class SyncClient {
     return () => { doc.listeners.delete(listener) }
   }
 
+  // ── Hydration ─────────────────────────────────────────────────────────
+
+  get isHydrated(): boolean {
+    return [...this.docs.values()].every(d => d.hydrated)
+  }
+
+  isDocHydrated(docId: string): boolean {
+    const doc = this.docs.get(docId)
+    if (!doc) throw new Error(`Unknown document: ${docId}`)
+    return doc.hydrated
+  }
+
   // ── Mutations ───────────────────────────────────────────────────────────
 
   mutate(docId: string, mutation: Mutation): void {
     const doc = this.docs.get(docId)
     if (!doc) throw new Error(`Unknown document: ${docId}`)
+    if (!doc.hydrated) throw new Error(`Cannot mutate "${docId}" before hydration — await client.ready`)
 
     if (mutation.kind === 'replace') {
       // Replace: update local state directly, diff at flush time
@@ -207,6 +242,20 @@ export class SyncClient {
       case 'state': {
         const received = msg.state
 
+        if (!doc.hydrated) {
+          // First state message — hydrate
+          doc.serverState = received
+          doc.localState = received
+          doc.lastSentState = received
+          doc.hydrated = true
+          for (const listener of doc.listeners) listener()
+          if ([...this.docs.values()].every(d => d.hydrated)) {
+            this._resolveReady?.()
+            this._resolveReady = null
+          }
+          break
+        }
+
         if (this._status === 'disconnected') {
           // Reconnect: full reset — accept server state, discard unsent local edits
           doc.serverState = received
@@ -259,6 +308,7 @@ export class SyncClient {
 
   /** Recompute local state by replaying queued named mutations on server state. */
   private recomputeLocal(doc: DocState): void {
+    if (!doc.hydrated) return
     const prev = doc.localState
     let next = doc.queue.rebase(doc.serverState, doc.config.applyMutation)
     if (doc.config.reconcile) {
@@ -272,7 +322,7 @@ export class SyncClient {
   private flush(): void {
     // Diff dirty docs and produce sanityPatch mutations
     for (const [docId, doc] of this.docs) {
-      if (!doc.dirty) continue
+      if (!doc.hydrated || !doc.dirty) continue
 
       const operations = diffValue(doc.lastSentState, doc.localState)
       if (operations.length === 0) {