@phtngyn/cms 0.2.0-beta.8 → 0.3.0

package/src/Operations.d.ts

@@ -0,0 +1,57 @@
+import { Context, Effect, Schema } from "effect";
+//#region ../server/src/MediaObjects.d.ts
+declare const MediaStorageError_base: Schema.Class<MediaStorageError, Schema.TaggedStruct<"Media.StorageError", {
+  readonly operation: Schema.NonEmptyString;
+  readonly cause: Schema.Defect;
+}>, import("effect/Cause").YieldableError>;
+declare class MediaStorageError extends MediaStorageError_base {}
+//#endregion
+//#region ../server/src/internal/operations/error.d.ts
+declare const OperationsError_base: Schema.Class<OperationsError, Schema.TaggedStruct<"Operations.Error", {
+  readonly operation: Schema.NonEmptyString;
+  readonly cause: Schema.Defect;
+}>, import("effect/Cause").YieldableError>;
+declare class OperationsError extends OperationsError_base {}
+//#endregion
+//#region src/Operations.d.ts
+export interface CmsOperationsOptions {
+  readonly databaseFile: string;
+  readonly directory: string;
+  readonly s3: {
+    readonly bucket: string;
+    readonly region: string;
+    readonly prefix?: string;
+    readonly endpoint?: string;
+    readonly forcePathStyle?: boolean;
+    readonly credentials?: {
+      readonly accessKeyId: string;
+      readonly secretAccessKey: string;
+      readonly sessionToken?: string;
+    };
+  };
+}
+/** Back up a stopped installation to a new directory. */
+export declare const backupCms: (options: CmsOperationsOptions) => Effect.Effect<{
+  readonly format: 1;
+  readonly createdAt: string;
+  readonly sqliteSha256: string;
+  readonly objects: readonly {
+    readonly key: string;
+    readonly byteSize: number;
+    readonly mimeType: string;
+    readonly sha256: string;
+  }[];
+}, MediaStorageError | OperationsError, never>;
+/** Restore into a fresh database path and media prefix while Nuxt is stopped. */
+export declare const restoreCms: (options: CmsOperationsOptions) => Effect.Effect<{
+  readonly format: 1;
+  readonly createdAt: string;
+  readonly sqliteSha256: string;
+  readonly objects: readonly {
+    readonly key: string;
+    readonly byteSize: number;
+    readonly mimeType: string;
+    readonly sha256: string;
+  }[];
+}, MediaStorageError | OperationsError, never>;
+//#endregion

package/src/Operations.js

