Persistence Overview

Dollie Editor produces and consumes a portable PageConfig. Your application decides where that definition lives and what must happen before it becomes public.

The document contract

A persisted builder document contains:

type BuilderDocument = {
  id: string;
  definition: PageConfig;
  pageData?: Record<string, JsonValue>;
  pageDataSchema?: PageDataSchema;
  revision?: string;
  metadata?: Record<string, JsonValue>;
  capabilities: BuilderCapabilities;
};

The page definition contains the ordered Sections. pageData contains host-defined, editor-authorable properties such as a title, slug, search description, or appearance preset. The host can provide a serializable pageDataSchema to render and validate those settings.

Metadata is different: it contains read-only operational facts supplied by the host, such as timestamps, tenant identity, or publication state. The revision protects both the definition and page data from stale writes.

Omit pageData from a save to preserve its current value:

await transport.save(document.id, {
  definition,
  pageData,
  revision: document.revision,
});

Choose a transport

Transport	Use it for
createInMemoryTransport	Prototypes, examples, and UI tests
createHttpTransport	The standard SDK endpoint shape over fetch
Custom TransportClient	Server functions, an existing API, or product-specific workflows

All transports expose load, save, publish, and validate. Bindings, templates, revisions, and AI fill are optional extensions.

Recommended save flow

Serialize editor state
        ↓
Validate against the allowed catalog
        ↓
Authorize the user and tenant
        ↓
Compare the submitted revision
        ↓
Persist a new revision
        ↓
Return the current BuilderDocument

Validation and authorization must also run on the server. Client checks improve the experience; they are not a trust boundary.

Start small

First make load and save work for one page. Add publishing, revision history, bindings, and AI only when the basic content loop is reliable.

Continue with HTTP Transport.