@templatical/core 0.26.3 → 0.27.1

package/dist/cloud/index.js

@@ -1,6 +1,27 @@
-import { SdkError, createDefaultTemplateContent } from "@templatical/types";
-import { computed, onScopeDispose, reactive, readonly, ref, watch } from "vue";
+import { SdkError } from "@templatical/types";
+import { computed, onScopeDispose, ref, watch } from "vue";
 //#region src/cloud/auth.ts
+/**
+* Whether a token-refresh failure is worth interrupting the user over.
+*
+* **Fatal** means the endpoint actively rejected the credentials — a `4xx`. No
+* amount of retrying fixes that: every subsequent request will fail the same
+* way, so the session really is over and the editor should say so.
+*
+* **Everything else is transient**: a network blip, a `5xx`, a timeout, a
+* malformed response. Those resolve on their own, and blanking the editor over
+* one interrupts someone mid-edit on a template that is very likely unsaved.
+* `AuthManager` reports every failure to `onError` and re-throws regardless, so
+* a caller that genuinely cannot proceed still finds out; this only decides
+* whether the *overlay* goes up.
+*
+* `404` is treated as fatal deliberately: a refresh URL that does not exist is a
+* misconfiguration, and retrying a typo forever is worse than saying so.
+*/
+function isFatalAuthError(error) {
+	const status = error instanceof SdkError ? error.statusCode : void 0;
+	return status !== void 0 && status >= 400 && status < 500;
+}
 var AuthManager = class AuthManager {
 	static DEFAULT_BASE_URL = "https://templatical.com";
 	accessToken = null;
@@ -172,10 +193,10 @@ const API_ROUTES = {
 	"templates.export": `${TEMPLATE}/export`,
 	"templates.importFromBeefree": `${BASE}/templates/import/from-beefree`,
 	"templates.sendTestEmail": `${TEMPLATE}/send-test-email`,
-	"snapshots.index": `${TEMPLATE}/snapshots`,
-	"snapshots.store": `${TEMPLATE}/snapshots`,
-	"snapshots.show": `${TEMPLATE}/snapshots/{snapshot}`,
-	"snapshots.restore": `${TEMPLATE}/snapshots/{snapshot}/restore`,
+	"versions.index": `${TEMPLATE}/versions`,
+	"versions.store": `${TEMPLATE}/versions`,
+	"versions.show": `${TEMPLATE}/versions/{version}`,
+	"versions.restore": `${TEMPLATE}/versions/{version}/restore`,
 	"comments.index": `${TEMPLATE}/comments`,
 	"comments.store": `${TEMPLATE}/comments`,
 	"comments.update": `${TEMPLATE}/comments/{comment}`,
@@ -249,10 +270,13 @@ var ApiClient = class {
 		}
 		return error.message;
 	}
-	async createTemplate(content) {
+	async createTemplate(content, name) {
 		return this.request(buildUrl(API_ROUTES["templates.store"], this.baseParams), {
 			method: "POST",
-			body: JSON.stringify({ content })
+			body: JSON.stringify(name !== void 0 ? {
+				content,
+				name
+			} : { content })
 		});
 	}
 	async getTemplate(id) {
@@ -261,22 +285,31 @@ var ApiClient = class {
 			template: id
 		}));
 	}