@@ -0,0 +1,263 @@
+import { n as MediaObjects, t as layer } from "./S3MediaObjects-y-WacEi9.js";
+import { Clock, Context, Crypto, Effect, FileSystem, Layer, Path, Schema, Stream } from "effect";
+import { createHash } from "node:crypto";
+import * as NodeCrypto from "@effect/platform-node/NodeCrypto";
+import * as NodeFileSystem from "@effect/platform-node/NodeFileSystem";
+import * as NodePath from "@effect/platform-node/NodePath";
+import { SqliteClient } from "@effect/sql-sqlite-node";
+import * as Hex from "effect/encoding/Hex";
+//#region ../server/src/internal/operations/error.ts
+var OperationsError = class extends Schema.TaggedError()("Operations.Error", {
+	operation: Schema.NonEmptyString,
+	cause: Schema.Defect()
+}) {};
+const operationsError = (operation, cause) => new OperationsError({
+	operation,
+	cause
+});
+//#endregion
+//#region ../server/src/internal/operations/files.ts
+const hashChunks = Effect.fn("Operations.hashChunks")(function* (stream) {
+	const hash = createHash("sha256");
+	let byteSize = 0;
+	yield* stream.pipe(Stream.runForEach((chunk) => Effect.sync(() => {
+		hash.update(chunk);
+		byteSize += chunk.length;
+	})));
+	return {
+		byteSize,
+		sha256: hash.digest("hex")
+	};
+});
+const hashFile = Effect.fn("Operations.hashFile")((fs, path, operation) => hashChunks(fs.stream(path).pipe(Stream.mapError((cause) => operationsError(operation, cause)))));
+/** The stream consumer cancels its reader; cancel here when consumption never started. */
+const releaseStream = Effect.fn("Operations.releaseStream")((stream) => stream && !stream.locked ? Effect.promise(() => stream.cancel().catch(() => {})) : Effect.void);
+const saveStream = Effect.fn("Operations.saveStream")((fs, path, stream) => Effect.scoped(Effect.gen(function* () {
+	const file = yield* fs.open(path, { flag: "wx" }).pipe(Effect.mapError((cause) => operationsError("media.copy", cause)));
+	const copied = yield* hashChunks(Stream.fromReadableStream({
+		evaluate: () => stream,
+		onError: (cause) => operationsError("media.copy", cause)
+	}).pipe(Stream.tap((chunk) => file.writeAll(chunk).pipe(Effect.mapError((cause) => operationsError("media.copy", cause))))));
+	yield* file.sync.pipe(Effect.mapError((cause) => operationsError("media.copy", cause)));
+	return copied;
+})).pipe(Effect.catchDefect((cause) => Effect.fail(operationsError("media.copy", cause)))));
+const hashStream = Effect.fn("Operations.hashStream")((stream) => hashChunks(Stream.fromReadableStream({
+	evaluate: () => stream,
+	onError: (cause) => operationsError("media.hash", cause)
+})));
+//#endregion
+//#region ../server/src/internal/operations/manifest.ts
+const Digest = Schema.String.check(Schema.isPattern(/^[0-9a-f]{64}$/u));
+const BackupManifest = Schema.Struct({
+	format: Schema.Literal(1),
+	createdAt: Schema.NonEmptyString,
+	sqliteSha256: Digest,
+	objects: Schema.Array(Schema.Struct({
+		key: Schema.NonEmptyString,
+		byteSize: Schema.Int.check(Schema.isGreaterThanOrEqualTo(0)),
+		mimeType: Schema.NonEmptyString,
+		sha256: Digest
+	}))
+});
+const objectPath = Effect.fn("Operations.objectPath")(function* (path, directory, key) {
+	const digest = yield* (yield* Crypto.Crypto).digest("SHA-256", new TextEncoder().encode(key)).pipe(Effect.mapError((cause) => operationsError("media.path", cause)));
+	return path.join(directory, "objects", `${Hex.encode(digest)}.bin`);
+});
+//#endregion
+//#region ../server/src/internal/operations/snapshot.ts
+const ReadyMedia = Schema.Array(Schema.Struct({
+	key: Schema.NonEmptyString,
+	byteSize: Schema.Int.check(Schema.isGreaterThanOrEqualTo(0)),
+	mimeType: Schema.NonEmptyString
+}));
+/** Read one immutable backup snapshot for both backup and restore validation. */
+const readSnapshot = Effect.fn("Operations.readSnapshot")(function* (filename, operation) {
+	const raw = yield* Effect.gen(function* () {
+		const db = yield* SqliteClient.SqliteClient;
+		return {
+			integrity: (yield* db`PRAGMA integrity_check`)[0],
+			ready: yield* db`
+        SELECT active_key AS key, byte_size AS byteSize, mime_type AS mimeType
+        FROM cms_media_assets WHERE status = 'ready'
+      `
+		};
+	}).pipe(Effect.provide(SqliteClient.layer({
+		filename,
+		readonly: true,
+		disableWAL: true
+	})), Effect.mapError((cause) => operationsError(operation, cause)), Effect.catchDefect((cause) => Effect.fail(operationsError(operation, cause))));
+	if ((yield* Schema.decodeUnknownEffect(Schema.Struct({ integrity_check: Schema.String }))(raw.integrity).pipe(Effect.mapError((cause) => operationsError(operation, cause)))).integrity_check !== "ok") return yield* operationsError(operation, /* @__PURE__ */ new Error(operation === "sqlite.inspect" ? "The SQLite snapshot failed its integrity check." : "The backup database failed its integrity check."));
+	return yield* Schema.decodeUnknownEffect(ReadyMedia)(raw.ready).pipe(Effect.mapError((cause) => operationsError(operation, cause)));
+});
+//#endregion
+//#region ../server/src/internal/operations/backup.ts
+function snapshot(databaseFile, output) {
+	return Effect.gen(function* () {
+		yield* (yield* SqliteClient.SqliteClient).backup(output);
+	}).pipe(Effect.provide(SqliteClient.layer({
+		filename: databaseFile,
+		readonly: true,
+		disableWAL: true
+	})), Effect.uninterruptible, Effect.mapError((cause) => operationsError("sqlite.backup", cause)), Effect.catchDefect((cause) => Effect.fail(operationsError("sqlite.backup", cause))));
+}
+const backupInstallation = Effect.fn("Operations.backupInstallation")(function* (options) {
+	const fs = yield* FileSystem.FileSystem;
+	const path = yield* Path.Path;
+	const directory = options.directory;
+	yield* fs.makeDirectory(directory).pipe(Effect.mapError((cause) => operationsError("directory.create", cause)));
+	return yield* Effect.gen(function* () {
+		const sqlite = path.join(directory, "cms.sqlite");
+		yield* snapshot(options.databaseFile, sqlite);
+		const readyMedia = yield* readSnapshot(sqlite, "sqlite.inspect");
+		const database = yield* hashFile(fs, sqlite, "sqlite.hash");
+		const objects = [];
+		yield* fs.makeDirectory(path.join(directory, "objects")).pipe(Effect.mapError((cause) => operationsError("objects.create", cause)));
+		const seen = /* @__PURE__ */ new Set();
+		let cursor;
+		do {
+			const page = yield* options.media.list("", cursor).pipe(Effect.mapError((cause) => operationsError("media.list", cause)));
+			for (const listed of page.objects) {
+				if (seen.has(listed.key)) return yield* operationsError("media.list", /* @__PURE__ */ new Error(`Duplicate media object: ${listed.key}`));
+				seen.add(listed.key);
+				const metadata = yield* options.media.stat(listed.key).pipe(Effect.mapError((cause) => operationsError("media.stat", cause)));
+				if (!metadata) return yield* operationsError("media.missing", /* @__PURE__ */ new Error(`Media object disappeared: ${listed.key}`));
+				const copied = yield* Effect.scoped(Effect.gen(function* () {
+					const stream = yield* Effect.acquireRelease(options.media.read(listed.key).pipe(Effect.mapError((cause) => operationsError("media.read", cause))), releaseStream, { interruptible: true });
+					if (!stream) return yield* operationsError("media.missing", /* @__PURE__ */ new Error(`Media object disappeared: ${listed.key}`));
+					return yield* saveStream(fs, yield* objectPath(path, directory, listed.key), stream);
+				}));
+				if (copied.byteSize !== listed.byteSize || copied.byteSize !== metadata.byteSize) return yield* operationsError("media.size", /* @__PURE__ */ new Error(`Media object changed during backup: ${listed.key}`));
+				objects.push({
+					key: listed.key,
+					byteSize: copied.byteSize,
+					mimeType: metadata.mimeType,
+					sha256: copied.sha256
+				});
+			}
+			if (page.nextCursor === cursor && cursor !== void 0) return yield* operationsError("media.list", /* @__PURE__ */ new Error("Media inventory cursor did not advance."));
+			cursor = page.nextCursor;
+		} while (cursor);
+		const copiedByKey = new Map(objects.map((object) => [object.key, object]));
+		for (const ready of readyMedia) {
+			const copied = copiedByKey.get(ready.key);
+			if (!copied) return yield* operationsError("media.missing", /* @__PURE__ */ new Error(`Ready media object is missing: ${ready.key}`));
+			if (copied.byteSize !== ready.byteSize || copied.mimeType !== ready.mimeType) return yield* operationsError("media.metadata", /* @__PURE__ */ new Error(`Ready media metadata differs from S3: ${ready.key}`));
+		}
+		objects.sort((left, right) => left.key.localeCompare(right.key));
+		const manifest = yield* Schema.decodeEffect(BackupManifest)({
+			format: 1,
+			createdAt: new Date(yield* Clock.currentTimeMillis).toISOString(),
+			sqliteSha256: database.sha256,
+			objects
+		}).pipe(Effect.mapError((cause) => operationsError("manifest.create", cause)));
+		yield* fs.writeFileString(path.join(directory, "manifest.json"), JSON.stringify(manifest, null, 2), { flag: "wx" }).pipe(Effect.mapError((cause) => operationsError("manifest.write", cause)));
+		return manifest;
+	}).pipe(Effect.onError(() => fs.remove(directory, {
+		recursive: true,
+		force: true
+	}).pipe(Effect.orDie)));
+});
+//#endregion
+//#region ../server/src/internal/operations/restore.ts
+const verifyDatabase = Effect.fn("Operations.verifyDatabase")(function* (path, expected) {
+	const ready = yield* readSnapshot(path, "sqlite.verify");
+	for (const row of ready) {
+		const object = expected.get(row.key);
+		if (!object) return yield* operationsError("sqlite.verify", /* @__PURE__ */ new Error(`Ready media is absent from the backup: ${row.key}`));
+		if (object.byteSize !== row.byteSize || object.mimeType !== row.mimeType) return yield* operationsError("sqlite.verify", /* @__PURE__ */ new Error(`Ready media metadata differs from backup: ${row.key}`));
+	}
+});
+const restoreInstallation = Effect.fn("Operations.restoreInstallation")(function* (options) {
+	const fs = yield* FileSystem.FileSystem;
+	const path = yield* Path.Path;
+	const crypto = yield* Crypto.Crypto;
+	if (yield* fs.exists(options.databaseFile).pipe(Effect.mapError((cause) => operationsError("sqlite.target", cause)))) return yield* operationsError("sqlite.target", /* @__PURE__ */ new Error("Restore needs a fresh database path."));
+	const raw = yield* fs.readFileString(path.join(options.directory, "manifest.json")).pipe(Effect.mapError((cause) => operationsError("manifest.read", cause)));
+	const manifest = yield* Schema.decodeEffect(Schema.fromJsonString(BackupManifest))(raw).pipe(Effect.mapError((cause) => operationsError("manifest.validate", cause)));
+	const objectsByKey = new Map(manifest.objects.map((object) => [object.key, object]));
+	if (objectsByKey.size !== manifest.objects.length) return yield* operationsError("manifest.validate", /* @__PURE__ */ new Error("Media object keys must be unique."));
+	const sqlite = path.join(options.directory, "cms.sqlite");
+	if ((yield* hashFile(fs, sqlite, "sqlite.hash")).sha256 !== manifest.sqliteSha256) return yield* operationsError("sqlite.hash", /* @__PURE__ */ new Error("The backup database checksum does not match."));
+	yield* verifyDatabase(sqlite, objectsByKey);
+	for (const object of manifest.objects) {
+		const file = yield* hashFile(fs, yield* objectPath(path, options.directory, object.key), "media.hash");
+		if (file.sha256 !== object.sha256 || file.byteSize !== object.byteSize) return yield* operationsError("media.hash", /* @__PURE__ */ new Error(`Backup media checksum does not match: ${object.key}`));
+	}
+	const existing = /* @__PURE__ */ new Set();
+	let cursor;
+	do {
+		const page = yield* options.media.list("", cursor).pipe(Effect.mapError((cause) => operationsError("media.list", cause)));
+		for (const object of page.objects) {
+			if (!objectsByKey.has(object.key)) return yield* operationsError("media.target", /* @__PURE__ */ new Error(`Target media prefix is not empty: ${object.key}`));
+			existing.add(object.key);
+		}
+		if (page.nextCursor === cursor && cursor !== void 0) return yield* operationsError("media.list", /* @__PURE__ */ new Error("Media inventory cursor did not advance."));
+		cursor = page.nextCursor;
+	} while (cursor);
+	for (const object of manifest.objects) {
+		if (!existing.has(object.key)) yield* options.media.put({
+			key: object.key,
+			byteSize: object.byteSize,
+			mimeType: object.mimeType,
+			filePath: yield* objectPath(path, options.directory, object.key)
+		}).pipe(Effect.mapError((cause) => operationsError("media.put", cause)));
+		const metadata = yield* options.media.stat(object.key).pipe(Effect.mapError((cause) => operationsError("media.stat", cause)));
+		if (!metadata) return yield* operationsError("media.missing", /* @__PURE__ */ new Error(`Restored media is unreadable: ${object.key}`));
+		const current = yield* Effect.scoped(Effect.gen(function* () {
+			const stream = yield* Effect.acquireRelease(options.media.read(object.key).pipe(Effect.mapError((cause) => operationsError("media.read", cause))), releaseStream, { interruptible: true });
+			if (!stream) return yield* operationsError("media.missing", /* @__PURE__ */ new Error(`Restored media is unreadable: ${object.key}`));
+			return yield* hashStream(stream);
+		}));
+		if (metadata.byteSize !== object.byteSize || metadata.mimeType !== object.mimeType || current.byteSize !== object.byteSize || current.sha256 !== object.sha256) return yield* operationsError("media.target", /* @__PURE__ */ new Error(`Restored media differs from backup: ${object.key}`));
+	}
+	yield* fs.makeDirectory(path.dirname(options.databaseFile), { recursive: true }).pipe(Effect.mapError((cause) => operationsError("sqlite.directory", cause)));
+	const suffix = yield* crypto.randomUUIDv4.pipe(Effect.mapError((cause) => operationsError("sqlite.copy", cause)));
+	const temporary = `${options.databaseFile}.restore-${suffix}`;
+	yield* Effect.gen(function* () {
+		yield* fs.copyFile(sqlite, temporary).pipe(Effect.mapError((cause) => operationsError("sqlite.copy", cause)));
+		if ((yield* hashFile(fs, temporary, "sqlite.copy")).sha256 !== manifest.sqliteSha256) return yield* operationsError("sqlite.copy", /* @__PURE__ */ new Error("The copied database checksum does not match."));
+		yield* Effect.gen(function* () {
+			yield* (yield* SqliteClient.SqliteClient)`UPDATE cms_revision_links SET revoked_at = ${new Date(yield* Clock.currentTimeMillis).toISOString()}, revoked_by = 'system:restore' WHERE revoked_at IS NULL`;
+		}).pipe(Effect.provide(SqliteClient.layer({
+			filename: temporary,
+			disableWAL: true
+		})), Effect.mapError((cause) => operationsError("sqlite.revision-links", cause)));
+		yield* fs.link(temporary, options.databaseFile).pipe(Effect.mapError((cause) => operationsError("sqlite.install", cause)));
+	}).pipe(Effect.ensuring(fs.remove(temporary, { force: true }).pipe(Effect.orDie)));
+	return manifest;
+});
+//#endregion
+//#region ../server/src/Operations.ts
+const platformLayer = Layer.mergeAll(NodeFileSystem.layer, NodePath.layer, NodeCrypto.layer);
+/** Run while the Nuxt process is stopped. The backup directory must not exist. */
+const backup = Effect.fn("Operations.backup")(backupInstallation, Effect.provide(platformLayer));
+/** Run while the Nuxt process is stopped, into a fresh database and media prefix. */
+const restore = Effect.fn("Operations.restore")(restoreInstallation, Effect.provide(platformLayer));
+//#endregion
+//#region src/Operations.ts
+/** Back up a stopped installation to a new directory. */
+const backupCms = Effect.fn("CmsOperations.backup")(function* (options) {
+	return yield* Effect.scoped(Effect.gen(function* () {
+		const media = Context.get(yield* Layer.build(layer(options.s3)), MediaObjects);
+		yield* media.check;
+		return yield* backup({
+			databaseFile: options.databaseFile,
+			directory: options.directory,
+			media
+		});
+	}));
+});
+/** Restore into a fresh database path and media prefix while Nuxt is stopped. */
+const restoreCms = Effect.fn("CmsOperations.restore")(function* (options) {
+	return yield* Effect.scoped(Effect.gen(function* () {
+		const media = Context.get(yield* Layer.build(layer(options.s3)), MediaObjects);
+		yield* media.check;
+		return yield* restore({
+			databaseFile: options.databaseFile,
+			directory: options.directory,
+			media
+		});
+	}));
+});
+//#endregion
+export { backupCms, restoreCms };

