@shop-on/theme-dev-host 0.4.0 → 0.6.0

package/README.md

@@ -63,10 +63,10 @@ load one state, tweak, and Save back to it — or branch to a fresh name with Sa
 as preset. Settings are **merged** into the preset map, so sibling presets are
 never clobbered.
 
-Without `--tunnel` the gateway is localhost-only. With `--tunnel`, paste the
-printed public URL into the **hosted** admin theme-editor (actions menu → "Local
-dev preview") to preview your local theme there — no backend or local admin
-needed. HMR there dials `ws://localhost:<theme-port>`, so it only works in a
+Without `--tunnel` the gateway is localhost-only. To preview your local theme in
+the **hosted** admin theme-editor, run `shop-on theme dev` instead: it starts this
+gateway and a tunnel, and registers the tunnel URL on your dev install, the only
+way the editor learns it — no backend or local admin needed. HMR there dials `ws://localhost:<theme-port>`, so it only works in a
 browser on the same machine as the dev server. See
 [docs/theme-dev-host.md](../../docs/theme-dev-host.md).
 

package/dist/auth.mjs

@@ -2,57 +2,72 @@
 import { EditorAuthError } from "./verify.mjs";
 //#region src/auth.ts
 const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const SID_TTL_MS = 18e5;
+const MAX_SIDS = 100;
 function reject(c, reason) {
 	console.warn(`theme-dev-host: 401 ${c.req.method} ${c.req.path} — ${reason}`);
 	return c.json({ error: reason }, 401);
 }
-async function applyJwt(c, header, verify) {
-	const claims = await verify(header.slice(7));
-	const storeSlug = c.req.param("storeSlug") ?? "";
-	const installId = c.req.param("installId") ?? "";
-	if (claims.shop_handle !== storeSlug) return reject(c, `shop mismatch (token shop_handle=${claims.shop_handle}, path=${storeSlug})`);
-	if (claims.install_id !== installId) return reject(c, `install mismatch (token install_id=${claims.install_id}, path=${installId})`);
-	c.set("sid", claims.sid);
-	c.set("shopHandle", storeSlug);
-	c.set("installId", installId);
-	return null;
-}
 function createEditorAuth(verify) {
-	const editorAuth = async (c, next) => {
-		const header = c.req.header("Authorization");
-		if (!header?.startsWith("Bearer ")) return reject(c, "missing bearer token");
+	const sids = /* @__PURE__ */ new Map();
+	function registerSid(sid) {
+		sids.delete(sid);
+		sids.set(sid, Date.now() + SID_TTL_MS);
+		if (sids.size > MAX_SIDS) sids.delete(sids.keys().next().value);
+	}
+	function sidLive(sid) {
+		const expires = sids.get(sid);
+		return expires !== void 0 && expires > Date.now();
+	}
+	async function applyJwt(c, header, scope) {
+		let claims;
 		try {
-			const fail = await applyJwt(c, header, verify);
-			if (fail) return fail;
+			claims = await verify(header.slice(7));
 		} catch (err) {
 			if (err instanceof EditorAuthError) return reject(c, err.reason);
 			throw err;
 		}
-		await next();
-	};
+		if (!claims.scp.includes(scope)) return reject(c, `wrong scope (route takes ${scope})`);
+		const storeSlug = c.req.param("storeSlug") ?? "";
+		const installId = c.req.param("installId") ?? "";
+		if (claims.shop_handle !== storeSlug) return reject(c, `shop mismatch (token shop_handle=${claims.shop_handle}, path=${storeSlug})`);
+		if (claims.install_id !== installId) return reject(c, `install mismatch (token install_id=${claims.install_id}, path=${installId})`);
+		if (scope === "editor") registerSid(claims.sid);
+		c.set("sid", claims.sid);
+		c.set("shopHandle", storeSlug);
+		c.set("installId", installId);
+		c.set("userId", claims.sub ?? "");
+		return null;
+	}
+	function bearerOnly(scope) {
+		return async (c, next) => {
+			const header = c.req.header("Authorization");
+			if (!header?.startsWith("Bearer ")) return reject(c, "missing bearer token");
+			const fail = await applyJwt(c, header, scope);
+			if (fail) return fail;
+			await next();
+		};
+	}
 	const editorAuthOrPreview = async (c, next) => {
 		const header = c.req.header("Authorization");
 		if (header?.startsWith("Bearer ")) {
-			try {
-				const fail = await applyJwt(c, header, verify);
-				if (fail) return fail;
-			} catch (err) {
-				if (err instanceof EditorAuthError) return reject(c, err.reason);
-				throw err;
-			}
+			const fail = await applyJwt(c, header, "editor");
+			if (fail) return fail;
 			await next();
 			return;
 		}
 		if (c.req.method !== "GET") return reject(c, "missing bearer token");
 		const sid = c.req.query("sid") ?? c.req.header("X-Editor-Sid") ?? void 0;
 		if (!sid || !UUID_RE.test(sid)) return reject(c, "missing or invalid sid");
+		if (!sidLive(sid)) return reject(c, "unknown sid (open the editor again to start a session)");
 		c.set("sid", sid);
 		c.set("shopHandle", c.req.param("storeSlug") ?? "");
 		c.set("installId", c.req.param("installId") ?? "");
 		await next();
 	};
 	return {
-		editorAuth,
+		editorAuth: bearerOnly("editor"),
+		publishAuth: bearerOnly("editor:publish"),
 		editorAuthOrPreview
 	};
 }

package/dist/drafts.mjs

@@ -1,44 +1,169 @@
 #!/usr/bin/env node
+import { applyOps, touchedEntries } from "@shop-on/theme-contract/ops";
 //#region src/drafts.ts
-const sessions = /* @__PURE__ */ new Map();
-const MAX_SESSIONS = 100;
-function sessionFor(sid) {
-	let s = sessions.get(sid);
-	if (!s) {
-		if (sessions.size >= MAX_SESSIONS) {
-			const oldest = sessions.keys().next().value;
-			if (oldest !== void 0) sessions.delete(oldest);
+/** Batches kept for `GET /draft/ops`; a client further behind gets `{reset}`. */
+const RING_SIZE = 256;
+const READ_COUNT = 32;
+const READ_BYTES = 524288;
+function createDraftStore() {
+	const drafts = /* @__PURE__ */ new Map();
+	function draftFor(key) {
+		let d = drafts.get(key);
+		if (!d) {
+			d = {
+				seq: 0,
+				publishedSeq: 0,
+				templates: /* @__PURE__ */ new Map(),
+				groups: /* @__PURE__ */ new Map(),
+				clients: /* @__PURE__ */ new Map(),
+				ring: []
+			};
+			drafts.set(key, d);
 		}
-		s = {
-			templates: {},
-			groups: {}
-		};
-		sessions.set(sid, s);
+		return d;
 	}
-	return s;
-}
-const drafts = {
-	getSettings(sid) {
-		return sessions.get(sid)?.settings;
-	},
-	setSettings(sid, settings) {
-		sessionFor(sid).settings = settings;
-	},
-	getTemplate(sid, templateId) {
-		return sessions.get(sid)?.templates[templateId];
-	},
-	setTemplate(sid, templateId, template) {
-		sessionFor(sid).templates[templateId] = template;
-	},
-	getGroups(sid) {
-		return { ...sessions.get(sid)?.groups };
-	},
-	setGroup(sid, groupType, group) {
-		sessionFor(sid).groups[groupType] = group;
-	},
-	clear(sid) {
-		sessions.delete(sid);
+	function push(d, batch) {
+		d.ring.push(batch);
+		if (d.ring.length > RING_SIZE) d.ring.shift();
 	}
-};
+	return {
+		seq(key) {
+			return drafts.get(key)?.seq ?? 0;
+		},
+		publishedSeq(key) {
+			return drafts.get(key)?.publishedSeq ?? 0;
+		},
+		hasUnpublishedEdits(key) {
+			const d = drafts.get(key);
+			return d !== void 0 && d.seq > d.publishedSeq;
+		},
+		/** The draft's settings, or undefined when the draft never touched them. */
+		settings(key) {
+			return drafts.get(key)?.settings;
+		},
+		/** undefined: not in the draft (read disk); null: deleted in the draft. */
+		template(key, id) {
+			return drafts.get(key)?.templates.get(id);
+		},
+		templates(key) {
+			return new Map(drafts.get(key)?.templates);
+		},
+		groups(key) {
+			return new Map(drafts.get(key)?.groups);
+		},
+		/**
+		* Apply one batch. Synchronous, so nothing interleaves between the read
+		* of the prior entries and the write. `disk` holds the disk copy of every
+		* touched entry; the draft's own copy wins where it has one.
+		*/
+		apply(key, body, userId, disk) {
+			const d = draftFor(key);
+			const client = d.clients.get(body.clientId);
+			if (client) {
+				if (body.batchNo === client.batchNo) return {
+					ok: true,
+					seq: client.seq
+				};
+				if (body.batchNo < client.batchNo) return {
+					ok: false,
+					status: 409,
+					error: "stale batch"
+				};
+			}
+			const touched = touchedEntries(body.ops);
+			const prior = {
+				settings: {},
+				templates: {},
+				groups: {}
+			};
+			if (touched.settings) prior.settings = d.settings ?? disk.settings;
+			for (const id of touched.templates) {
+				const entry = d.templates.has(id) ? d.templates.get(id) : disk.templates[id];
+				if (entry) prior.templates[id] = entry;
+			}
+			for (const type of touched.groups) {
+				const entry = d.groups.has(type) ? d.groups.get(type) : disk.groups[type];
+				if (entry) prior.groups[type] = entry;
+			}
+			const next = applyOps(prior, body.ops);
+			const same = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+			if (!(touched.settings && !same(prior.settings, next.settings) || [...touched.templates].some((id) => !same(prior.templates[id], next.templates[id])) || [...touched.groups].some((type) => !same(prior.groups[type], next.groups[type])))) {
+				d.clients.set(body.clientId, {
+					batchNo: body.batchNo,
+					seq: d.seq
+				});
+				return {
+					ok: true,
+					seq: d.seq
+				};
+			}
+			if (touched.settings) d.settings = next.settings;
+			for (const id of touched.templates) d.templates.set(id, next.templates[id] ?? null);
+			for (const type of touched.groups) d.groups.set(type, next.groups[type] ?? null);
+			d.seq += 1;
+			d.clients.set(body.clientId, {
+				batchNo: body.batchNo,
+				seq: d.seq
+			});
+			push(d, {
+				seq: d.seq,
+				clientId: body.clientId,
+				batchId: body.batchId,
+				userId,
+				ops: body.ops
+			});
+			return {
+				ok: true,
+				seq: d.seq
+			};
+		},
+		/** Drop every edit (publish / discard): the next read is the disk copy. */
+		reset(key, reset) {
+			const d = draftFor(key);
+			d.settings = void 0;
+			d.templates.clear();
+			d.groups.clear();
+			d.clients.clear();
+			d.seq += 1;
+			d.publishedSeq = d.seq;
+			push(d, {
+				seq: d.seq,
+				clientId: "",
+				batchId: "",
+				userId: "",
+				ops: [],
+				reset
+			});
+			return d.seq;
+		},
+		/** Batches after `since`, or `{reset}` when the ring cannot catch the client up. */
+		readSince(key, since) {
+			const d = drafts.get(key);
+			const seq = d?.seq ?? 0;
+			if (since === seq) return {
+				seq,
+				batches: []
+			};
+			const ring = d?.ring ?? [];
+			if (since > seq || ring.length === 0 || since < ring[0].seq - 1) return {
+				reset: true,
+				seq
+			};
+			const after = ring.filter((b) => b.seq > since);
+			const batches = [];
+			let bytes = 0;
+			for (const batch of after) {
+				batches.push(batch);
+				bytes += Buffer.byteLength(JSON.stringify(batch.ops));
+				if (batches.length === READ_COUNT || bytes >= READ_BYTES) break;
+			}
+			return {
+				seq,
+				batches,
+				...batches.length < after.length ? { more: true } : {}
+			};
+		}
+	};
+}
 //#endregion
-export { drafts };
+export { createDraftStore };

package/dist/editor-app.mjs

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import { LANG_RE, loadLocale, loadStorefrontLocale, parseLang, readJsonDir, resolveDisplayName, resolveTranslations, unwrapSettings } from "./locale.mjs";
-import { drafts } from "./drafts.mjs";
+import { createDraftStore } from "./drafts.mjs";
+import { loadRichTextSanitizer } from "./richtext.mjs";
 import { isValidPresetHandle, writeSettingsPreset, writeThemeSourceFiles } from "./save.mjs";
 import "./auth.mjs";
 import path from "node:path";
@@ -8,14 +9,19 @@ import "hono";
 import { readFile, readdir, stat } from "node:fs/promises";
 import { currentPresetHandle } from "@shop-on/theme-contract/preset-listing";
 import { bodyLimit } from "hono/body-limit";
+import { MAX_BATCH_BYTES, OpBatchBodySchema, chunkOps, touchedEntries } from "@shop-on/theme-contract/ops";
+import { applyEditorTool, isEditorToolName } from "@shop-on/theme-contract/editor-tools";
+import { readThemeAiDir } from "@shop-on/theme-contract/ai-files";
+import { invalidTemplateId } from "@shop-on/theme-contract/store-path";
 //#region src/editor-app.ts
-const TEMPLATE_ID_RE = /^[A-Za-z0-9_.-]+$/;
-const invalidTemplateId = (id) => !id || !TEMPLATE_ID_RE.test(id) || /[/\\]|\.\./.test(id);
 const PREFIX = "/api/stores/:storeSlug/:installId";
+const PROTOCOL_VERSION = 2;
 function registerEditorRoutes(app, configDir, auth, store, opts) {
-	const { editorAuth, editorAuthOrPreview } = auth;
+	const { editorAuth, publishAuth, editorAuthOrPreview } = auth;
 	const themeSrcDir = opts?.themeSrcDir;
 	const presetOverride = opts?.preset;
+	const drafts = createDraftStore();
+	const draftKey = (c) => `${c.req.param("storeSlug")}/${c.req.param("installId")}`;
 	if (store) app.use(`${PREFIX}/*`, async (c, next) => {
 		const slug = c.req.param("storeSlug");
 		const install = c.req.param("installId");
@@ -29,6 +35,10 @@ function registerEditorRoutes(app, configDir, auth, store, opts) {
 		maxSize: 8388608,
 		onError: (c) => c.json({ error: "draft too large" }, 413)
 	});
+	const opsBodyLimit = bodyLimit({
+		maxSize: MAX_BATCH_BYTES,
+		onError: (c) => c.json({ error: "batch too large" }, 413)
+	});
 	async function loadSettingsData() {
 		try {
 			return JSON.parse(await readFile(path.join(configDir, "settings-data.json"), "utf-8"));
@@ -46,13 +56,13 @@ function registerEditorRoutes(app, configDir, auth, store, opts) {
 			return null;
 		}
 	}
-	async function sectionGroupsFor(sid) {
-		const groups = drafts.getGroups(sid);
+	async function diskGroups() {
+		const groups = {};
 		try {
 			for (const file of await readdir(path.join(configDir, "section-groups"))) {
 				if (!file.endsWith(".json")) continue;
 				const data = JSON.parse(await readFile(path.join(configDir, "section-groups", file), "utf-8"));
-				if (data.type && !groups[data.type]) groups[data.type] = {
+				if (data.type) groups[data.type] = {
 					sections: data.sections ?? {},
 					order: data.order ?? []
 				};
@@ -60,8 +70,31 @@ function registerEditorRoutes(app, configDir, auth, store, opts) {
 		} catch {}
 		return groups;
 	}
+	async function sectionGroupsFor(key) {
+		const groups = await diskGroups();
+		for (const [type, entry] of drafts.groups(key)) if (entry) groups[type] = entry;
+		else delete groups[type];
+		return groups;
+	}
+	async function diskPrior(ops) {
+		const touched = touchedEntries(ops);
+		const prior = {
+			settings: {},
+			templates: {},
+			groups: {}
+		};
+		if (touched.settings) prior.settings = await liveSettings();
+		for (const id of touched.templates) {
+			const tpl = await diskTemplate(id);
+			if (tpl) prior.templates[id] = tpl;
+		}
+		if (touched.groups.size > 0) prior.groups = await diskGroups();
+		return prior;
+	}
 	app.get(`${PREFIX}/editor-loader`, editorAuthOrPreview, async (c) => {
-		const sid = c.get("sid");
+		const key = draftKey(c);
+		const seq = drafts.seq(key);
+		const publishedSeq = drafts.publishedSeq(key);
 		const locale = await loadLocale(configDir, parseLang(c));
 		const [schemaRaw, sections, blocks, templates, sectionGroups] = await Promise.all([
 			readFile(path.join(configDir, "settings-schema.json"), "utf-8").catch(() => null),
@@ -72,14 +105,20 @@ function registerEditorRoutes(app, configDir, auth, store, opts) {
 		]);
 		const themeSchema = (schemaRaw ? JSON.parse(schemaRaw) : []).map((s) => resolveTranslations(s, locale));
 		const settingsData = await loadSettingsData();
-		const settings = drafts.getSettings(sid) ?? unwrapSettings(settingsData, presetOverride);
+		const settings = drafts.settings(key) ?? unwrapSettings(settingsData, presetOverride);
 		const activePreset = presetOverride ?? settingsData.current?.preset ?? "default";
+		const draftIndex = drafts.template(key, "index");
 		const initialTemplateData = {
 			sections: {},
 			order: [],
-			...drafts.getTemplate(sid, "index") ?? await diskTemplate("index")
+			...draftIndex === void 0 ? await diskTemplate("index") : draftIndex
 		};
-		initialTemplateData.section_groups = await sectionGroupsFor(sid);
+		initialTemplateData.section_groups = await sectionGroupsFor(key);
+		const diskIds = new Set(templates.map(({ id }) => id));
+		const draftOnly = [...drafts.templates(key)].filter(([id, entry]) => entry && !diskIds.has(id)).map(([id, entry]) => ({
+			id,
+			name: resolveDisplayName(entry, id, locale)
+		}));
 		let layoutSchema = {};
 		try {
 			layoutSchema = resolveTranslations(JSON.parse(await readFile(path.join(configDir, "layouts", "main.json"), "utf-8")), locale);
@@ -94,37 +133,168 @@ function registerEditorRoutes(app, configDir, auth, store, opts) {
 				type: id,
 				...resolveTranslations(data, locale)
 			})),
-			templates: templates.map(({ id, data }) => ({
+			templates: [...templates.map(({ id, data }) => ({
 				id,
 				name: resolveDisplayName(data, id, locale)
-			})),
+			})), ...draftOnly],
 			sectionGroupDefaults: sectionGroups.map(({ data }) => resolveTranslations(data, locale)),
 			initialTemplateData,
 			layoutSchema,
 			settings,
-			activePreset
+			activePreset,
+			seq,
+			publishedSeq,
+			protocolVersion: PROTOCOL_VERSION
 		});
 	});
-	app.put(`${PREFIX}/draft`, editorAuth, writeBodyLimit, async (c) => {
-		const body = await c.req.json().catch(() => null);
-		if (!body?.settings || typeof body.settings !== "object") return c.json({ error: "settings required" }, 400);
-		drafts.setSettings(c.get("sid"), body.settings);
-		return c.json({ ok: true });
+	for (const route of [
+		"/draft",
+		"/draft/template",
+		"/draft/section-group"
+	]) app.put(`${PREFIX}${route}`, (c) => c.json({ error: "Draft PUTs were replaced by POST /draft/ops; reload the editor." }, 410));
+	app.post(`${PREFIX}/draft/ops`, opsBodyLimit, editorAuth, async (c) => {
+		const raw = await c.req.json().catch(() => void 0);
+		if (raw === void 0) return c.json({ error: "invalid JSON body" }, 400);
+		const parsed = OpBatchBodySchema.safeParse(raw);
+		if (!parsed.success) return c.json({
+			error: "invalid batch",
+			issues: parsed.error.issues.slice(0, 5)
+		}, 422);
+		const key = draftKey(c);
+		const prior = await diskPrior(parsed.data.ops);
+		const result = drafts.apply(key, parsed.data, c.get("userId"), prior);
+		if (!result.ok) return c.json({ error: result.error }, result.status);
+		return c.json({ seq: result.seq });
 	});
-	app.put(`${PREFIX}/draft/template`, editorAuth, writeBodyLimit, async (c) => {
-		const body = await c.req.json().catch(() => null);
-		if (invalidTemplateId(body?.templateId) || !body?.template) return c.json({ error: "templateId and template required" }, 400);
-		drafts.setTemplate(c.get("sid"), body.templateId, body.template);
-		return c.json({ ok: true });
+	app.get(`${PREFIX}/draft/ops`, editorAuth, (c) => {
+		const raw = c.req.query("since") ?? "";
+		if (!/^\d{1,15}$/.test(raw)) return c.json({ error: "since must be a non-negative integer" }, 400);
+		return c.json(drafts.readSince(draftKey(c), Number(raw)));
 	});
-	app.put(`${PREFIX}/draft/section-group`, editorAuth, writeBodyLimit, async (c) => {
+	async function engineInputs(lang) {
+		const locale = await loadLocale(configDir, lang);
+		const [schemaRaw, sections, blocks, ai] = await Promise.all([
+			readFile(path.join(configDir, "settings-schema.json"), "utf-8").catch(() => null),
+			readJsonDir(path.join(configDir, "sections")),
+			readJsonDir(path.join(configDir, "blocks")),
+			readThemeAiDir(path.join(configDir, "ai"))
+		]);
+		for (const { reason } of ai.skipped) console.warn(`[editor-tools] src/ai/: skipped ${reason}`);
+		const resolved = (items) => items.map(({ id, data }) => ({
+			type: id,
+			...resolveTranslations(data, locale)
+		}));
+		return {
+			schemas: {
+				settingsSchema: (schemaRaw ? JSON.parse(schemaRaw) : []).map((s) => resolveTranslations(s, locale)),
+				sections: resolved(sections),
+				blocks: resolved(blocks)
+			},
+			recipes: ai.recipes,
+			guide: ai.guide
+		};
+	}
+	async function documentFor(key) {
+		const templates = {};
+		for (const { id, data } of await readJsonDir(path.join(configDir, "templates"))) templates[id] = data;
+		for (const [id, entry] of drafts.templates(key)) if (entry) templates[id] = entry;
+		else delete templates[id];
+		return {
+			settings: drafts.settings(key) ?? await liveSettings(),
+			templates,
+			groups: await sectionGroupsFor(key)
+		};
+	}
+	app.post(`${PREFIX}/editor-tools/:tool`, opsBodyLimit, editorAuth, async (c) => {
+		const tool = c.req.param("tool");
+		if (tool !== "apply_ops" && !isEditorToolName(tool)) return c.json({ error: "unknown tool" }, 404);
 		const body = await c.req.json().catch(() => null);
-		if (!body?.groupType || !body?.group) return c.json({ error: "groupType and group required" }, 400);
-		drafts.setGroup(c.get("sid"), body.groupType, body.group);
-		return c.json({ ok: true });
+		if (typeof body?.callId !== "string" || !/^[A-Za-z0-9_-]{1,64}$/.test(body.callId)) return c.json({ error: "callId required" }, 422);
+		const key = draftKey(c);
+		let ops;
+		let result = {};
+		if (tool === "apply_ops") {
+			const raw = body.args?.ops;
+			if (!Array.isArray(raw) || raw.length === 0) return c.json({
+				ok: false,
+				reason: "apply_ops takes {ops: [op, ...]}"
+			});
+			ops = raw;
+		} else {
+			const seq = drafts.seq(key);
+			const expected = body.args?.expected_seq;
+			if (typeof expected === "number" && expected !== seq) return c.json({
+				ok: false,
+				reason: "STALE_READ",
+				seq
+			}, 409);
+			let inputs;
+			try {
+				inputs = await engineInputs(parseLang(c));
+			} catch (err) {
+				return c.json({
+					ok: false,
+					reason: err.message
+				});
+			}
+			const out = applyEditorTool(tool, body.args, {
+				...inputs,
+				doc: await documentFor(key),
+				sanitizeRichText: await loadRichTextSanitizer(),
+				images: "trusted"
+			});
+			if (!out.ok) return c.json({
+				ok: false,
+				reason: out.reason
+			});
+			ops = out.ops;
+			result = out.result;
+		}
+		const clientId = `mcp:${c.get("sid")}:${body.callId}`;
+		const batches = [];
+		for (const [n, chunk] of chunkOps(ops).entries()) {
+			const batch = OpBatchBodySchema.safeParse({
+				clientId,
+				batchNo: n + 1,
+				batchId: crypto.randomUUID(),
+				ops: chunk
+			});
+			if (!batch.success) {
+				const issue = batch.error.issues[0];
+				return c.json({
+					ok: false,
+					reason: `invalid ops at ${issue.path.join(".")}: ${issue.message}`
+				});
+			}
+			batches.push(batch.data);
+		}
+		for (const [n, batch] of batches.entries()) {
+			const applied = drafts.apply(key, batch, c.get("userId"), await diskPrior(batch.ops));
+			if (!applied.ok) return c.json({
+				error: applied.error,
+				seq: drafts.seq(key),
+				applied: n
+			}, applied.status);
+		}
+		return c.json({
+			ok: true,
+			result,
+			seq: drafts.seq(key)
+		});
+	});
+	app.post(`${PREFIX}/draft/touch`, editorAuth, (c) => c.body(null, 204));
+	app.delete(`${PREFIX}/draft`, publishAuth, (c) => {
+		const key = draftKey(c);
+		if (!drafts.hasUnpublishedEdits(key)) return c.json({ error: "No unpublished changes" }, 404);
+		return c.json({
+			ok: true,
+			seq: drafts.reset(key, "discard")
+		});
 	});
-	app.post(`${PREFIX}/publish`, editorAuth, async (c) => {
-		drafts.clear(c.get("sid"));
+	app.post(`${PREFIX}/publish`, publishAuth, (c) => {
+		const key = draftKey(c);
+		if (!drafts.hasUnpublishedEdits(key)) return c.json({ error: "No unpublished changes" }, 404);
+		drafts.reset(key, "publish");
 		return c.json({
 			ok: true,
 			published: true
@@ -167,15 +337,19 @@ function registerEditorRoutes(app, configDir, auth, store, opts) {
 		return c.json({ ok: true });
 	});
 	app.get(`${PREFIX}/settings`, editorAuthOrPreview, async (c) => {
-		return c.json(drafts.getSettings(c.get("sid")) ?? await liveSettings());
+		const key = draftKey(c);
+		c.header("X-Draft-Seq", String(drafts.seq(key)));
+		return c.json(drafts.settings(key) ?? await liveSettings());
 	});
 	app.get(`${PREFIX}/template`, editorAuthOrPreview, async (c) => {
 		const id = c.req.query("templateId");
 		if (invalidTemplateId(id)) return c.json({ error: "invalid or missing templateId" }, 400);
-		const draft = drafts.getTemplate(c.get("sid"), id);
-		const template = draft ? { ...draft } : await diskTemplate(id);
+		const key = draftKey(c);
+		c.header("X-Draft-Seq", String(drafts.seq(key)));
+		const draft = drafts.template(key, id);
+		const template = draft === void 0 ? await diskTemplate(id) : draft && { ...draft };
 		if (!template) return c.json({ error: "Template not found" }, 404);
-		template.section_groups = await sectionGroupsFor(c.get("sid"));
+		template.section_groups = await sectionGroupsFor(key);
 		return c.json(template);
 	});
 	app.get(`${PREFIX}/templates`, editorAuthOrPreview, async (c) => {

package/dist/gateway.mjs

@@ -27,7 +27,8 @@ async function startGateway(opts) {
 	app.all("*", createProxy(`http://localhost:${opts.themePort}`));
 	const server = serve({
 		fetch: app.fetch,
-		port: opts.port
+		port: opts.port,
+		hostname: "127.0.0.1"
 	});
 	const watcher = opts.watch === false ? void 0 : watchThemeConfig(themeSrcDir, configDir, { preset: opts.preset });
 	return {

package/dist/launch.mjs

@@ -46,7 +46,7 @@ const child = spawn(cmd, args, {
 	stdio: "inherit",
 	env: {
 		...process.env,
-		ORCHESTRATOR_URL: `http://localhost:${port}`,
+		ORCHESTRATOR_URL: `http://127.0.0.1:${port}`,
 		STORE_SLUG: slug,
 		INSTALL_ID: install,
 		...preset ? { THEME_PRESET: preset } : {},
@@ -78,7 +78,7 @@ if (preset) console.log(`  preset      editing '${preset}' — Save writes back
 if (tunnel) console.log(`  public      ${tunnel.url}`);
 console.log("");
 console.log(`  preview origin → ${origin}`);
-console.log(tunnel ? "  ^ paste into the hosted admin theme-editor: actions menu → \"Local dev preview\"." : "  ^ localhost-only; add --tunnel to drive a hosted admin.");
+console.log(tunnel ? "  ^ `shop-on theme dev` opens the hosted theme editor on this URL." : "  ^ localhost-only; `shop-on theme dev` drives a hosted admin.");
 console.log("  Ctrl-C to stop both.");
 let shuttingDown = false;
 async function shutdown(code) {

package/dist/materialize.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { watch } from "node:fs";
 import path from "node:path";
-import { copyFile, mkdir, readFile, readdir, rm, stat, writeFile } from "node:fs/promises";
+import { copyFile, cp, mkdir, readFile, readdir, rm, stat, writeFile } from "node:fs/promises";
 import { currentPresetHandle } from "@shop-on/theme-contract/preset-listing";
 import { overlayPresetListing } from "@shop-on/theme-contract/preset-materializer";
 //#region src/materialize.ts
@@ -13,6 +13,8 @@ const JSON_DIRS = [
 	"layouts",
 	"locales"
 ];
+const AI_DIR = "ai";
+const isWatched = (file) => file.endsWith(".json") || file.endsWith(".md");
 async function copyJsonDir(srcDir, destDir) {
 	let files;
 	try {
@@ -44,6 +46,14 @@ async function resolveActivePreset(themeSrcDir, presetOverride) {
 async function materializeThemeConfig(themeSrcDir, configDir, presetOverride) {
 	await mkdir(configDir, { recursive: true });
 	for (const dir of JSON_DIRS) await copyJsonDir(path.join(themeSrcDir, dir), path.join(configDir, dir));
+	await rm(path.join(configDir, AI_DIR), {
+		recursive: true,
+		force: true
+	});
+	if (await dirExists(path.join(themeSrcDir, AI_DIR))) await cp(path.join(themeSrcDir, AI_DIR), path.join(configDir, AI_DIR), {
+		recursive: true,
+		filter: async (src) => (await stat(src)).isDirectory() || isWatched(src)
+	});
 	try {
 		await copyFile(path.join(themeSrcDir, "config", "settings-schema.json"), path.join(configDir, "settings-schema.json"));
 	} catch {}
@@ -63,7 +73,7 @@ function watchThemeConfig(themeSrcDir, configDir, opts = {}) {
 	const onError = opts.onError ?? ((err) => console.warn("[theme-dev-host] re-materialize failed:", err));
 	let timer;
 	return watch(themeSrcDir, { recursive: true }, (_event, filename) => {
-		if (!filename || !filename.toString().endsWith(".json")) return;
+		if (!filename || !isWatched(filename.toString())) return;
 		clearTimeout(timer);
 		timer = setTimeout(() => {
 			materializeThemeConfig(themeSrcDir, configDir, opts.preset).catch(onError);

package/dist/richtext.mjs

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+import { RICHTEXT_SANITIZE_CONFIG, registerRichTextHooks } from "@shop-on/theme-contract/editor-tools";
+//#region src/richtext.ts
+let loading;
+function loadRichTextSanitizer() {
+	loading ??= import("isomorphic-dompurify").then(({ default: purify }) => {
+		registerRichTextHooks(purify);
+		return (html) => purify.sanitize(html, RICHTEXT_SANITIZE_CONFIG);
+	}, (err) => {
+		loading = void 0;
+		throw err;
+	});
+	return loading;
+}
+//#endregion
+export { loadRichTextSanitizer };

package/dist/tunnel.mjs

@@ -7,7 +7,7 @@ const PROVIDERS = {
 			"cloudflared",
 			"tunnel",
 			"--url",
-			`http://localhost:${port}`
+			`http://127.0.0.1:${port}`
 		],
 		urlRe: /https:\/\/[a-z0-9-]+\.trycloudflare\.com/,
 		signup: false
@@ -16,7 +16,7 @@ const PROVIDERS = {
 		argv: (port) => [
 			"ngrok",
 			"http",
-			String(port),
+			`127.0.0.1:${port}`,
 			"--log",
 			"stdout"
 		],
@@ -28,7 +28,7 @@ const PROVIDERS = {
 			"zrok",
 			"share",
 			"public",
-			`http://localhost:${port}`
+			`http://127.0.0.1:${port}`
 		],
 		urlRe: /https:\/\/[a-z0-9-]+\.share\.zrok\.io/,
 		signup: true

package/dist/verify.mjs

@@ -25,7 +25,7 @@ function createEditorVerifier(pem) {
 				issuer: "SPN"
 			});
 			const claims = payload;
-			if (!Array.isArray(claims.scp) || !claims.scp.includes("editor")) throw new EditorAuthError("wrong scope");
+			if (!Array.isArray(claims.scp)) throw new EditorAuthError("wrong scope");
 			if (!claims.sid || !claims.shop_handle || !claims.install_id) throw new EditorAuthError("missing claims");
 			return claims;
 		} catch (err) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shop-on/theme-dev-host",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Local theme-editor dev server: serves the editor contract + proxies a theme's dev server behind one origin, so a theme runs locally and previews in a real admin theme-editor. Nucleus of the future theme CLI.",
   "license": "SEE LICENSE IN dist/LICENSE.md",
   "bin": {
@@ -14,8 +14,9 @@
   "dependencies": {
     "@hono/node-server": "^2.1.5",
     "hono": "^4.13.13",
+    "isomorphic-dompurify": "4.6.0",
     "jose": "^6.2.13",
-    "@shop-on/theme-contract": "0.4.0"
+    "@shop-on/theme-contract": "0.6.0"
   },
   "devDependencies": {
     "@types/node": "26.6.5",