Version History

Version history is an open contract. Templatical Cloud implements it, the same way your own backend would.

const editor = await initCloud({ container: '#editor', auth: { url: '/api/token' } });

Nothing to configure. Cloud supplies the provider, and the header's history control appears as soon as a template is created or loaded.

The adapter

Method	Cloud
list	Returns every version for the template, with its content — so scrubbing through history never waits
get	Fetches one version's content
create	Records a version on demand
restore	An atomic, audited server endpoint

Both mutations are enabled: version storage is part of what the plan pays for, so there is no Cloud tier that can list history but not restore it.

Automatic versions

Cloud's templates adapter records them as part of its own save, throttled to at most one per minute. That is the contract's rule for every implementation — whoever owns the storage owns the retention policy. A save that only renames the template records nothing.

Bringing your own

Not the storage. A version is keyed to a template id Cloud issued, and Cloud's templates adapter records an automatic version as part of every save, and that same id anchors collaboration, comments, AI rewrite, scoring and the server-side export — which is why initCloud() accepts a templates key for its configuration and events, never a full provider. A consumer-supplied history would drive the UI while Cloud carried on writing versions into its own store: two stores, one of them invisible and billable.

versionHistory follows the same shape. initCloud({ versionHistory }) takes VersionHistoryOptions — onCreated, onRestored — and nothing else: no boolean to turn it off, no full-provider form. A value carrying list / get / create / restore still has those methods ignored, named in a console warning, with only its events kept.

await initCloud({
  container: '#editor',
  auth: { url: '/api/templatical/token' },
  versionHistory: {
    onRestored: (template) => navigate(`/templates/${template.id}`),
  },
});

Bring your own storage with init(), where the whole set — templates, version history, rendering — is yours.

Events

versionHistory: {
  onCreated: (version) => {},
  onRestored: (template) => {},
}

The same events as the open contract.

Headless use

import { createCloudVersionHistoryProvider } from '@templatical/core/cloud';
import { useVersionHistory } from '@templatical/core';

const history = useVersionHistory({
  provider: createCloudVersionHistoryProvider(authManager),
  getTemplateId: () => 'template-id',
});

await history.load();
await history.restore(history.versions.value[1].id);

The ApiClient methods underneath are getVersions, getVersion, createVersion and restoreVersion — see the headless API.