package/src/People-DvNZauWw.js

@@ -0,0 +1,69 @@
+import { Schema } from "effect";
+//#region ../model/src/Studio.ts
+/** A same-origin Nuxt page contributed to Studio's Tools navigation. */
+const StudioModule = Schema.Struct({
+	id: Schema.NonEmptyString,
+	label: Schema.NonEmptyString,
+	icon: Schema.NonEmptyString,
+	path: Schema.NonEmptyString,
+	access: Schema.Literals(["administrator", "signed-in"])
+});
+const reservedIds = /* @__PURE__ */ new Set([
+	"overview",
+	"content",
+	"documents",
+	"inbox",
+	"calendar",
+	"trash",
+	"media",
+	"seo",
+	"activity",
+	"people",
+	"users",
+	"account"
+]);
+/** Validates names and frame paths before they cross into the browser bundle. */
+function defineStudioModules(modules) {
+	const ids = /* @__PURE__ */ new Set();
+	return modules.map((module) => {
+		if (!/^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/u.test(module.id) || reservedIds.has(module.id) || ids.has(module.id)) throw new Error(`Studio tool ID ${JSON.stringify(module.id)} is invalid or already used.`);
+		if (!module.label.trim() || !module.icon.trim()) throw new Error(`Studio tool ${module.id} needs a label and icon.`);
+		if (!/^\/(?!\/)[a-z0-9/_-]*$/u.test(module.path) || module.path === "/_cms" || module.path.startsWith("/_cms/")) throw new Error(`Studio tool ${module.id} needs a same-origin path outside Studio.`);
+		ids.add(module.id);
+		return Schema.decodeSync(StudioModule)({
+			...module,
+			access: module.access ?? "administrator"
+		});
+	});
+}
+//#endregion
+//#region ../model/src/People.ts
+const Role = Schema.Literals([
+	"administrator",
+	"editor",
+	"viewer"
+]);
+const PersonEmail = Schema.NonEmptyString.check(Schema.isMaxLength(320), Schema.isPattern(/^[^\s@]+@[^\s@]+\.[^\s@]+$/u));
+const Person = Schema.Struct({
+	id: Schema.NonEmptyString,
+	name: Schema.NonEmptyString,
+	email: PersonEmail,
+	role: Role,
+	createdAt: Schema.String
+});
+const PeoplePage = Schema.Struct({
+	people: Schema.Array(Person),
+	total: Schema.Int.check(Schema.isGreaterThanOrEqualTo(0))
+});
+const CreatePerson = Schema.Struct({
+	name: Schema.NonEmptyString.check(Schema.isMaxLength(200)),
+	email: PersonEmail,
+	role: Role
+});
+const Invitation = Schema.Struct({
+	email: PersonEmail,
+	token: Schema.NonEmptyString,
+	expiresAt: Schema.String
+});
+//#endregion
+export { PersonEmail as a, defineStudioModules as c, Person as i, Invitation as n, Role as o, PeoplePage as r, StudioModule as s, CreatePerson as t };