-	async updateTemplate(id, content) {
+	/**
+	* Apply a partial update. Takes a patch rather than bare content so a rename
+	* can travel without content and vice versa — the shape `TemplatePatch`
+	* defines, which is what `createCloudTemplatesProvider` forwards verbatim. Only
+	* the keys present are sent.
+	*/
+	async updateTemplate(id, patch) {
 		return this.request(buildUrl(API_ROUTES["templates.update"], {
 			...this.baseParams,
 			template: id
 		}), {
 			method: "PUT",
-			body: JSON.stringify({ content })
+			body: JSON.stringify(patch)
 		});
 	}
-	async createSnapshot(templateId, content) {
-		return this.request(buildUrl(API_ROUTES["snapshots.store"], {
+	async createVersion(templateId, content, label) {
+		return this.request(buildUrl(API_ROUTES["versions.store"], {
 			...this.baseParams,
 			template: templateId
 		}), {
 			method: "POST",
-			body: JSON.stringify({ content })
+			body: JSON.stringify(label !== void 0 ? {
+				content,
+				label
+			} : { content })
 		});
 	}
 	async deleteTemplate(id) {
@@ -285,17 +318,24 @@ var ApiClient = class {
 			template: id
 		}), { method: "DELETE" });
 	}
-	async getSnapshots(templateId) {
-		return this.request(buildUrl(API_ROUTES["snapshots.index"], {
+	async getVersions(templateId) {
+		return this.request(buildUrl(API_ROUTES["versions.index"], {
 			...this.baseParams,
 			template: templateId
 		}));
 	}
-	async restoreSnapshot(templateId, snapshotId) {
-		return this.request(buildUrl(API_ROUTES["snapshots.restore"], {
+	async getVersion(templateId, versionId) {
+		return this.request(buildUrl(API_ROUTES["versions.show"], {
 			...this.baseParams,
 			template: templateId,
-			snapshot: snapshotId
+			version: versionId
+		}));
+	}
+	async restoreVersion(templateId, versionId) {
+		return this.request(buildUrl(API_ROUTES["versions.restore"], {
+			...this.baseParams,
+			template: templateId,
+			version: versionId
 		}), { method: "POST" });
 	}
 	async exportTemplate(templateId, fontsPayload) {
@@ -424,7 +464,7 @@ var WebSocketClient = class {
 		try {
 			({default: Pusher} = await import("pusher-js"));
 		} catch {
-			throw new Error("Cloud features require the optional peer dependency 'pusher-js'. Install it with: npm install pusher-js");
+			throw new Error("[Templatical] Cloud features require the optional peer dependency 'pusher-js'. Please install it.");
 		}
 		const { host, port, appKey } = this.config;
 		const authEndpoint = this.authManager.resolveUrl(buildUrl(API_ROUTES["broadcasting.auth"], {
@@ -507,251 +547,6 @@ function handleOperation(editor, payload) {
 	}
 }
 //#endregion
-//#region src/cloud/editor.ts
-function getColumnCount(layout) {
-	if (layout === "1") return 1;
-	if (layout === "3") return 3;
-	return 2;
-}
-function useEditor(options) {
-	const api = new ApiClient(options.authManager);
-	const state = reactive({
-		template: null,
-		content: createDefaultTemplateContent(options.defaultFontFamily, options.templateDefaults),
-		selectedBlockId: null,
-		viewport: "desktop",
-		darkMode: false,
-		previewMode: false,
-		isDirty: false,
-		isSaving: false,
-		isLoading: false,
-		uiTheme: "auto"
-	});
-	const content = computed({
-		get: () => state.content,
-		set: (value) => {
-			state.content = value;
-			state.isDirty = true;
-		}
-	});
-	const selectedBlock = computed(() => {
-		if (!state.selectedBlockId) return null;
-		return findBlockById(state.content.blocks, state.selectedBlockId);
-	});
-	const savedBlockIds = computed(() => {
-		const ids = /* @__PURE__ */ new Set();
-		const blocks = state.template?.content?.blocks;
-		if (!blocks) return ids;
-		for (const block of blocks) {
-			ids.add(block.id);
-			if (block.type === "section") for (const column of block.children) for (const child of column) ids.add(child.id);
-		}
-		return ids;
-	});
-	function findBlockById(blocks, id) {
-		for (const block of blocks) {
-			if (block.id === id) return block;
-			if (block.type === "section") for (const column of block.children) {
-				const found = findBlockById(column, id);
-				if (found) return found;
-			}
-		}
-		return null;
-	}
-	function findBlockParent(blocks, id, parent = { blocks }) {
-		for (let i = 0; i < blocks.length; i++) {
-			const block = blocks[i];
-			if (block.id === id) return parent;
-			if (block.type === "section") for (let colIdx = 0; colIdx < block.children.length; colIdx++) {
-				const result = findBlockParent(block.children[colIdx], id, {
-					blocks: block.children[colIdx],
-					sectionId: block.id,
-					columnIndex: colIdx
-				});
-				if (result) return result;
-			}
-		}
-		return null;
-	}
-	function isBlockLocked(blockId) {
-		return options.lockedBlocks?.value.has(blockId) ?? false;
-	}
-	function setContent(newContent, markDirty = true) {
-		state.content = newContent;
-		if (markDirty) state.isDirty = true;
-	}
-	function selectBlock(blockId) {
-		if (blockId && isBlockLocked(blockId)) return;
-		state.selectedBlockId = blockId;
-	}
-	function setViewport(viewport) {
-		state.viewport = viewport;
-	}
-	function setDarkMode(darkMode) {
-		state.darkMode = darkMode;
-	}
-	function setUiTheme(theme) {
-		state.uiTheme = theme;
-	}
-	function setPreviewMode(previewMode) {
-		state.previewMode = previewMode;
-		if (previewMode) state.selectedBlockId = null;
-	}
-	function updateBlock(blockId, updates) {
-		if (isBlockLocked(blockId)) return;
-		const block = findBlockById(state.content.blocks, blockId);
-		if (block) {
-			Object.assign(block, updates);
-			state.isDirty = true;
-		}
-	}
-	function updateSettings(updates) {
-		state.content.settings = {
-			...state.content.settings,
-			...updates
-		};
-		state.isDirty = true;
-	}
-	function addBlock(block, targetSectionId, columnIndex = 0, index) {
-		if (targetSectionId) {
-			const section = findBlockById(state.content.blocks, targetSectionId);
-			if (section && section.type === "section") {
-				section.children[columnIndex] = section.children[columnIndex] || [];
-				const targetArray = section.children[columnIndex];
-				if (index !== void 0 && index < targetArray.length) targetArray.splice(index, 0, block);
-				else targetArray.push(block);
-			}
-		} else if (index !== void 0 && index < state.content.blocks.length) state.content.blocks.splice(index, 0, block);
-		else state.content.blocks.push(block);
-		state.isDirty = true;
-	}
-	function removeBlock(blockId) {
-		if (isBlockLocked(blockId)) return;
-		const parent = findBlockParent(state.content.blocks, blockId);
-		if (parent) {
-			const index = parent.blocks.findIndex((b) => b.id === blockId);
-			if (index !== -1) {
-				parent.blocks.splice(index, 1);
-				if (state.selectedBlockId === blockId) state.selectedBlockId = null;
-				state.isDirty = true;
-			}
-		}
-	}
-	function moveBlock(blockId, newIndex, targetSectionId, columnIndex = 0) {
-		const parent = findBlockParent(state.content.blocks, blockId);
-		if (!parent) return;
-		const oldIndex = parent.blocks.findIndex((b) => b.id === blockId);
-		if (oldIndex === -1) return;
-		let targetArray;
-		if (targetSectionId) {
-			const section = findBlockById(state.content.blocks, targetSectionId);
-			if (!section || section.type !== "section") return;
-			if (columnIndex < 0 || columnIndex >= getColumnCount(section.columns)) return;
-			section.children[columnIndex] = section.children[columnIndex] || [];
-			targetArray = section.children[columnIndex];
-		} else targetArray = state.content.blocks;
-		const [block] = parent.blocks.splice(oldIndex, 1);
-		targetArray.splice(newIndex, 0, block);
-		state.isDirty = true;
-	}
-	async function create(content) {
-		state.isLoading = true;
-		try {
-			if (content) state.content = content;
-			const template = await api.createTemplate(state.content);
-			state.template = template;
-			state.isDirty = false;
-			return template;
-		} catch (error) {
-			options.onError?.(error);
-			throw error;
-		} finally {
-			state.isLoading = false;
-		}
-	}
-	async function load(templateId) {
-		state.isLoading = true;
-		try {
-			const template = await api.getTemplate(templateId);
-			state.template = template;
-			state.content = template.content;
-			state.isDirty = false;
-			return template;
-		} catch (error) {
-			options.onError?.(error);
-			throw error;
-		} finally {
-			state.isLoading = false;
-		}
-	}
-	async function save() {
-		if (!state.template?.id) throw new SdkError("No template loaded. Call create() or load() before saving.");
-		state.isSaving = true;
-		try {
-			const template = await api.updateTemplate(state.template.id, state.content);
-			state.template = template;
-			state.isDirty = false;
-			return template;
-		} catch (error) {
-			options.onError?.(error);
-			throw error;
-		} finally {
-			state.isSaving = false;
-		}
-	}
-	async function createSnapshot() {
-		if (!state.template?.id) return;
-		try {
-			await api.createSnapshot(state.template.id, state.content);
-		} catch (error) {
-			options.onError?.(error);
-			throw error;
-		}
-	}
-	function hasTemplate() {
-		return state.template?.id !== void 0;
-	}
-	function markDirty() {
-		state.isDirty = true;
-	}
-	function findBlockLocation(blockId) {
-		const parent = findBlockParent(state.content.blocks, blockId);
-		if (!parent) return null;
-		const index = parent.blocks.findIndex((b) => b.id === blockId);
-		if (index === -1) return null;
-		return {
-			targetSectionId: parent.sectionId,
-			columnIndex: parent.columnIndex,
-			index
-		};
-	}
-	return {
-		state: readonly(state),
-		content,
-		selectedBlock,
-		savedBlockIds,
-		isBlockLocked,
-		findBlockLocation,
-		setContent,
-		selectBlock,
-		setViewport,
-		setDarkMode,
-		setUiTheme,
-		setPreviewMode,
-		updateBlock,
-		updateSettings,
-		addBlock,
-		removeBlock,
-		moveBlock,
-		create,
-		load,
-		save,
-		createSnapshot,
-		hasTemplate,
-		markDirty
-	};
-}
-//#endregion
 //#region src/cloud/ai-chat.ts
 let messageIdCounter = 0;
 function generateMessageId() {
@@ -1370,32 +1165,63 @@ function useDesignReference(options) {
 	};
 }
 //#endregion
-//#region src/cloud/comments.ts
-function useComments(options) {
-	const { authManager, getTemplateId, getSocketId, onComment, onError, hasCommentingFeature } = options;
+//#region src/cloud/comments-provider.ts
+/** The Pusher event Cloud's backend fans comment writes out on. */
+const BROADCAST_EVENT = "comment-broadcast";
+/**
+* Cloud's wire shape → the contract shape. The whole job of this adapter, plus
+* auth: snake_case to camelCase, and the two flat `author_*` / `resolved_by_*`
+* pairs into {@link CommentAuthor} objects.
+*/
+function toComment(record) {
+	const comment = {
+		id: record.id,
+		body: record.body,
+		author: {
+			id: record.author_identifier,
+			name: record.author_name
+		},
+		createdAt: record.created_at,
+		blockId: record.block_id,
+		parentId: record.parent_id,
+		resolvedAt: record.resolved_at
+	};
+	if (record.updated_at !== record.created_at) comment.updatedAt = record.updated_at;
+	if (record.resolved_by_identifier) comment.resolvedBy = {
+		id: record.resolved_by_identifier,
+		name: record.resolved_by_name ?? ""
+	};
+	if (record.replies?.length) comment.replies = record.replies.map(toComment);
+	return comment;
+}
+/**
+* Cloud-backed {@link CommentsProvider} — the Templatical Cloud adapter for the
+* same review contract consumers implement themselves.
+*
+* All four mutations are enabled: comment storage and its realtime fan-out are
+* what the `commenting` plan feature pays for, so there is no Cloud tier that can
+* read a thread but not reply to it. A consumer who wants a read-only review
+* supplies their own provider with the mutations set to `false`.
+*
+* Two things about the write payloads are Cloud's alone and stay on this side of
+* the seam:
+*
+* - **The author is signed.** `user_id` / `user_name` / `user_signature` come from
+*   the JWT, not from the editor's `user` config, so a browser cannot attribute a
+*   comment to someone else. The editor's `user` key still gates the feature and
+*   drives "you wrote this" in the UI; the two agree because `initCloud()` fills
+*   `user` from the same JWT.
+* - **`X-Socket-ID`.** Cloud excludes the originating socket from the broadcast,
+*   which is why a local write and its echo can't double-post. Every implementation
+*   is nonetheless echo-safe (`upsert` replaces by id), so a backend without that
+*   header is fine too.
+*/
+function createCloudCommentsProvider(options) {
+	const { authManager, channel, getSocketId } = options;
 	const api = new ApiClient(authManager);
-	const comments = ref([]);
-	const isLoading = ref(false);
-	const isSubmitting = ref(false);
-	const isEnabled = computed(() => {
-		return (hasCommentingFeature?.() ?? false) && authManager.userConfig !== null;
-	});
-	const totalCount = computed(() => {
-		let count = 0;
-		for (const thread of comments.value) count += 1 + (thread.replies?.length ?? 0);
-		return count;
-	});
-	const unresolvedCount = computed(() => {
-		return comments.value.filter((c) => !c.resolved_at).length;
-	});
-	const commentCountByBlock = computed(() => {
-		const map = /* @__PURE__ */ new Map();
-		for (const thread of comments.value) if (thread.block_id) map.set(thread.block_id, (map.get(thread.block_id) ?? 0) + 1 + (thread.replies?.length ?? 0));
-		return map;
-	});
-	function getUserPayload() {
+	function userPayload() {
 		const user = authManager.userConfig;
-		if (!user) throw new Error("User config not available");
+		if (!user) throw new Error("[Templatical] Cloud comments need a signed user in the auth token. The project's token endpoint must include a `user` claim.");
 		return {
 			user_id: user.id,
 			user_name: user.name,
@@ -1404,226 +1230,70 @@ function useComments(options) {
 	}
 	function socketHeaders() {
 		const socketId = getSocketId?.();
-		if (!socketId) return;
-		return { "X-Socket-ID": socketId };
-	}
-	function emitEvent(type, comment) {
-		onComment?.({
-			type,
-			comment
-		});
-	}
-	function findComment(commentId) {
-		for (const thread of comments.value) {
-			if (thread.id === commentId) return thread;
-			for (const reply of thread.replies ?? []) if (reply.id === commentId) return reply;
-		}
-		return null;
-	}
-	async function loadComments() {
-		const templateId = getTemplateId();
-		if (!templateId) return;
-		isLoading.value = true;
-		try {
-			comments.value = await api.getComments(templateId);
-		} catch (err) {
-			const wrappedError = err instanceof Error ? err : new Error("Failed to load comments", { cause: err });
-			onError?.(wrappedError);
-		} finally {
-			isLoading.value = false;
-		}
-	}
-	async function addComment(body, blockId, parentId) {
-		const templateId = getTemplateId();
-		if (!templateId) return null;
-		isSubmitting.value = true;
-		try {
-			const comment = await api.createComment(templateId, {
-				body,
-				block_id: blockId,
-				parent_id: parentId,
-				...getUserPayload()
-			}, socketHeaders());
-			if (parentId) {
-				const parent = findComment(parentId);
-				if (parent) parent.replies = [...parent.replies ?? [], comment];
-			} else comments.value = [...comments.value, comment];
-			emitEvent("created", comment);
-			return comment;
-		} catch (err) {
-			const wrappedError = err instanceof Error ? err : new Error("Failed to create comment", { cause: err });
-			onError?.(wrappedError);
-			return null;
-		} finally {
-			isSubmitting.value = false;
-		}
-	}
-	async function editComment(commentId, body) {
-		const templateId = getTemplateId();
-		if (!templateId) return null;
-		isSubmitting.value = true;
-		try {
-			const updated = await api.updateComment(templateId, commentId, {
-				body,
-				...getUserPayload()
-			}, socketHeaders());
-			updateCommentInState(commentId, updated);
-			emitEvent("updated", updated);
-			return updated;
-		} catch (err) {
-			const wrappedError = err instanceof Error ? err : new Error("Failed to update comment", { cause: err });
-			onError?.(wrappedError);
-			return null;
-		} finally {
-			isSubmitting.value = false;
-		}
-	}
-	async function removeComment(commentId) {
-		const templateId = getTemplateId();
-		if (!templateId) return false;
-		const comment = findComment(commentId);
-		if (!comment) return false;
-		const commentSnapshot = {
-			...comment,
-			replies: [...comment.replies ?? []]
-		};
-		isSubmitting.value = true;
-		try {
-			await api.deleteComment(templateId, commentId, getUserPayload(), socketHeaders());
-			if (comment.parent_id) {
-				const parent = findComment(comment.parent_id);
-				if (parent) parent.replies = (parent.replies ?? []).filter((r) => r.id !== commentId);
-			} else comments.value = comments.value.filter((c) => c.id !== commentId);
-			emitEvent("deleted", commentSnapshot);
-			return true;
-		} catch (err) {
-			const wrappedError = err instanceof Error ? err : new Error("Failed to delete comment", { cause: err });
-			onError?.(wrappedError);
-			return false;
-		} finally {
-			isSubmitting.value = false;
-		}
-	}
-	async function toggleResolve(commentId) {
-		const templateId = getTemplateId();
-		if (!templateId) return null;
-		isSubmitting.value = true;
-		try {
-			const updated = await api.resolveComment(templateId, commentId, getUserPayload(), socketHeaders());
-			updateCommentInState(commentId, updated);
-			emitEvent(updated.resolved_at ? "resolved" : "unresolved", updated);
-			return updated;
-		} catch (err) {
-			const wrappedError = err instanceof Error ? err : new Error("Failed to toggle comment resolution", { cause: err });
-			onError?.(wrappedError);
-			return null;
-		} finally {
-			isSubmitting.value = false;
-		}
+		return socketId ? { "X-Socket-ID": socketId } : void 0;
 	}
-	function applyRemoteCreate(comment) {
-		if (comment.parent_id) {
-			const parent = findComment(comment.parent_id);
-			if (parent) parent.replies = [...parent.replies ?? [], comment];
-		} else comments.value = [...comments.value, comment];
-		emitEvent("created", comment);
-	}
-	function applyRemoteUpdate(comment) {
-		updateCommentInState(comment.id, comment);
-		emitEvent("updated", comment);
-	}
-	function applyRemoteDelete(commentId, parentId) {
-		const comment = findComment(commentId);
-		const snapshot = comment ? {
-			...comment,
-			replies: [...comment.replies ?? []]
-		} : null;
-		if (parentId) {
-			const parent = findComment(parentId);
-			if (parent) parent.replies = (parent.replies ?? []).filter((r) => r.id !== commentId);
-		} else comments.value = comments.value.filter((c) => c.id !== commentId);
-		if (snapshot) emitEvent("deleted", snapshot);
-	}
-	function updateCommentInState(commentId, updated) {
-		for (let i = 0; i < comments.value.length; i++) {
-			if (comments.value[i].id === commentId) {
-				comments.value = [
-					...comments.value.slice(0, i),
-					{
-						...updated,
-						replies: comments.value[i].replies
-					},
-					...comments.value.slice(i + 1)
-				];
-				return;
-			}
-			const replies = comments.value[i].replies ?? [];
-			for (let j = 0; j < replies.length; j++) if (replies[j].id === commentId) {
-				const newReplies = [
-					...replies.slice(0, j),
-					updated,
-					...replies.slice(j + 1)
-				];
-				comments.value = [
-					...comments.value.slice(0, i),
-					{
-						...comments.value[i],
-						replies: newReplies
-					},
-					...comments.value.slice(i + 1)
-				];
-				return;
+	return {
+		async list(templateId) {
+			return (await api.getComments(templateId)).map(toComment);
+		},
+		async create(templateId, input) {
+			return toComment(await api.createComment(templateId, {
+				body: input.body,
+				block_id: input.blockId,
+				parent_id: input.parentId,
+				...userPayload()
+			}, socketHeaders()));
+		},
+		async update(templateId, commentId, patch) {
+			if (patch.body === void 0) throw new Error("[Templatical] Cloud comments: update() needs a `body` in the patch.");
+			return toComment(await api.updateComment(templateId, commentId, {
+				body: patch.body,
+				...userPayload()
+			}, socketHeaders()));
+		},
+		async delete(templateId, commentId) {
+			await api.deleteComment(templateId, commentId, userPayload(), socketHeaders());
+		},
+		async setResolved(templateId, commentId, _resolved) {
+			return toComment(await api.resolveComment(templateId, commentId, userPayload(), socketHeaders()));
+		},
+		subscribe(_templateId, onChange) {
+			function handle(payload) {
+				const comment = toComment(payload.comment);
+				switch (payload.action) {
+					case "comment_created":
+						onChange({
+							type: "created",
+							comment
+						});
+						break;
+					case "comment_deleted":
+						onChange({
+							type: "deleted",
+							commentId: comment.id,
+							parentId: comment.parentId
+						});
+						break;
+					case "comment_updated":
+					case "comment_resolved":
+					case "comment_unresolved": onChange({
+						type: "updated",
+						comment
+					});
+				}
 			}
+			const stopWatching = watch(channel, (next, previous) => {
+				previous?.unbind(BROADCAST_EVENT, handle);
+				next?.bind(BROADCAST_EVENT, handle);
+			}, { immediate: true });
+			return () => {
+				stopWatching();
+				channel.value?.unbind(BROADCAST_EVENT, handle);
+			};
 		}
-	}
-	return {
-		comments,
-		isLoading,
-		isSubmitting,
-		isEnabled,
-		commentCountByBlock,
-		totalCount,
-		unresolvedCount,
-		loadComments,
-		addComment,
-		editComment,
-		removeComment,
-		toggleResolve,
-		applyRemoteCreate,
-		applyRemoteUpdate,
-		applyRemoteDelete
 	};
 }
 //#endregion
-//#region src/cloud/comment-listener.ts
-function useCommentListener(options) {
-	const { comments, channel } = options;
-	watch(channel, (newChannel, oldChannel) => {
-		if (oldChannel) oldChannel.unbind("comment-broadcast");
-		if (newChannel) newChannel.bind("comment-broadcast", (payload) => {
-			handleCommentBroadcast(comments, payload);
-		});
-	});
-	onScopeDispose(() => {
-		channel.value?.unbind("comment-broadcast");
-	});
-}
-function handleCommentBroadcast(comments, payload) {
-	switch (payload.action) {
-		case "comment_created":
-			comments.applyRemoteCreate(payload.comment);
-			break;
-		case "comment_updated":
-			comments.applyRemoteUpdate(payload.comment);
-			break;
-		case "comment_deleted":
-			comments.applyRemoteDelete(payload.comment.id, payload.comment.parent_id);
-			break;
-		case "comment_resolved":
-		case "comment_unresolved": comments.applyRemoteUpdate(payload.comment);
-	}
-}
-//#endregion
 //#region src/cloud/collaboration.ts
 const COLLAB_EVENTS = [
 	"pusher:member_added",
@@ -1922,8 +1592,9 @@ function useWebSocket(options) {
 * editor UI never see them. Plan gating is applied by the caller before this
 * provider is constructed.
 *
-* Wraps the existing `ApiClient` saved-module endpoints, so the REST contract
-* is unchanged from before saved blocks became an open-source feature.
+* Wraps the `ApiClient` saved-module endpoints. The REST contract keeps the
+* `savedModules.*` route names even though the type is `SavedBlock`, so the
+* names deliberately differ from the contract's.
 *
 * Rows pass straight through, unmapped: the Cloud endpoints speak the same
 * `SavedBlock` shape the contract defines, so this adapter only supplies auth
@@ -1950,42 +1621,217 @@ function createCloudSavedBlocksProvider(authManager) {
 	};
 }
 //#endregion
-//#region src/cloud/snapshots.ts
-function useSnapshotHistory(options) {
-	const api = new ApiClient(options.authManager);
-	const snapshots = ref([]);
-	const isLoading = ref(false);
-	const isRestoring = ref(false);
-	async function loadSnapshots() {
-		isLoading.value = true;
-		try {
-			snapshots.value = await api.getSnapshots(options.templateId);
-		} catch (error) {
-			options.onError?.(error);
-			throw error;
-		} finally {
-			isLoading.value = false;
-		}
+//#region src/cloud/templates-provider.ts
+/**
+* How often a save may also record an automatic version. Cloud's storage, Cloud's
+* number — an editor-side default would be guessing on someone else's behalf.
+*/
+const AUTO_VERSION_INTERVAL_MS = 6e4;
+/**
+* Cloud-backed {@link TemplatesProvider} — the Templatical Cloud adapter for the
+* same save/load contract consumers implement themselves.
+*
+* Auth (JWT via {@link AuthManager}) and project/tenant scoping live entirely on
+* this side of the seam; the editor's header, Cmd+S, autosave and
+* unsaved-changes guard never see them.
+*
+* All three methods are enabled: Cloud's template storage is what the plan pays
+* for, so there is no tier in which a Cloud session can load but not save. A
+* consumer who wants read-only supplies their own provider with `save: false`.
+*
+* **This is also where automatic versions are recorded.** The editor never
+* creates one on its own — whoever implements `save` decides whether a save also
+* records a version, which keeps throttling and retention with the side that
+* pays for the storage. Cloud throttles to one automatic version per
+* {@link AUTO_VERSION_INTERVAL_MS}, so an autosave firing every few seconds does
+* not turn history into a keystroke log. Keep this on the provider side: an
+* editor-side timer would put Cloud's retention policy in the editor.
+*
+* Note `initCloud()` **rejects** a consumer-supplied templates provider, unlike
+* `savedBlocks` and `testEmail`. Those are inert — nothing keys off them. The
+* template id is the join key for collaboration, version history, comments, AI
+* rewrite, scoring and the server-side export, so an id Cloud never issued would
+* degrade all six silently.
+*/
+function createCloudTemplatesProvider(authManager) {
+	const api = new ApiClient(authManager);
+	let lastAutoVersionAt = 0;
+	/**
+	* Fire-and-forget: a version is a convenience on top of a save that already
+	* succeeded, so a failing history endpoint must not turn a successful save
+	* into a failed one. The clock advances before the request, so a slow endpoint
+	* can't let a burst of saves queue several at once.
+	*
+	* Logged rather than swallowed: history quietly not filling up is exactly the
+	* kind of failure nobody notices until they need a version that was never
+	* recorded.
+	*/
+	function maybeRecordVersion(templateId, content) {
+		const now = Date.now();
+		if (now - lastAutoVersionAt < AUTO_VERSION_INTERVAL_MS) return;
+		lastAutoVersionAt = now;
+		api.createVersion(templateId, content).catch((error) => {
+			console.warn("[Templatical] Automatic version not recorded — the save itself succeeded:", error);
+		});
 	}
-	async function restoreSnapshot(snapshotId) {
-		isRestoring.value = true;
-		try {
-			const template = await api.restoreSnapshot(options.templateId, snapshotId);
-			options.onRestore?.(template);
+	return {
+		load(id) {
+			return api.getTemplate(id);
+		},
+		create(input) {
+			return api.createTemplate(input.content, input.name);
+		},
+		async save(id, patch) {
+			const template = await api.updateTemplate(id, patch);
+			if (patch.content) maybeRecordVersion(id, patch.content);
 			return template;
-		} catch (error) {
-			options.onError?.(error);
-			throw error;
-		} finally {
-			isRestoring.value = false;
 		}
+	};
+}
+//#endregion
+//#region src/cloud/export.ts
+/**
+* Flatten a {@link FontsConfig} into the export payload.
+*
+* Unconditional: gating fonts by entitlement meters no resource Cloud buys, and
+* would only make the paid tier render fewer fonts than the free editor.
+*/
+function resolveExportFonts(fonts) {
+	return {
+		customFonts: fonts?.customFonts ?? [],
+		defaultFallback: fonts?.defaultFallback ?? "Arial, sans-serif"
+	};
+}
+/**
+* Cloud's server-side export endpoint, as a plain API wrapper.
+*
+* Both calls render from the **stored** template, so callers save first when the
+* canvas may have moved on — see `createCloudRenderProvider`, which is where that
+* policy lives.
+*/
+function useExport(options) {
+	const api = new ApiClient(options.authManager);
+	async function exportHtml(templateId, fonts) {
+		const result = await api.exportTemplate(templateId, fonts);
+		return {
+			html: result.html,
+			mjml: result.mjml
+		};
+	}
+	async function getMjmlSource(templateId, fonts) {
+		return (await api.exportTemplate(templateId, fonts)).mjml;
 	}
 	return {
-		snapshots,
-		isLoading,
-		isRestoring,
-		loadSnapshots,
-		restoreSnapshot
+		exportHtml,
+		getMjmlSource
+	};
+}
+//#endregion
+//#region src/cloud/render-provider.ts
+/**
+* Templatical Cloud's renderer, shaped as a {@link RenderProvider} so it plugs
+* into the same editor seam a consumer's own backend would.
+*
+* **Why Cloud renders server-side at all**, rather than running the bundled
+* renderer like an OSS consumer: its output is a deliberate *superset* that a
+* browser cannot produce. A countdown block resolves to a URL serving a live,
+* on-demand animated GIF; a video block gets a composited play button. Both are
+* injected into the published renderer through `blockRenderers` in Cloud's Node
+* sidecar, so the delta is two functions and parity on the other twelve block
+* types holds by construction.
+*
+* Two consequences of the endpoint rendering the **stored** template:
+*
+* - **Every render saves first.** The same trade the test-email adapter makes, for
+*   the same reason: exporting a stale version of what is on screen is worse than
+*   a write the caller did not ask for. It also means `toMjml()` needs a template
+*   to exist — a Cloud session that never created one gets a clear rejection
+*   rather than an export of nothing.
+* - **`payload.content` is ignored**, along with the custom-block `renderedHtml`
+*   the editor pre-rendered into it. Cloud's `save()` persists that same content
+*   immediately before, so the server reads it from storage rather than trusting an
+*   echo. `payload.fonts` *is* read, because it is the only place the editor's
+*   effective font set is expressed. Don't "fix" the content branch.
+*
+* `compileMjml` is deliberately absent: `toMjml` and `toHtml` are both whole-
+* pipeline calls here, so there is no MJML the editor would hand back for
+* compiling.
+*/
+function createCloudRenderProvider(options) {
+	const exporter = useExport({ authManager: options.authManager });
+	function exportFonts(payload) {
+		return {
+			customFonts: payload.fonts?.customFonts ?? [],
+			defaultFallback: payload.fonts?.defaultFallback ?? "Arial, sans-serif"
+		};
+	}
+	async function saveThenResolveId() {
+		if (options.getTemplateId() === null) throw new Error("[Templatical] Cloud renders from the saved template, so one must exist first. Call create() or load() before toMjml() / toHtml().");
+		return (await options.save()).id;
+	}
+	return {
+		async toMjml(payload) {
+			const fonts = exportFonts(payload);
+			const templateId = await saveThenResolveId();
+			return exporter.getMjmlSource(templateId, fonts);
+		},
+		async toHtml(payload) {
+			const fonts = exportFonts(payload);
+			const templateId = await saveThenResolveId();
+			const { html } = await exporter.exportHtml(templateId, fonts);
+			return html;
+		}
+	};
+}
+//#endregion
+//#region src/cloud/version-history-provider.ts
+/**
+* Cloud's wire shape → the contract shape. The only real work this adapter does:
+* snake_case to camelCase, and `is_autosave` to `isAutomatic`.
+*
+* `content` is carried through deliberately — Cloud's index endpoint already
+* returns it, so every listed version arrives hydrated and the editor never
+* calls `get` while scrubbing. See {@link TemplateVersion.content}: that is the
+* hint working as intended, not a shortcut. `get` is implemented anyway, because
+* it is the contract's operation and Cloud is one implementation of it like any
+* other.
+*/
+function toVersion(record) {
+	return {
+		id: record.id,
+		createdAt: record.created_at,
+		isAutomatic: record.is_autosave,
+		content: record.content
+	};
+}
+/**
+* Cloud-backed {@link VersionHistoryProvider} — the Templatical Cloud adapter for
+* the same contract consumers implement themselves.
+*
+* Both mutations are enabled: version storage is what the plan pays for, so
+* there is no Cloud tier that can list history but not restore it. A consumer
+* who wants read-only history supplies their own provider with `restore: false`.
+*
+* **Automatic versions are not created here.** They are recorded by
+* `createCloudTemplatesProvider`'s `save`, because the contract puts that
+* decision on whoever implements `save` — the side that knows the storage cost.
+* `create` here is for a version a person asked for.
+*/
+function createCloudVersionHistoryProvider(authManager) {
+	const api = new ApiClient(authManager);
+	return {
+		async list(templateId) {
+			return { versions: (await api.getVersions(templateId)).map(toVersion) };
+		},
+		async get(templateId, versionId) {
+			return (await api.getVersion(templateId, versionId)).content;
+		},
+		async create(templateId, content, meta) {
+			return toVersion(await api.createVersion(templateId, content, meta?.label));
+		},
+		restore(templateId, versionId) {
+			return api.restoreVersion(templateId, versionId);
+		}
 	};
 }
 //#endregion
@@ -2055,35 +1901,6 @@ function createCloudTestEmailProvider(options) {
 	};
 }
 //#endregion
-//#region src/cloud/export.ts
-function useExport(options) {
-	const { authManager, getFontsConfig, canUseCustomFonts } = options;
-	const api = new ApiClient(authManager);
-	function getExportFontsPayload() {
-		const fontsConfig = getFontsConfig?.();
-		return {
-			customFonts: (canUseCustomFonts?.() ?? true) && fontsConfig?.customFonts ? fontsConfig.customFonts : [],
-			defaultFallback: fontsConfig?.defaultFallback ?? "Arial, sans-serif"
-		};
-	}
-	async function exportHtml(templateId) {
-		const fontsPayload = getExportFontsPayload();
-		const result = await api.exportTemplate(templateId, fontsPayload);
-		return {
-			html: result.html,
-			mjml: result.mjml
-		};
-	}
-	async function getMjmlSource(templateId) {
-		const fontsPayload = getExportFontsPayload();
-		return (await api.exportTemplate(templateId, fontsPayload)).mjml;
-	}
-	return {
-		exportHtml,
-		getMjmlSource
-	};
-}
-//#endregion
 //#region src/cloud/plan-config.ts
 function usePlanConfig(options) {
 	const { authManager, onError } = options;
@@ -2239,6 +2056,6 @@ function useMcpListener(options) {
 	});
 }
 //#endregion
-export { API_ROUTES, ApiClient, AuthManager, WebSocketClient, buildUrl, createCloudSavedBlocksProvider, createCloudTestEmailProvider, createSdkAuthManager, handleOperation, performHealthCheck, resolveWebSocketConfig, useAiChat, useAiConfig, useAiRewrite, useCollaboration, useCollaborationBroadcast, useCommentListener, useComments, useDesignReference, useEditor, useExport, useMcpListener, usePlanConfig, useSnapshotHistory, useTemplateScoring, useTestEmail, useWebSocket };
+export { API_ROUTES, ApiClient, AuthManager, WebSocketClient, buildUrl, createCloudCommentsProvider, createCloudRenderProvider, createCloudSavedBlocksProvider, createCloudTemplatesProvider, createCloudTestEmailProvider, createCloudVersionHistoryProvider, createSdkAuthManager, handleOperation, isFatalAuthError, performHealthCheck, resolveExportFonts, resolveWebSocketConfig, useAiChat, useAiConfig, useAiRewrite, useCollaboration, useCollaborationBroadcast, useDesignReference, useExport, useMcpListener, usePlanConfig, useTemplateScoring, useTestEmail, useWebSocket };
 
 //# sourceMappingURL=index.js.map