@yugoo-design/dsh-design-studio 0.1.2 → 0.2.2

package/lib/instance-changes-RvOGeBaE.js

@@ -0,0 +1,691 @@
+import { extname, isAbsolute, relative, resolve, sep } from "node:path";
+import { DesignBundleVersion, DesignKitVersion, compileSchema, loadDesignBundle, loadDesignKit } from "@yugoo-design/dsh-design-core";
+import { createHash } from "node:crypto";
+//#region src/load.ts
+/** Studio-owned loading of a Kit from its directory source. */
+async function loadStudioKit(fs, kitRoot, options = {}) {
+	const root = resolve(kitRoot);
+	return await loadDesignKit(fs, root, {
+		sourceId: options.sourceId ?? `directory:${root}`,
+		...options.bundles ? { resolveBundle: async (pin) => {
+			const location = options.bundles.find((entry) => entry.name === pin.name && entry.version === pin.version);
+			return location ? loadDesignBundle(fs, location, pin) : void 0;
+		} } : {}
+	});
+}
+//#endregion
+//#region src/panel-preview.ts
+/** Definition-only Panel preview preparation; never writes or runs a Bundle. */
+function failure(code, message) {
+	return { diagnostics: [{
+		code,
+		message
+	}] };
+}
+/** Shared finalization over a real Core-compiled Bundle, with optional real Kit context. */
+function finalizeStudioPanelPreview(input) {
+	const { compiled, revision, sampleSource } = input;
+	const bundle = { ...input.bundle }, kit = input.kit === void 0 ? void 0 : { ...input.kit };
+	if (!Number.isSafeInteger(revision) || revision < 0 || typeof sampleSource !== "string") return failure("preview.request", "Select an exact Bundle, text sample JSON and a non-negative editor revision.");
+	if ((compiled.catalogName ?? compiled.name) !== bundle.name) return failure("preview.bundle_pin", "The source does not match the selected Bundle version.");
+	const panelYaml = compiled.metadata?.panelYaml;
+	if (typeof panelYaml !== "string") return failure("preview.not_declarative", "Only an existing declarative Panel can be previewed.");
+	const schema = compiled.metadata?.schemaDocument;
+	if (schema === void 0) return failure("preview.definition", "The loader did not produce a declarative Panel and schema.");
+	if (new TextEncoder().encode(sampleSource).length > 262144) return failure("preview.size", "Sample JSON is limited to 256 KiB.");
+	let sample;
+	try {
+		sample = JSON.parse(sampleSource);
+	} catch {
+		return failure("preview.sample_json", "The preview sample must be valid JSON.");
+	}
+	if (sample === null || typeof sample !== "object" || Array.isArray(sample)) return failure("preview.sample_json", "The preview sample must be a JSON object.");
+	try {
+		const errors = compileSchema(schema)(sample);
+		if (errors.length > 0) return { diagnostics: errors.map((message) => ({
+			code: "preview.sample_schema",
+			message
+		})) };
+		let artifacts;
+		try {
+			const mapping = input.readSampleResource?.("reference/preview-artifacts.json");
+			if (mapping !== void 0) {
+				if (new TextEncoder().encode(mapping).length > 16384) throw new Error("Sample artifact mapping exceeds 16 KiB.");
+				const parsed = JSON.parse(mapping);
+				if (parsed?.version !== 1 || !parsed.files || typeof parsed.files !== "object" || Array.isArray(parsed.files) || Object.keys(parsed).some((key) => !["version", "files"].includes(key)) || Object.keys(parsed.files).length > 8) throw new Error("Sample artifact mapping needs version 1 and at most eight files.");
+				artifacts = Object.create(null);
+				let bytes = 0;
+				const safe = (path) => typeof path === "string" && !/[\\:\x00-\x20?#%]/u.test(path) && path.split("/").every((part) => part !== "" && ![
+					".",
+					"..",
+					"__proto__",
+					"constructor",
+					"prototype"
+				].includes(part));
+				for (const [path, resource] of Object.entries(parsed.files)) {
+					if (!safe(path) || !path.startsWith(`${compiled.name}/artifacts/`) || !/\.(?:html|svg)$/iu.test(path) || !safe(resource) || !resource.startsWith("reference/preview-artifacts/") || !/\.(?:html|svg)$/iu.test(resource)) throw new Error("Sample artifacts must map Bundle HTML/SVG paths to confined preview resources.");
+					const content = input.readSampleResource?.(resource);
+					const size = typeof content === "string" ? new TextEncoder().encode(content).length : 0;
+					if (!size || size > 262144 || (bytes += size) > 1048576) throw new Error("Sample artifact missing or exceeds the 256 KiB file / 1 MiB total limit.");
+					artifacts[path] = content;
+				}
+			}
+		} catch (error) {
+			return failure("preview.sample_artifacts", error instanceof Error ? error.message : String(error));
+		}
+		return {
+			preview: {
+				revision,
+				...kit === void 0 ? {} : { kit },
+				bundle,
+				panelYaml,
+				sample,
+				...artifacts === void 0 ? {} : { artifacts }
+			},
+			diagnostics: []
+		};
+	} catch (error) {
+		return failure("preview.definition", error instanceof Error ? error.message : String(error));
+	}
+}
+/**
+* Compile one Panel edit against an exact, host-resolved Kit snapshot.
+*
+* The host must supply an immutable/read-confined source port and root for the
+* selected pin, not arbitrary browser paths or a mutable production project.
+* Only panel.yaml is overlaid. All schemas, methods, locales and renderer
+* contracts still come from that snapshot and pass through the runtime loader.
+* The returned sample is fresh JSON and can be edited in a sandboxed preview;
+* this function grants no artifact, filesystem, model or publication authority.
+* A preview consumer must discard a result if its editor revision has changed.
+*/
+async function prepareStudioPanelPreview(source, kitRoot, request, loadOptions = {}) {
+	const { panelSource, sampleSource, revision } = request;
+	const kitPin = { ...request.kit };
+	const bundlePin = { ...request.bundle };
+	if (!isAbsolute(kitRoot) || !/^[a-z][a-z0-9_]*$/.test(bundlePin.name) || !Number.isSafeInteger(revision) || revision < 0 || typeof panelSource !== "string" || typeof sampleSource !== "string") return failure("preview.request", "Select an exact Bundle and a non-negative editor revision.");
+	if (new TextEncoder().encode(panelSource).length > 1048576 || new TextEncoder().encode(sampleSource).length > 262144) return failure("preview.size", "Panel source is limited to 1 MiB and sample JSON to 256 KiB.");
+	let sample;
+	try {
+		sample = JSON.parse(sampleSource);
+	} catch {
+		return failure("preview.sample_json", "The preview sample must be valid JSON.");
+	}
+	if (sample === null || typeof sample !== "object" || Array.isArray(sample)) return failure("preview.sample_json", "The preview sample must be a JSON object.");
+	try {
+		const base = await loadStudioKit(source, kitRoot, loadOptions);
+		if (base.name !== kitPin.name) return failure("preview.kit_pin", "The source does not match the selected Kit version.");
+		const bundle = base.skills.find((skill) => (skill.catalogName ?? skill.name) === bundlePin.name);
+		if (bundle === void 0) return failure("preview.bundle_pin", "The source does not match the selected Bundle version.");
+		if (typeof bundle.metadata?.panelYaml !== "string") return failure("preview.not_declarative", "Only an existing declarative Panel can be edited in this preview.");
+		const panelPath = resolve(bundle.resourceRoot ?? resolve(kitRoot, "skills", bundle.name), "panel.yaml");
+		const candidate = await loadStudioKit({
+			readText: (path) => resolve(path) === panelPath ? Promise.resolve(panelSource) : source.readText(path),
+			...source.readResource ? { readResource: (path) => resolve(path) === panelPath ? Promise.resolve({
+				kind: "text",
+				content: panelSource
+			}) : source.readResource(path) } : {},
+			listDir: (path) => source.listDir(path),
+			...source.isDirectory ? { isDirectory: (path) => source.isDirectory(path) } : {},
+			...source.realPath ? { realPath: (path) => source.realPath(path) } : {}
+		}, kitRoot, loadOptions);
+		const compiled = candidate.skills.find((skill) => (skill.catalogName ?? skill.name) === bundlePin.name);
+		if (compiled === void 0) return failure("preview.bundle_pin", "The source does not match the selected Bundle version.");
+		return finalizeStudioPanelPreview({
+			compiled,
+			revision,
+			kit: kitPin,
+			bundle: bundlePin,
+			sampleSource,
+			readSampleResource: (path) => candidate.resources[`${compiled.name}/${path}`]
+		});
+	} catch (error) {
+		return failure("preview.definition", error instanceof Error ? error.message : String(error));
+	}
+}
+//#endregion
+//#region src/content-archive.ts
+/** Portable regular-file content, not a plugin installer or publication format. */
+const MAX_BYTES = 16777216;
+const MAX_JSON = 33554432;
+const MAX_FILES = 4096;
+const HASH = /^[0-9a-f]{64}$/;
+const sha = (value) => createHash("sha256").update(value).digest("hex");
+const OPAQUE_RESOURCE_EXTENSIONS = /* @__PURE__ */ new Set([
+	".bin",
+	".png",
+	".jpg",
+	".jpeg",
+	".gif",
+	".webp",
+	".avif",
+	".ico",
+	".bmp",
+	".pdf",
+	".woff",
+	".woff2",
+	".ttf",
+	".otf",
+	".eot",
+	".wasm"
+]);
+/** Shared by archive capture and virtual import; full bytes and directory entries remain intact. */
+function readStudioArchiveResource(path, bytes) {
+	return OPAQUE_RESOURCE_EXTENSIONS.has(extname(path).toLowerCase()) ? {
+		kind: "opaque",
+		byteLength: bytes.byteLength
+	} : {
+		kind: "text",
+		content: new TextDecoder("utf-8", { fatal: true }).decode(bytes)
+	};
+}
+function object(value) {
+	if (!value || typeof value !== "object" || Array.isArray(value)) throw Error("Invalid archive object.");
+	return value;
+}
+function keys(value, allowed) {
+	if (Object.keys(value).length !== allowed.length || allowed.some((key) => !Object.hasOwn(value, key))) throw Error("Unknown or missing archive fields.");
+}
+function text(value, limit) {
+	if (typeof value !== "string" || !value.trim() || Buffer.byteLength(value) > limit || /[\u0000-\u001f\u007f]/u.test(value)) throw Error("Invalid archive metadata text.");
+	return value;
+}
+function metadataText(value) {
+	if (typeof value !== "string" || Buffer.byteLength(value) > 2048) throw Error("Invalid archive metadata text.");
+	return value;
+}
+function pin(value, kind) {
+	const data = object(value);
+	keys(data, ["name", "version"]);
+	const name = text(data.name, 128), version = text(data.version, 32);
+	if (!/^[a-z][a-z0-9_]*$/.test(name)) throw Error("Unsupported archive content identity.");
+	safePath(name);
+	safePath(version);
+	if (kind === "kit") DesignKitVersion(version);
+	else DesignBundleVersion(version);
+	return Object.freeze({
+		name,
+		version
+	});
+}
+function safePath(value) {
+	const path = text(value, 1024);
+	if (path !== path.normalize("NFC") || /[\\:*?"<>|]/u.test(path)) throw Error("Unsafe archive path.");
+	if (/\.(exe|dll|node|so|dylib|com|msi|sys)$/iu.test(path)) throw Error("Native executable payload propagation is unsupported.");
+	for (const part of path.split("/")) if (!part || part === "." || part === ".." || [".git", "node_modules"].includes(part.toLowerCase()) || /[. ]$/u.test(part) || /^(con|prn|aux|nul|com[1-9¹²³]|lpt[1-9¹²³])(?:\.|$)/iu.test(part)) throw Error("Unsafe archive path.");
+	return path;
+}
+function canonical(data) {
+	return JSON.stringify(data);
+}
+/** Parse a bounded JSON envelope; hashes include metadata and every original byte. */
+function readStudioContentArchive(source) {
+	if (typeof source !== "string" || Buffer.byteLength(source) > MAX_JSON) throw Error("Archive JSON exceeds 32 MiB.");
+	const raw = object(JSON.parse(source));
+	keys(raw, [
+		"format",
+		"kind",
+		"pin",
+		...Object.hasOwn(raw, "title") ? ["title"] : [],
+		...Object.hasOwn(raw, "provenance") ? ["provenance"] : [],
+		"dependencies",
+		"files",
+		"sha256"
+	]);
+	if (raw.format !== "studio-content-archive/v1" || raw.kind !== "kit" && raw.kind !== "bundle") throw Error("Unsupported archive format.");
+	const identity = pin(raw.pin, raw.kind);
+	let title;
+	if (raw.title !== void 0) {
+		const names = object(raw.title);
+		keys(names, ["zh", "en"]);
+		title = Object.freeze({
+			zh: text(names.zh, 800),
+			en: text(names.en, 800)
+		});
+		if (title.zh.length > 200 || title.en.length > 200) throw Error("Archive display title exceeds 200 characters.");
+	}
+	let origin;
+	if (raw.provenance !== void 0) {
+		const provenance = object(raw.provenance);
+		keys(provenance, ["source", "license"].filter((key) => Object.hasOwn(provenance, key)));
+		origin = Object.freeze({
+			...provenance.source === void 0 ? {} : { source: metadataText(provenance.source) },
+			...provenance.license === void 0 ? {} : { license: metadataText(provenance.license) }
+		});
+	}
+	if (!Array.isArray(raw.dependencies) || raw.dependencies.length > MAX_FILES) throw Error("Invalid archive dependencies.");
+	const dependencies = raw.dependencies.map((value) => pin(value, "bundle"));
+	const names = /* @__PURE__ */ new Set();
+	for (const dependency of dependencies) {
+		if (names.has(dependency.name) || raw.kind === "bundle" && dependency.name === identity.name) throw Error("Duplicate or self archive dependency.");
+		names.add(dependency.name);
+	}
+	if (!Array.isArray(raw.files) || !raw.files.length || raw.files.length > MAX_FILES) throw Error("Invalid archive file count.");
+	let total = 0;
+	const paths = /* @__PURE__ */ new Map();
+	const prefixes = /* @__PURE__ */ new Map();
+	const directories = /* @__PURE__ */ new Set();
+	const files = raw.files.map((value) => {
+		const entry = object(value);
+		keys(entry, [
+			"path",
+			"base64",
+			"bytes",
+			"sha256"
+		]);
+		const path = safePath(entry.path), folded = path.toLowerCase();
+		const segments = path.split("/");
+		for (let index = 1; index <= segments.length; index++) {
+			const prefix = segments.slice(0, index).join("/"), foldedPrefix = prefix.toLowerCase();
+			if (prefixes.has(foldedPrefix) && prefixes.get(foldedPrefix) !== prefix) throw Error("Case-conflicting archive path segments.");
+			prefixes.set(foldedPrefix, prefix);
+		}
+		if (paths.has(folded)) throw Error("Duplicate or case-conflicting archive paths.");
+		paths.set(folded, path);
+		const parts = folded.split("/");
+		parts.pop();
+		while (parts.length) {
+			directories.add(parts.join("/"));
+			parts.pop();
+		}
+		if (!Number.isSafeInteger(entry.bytes) || entry.bytes < 0 || entry.bytes > MAX_BYTES - total) throw Error("Archive content exceeds 16 MiB or has an invalid byte count.");
+		if (typeof entry.base64 !== "string" || entry.base64.length > Math.ceil(MAX_BYTES / 3) * 4 || entry.base64.length % 4 || !/^[A-Za-z0-9+/]*={0,2}$/u.test(entry.base64)) throw Error("Invalid archive base64.");
+		const bytes = Buffer.from(entry.base64, "base64");
+		if (bytes.toString("base64") !== entry.base64 || entry.bytes !== bytes.length || typeof entry.sha256 !== "string" || !HASH.test(entry.sha256) || sha(bytes) !== entry.sha256) throw Error("Archive file integrity mismatch.");
+		total += bytes.length;
+		if (total > MAX_BYTES) throw Error("Archive content exceeds 16 MiB.");
+		return Object.freeze({
+			path,
+			base64: entry.base64,
+			bytes: bytes.length,
+			sha256: entry.sha256
+		});
+	}).sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0);
+	if ([...directories].some((path) => paths.has(path))) throw Error("Archive file/directory collision.");
+	const data = {
+		format: raw.format,
+		kind: raw.kind,
+		pin: identity,
+		...title === void 0 ? {} : { title },
+		...origin === void 0 ? {} : { provenance: origin },
+		dependencies: Object.freeze(dependencies),
+		files: Object.freeze(files)
+	};
+	if (typeof raw.sha256 !== "string" || !HASH.test(raw.sha256) || sha(canonical(data)) !== raw.sha256) throw Error("Archive envelope integrity mismatch.");
+	return Object.freeze({
+		...data,
+		sha256: raw.sha256
+	});
+}
+/** Pure virtual source: explicit text reads stay strict; attached byte assets remain opaque. */
+function virtualSource(files, root) {
+	const map = new Map(files.map((file) => [file.path, file.base64]));
+	const key = (path) => {
+		const result = relative(root, resolve(path));
+		if (isAbsolute(result) || result === ".." || result.startsWith(`..${sep}`)) throw Error("Archive validation path escapes source.");
+		return result.split(sep).join("/");
+	};
+	const children = (path) => {
+		const prefix = key(path);
+		const head = prefix ? `${prefix}/` : "";
+		return [...new Set([...map.keys()].filter((file) => file.startsWith(head)).map((file) => file.slice(head.length).split("/")[0]))].sort();
+	};
+	return {
+		async readText(path) {
+			const content = map.get(key(path));
+			return content === void 0 ? void 0 : new TextDecoder("utf-8", { fatal: true }).decode(Buffer.from(content, "base64"));
+		},
+		async readResource(path) {
+			const content = map.get(key(path));
+			return content === void 0 ? void 0 : readStudioArchiveResource(path, Buffer.from(content, "base64"));
+		},
+		async listDir(path) {
+			return children(path);
+		},
+		async isDirectory(path) {
+			return children(path).length > 0;
+		},
+		async realPath(path) {
+			key(path);
+			return resolve(path);
+		}
+	};
+}
+const bundlePin = (skill) => ({
+	name: skill.catalogName ?? skill.name,
+	version: String(skill.version)
+});
+const samePin = (left, right) => left.name === right.name && left.version === right.version;
+const bundlePrefix = (identity) => `bundles/${identity.name}/${identity.version}/`;
+const within = (root, path) => {
+	const rel = relative(root, resolve(path));
+	return !isAbsolute(rel) && rel !== ".." && !rel.startsWith(`..${sep}`);
+};
+/** All reads dispatch to captured bytes; there is no live filesystem fallback. */
+function sourceView(snapshot) {
+	const bundles = snapshot.bundles ?? [];
+	const sources = [...bundles.map((bundle) => bundle.snapshot), snapshot].sort((a, b) => b.root.length - a.root.length);
+	const owner = (path) => {
+		const source = sources.find((source) => within(source.root, path));
+		if (!source) throw Error("Archive validation path escapes captured sources.");
+		return source;
+	};
+	return {
+		fs: {
+			readText: (path) => owner(path).fs.readText(path),
+			async readResource(path) {
+				const source = owner(path);
+				if (typeof source.readBytes === "function") return readStudioArchiveResource(path, await source.readBytes(path));
+				if (source.fs.readResource) return source.fs.readResource(path);
+				const content = await source.fs.readText(path);
+				return content === void 0 ? void 0 : {
+					kind: "text",
+					content
+				};
+			},
+			listDir: (path) => owner(path).fs.listDir(path),
+			async isDirectory(path) {
+				const source = owner(path);
+				return source.fs.isDirectory ? source.fs.isDirectory(path) : (await source.fs.listDir(path)).length > 0;
+			},
+			async realPath(path) {
+				const source = owner(path);
+				return source.fs.realPath ? source.fs.realPath(path) : resolve(path);
+			}
+		},
+		options: {
+			sourceId: snapshot.sourceId,
+			bundles: bundles.map((bundle) => ({
+				name: bundle.name,
+				version: bundle.version,
+				rootDir: bundle.snapshot.root,
+				sourceId: bundle.sourceId
+			}))
+		}
+	};
+}
+function archiveSnapshot(archive) {
+	const root = resolve("/studio-content-archive-virtual");
+	const sourceId = `archive:untrusted:${archive.sha256}`;
+	const independent = archive.kind === "kit" && archive.files.some((file) => file.path === "kit.yaml");
+	const filesAt = (files, root) => {
+		const fs = virtualSource(files, root);
+		return {
+			root,
+			sourceId,
+			fs,
+			async listFiles() {
+				return files.map((file) => file.path);
+			},
+			async readBytes(path) {
+				const file = files.find((file) => resolve(root, file.path) === resolve(path));
+				if (!file) throw Error("Missing archive source file.");
+				return Buffer.from(file.base64, "base64");
+			}
+		};
+	};
+	if (!independent) return filesAt(archive.files, root);
+	const bundleFiles = /* @__PURE__ */ new Set();
+	const bundles = archive.dependencies.map((identity) => {
+		const prefix = bundlePrefix(identity);
+		const files = archive.files.filter((file) => file.path.startsWith(prefix)).map((file) => {
+			bundleFiles.add(file.path);
+			return Object.freeze({
+				...file,
+				path: file.path.slice(prefix.length)
+			});
+		});
+		if (!files.length) throw Error(`Archive is missing exact Bundle content: ${identity.name}@${identity.version}`);
+		return {
+			...identity,
+			sourceId,
+			snapshot: filesAt(files, resolve(root, prefix))
+		};
+	});
+	if (archive.files.some((file) => file.path.startsWith("bundles/") && !bundleFiles.has(file.path))) throw Error("Archive contains unreferenced Bundle content.");
+	return {
+		...filesAt(archive.files.filter((file) => !bundleFiles.has(file.path)), root),
+		bundles
+	};
+}
+/** No writes, extraction, permission restoration, script execution, installation or publication. */
+async function prepareStudioContentImport(source, options = {}) {
+	const archive = readStudioContentArchive(source);
+	let validation;
+	let contents = Object.freeze([]);
+	let requiresTrustReview = archive.files.some((file) => /\.(m?js|cjs|[cm]?tsx?|sh|ps1|cmd|bat|py|wasm)$/iu.test(file.path));
+	try {
+		const snapshot = archiveSnapshot(archive), view = sourceView(snapshot);
+		const selected = [];
+		if (archive.kind === "kit") {
+			const kit = await loadStudioKit(view.fs, snapshot.root, view.options);
+			selected.push(...kit.skills);
+			if (kit.name !== archive.pin.name || String(kit.version) !== archive.pin.version) throw Error("Archive Kit identity disagrees with source.");
+			if (JSON.stringify(kit.skills.map(bundlePin)) !== JSON.stringify(archive.dependencies)) throw Error("Archive Kit member pins disagree with source.");
+			if (snapshot.bundles) {
+				const kitFiles = archive.files.filter((file) => !file.path.startsWith("bundles/"));
+				contents = Object.freeze([Object.freeze({
+					kind: "kit",
+					pin: archive.pin,
+					files: Object.freeze(kitFiles)
+				}), ...snapshot.bundles.map((bundle) => Object.freeze({
+					kind: "bundle",
+					pin: Object.freeze({
+						name: bundle.name,
+						version: bundle.version
+					}),
+					files: Object.freeze(archive.files.filter((file) => file.path.startsWith(bundlePrefix(bundle))).map((file) => Object.freeze({
+						...file,
+						path: file.path.slice(bundlePrefix(bundle).length)
+					})))
+				}))]);
+			} else contents = Object.freeze([Object.freeze({
+				kind: "kit",
+				pin: archive.pin,
+				files: archive.files
+			})]);
+		} else {
+			const bundle = await loadDesignBundle(snapshot.fs, {
+				rootDir: snapshot.root,
+				sourceId: snapshot.sourceId
+			}, archive.pin);
+			selected.push(bundle.skill);
+			const context = options.validationContext;
+			if (archive.dependencies.length && (!context || !isAbsolute(context.root))) throw Error("Independent Bundle dependency validation requires a host-resolved immutable Kit context.");
+			if (context) {
+				if (!isAbsolute(context.root)) throw Error("Archive context must have a host-resolved absolute root.");
+				const contextView = sourceView(context);
+				const kit = await loadStudioKit(contextView.fs, context.root, contextView.options);
+				if (archive.dependencies.some((dependency) => !kit.skills.some((skill) => samePin(bundlePin(skill), dependency)))) throw Error("Archive Bundle dependency is unresolved in context.");
+				const existing = kit.skills.find((skill) => samePin(bundlePin(skill), archive.pin));
+				if (existing?.resourceRoot) {
+					const local = virtualSource(archive.files, existing.resourceRoot);
+					const owns = (path) => within(existing.resourceRoot, path);
+					await loadStudioKit({
+						readText: (path) => owns(path) ? local.readText(path) : contextView.fs.readText(path),
+						readResource: (path) => owns(path) ? local.readResource(path) : contextView.fs.readResource(path),
+						listDir: (path) => owns(path) ? local.listDir(path) : contextView.fs.listDir(path),
+						async isDirectory(path) {
+							return owns(path) ? local.isDirectory(path) : contextView.fs.isDirectory(path);
+						},
+						async realPath(path) {
+							return owns(path) ? resolve(path) : contextView.fs.realPath(path);
+						}
+					}, context.root, contextView.options);
+				}
+			}
+			contents = Object.freeze([Object.freeze({
+				kind: "bundle",
+				pin: archive.pin,
+				files: archive.files
+			})]);
+		}
+		requiresTrustReview ||= selected.some((skill) => {
+			const manifest = skill.metadata?.skillManifest;
+			const rules = skill.metadata?.validationDocument;
+			return manifest?.presentation?.mode === "native" || !!rules?.rules?.some((rule) => typeof rule.check?.driver === "string");
+		});
+		validation = Object.freeze({
+			valid: true,
+			diagnostics: Object.freeze([])
+		});
+	} catch (error) {
+		contents = Object.freeze([]);
+		validation = Object.freeze({
+			valid: false,
+			diagnostics: Object.freeze([Object.freeze({
+				code: "archive.definition",
+				message: error instanceof Error ? error.message : String(error),
+				subject: archive.pin.name
+			})])
+		});
+	}
+	return Object.freeze({
+		archive,
+		files: archive.files,
+		contents,
+		executionGranted: false,
+		requiresTrustReview,
+		validation
+	});
+}
+/** Capture only immutable host snapshots, preserving full exact referenced trees. */
+function exportStudioContentArchive(snapshot, input) {
+	return exportArchive(snapshot, input, true);
+}
+/** Capture saved source bytes, including incomplete working copies, without definition validation. */
+function exportStudioSourceArchive(snapshot, input) {
+	return exportArchive(snapshot, input, false);
+}
+async function exportArchive(snapshot, input, validateDefinition) {
+	const request = JSON.parse(JSON.stringify(input));
+	if (!isAbsolute(snapshot.root)) throw Error("Archive source root must be host-resolved absolute.");
+	const standalone = snapshot.bundle !== void 0;
+	if (standalone && (request.kind !== "bundle" || !samePin(snapshot.bundle, request.pin))) throw Error("Standalone Bundle snapshot pin disagrees with export.");
+	const view = validateDefinition ? sourceView(snapshot) : void 0;
+	const kit = !validateDefinition || standalone ? void 0 : await loadStudioKit(view.fs, snapshot.root, view.options);
+	const selected = !validateDefinition ? void 0 : standalone ? (await loadDesignBundle(view.fs, {
+		rootDir: snapshot.root,
+		sourceId: snapshot.sourceId ?? "studio:exact-instance"
+	}, request.pin)).skill : request.kind === "kit" ? kit : kit.skills.find((skill) => samePin(bundlePin(skill), request.pin));
+	if (validateDefinition && (!selected || !samePin(request.kind === "kit" ? {
+		name: selected.name,
+		version: String(selected.version)
+	} : bundlePin(selected), request.pin))) throw Error("Export pin disagrees with snapshot.");
+	const files = [];
+	let total = 0;
+	const append = async (source, prefix, selectPrefix = "") => {
+		const all = await source.listFiles();
+		if (all.length > MAX_FILES) throw Error("Snapshot file count exceeds 4096.");
+		for (const path of [...all].sort()) {
+			safePath(path);
+			if (selectPrefix && !path.startsWith(selectPrefix)) continue;
+			const target = prefix + path.slice(selectPrefix.length);
+			safePath(target);
+			const bytes = await source.readBytes(resolve(source.root, path));
+			total += bytes.byteLength;
+			if (total > MAX_BYTES || files.length >= MAX_FILES) throw Error("Archive content exceeds 16 MiB or 4096 files.");
+			files.push({
+				path: target,
+				base64: Buffer.from(bytes).toString("base64"),
+				bytes: bytes.byteLength,
+				sha256: sha(bytes)
+			});
+		}
+	};
+	if (!validateDefinition) {
+		await append(snapshot, "");
+		if (request.kind === "kit") for (const bundle of snapshot.bundles ?? []) await append(bundle.snapshot, bundlePrefix(bundle));
+	} else if (standalone) await append(snapshot, "");
+	else if (snapshot.bundles) {
+		const referenced = kit.skills.map((skill) => {
+			const identity = bundlePin(skill), matches = snapshot.bundles.filter((bundle) => samePin(bundle, identity));
+			if (matches.length !== 1) throw Error("Missing or ambiguous exact Bundle snapshot.");
+			return matches[0];
+		});
+		if (request.kind === "kit") {
+			if ((await snapshot.listFiles()).some((path) => path === "bundles" || path.startsWith("bundles/"))) throw Error("Kit-owned files collide with archive Bundle transport paths.");
+			await append(snapshot, "");
+			for (const bundle of referenced) await append(bundle.snapshot, bundlePrefix(bundle));
+		} else await append(referenced.find((bundle) => samePin(bundle, request.pin)).snapshot, "");
+	} else await append(snapshot, "", request.kind === "bundle" ? `skills/${selected.name}/` : "");
+	files.sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0);
+	const data = {
+		format: "studio-content-archive/v1",
+		kind: request.kind,
+		pin: request.pin,
+		...request.title === void 0 ? {} : { title: {
+			zh: request.title.zh,
+			en: request.title.en
+		} },
+		...request.provenance === void 0 ? {} : { provenance: request.provenance },
+		dependencies: request.kind === "kit" && validateDefinition ? kit.skills.map(bundlePin) : request.dependencies ?? (request.kind === "kit" ? snapshot.bundles?.map((bundle) => ({
+			name: bundle.name,
+			version: bundle.version
+		})) ?? [] : []),
+		files
+	};
+	if (validateDefinition && request.kind === "kit" && request.dependencies !== void 0 && JSON.stringify(request.dependencies) !== JSON.stringify(data.dependencies)) throw Error("Explicit Kit pins disagree with source membership.");
+	const serialized = JSON.stringify({
+		...data,
+		sha256: sha(canonical(data))
+	});
+	if (!validateDefinition) {
+		readStudioContentArchive(serialized);
+		return serialized;
+	}
+	const prepared = await prepareStudioContentImport(serialized, { validationContext: standalone ? void 0 : snapshot });
+	if (!prepared.validation.valid) throw Error(prepared.validation.diagnostics[0].message);
+	return serialized;
+}
+//#endregion
+//#region src/instance-changes.ts
+const STUDIO_INSTANCE_CHANGE_LIMITS = Object.freeze({
+	files: 64,
+	fileBytes: 1048576,
+	totalBytes: 4194304,
+	diffBytes: 8388608,
+	sampleBytes: 262144
+});
+/** Copy before any asynchronous host work so callers cannot mutate an in-flight edit. */
+function normalizeStudioInstanceChanges(value) {
+	const { files, fileBytes, totalBytes, sampleBytes } = STUDIO_INSTANCE_CHANGE_LIMITS;
+	if (!value || typeof value.id !== "string" || !value.id || value.id.length > 128 || !Number.isSafeInteger(value.expectedRevision) || value.expectedRevision < 0 || value.expectedRevision >= Number.MAX_SAFE_INTEGER || !Array.isArray(value.changes) || !value.changes.length || value.changes.length > files) throw new Error(`Select an instance revision and 1–${files} file changes.`);
+	const seen = /* @__PURE__ */ new Set(), encoder = new TextEncoder();
+	let bytes = 0;
+	const changes = value.changes.map((change) => {
+		const { path, content } = change ?? {};
+		if (typeof path !== "string" || !path || path.length > 1024 || /[\\:\u0000-\u001f\u007f]/u.test(path) || path.split("/").length > 32 || path.split("/").some((part) => !part || [
+			".",
+			"..",
+			".git",
+			"node_modules",
+			"__proto__",
+			"constructor",
+			"prototype"
+		].includes(part)) || seen.has(path)) throw new Error("Invalid or duplicate instance source path.");
+		seen.add(path);
+		if (content !== null && (typeof content !== "string" || content.length > fileBytes || !content.isWellFormed() || content.includes("\0") || encoder.encode(content).length > fileBytes)) throw new Error("Source must be UTF-8 text of at most 1 MiB per file.");
+		bytes += encoder.encode(path).length + (content === null ? 0 : encoder.encode(content).length);
+		if (bytes > totalBytes) throw new Error("Instance changes exceed the 4 MiB total text budget.");
+		return Object.freeze({
+			path,
+			content
+		});
+	});
+	if (value.sampleSource !== void 0 && (typeof value.sampleSource !== "string" || value.sampleSource.length > sampleBytes || !value.sampleSource.isWellFormed() || encoder.encode(value.sampleSource).length > sampleBytes)) throw new Error("Isolated preview sample must be UTF-8 JSON text of at most 256 KiB.");
+	const bundle = value.bundle;
+	if (bundle !== void 0 && (typeof bundle.name !== "string" || !/^[a-zA-Z0-9][a-zA-Z0-9_.-]*$/.test(bundle.name) || typeof bundle.version !== "string" || !/^\d+\.\d+$/.test(bundle.version))) throw new Error("Select an exact preview Bundle pin.");
+	return Object.freeze({
+		id: value.id,
+		expectedRevision: value.expectedRevision,
+		changes: Object.freeze(changes),
+		...bundle ? { bundle: Object.freeze({
+			name: bundle.name,
+			version: bundle.version
+		}) } : {},
+		...value.sampleSource === void 0 ? {} : { sampleSource: value.sampleSource }
+	});
+}
+//#endregion
+export { readStudioArchiveResource as a, prepareStudioPanelPreview as c, exportStudioSourceArchive as i, loadStudioKit as l, normalizeStudioInstanceChanges as n, readStudioContentArchive as o, exportStudioContentArchive as r, finalizeStudioPanelPreview as s, STUDIO_INSTANCE_CHANGE_LIMITS as t };