package/src/PreviewFocus-C_EelZO5.js

@@ -0,0 +1,104 @@
+import { l as DocumentId } from "./Document-CKXMSEf1.js";
+import { Schema } from "effect";
+//#region ../model/src/PreviewFocus.ts
+const NodeIndex = Schema.Int.check(Schema.isBetween({
+	minimum: 0,
+	maximum: 1e5
+}));
+const FieldPathSegment = Schema.Union([Schema.Struct({
+	kind: Schema.Literal("field"),
+	name: Schema.NonEmptyString
+}), Schema.Struct({
+	kind: Schema.Literal("item"),
+	id: Schema.NonEmptyString
+})]);
+const FieldPath = Schema.Array(FieldPathSegment).check(Schema.isMinLength(1), Schema.isMaxLength(32));
+const PreviewFocusTarget = Schema.Union([
+	Schema.Struct({ kind: Schema.Literal("title") }),
+	Schema.Struct({ kind: Schema.Literal("document") }),
+	Schema.Struct({
+		kind: Schema.Literal("field"),
+		path: FieldPath
+	}),
+	Schema.Struct({
+		kind: Schema.Literal("blockField"),
+		blockId: Schema.NonEmptyString,
+		path: FieldPath
+	}),
+	Schema.Struct({
+		kind: Schema.Literal("block"),
+		blockId: Schema.NonEmptyString
+	}),
+	Schema.Struct({
+		kind: Schema.Literal("body"),
+		path: Schema.Array(NodeIndex).check(Schema.isMinLength(1), Schema.isMaxLength(16)),
+		nodeId: Schema.optionalKey(Schema.NonEmptyString),
+		blockId: Schema.optionalKey(Schema.NonEmptyString)
+	})
+]);
+const PreviewSource = Schema.Struct({
+	documentId: DocumentId,
+	target: PreviewFocusTarget,
+	approximate: Schema.Boolean
+});
+Schema.Struct({
+	type: Schema.Literal("cms-preview:activate"),
+	documentId: DocumentId,
+	target: PreviewFocusTarget,
+	approximate: Schema.optionalKey(Schema.Boolean)
+});
+Schema.Struct({
+	type: Schema.Literal("cms-preview:ready"),
+	documentId: DocumentId
+});
+Schema.Struct({
+	type: Schema.Literal("cms-preview:navigate"),
+	path: Schema.String
+});
+const StudioFocusMessage = Schema.Struct({
+	type: Schema.Literal("cms-studio:focus"),
+	documentId: DocumentId,
+	target: PreviewFocusTarget,
+	reveal: Schema.Boolean
+});
+const StudioPreviewModeMessage = Schema.Struct({
+	type: Schema.Literal("cms-studio:mode"),
+	documentId: DocumentId,
+	mode: Schema.Literals(["edit", "browse"])
+});
+/** A structural key keeps field names and item IDs unambiguous. */
+function previewTargetKey(target) {
+	if (target.kind === "body" && target.nodeId) return `node:${target.nodeId}`;
+	switch (target.kind) {
+		case "field": return JSON.stringify([target.kind, fieldPathKey(target.path)]);
+		case "blockField": return JSON.stringify([
+			target.kind,
+			target.blockId,
+			fieldPathKey(target.path)
+		]);
+		case "block": return JSON.stringify([target.kind, target.blockId]);
+		case "body": return JSON.stringify([
+			target.kind,
+			target.path,
+			target.blockId ?? null
+		]);
+		default: return target.kind;
+	}
+}
+function fieldPathKey(path) {
+	return JSON.stringify(path.map((segment) => [segment.kind, segment.kind === "field" ? segment.name : segment.id]));
+}
+function encodePreviewSource(source) {
+	return encodeURIComponent(JSON.stringify(source));
+}
+function parsePreviewSource(value) {
+	if (!value || value.length > 16384) return null;
+	try {
+		const decoded = JSON.parse(decodeURIComponent(value));
+		return Schema.is(PreviewSource)(decoded) ? decoded : null;
+	} catch {
+		return null;
+	}
+}
+//#endregion
+export { encodePreviewSource as a, StudioPreviewModeMessage as i, PreviewSource as n, parsePreviewSource as o, StudioFocusMessage as r, previewTargetKey as s, PreviewFocusTarget as t };