yugoo-design 0.1.2 → 0.2.0

package/payload/shared/scripts/studio-CS5TyoYn.mjs

@@ -0,0 +1,868 @@
+import { Pt as require_dist } from "./core-entry-DESmwP78.mjs";
+import { t as loadStudioKit } from "./load-C-RwS23Y.mjs";
+import { r as readStudioContentArchive } from "./content-archive-CnwVcuWA.mjs";
+import { t as finalizeStudioPanelPreview } from "./panel-preview-BeVRYFk1.mjs";
+import { isAbsolute, join, relative, resolve, sep } from "node:path";
+import { lstat, readFile, readdir, realpath } from "node:fs/promises";
+//#region packages/studio/src/composition.ts
+var import_dist = require_dist();
+function pinKey(name, version) {
+	return `${name}\u0000${version}`;
+}
+function comparePins(left, right) {
+	if (left.name !== right.name) return left.name < right.name ? -1 : 1;
+	if (left.version === right.version) return 0;
+	return left.version < right.version ? -1 : 1;
+}
+/**
+* Derive the flat searchable Bundle catalog and reverse dependencies.
+* @param snapshot - authoritative Core-compiled installed catalog snapshot.
+* @returns a frozen derived catalog; identical Bundle pins are coalesced.
+*/
+function buildStudioCompositionCatalog(snapshot) {
+	const entries = /* @__PURE__ */ new Map();
+	const kits = [];
+	for (const bundle of snapshot.bundles ?? []) {
+		const key = pinKey(bundle.name, bundle.version);
+		if (entries.has(key)) throw new Error(`studio.duplicate_bundle: ${bundle.name}@${bundle.version}`);
+		entries.set(key, {
+			bundle,
+			usedBy: []
+		});
+	}
+	for (const kit of snapshot.kits) {
+		const kitPin = Object.freeze({
+			name: kit.name,
+			version: kit.version
+		});
+		kits.push(kitPin);
+		for (const bundle of kit.bundles) {
+			const key = pinKey(bundle.name, bundle.version);
+			const current = entries.get(key);
+			if (current === void 0 && snapshot.bundles !== void 0) throw new Error(`studio.missing_bundle: ${kit.name}@${kit.version} references ${bundle.name}@${bundle.version}`);
+			if (current === void 0) entries.set(key, {
+				bundle,
+				usedBy: [kitPin]
+			});
+			else current.usedBy.push(kitPin);
+		}
+	}
+	const bundles = [...entries.values()].map(({ bundle, usedBy }) => Object.freeze({
+		name: bundle.name,
+		version: bundle.version,
+		definition: bundle.definition,
+		usedBy: Object.freeze([...usedBy].sort(comparePins))
+	})).sort(comparePins);
+	return Object.freeze({
+		bundles: Object.freeze(bundles),
+		kits: Object.freeze(kits.sort(comparePins))
+	});
+}
+/**
+* Search Bundle name and description in deterministic catalog order.
+* @param catalog - derived flat catalog.
+* @param query - case-insensitive trimmed text; empty returns the full catalog.
+* @returns matching immutable catalog entries.
+*/
+function searchStudioBundles(catalog, query) {
+	const normalized = query.trim().toLowerCase();
+	if (normalized === "") return catalog.bundles;
+	return Object.freeze(catalog.bundles.filter((entry) => entry.name.toLowerCase().includes(normalized) || entry.definition.description.toLowerCase().includes(normalized) || Object.values(entry.definition.title ?? {}).some((text) => text.toLowerCase().includes(normalized)) || Object.values(entry.definition.pickerDescription ?? {}).some((text) => text.toLowerCase().includes(normalized))));
+}
+//#endregion
+//#region packages/studio/src/management.ts
+function utf8ByteLength$1(text) {
+	return new TextEncoder().encode(text).length;
+}
+/**
+* JSON-facing read-only Kit catalog and workspace inspection over the
+* authoritative Core-compiled catalog. The Studio never mutates installed
+* content: source files and the Design Core loader remain the only authorities.
+*/
+var StudioManagementService = class {
+	#catalog;
+	/** @param catalog - current authoritative installed Kit snapshot provider. */
+	constructor(catalog) {
+		this.#catalog = catalog;
+	}
+	/**
+	* Build a detached, frozen, JSON-only browser view.
+	* @param query - optional Bundle name/description search.
+	* @returns current published Kit pins and the searched Bundle catalog.
+	*/
+	async workspace(query = "") {
+		const snapshot = await this.#catalog.snapshot();
+		const composition = buildStudioCompositionCatalog(snapshot);
+		const normalizedQuery = query.trim();
+		const kits = Object.freeze(composition.kits.map((kit) => {
+			const definition = snapshot.kits.find((entry) => entry.name === kit.name && entry.version === kit.version).definition;
+			return Object.freeze({
+				name: kit.name,
+				version: kit.version,
+				...definition.description === void 0 ? {} : { description: definition.description },
+				...definition.pickerDescription ? { displayDescription: Object.freeze({ ...definition.pickerDescription }) } : {}
+			});
+		}));
+		const bundles = Object.freeze(searchStudioBundles(composition, normalizedQuery).map((bundle) => Object.freeze({
+			name: bundle.name,
+			version: bundle.version,
+			description: bundle.definition.description,
+			...bundle.definition.title ? { title: Object.freeze({ ...bundle.definition.title }) } : {},
+			...bundle.definition.pickerDescription ? { displayDescription: Object.freeze({ ...bundle.definition.pickerDescription }) } : {},
+			usedBy: Object.freeze(bundle.usedBy.map((kit) => Object.freeze({
+				name: kit.name,
+				version: kit.version
+			})))
+		})));
+		return Object.freeze({
+			query: normalizedQuery,
+			kits,
+			bundles
+		});
+	}
+	/**
+	* Read the Kit workspace view model for one exact installed Kit version.
+	*
+	* The view is JSON-only: the complete raw mindset.md source is exposed for
+	* reading, mounts carry exact version pins plus their reverse Kit
+	* references, and resources project only the paths the Core loader compiled
+	* into the version. No Core-compiled definition object crosses into the view.
+	* @param name - the Kit id.
+	* @param version - exact installed Kit version.
+	* @returns the frozen workspace view, or resolution diagnostics.
+	*/
+	async readKitWorkspace(name, version) {
+		const snapshot = await this.#catalog.snapshot();
+		const entry = snapshot.kits.find((kit) => kit.name === name && kit.version === version);
+		if (entry === void 0) {
+			const installed = snapshot.kits.filter((kit) => kit.name === name).map((kit) => kit.version);
+			if (installed.length === 0) return Object.freeze({ diagnostics: Object.freeze([Object.freeze({
+				code: "workspace.kit_missing",
+				message: `Kit ${JSON.stringify(name)} is not installed`,
+				subject: name
+			})]) });
+			return Object.freeze({ diagnostics: Object.freeze([Object.freeze({
+				code: "workspace.version_missing",
+				message: `Kit ${JSON.stringify(name)} version ${JSON.stringify(version)} is not installed; the installed versions are ${installed.map((candidate) => JSON.stringify(candidate)).join(", ")}`,
+				subject: version
+			})]) });
+		}
+		const definition = entry.definition;
+		const mounts = Object.freeze(entry.bundles.map((bundle) => Object.freeze({
+			name: bundle.name,
+			version: bundle.version,
+			description: bundle.definition.description,
+			...bundle.definition.title ? { title: Object.freeze({ ...bundle.definition.title }) } : {},
+			...bundle.definition.pickerDescription ? { displayDescription: Object.freeze({ ...bundle.definition.pickerDescription }) } : {},
+			mountedBy: Object.freeze(snapshot.kits.filter((kit) => kit.bundles.some((candidate) => candidate.name === bundle.name && candidate.version === bundle.version)).map((kit) => Object.freeze({
+				name: kit.name,
+				version: kit.version
+			})))
+		})));
+		const resources = Object.freeze(Object.entries(definition.resources).map(([path, content]) => Object.freeze({
+			path,
+			bytes: utf8ByteLength$1(content)
+		})).sort((left, right) => left.path < right.path ? -1 : left.path > right.path ? 1 : 0));
+		return Object.freeze({
+			workspace: Object.freeze({
+				name: entry.name,
+				version: entry.version,
+				description: definition.description ?? "",
+				...definition.pickerDescription ? { displayDescription: Object.freeze({ ...definition.pickerDescription }) } : {},
+				mindsetSource: definition.mindsetSource,
+				mounts,
+				resources,
+				relationVocabulary: Object.freeze({
+					schemaVersion: 1,
+					pin: definition.relationVocabulary?.revision ?? "legacy-unavailable",
+					relations: Object.freeze((definition.relationVocabulary?.relations ?? []).map((relation) => Object.freeze({
+						type: relation.type,
+						meaning: relation.meaning,
+						direction: relation.direction,
+						label: Object.freeze({ ...relation.label }),
+						description: Object.freeze({ ...relation.description }),
+						...relation.domain ? { domain: Object.freeze([...relation.domain]) } : {},
+						...relation.range ? { range: Object.freeze([...relation.range]) } : {},
+						...relation.inverse ? { inverse: relation.inverse } : {},
+						...relation.cardinality ? { cardinality: Object.freeze({ ...relation.cardinality }) } : {},
+						...relation.reasoning ? { reasoning: Object.freeze({ ...relation.reasoning }) } : {},
+						...relation.evidence ? { evidence: Object.freeze({ ...relation.evidence }) } : {}
+					})))
+				})
+			}),
+			diagnostics: Object.freeze([])
+		});
+	}
+};
+//#endregion
+//#region packages/studio/src/types.ts
+/**
+* Thrown by a Bundle source port when a file exists but is not decodable
+* UTF-8 text. The Studio surfaces binary content as an explicit diagnostic
+* instead of lossy-decoding it into a text viewer.
+*/
+var StudioBinaryContentError = class extends Error {
+	/** The path whose content is not UTF-8 text. */
+	path;
+	/** @param path - absolute path of the non-text file. */
+	constructor(path) {
+		super(`design studio: ${JSON.stringify(path)} is not UTF-8 text`);
+		this.name = "StudioBinaryContentError";
+		this.path = path;
+	}
+};
+//#endregion
+//#region packages/studio/src/bundle-source.ts
+/**
+* Read-only inspection of real Bundle source files.
+*
+* The Bundle content authority is the Kit source directory on disk. The read
+* model exposes the physical file tree, byte-exact text content, and the
+* loader-compiled manifest/schema/validation summaries with Panel
+* classification. Identity is reconciled against the host's Core-compiled
+* catalog by exact Kit and Bundle name+version; an ambiguous physical source
+* or a catalog/source disagreement fails loud instead of guessing. The Studio
+* never writes: traversal, `.git`, directories, and binary content are
+* rejected, and no mutation port exists.
+*/
+function diagnostic(code, message, subject) {
+	return Object.freeze([Object.freeze(subject === void 0 ? {
+		code,
+		message
+	} : {
+		code,
+		message,
+		subject
+	})]);
+}
+function jsonProject(value) {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return void 0;
+	return Object.freeze(JSON.parse(JSON.stringify(value)));
+}
+function utf8ByteLength(content) {
+	return new TextEncoder().encode(content).length;
+}
+/**
+* Split one relative file path into safe segments. Rejects absolute paths,
+* empty/`.`/`..`/`.git` segments, backslashes, and control characters.
+* @param path - candidate slash-separated relative path.
+* @returns the segments, or undefined when the shape is unsafe.
+*/
+function safeSegments(path) {
+	if (path === "" || path.startsWith("/") || path.endsWith("/") || path.includes("\\") || /[\u0000-\u001f\u007f]/u.test(path)) return;
+	const parts = path.split("/");
+	if (parts.some((part) => part === "" || part === "." || part === ".." || part === ".git")) return void 0;
+	return parts;
+}
+function panelOf(manifest) {
+	const presentation = manifest?.presentation;
+	if (typeof presentation !== "object" || presentation === null || Array.isArray(presentation)) return void 0;
+	const { mode, renderer } = presentation;
+	if (mode === "native") return Object.freeze(typeof renderer === "string" ? {
+		kind: "native",
+		renderer
+	} : { kind: "native" });
+	if (mode === "declarative") return Object.freeze({ kind: "declarative" });
+}
+function validationOf(skill) {
+	const document = skill.metadata?.validationDocument;
+	if (document === void 0 || !Array.isArray(document.rules)) return void 0;
+	const drivers = /* @__PURE__ */ new Set();
+	for (const rule of document.rules) if (typeof rule.check?.driver === "string") drivers.add(rule.check.driver);
+	return Object.freeze({
+		rules: document.rules.length,
+		drivers: Object.freeze([...drivers].sort())
+	});
+}
+/**
+* Read-only Bundle inspection over real Kit source files, reconciled against
+* the host's Core-compiled catalog. The injected port owns the physical
+* filesystem; this service owns resolution, path safety, identity
+* reconciliation, and the JSON-only read models.
+*/
+var StudioBundleSourceService = class {
+	#catalog;
+	#source;
+	/**
+	* @param catalog - current authoritative installed Kit snapshot provider.
+	* @param source - host-supplied read-only physical source operations.
+	*/
+	constructor(catalog, source) {
+		this.#catalog = catalog;
+		this.#source = source;
+	}
+	/**
+	* Read one Bundle's workspace: physical file tree, loader-compiled
+	* manifest/schema/validation summaries, and Panel classification.
+	* @param name - the Bundle id.
+	* @returns the workspace, or resolution/reconciliation diagnostics.
+	*/
+	async readBundleWorkspace(name, version) {
+		const resolved = await this.#resolve(name, version);
+		if ("diagnostics" in resolved) return resolved;
+		const { kitRoot, bundleRoot } = resolved;
+		let skill;
+		let kitName;
+		let kitVersion;
+		try {
+			if (resolved.skill) skill = resolved.skill;
+			else {
+				const kit = await loadStudioKit(this.#source, kitRoot);
+				const found = kit.skills.find((candidate) => candidate.name === name);
+				if (found === void 0) return Object.freeze({ diagnostics: diagnostic("bundle.not_in_catalog", `Bundle ${JSON.stringify(name)} is not referenced by the Mindset <design_skills> catalog`, name) });
+				skill = found;
+				kitName = kit.name;
+				kitVersion = String(kit.version);
+			}
+		} catch (error) {
+			return Object.freeze({ diagnostics: diagnostic("kit.load", error instanceof Error ? error.message : String(error), name) });
+		}
+		const bundleVersion = String(skill.version);
+		const catalogKit = (await this.#catalog.snapshot()).kits.find((kit) => kit.name === kitName && kit.version === kitVersion);
+		if (!resolved.skill && catalogKit === void 0) return Object.freeze({ diagnostics: diagnostic("studio.source_catalog_mismatch", `source Kit ${JSON.stringify(kitName)}@${JSON.stringify(kitVersion)} is not present in the compiled catalog`, name) });
+		if (!resolved.skill && !catalogKit?.bundles.some((bundle) => bundle.name === name && bundle.version === bundleVersion)) return Object.freeze({ diagnostics: diagnostic("studio.source_catalog_mismatch", `source Bundle ${JSON.stringify(name)}@${JSON.stringify(bundleVersion)} disagrees with the compiled catalog`, name) });
+		const files = [];
+		for (const path of await this.#source.listFiles(bundleRoot)) {
+			let content;
+			try {
+				content = await this.#source.readText(join(bundleRoot, path));
+			} catch (error) {
+				if (error instanceof StudioBinaryContentError) continue;
+				throw error;
+			}
+			if (content === void 0) continue;
+			files.push(Object.freeze({
+				path,
+				bytes: utf8ByteLength(content)
+			}));
+		}
+		const manifest = jsonProject(skill.metadata?.skillManifest);
+		const schema = jsonProject(skill.metadata?.schemaDocument);
+		const validation = validationOf(skill);
+		const panel = panelOf(manifest);
+		return Object.freeze({
+			workspace: Object.freeze({
+				name,
+				version: bundleVersion,
+				...kitName === void 0 ? {} : { kit: kitName },
+				description: skill.description,
+				...skill.pickerDescription ? { displayDescription: Object.freeze({ ...skill.pickerDescription }) } : {},
+				files: Object.freeze(files),
+				...manifest === void 0 ? {} : { manifest },
+				...schema === void 0 ? {} : { schema },
+				...validation === void 0 ? {} : { validation },
+				...panel === void 0 ? {} : { panel }
+			}),
+			diagnostics: Object.freeze([])
+		});
+	}
+	/**
+	* Read one complete Bundle file byte-exactly as UTF-8 text.
+	* @param input - Bundle id and Bundle-relative path.
+	* @returns the file content, or resolution diagnostics.
+	*/
+	async readBundleFile(input) {
+		const located = await this.#locate(input.name, input.path, input.version);
+		if ("diagnostics" in located) return located;
+		let content;
+		try {
+			content = await this.#source.readText(located.absolute);
+		} catch (error) {
+			if (error instanceof StudioBinaryContentError) return Object.freeze({ diagnostics: diagnostic("bundle_file.binary", `Bundle ${JSON.stringify(input.name)} file ${JSON.stringify(input.path)} is not UTF-8 text`, input.path) });
+			throw error;
+		}
+		if (content === void 0) return Object.freeze({ diagnostics: diagnostic("bundle_file.missing", `Bundle ${JSON.stringify(input.name)} has no file ${JSON.stringify(input.path)}`, input.path) });
+		return Object.freeze({
+			file: Object.freeze({
+				path: input.path,
+				content
+			}),
+			diagnostics: Object.freeze([])
+		});
+	}
+	/** Resolve one Bundle id to exactly one physical root; same-name multi-root fails loud. */
+	async #resolve(name, version) {
+		if (this.#source.resolveBundleRoot) {
+			const candidates = ((await this.#catalog.snapshot()).bundles ?? []).filter((bundle) => bundle.name === name && (version === void 0 || bundle.version === version));
+			if (candidates.length !== 1) return { diagnostics: diagnostic(candidates.length ? "studio.ambiguous_version" : "bundle.missing", `Select one registered exact version of Bundle ${JSON.stringify(name)}`, name) };
+			const selected = candidates[0];
+			const root = await this.#source.resolveBundleRoot({
+				name,
+				version: selected.version
+			});
+			if (!root) return { diagnostics: diagnostic("bundle.missing", `Missing retained source for ${name}@${selected.version}`, name) };
+			if ((selected.definition.catalogName ?? selected.definition.name) !== name || String(selected.definition.version) !== selected.version) return { diagnostics: diagnostic("studio.source_catalog_mismatch", "Independent Bundle definition disagrees with its exact pin", name) };
+			return {
+				bundleRoot: root,
+				skill: selected.definition
+			};
+		}
+		const matches = [];
+		for (const kitRoot of await this.#source.listKitRoots()) {
+			const root = resolve(kitRoot);
+			const bundleRoot = join(root, "skills", name);
+			if (await this.#source.isDirectory(bundleRoot)) matches.push({
+				kitRoot: root,
+				bundleRoot
+			});
+		}
+		if (matches.length === 0) return { diagnostics: diagnostic("bundle.missing", `no source Bundle named ${JSON.stringify(name)}`, name) };
+		if (matches.length > 1) return { diagnostics: diagnostic("studio.duplicate_source", `Bundle ${JSON.stringify(name)} exists in ${matches.length} configured Kit sources: ${matches.map((match) => JSON.stringify(match.bundleRoot)).join(", ")}`, name) };
+		const match = matches[0];
+		if (version !== void 0) try {
+			const kit = await loadStudioKit(this.#source, match.kitRoot);
+			const skill = kit.skills.find((candidate) => candidate.name === name);
+			if (skill === void 0 || String(skill.version) !== version) return { diagnostics: diagnostic("bundle.version_missing", `Source does not provide Bundle ${JSON.stringify(name)}@${JSON.stringify(version)}`, version) };
+			if (!(await this.#catalog.snapshot()).kits.find((candidate) => candidate.name === kit.name && candidate.version === String(kit.version))?.bundles.some((bundle) => bundle.name === name && bundle.version === version)) return { diagnostics: diagnostic("studio.source_catalog_mismatch", "Legacy source does not match the registered exact Bundle version", name) };
+		} catch (error) {
+			return { diagnostics: diagnostic("kit.load", error instanceof Error ? error.message : String(error), name) };
+		}
+		return match;
+	}
+	/** Resolve and path-check one Bundle file target against the physical file tree. */
+	async #locate(name, path, version) {
+		const resolved = await this.#resolve(name, version);
+		if ("diagnostics" in resolved) return resolved;
+		if (safeSegments(path) === void 0) return { diagnostics: diagnostic("bundle_file.path_forbidden", `path must stay inside the Bundle directory: ${JSON.stringify(path)}`, path) };
+		if (!(await this.#source.listFiles(resolved.bundleRoot)).includes(path)) return { diagnostics: diagnostic("bundle_file.missing", `Bundle ${JSON.stringify(name)} has no regular file ${JSON.stringify(path)}`, path) };
+		return { absolute: join(resolved.bundleRoot, path) };
+	}
+};
+//#endregion
+//#region packages/studio/src/snapshot.ts
+/**
+* Project one Core-compiled Kit into its version-addressed snapshot form.
+* @param kit - compiled Kit from the host catalog authority.
+* @returns the frozen snapshot entry retaining the definition by reference.
+*/
+function snapshotKit(kit) {
+	return Object.freeze({
+		name: kit.name,
+		version: String(kit.version),
+		definition: kit,
+		bundles: Object.freeze(kit.skills.map((skill) => Object.freeze({
+			name: skill.catalogName ?? skill.name,
+			version: String(skill.version),
+			definition: skill
+		})))
+	});
+}
+//#endregion
+//#region packages/companion/src/studio.mjs
+/** Thin read-only port for the existing Studio domain; no second catalog. */
+async function createCompanionStudio(kit, kitRoot, stateRoot, contentLibrary) {
+	const currentKit = async () => typeof kit === "function" ? kit() : kit;
+	const root = resolve(typeof kit === "function" ? kitRoot : kit.sourceRoot ?? kitRoot);
+	let kitSnapshot, bundleSnapshot, catalogKit;
+	const invalidateCatalog = () => {
+		kitSnapshot = void 0;
+		bundleSnapshot = void 0;
+	};
+	const checkCatalogKit = async () => {
+		const selected = await currentKit();
+		if (selected !== catalogKit) {
+			invalidateCatalog();
+			catalogKit = selected;
+		}
+	};
+	const installedKits = async () => {
+		await checkCatalogKit();
+		return kitSnapshot ??= Promise.resolve(currentKit()).then((selected) => [selected]).catch((error) => {
+			kitSnapshot = void 0;
+			throw error;
+		});
+	};
+	const selectedKit = async (pin) => {
+		const selected = (await installedKits()).find((item) => item.name === pin.name && String(item.version) === pin.version);
+		if (!selected) throw new Error("Select the exact registered Kit version.");
+		return selected;
+	};
+	const installedBundles = async () => {
+		await checkCatalogKit();
+		return bundleSnapshot ??= readInstalledBundles().catch((error) => {
+			bundleSnapshot = void 0;
+			throw error;
+		});
+	};
+	const readInstalledBundles = async () => [...(await currentKit()).skills];
+	const catalog = { snapshot: async () => {
+		if (!contentLibrary) invalidateCatalog();
+		return {
+			kits: (await installedKits()).map(snapshotKit),
+			bundles: (await installedBundles()).map((skill) => ({
+				name: skill.catalogName ?? skill.name,
+				version: String(skill.version),
+				definition: skill
+			}))
+		};
+	} };
+	const safe = async (path) => {
+		const owner = [
+			root,
+			...(await installedKits()).map((kit) => kit.sourceRoot).filter(Boolean),
+			...(await installedBundles()).map((skill) => skill.resourceRoot).filter(Boolean)
+		].find((base) => {
+			const rel = relative(base, resolve(path));
+			return !isAbsolute(rel) && rel !== ".." && !rel.startsWith(`..${sep}`);
+		});
+		if (!owner) throw new Error("Studio path outside registered content.");
+		const rel = relative(owner, resolve(path));
+		if (rel.split(sep).some((part) => [".git", "node_modules"].includes(part))) throw new Error("Studio path outside registered content.");
+		let current = await realpath(owner);
+		for (const part of rel.split(sep).filter(Boolean)) {
+			current = join(current, part);
+			if ((await lstat(current)).isSymbolicLink()) throw new Error("Studio does not follow source symlinks.");
+		}
+		return current;
+	};
+	const source = {
+		listKitRoots: async () => [root],
+		resolveBundleRoot: async (pin) => (await installedBundles()).find((skill) => (skill.catalogName ?? skill.name) === pin.name && String(skill.version) === pin.version)?.resourceRoot,
+		readText: async (path) => {
+			try {
+				const file = await safe(path);
+				if (!(await lstat(file)).isFile()) throw new Error("Studio expects a regular file.");
+				const bytes = await readFile(file);
+				try {
+					const text = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+					if (text.includes("\0")) throw new Error("binary");
+					return text;
+				} catch {
+					throw new StudioBinaryContentError(path);
+				}
+			} catch (error) {
+				if (error.code === "ENOENT") return void 0;
+				throw error;
+			}
+		},
+		listDir: async (path) => {
+			try {
+				return (await readdir(await safe(path))).filter((name) => ![".git", "node_modules"].includes(name));
+			} catch (error) {
+				if (error.code === "ENOENT") return [];
+				throw error;
+			}
+		},
+		isDirectory: async (path) => {
+			try {
+				return (await lstat(await safe(path))).isDirectory();
+			} catch (error) {
+				if (error.code === "ENOENT") return false;
+				throw error;
+			}
+		},
+		listFiles: async (path) => {
+			const base = await safe(path), files = [];
+			const visit = async (dir) => {
+				for (const entry of await readdir(dir, { withFileTypes: true })) {
+					if ([".git", "node_modules"].includes(entry.name) || entry.isSymbolicLink()) continue;
+					const next = join(dir, entry.name);
+					if (entry.isDirectory()) await visit(next);
+					else if (entry.isFile()) files.push(relative(base, next).split(sep).join("/"));
+				}
+			};
+			await visit(base);
+			return files.sort();
+		}
+	};
+	const management = new StudioManagementService(catalog);
+	const bundles = new StudioBundleSourceService(catalog, source);
+	const previewInstalledPanel = async (input) => {
+		const diagnostic = (code, message) => ({ diagnostics: [{
+			code,
+			message
+		}] });
+		if (!input || !Number.isSafeInteger(input.revision) || input.revision < 0 || input.kit !== void 0 && (typeof input.kit?.name !== "string" || typeof input.kit?.version !== "string") || typeof input.bundle?.name !== "string" || typeof input.bundle?.version !== "string" || !/^[a-z][a-z0-9_]*$/.test(input.bundle.name) || input.sampleSource !== void 0 && typeof input.sampleSource !== "string") return diagnostic("preview.request", "Select exact Kit and Bundle pins and a non-negative preview revision.");
+		const kitPin = { ...input.kit }, bundlePin = { ...input.bundle }, revision = input.revision;
+		const requestedSample = input.sampleSource;
+		if (requestedSample !== void 0 && Buffer.byteLength(requestedSample) > 262144) return diagnostic("preview.size", "Sample JSON is limited to 256 KiB.");
+		try {
+			if (input.kit === void 0) {
+				const selected = (await installedBundles()).find((skill) => (skill.catalogName ?? skill.name) === bundlePin.name && String(skill.version) === bundlePin.version);
+				if (!selected) throw new Error("Select the exact registered Bundle version.");
+				const retained = contentLibrary ? await contentLibrary.store.resolveBundle(bundlePin) : void 0;
+				const base = retained?.resourceRoot ?? selected.resourceRoot;
+				if (!base) throw new Error("Independent Bundle source is unavailable.");
+				const { createStudioInstanceAdapters } = await import("./studio-instance-composition-BJzYMyvV.mjs");
+				const { composition } = createStudioInstanceAdapters({
+					listBundles: async () => [bundlePin],
+					captureKit: async () => {
+						throw new Error("Standalone preview has no Kit.");
+					},
+					captureBundle: async () => {
+						throw new Error("Standalone preview uses only its captured source.");
+					}
+				});
+				return composition.preview({
+					kind: "bundle",
+					bundle: bundlePin,
+					runtimeName: selected.name,
+					bundleFiles: await captureRegisteredTree(base),
+					sourceId: retained?.sourceId ?? "companion:explicit-kit",
+					revision,
+					...requestedSample === void 0 ? {} : { sampleSource: requestedSample }
+				});
+			}
+			const selected = await selectedKit(kitPin);
+			const root = selected.sourceRoot ?? kitRoot;
+			const locations = [];
+			for (const skill of selected.skills) {
+				const pin = {
+					name: skill.catalogName ?? skill.name,
+					version: String(skill.version)
+				};
+				const retained = contentLibrary ? await contentLibrary.store.resolveBundle(pin) : void 0;
+				locations.push({
+					...pin,
+					rootDir: retained?.resourceRoot ?? skill.resourceRoot ?? join(root, "skills", skill.name),
+					sourceId: retained?.sourceId ?? "companion:explicit-kit"
+				});
+			}
+			const loadOptions = {
+				sourceId: "companion:explicit-kit",
+				bundles: locations
+			};
+			const capturedRoots = [.../* @__PURE__ */ new Set([root, ...locations.map((location) => location.rootDir)])];
+			const files = [];
+			for (const base of capturedRoots) for (const path of await source.listFiles(base)) files.push({
+				base,
+				path
+			});
+			if (files.length > 4096) throw new Error("Installed preview source exceeds 4096 files.");
+			const texts = /* @__PURE__ */ new Map(), binary = /* @__PURE__ */ new Set(), directories = new Set(capturedRoots);
+			let bytes = 0;
+			for (const { base, path } of files) {
+				const absolute = join(base, path), info = await lstat(await safe(absolute));
+				bytes += info.size;
+				if (bytes > 16777216) throw new Error("Installed preview source exceeds 16 MiB.");
+				try {
+					const text = await source.readText(absolute);
+					if (text !== void 0) texts.set(absolute, text);
+					if (text !== void 0 && Buffer.byteLength(text) > info.size) {
+						bytes += Buffer.byteLength(text) - info.size;
+						if (bytes > 16777216) throw new Error("Installed preview source exceeds 16 MiB.");
+					}
+				} catch (error) {
+					if (error instanceof StudioBinaryContentError) binary.add(absolute);
+					else throw error;
+				}
+				const parts = path.split("/");
+				for (let count = 1; count < parts.length; count++) directories.add(join(base, ...parts.slice(0, count)));
+			}
+			const paths = /* @__PURE__ */ new Set([
+				...texts.keys(),
+				...binary,
+				...directories
+			]);
+			const installed = await loadStudioKit({
+				readText: async (path) => {
+					const key = resolve(path);
+					if (binary.has(key)) throw new StudioBinaryContentError(key);
+					return texts.get(key);
+				},
+				isDirectory: async (path) => directories.has(resolve(path)),
+				listDir: async (path) => {
+					const base = resolve(path);
+					return [...new Set([...paths].filter((key) => key !== base && relative(base, key).split(sep).length === 1 && !relative(base, key).startsWith("..")).map((key) => relative(base, key)))].sort();
+				}
+			}, root, loadOptions);
+			if (installed.name !== kitPin.name || String(installed.version) !== kitPin.version) return diagnostic("preview.kit_pin", "Source does not match the selected Kit version.");
+			const bundle = installed.skills.find((entry) => (entry.catalogName ?? entry.name) === bundlePin.name && String(entry.version) === bundlePin.version);
+			if (!bundle) return diagnostic("preview.bundle_pin", "Source does not match the selected Bundle version.");
+			if (typeof bundle.metadata?.panelYaml !== "string") return diagnostic("preview.not_declarative", "This Bundle has no declarative Panel preview.");
+			const bundleRoot = bundle.resourceRoot ?? join(root, "skills", bundle.name);
+			const panelSource = texts.get(join(bundleRoot, "panel.yaml"));
+			if (panelSource === void 0) return diagnostic("preview.definition", "Panel source is missing.");
+			if (Buffer.byteLength(panelSource) > 1048576) return diagnostic("preview.size", "Panel source is limited to 1 MiB and sample JSON to 256 KiB.");
+			const initial = bundle.metadata.panelManifest?.initial_values;
+			const example = texts.get(join(bundleRoot, "reference", "preview.json"));
+			if (requestedSample === void 0 && example === void 0 && initial === void 0) return diagnostic("preview.sample_missing", "No preview sample is provided. Add reference/preview.json to this Bundle or supply isolated sample JSON.");
+			const sampleSource = requestedSample ?? example ?? JSON.stringify(initial);
+			return finalizeStudioPanelPreview({
+				compiled: bundle,
+				kit: kitPin,
+				bundle: bundlePin,
+				revision,
+				sampleSource,
+				readSampleResource: (path) => texts.get(join(bundleRoot, path))
+			});
+		} catch (error) {
+			return diagnostic("preview.definition", error instanceof Error ? error.message : String(error));
+		}
+	};
+	const hasBundle = async (name) => (await installedBundles()).some((skill) => (skill.catalogName ?? skill.name) === name);
+	const unknownBundle = (name) => ({ diagnostics: [{
+		code: "bundle.missing",
+		message: "Select an installed Bundle by its exact name.",
+		subject: String(name)
+	}] });
+	let instanceService;
+	const captureRegisteredTree = async (base) => {
+		const paths = await source.listFiles(base);
+		if (paths.length > 4096) throw new Error("Content snapshot exceeds 4096 files.");
+		const entries = [];
+		let total = 0;
+		for (const path of paths) {
+			const file = await safe(join(base, path)), info = await lstat(file);
+			if (!info.isFile() || total + info.size > 16777216) throw new Error("Content snapshot exceeds 16 MiB or contains an invalid file.");
+			const bytes = await readFile(file);
+			total += bytes.length;
+			if (total > 16777216) throw new Error("Content snapshot exceeds 16 MiB.");
+			entries.push({
+				path,
+				base64: bytes.toString("base64")
+			});
+		}
+		return entries;
+	};
+	const instances = () => {
+		if (!stateRoot) throw new Error("Studio authoring storage is not configured.");
+		return instanceService ??= Promise.all([import("./studio-instances-D-Y1WNya.mjs"), import("./studio-instance-composition-BJzYMyvV.mjs")]).then(async ([{ createStudioInstances }, { createStudioInstanceAdapters }]) => {
+			return createStudioInstances({
+				stateRoot,
+				...createStudioInstanceAdapters({
+					listBundles: async () => (await installedBundles()).map((skill) => ({
+						name: skill.catalogName ?? skill.name,
+						version: String(skill.version)
+					})),
+					captureKit: async (pin) => {
+						const selected = await selectedKit(pin);
+						let files = await captureRegisteredTree(selected.sourceRoot ?? root);
+						if (!files.some((file) => file.path === "kit.yaml")) {
+							const engineering = /* @__PURE__ */ new Set([
+								"skills",
+								"node_modules",
+								"lib",
+								"dist",
+								"src",
+								"test",
+								"tests",
+								"scripts",
+								".git",
+								".cache",
+								"package.json",
+								"pnpm-lock.yaml",
+								"tsconfig.json",
+								"tsdown.config.ts"
+							]);
+							files = files.filter((file) => !engineering.has(file.path.split("/")[0]));
+							files.push({
+								path: "kit.yaml",
+								base64: Buffer.from((0, import_dist.stringify)({
+									version: 1,
+									mounts: selected.skills.map((skill) => ({
+										bindingKey: skill.name,
+										name: skill.catalogName ?? skill.name,
+										version: String(skill.version)
+									}))
+								})).toString("base64")
+							});
+						}
+						return {
+							files,
+							title: selected.title
+						};
+					},
+					captureBundle: async (pin) => {
+						const selected = (await installedBundles()).find((skill) => (skill.catalogName ?? skill.name) === pin.name && String(skill.version) === pin.version);
+						if (!selected) throw new Error("Select the exact registered Bundle.");
+						const retained = contentLibrary ? await contentLibrary.store.resolveBundle(pin) : void 0;
+						const base = retained?.resourceRoot ?? selected.resourceRoot ?? join(root, "skills", selected.name);
+						return {
+							files: await captureRegisteredTree(base),
+							sourceId: retained?.sourceId ?? "companion:explicit-kit"
+						};
+					}
+				})
+			});
+		}).catch((error) => {
+			instanceService = void 0;
+			throw error;
+		});
+	};
+	return {
+		listInstances: async (input) => (await instances()).list(input),
+		readInstance: async (input) => (await instances()).read(input),
+		createInstance: async (input) => (await instances()).create(input),
+		importInstanceSources: async (input) => (await instances()).importSources(input),
+		copyInstance: async (input) => (await instances()).copy(input),
+		editCurrentInstance: async (input) => (await instances()).editCurrent(input),
+		loadCurrentKit: async (kit) => {
+			const service = await instances();
+			const records = (await service.list({ kind: "kit" })).filter((record) => record.kit?.name === kit.name);
+			const current = records.find((record) => record.current) ?? records[0] ?? await service.editCurrent({
+				kind: "kit",
+				kit
+			});
+			return service.loadKit({ id: current.id });
+		},
+		renameInstance: async (input) => (await instances()).rename(input),
+		removeInstance: async (input) => (await instances()).remove(input),
+		updateInstanceMounts: async (input) => (await instances()).updateMounts(input),
+		readInstanceFile: async (input) => (await instances()).readFile(input),
+		saveInstanceFile: async (input) => (await instances()).saveFile(input),
+		prepareInstanceChanges: async (input) => (await instances()).prepareChanges(input),
+		saveInstanceChanges: async (input) => (await instances()).saveChanges(input),
+		previewInstance: async (input) => (await instances()).preview(input),
+		workspace: ({ query = "" }) => {
+			invalidateCatalog();
+			return management.workspace(query);
+		},
+		readKitFiles: async ({ name, version }) => {
+			const current = await selectedKit({
+				name,
+				version
+			});
+			return source.listFiles(current.sourceRoot ?? root);
+		},
+		readKitFile: async ({ name, version, path }) => {
+			const current = await selectedKit({
+				name,
+				version
+			});
+			if (typeof path !== "string" || !path || /[\\\\:\u0000]/.test(path) || path.split("/").some((part) => !part || part === "." || part === "..")) throw new Error("Invalid Kit file path.");
+			const target = await safe(join(current.sourceRoot ?? root, path));
+			if ((await lstat(target)).size > 1048576) throw new Error("This file is too large for the text viewer.");
+			const content = await source.readText(target);
+			if (content === void 0) throw new Error("Kit file not found.");
+			return { content };
+		},
+		readKitWorkspace: ({ name, version }) => management.readKitWorkspace(name, version),
+		readBundleWorkspace: async ({ name, version }) => await hasBundle(name) ? bundles.readBundleWorkspace(name, version) : unknownBundle(name),
+		readBundleFile: async (input) => await hasBundle(input.name) ? bundles.readBundleFile(input) : unknownBundle(input.name),
+		previewInstalledPanel,
+		readArchive: ({ source }) => readStudioContentArchive(source),
+		exportContentArchive: async (input) => {
+			if (!input || typeof input !== "object" || Array.isArray(input)) throw new Error("Select one exact archive export target.");
+			const request = structuredClone(input);
+			const copy = Object.hasOwn(request, "id") || Object.hasOwn(request, "expectedRevision");
+			const required = copy ? ["id", "expectedRevision"] : ["kind", "pin"];
+			if (required.some((key) => !Object.hasOwn(request, key)) || Object.keys(request).some((key) => ![
+				...required,
+				"provenance",
+				...copy ? ["dependencies"] : []
+			].includes(key))) throw new Error("Archive export accepts one installed target or one exact saved working copy, never a mixed target.");
+			const exact = (value) => value && typeof value === "object" && !Array.isArray(value) && Object.keys(value).length === 2 && ["name", "version"].every((key) => Object.hasOwn(value, key) && typeof value[key] === "string" && value[key].length > 0);
+			const provenance = request.provenance;
+			if (provenance !== void 0 && (!provenance || typeof provenance !== "object" || Array.isArray(provenance) || Object.keys(provenance).some((key) => !["source", "license"].includes(key) || typeof provenance[key] !== "string"))) throw new Error("Invalid archive provenance declarations.");
+			if (request.dependencies !== void 0 && (!Array.isArray(request.dependencies) || !request.dependencies.every(exact))) throw new Error("Archive export dependencies require exact pins.");
+			if (copy) {
+				if (typeof request.id !== "string" || !request.id || !Number.isSafeInteger(request.expectedRevision) || request.expectedRevision < 0) throw new Error("Archive export requires an exact working-copy id and revision.");
+				return (await instances()).exportArchive(request);
+			}
+			if (!["kit", "bundle"].includes(request.kind) || !exact(request.pin)) throw new Error("Archive export requires an exact installed pin.");
+			const service = await instances();
+			const current = await service.editCurrent({
+				kind: request.kind,
+				[request.kind]: request.pin
+			});
+			return service.exportArchive({
+				id: current.id,
+				expectedRevision: current.revision,
+				provenance: request.provenance
+			});
+		}
+	};
+}
+//#endregion
+export { createCompanionStudio };