@yugoo-design/dsh-design-studio-dsh 0.1.0-beta.3 → 0.1.0

package/README.md

@@ -9,7 +9,7 @@ explicit `kitSources` mode remains available with its strict startup validation.
 
 `dsh-design-studio-dsh` is the DSH-only adapter around the host-neutral read-only Studio application and shared `StudioWorkspace`. It owns the session-free `studioManagement` Typert Remote, a root-scoped Settings launcher, and the plugin-owned `/design-studio/` full-page route. It does not change the Agent loop, Design Project selection, Design Files, or G/R/A services, and it persists nothing: Studio 1.0 has no durable record, no working copies, and no mutation endpoint.
 
-The Remote exposes exactly four read methods: `workspace`, `readKitWorkspace` (exact `name@version` pin required; a diverging response identity diagnoses), `readBundleWorkspace`, and `readBundleFile`. The catalog snapshot projects `ctx.design.listKits()`. Bundle source reads run through `ctx.fs`: the `kitSources` config lists installed content packages (`packageName`, resolved like the Design Core kit-loader) or absolute directories (`root`); every path resolves through the filesystem capability and must stay canonically contained in a configured root, so traversal and symlink escapes never read outside the authored trees and non-UTF-8 content diagnoses as binary. Invalid or ambiguous configuration — a missing root, a root without `mindset.md`, a relative path, a duplicate root, or one Kit/Bundle name declared by two roots — fails loud at startup. Without `kitSources` the catalog stays readable and Bundle reads diagnose `studio.source_not_configured`. Disposal rejects new work and drains admitted calls.
+The Remote exposes exactly six read methods: `workspace`, `readKitWorkspace` (exact `name@version` pin required; a diverging response identity diagnoses), `readKitFiles` and `readKitFile` (the same exact Kit pin), `readBundleWorkspace`, and `readBundleFile`. Kit file inspection includes `kit.yaml`, `mindset.md` and other authored files beneath the selected Kit root, excluding `.git` and `node_modules`; the text viewer accepts regular UTF-8 files up to 1 MiB, with bounded tree traversal. Missing sources, forbidden paths, binary content and oversized files diagnose rather than falling back to another version. The catalog snapshot projects `ctx.design.listKits()`. Bundle source reads run through `ctx.fs`: the `kitSources` config lists installed content packages (`packageName`, resolved like the Design Core kit-loader) or absolute directories (`root`); every path resolves through the filesystem capability and must stay canonically contained in a configured root, so traversal and symlink escapes never read outside the authored trees and non-UTF-8 content diagnoses as binary. Invalid or ambiguous configuration — a missing root, a root without `mindset.md`, a relative path, a duplicate root, or one Kit/Bundle name declared by two roots — fails loud at startup. Without `kitSources` the catalog stays readable and Bundle reads diagnose `studio.source_not_configured`. Disposal rejects new work and drains admitted calls.
 
 Strict codecs follow the current Typert `create(): TypertSchema` factory contract.
 The existing Zod validators supply that parser capability; both Host registration
@@ -26,3 +26,13 @@ dependencies or remaining static/dynamic module imports. Its page-route test als
 checks the emitted JavaScript with the shared loader analyzer and exercises real
 bundler rejection cases. These checks establish browser module closure; rendered
 Host interaction remains a separate integration check.
+
+Only the standalone browser page injects `PanelSelect` and
+`PANEL_SELECT_MENU_CSS` from the isolated public `dsh-design-panel/select` into
+Studio's optional neutral choice-control port. This is a shared control and popup
+style, not the broad provider API or Panel/DSL workspace renderer. The server,
+Settings launcher and transports retain their existing dependency boundary.
+The menu snapshots Studio's semantic
+tokens and fonts; inside an open native dialog it stays within that dialog's top
+layer, otherwise it uses the owning document body. These source changes do not
+establish installed Web/Desktop interaction acceptance.

package/lib/client-adapter.d.ts

@@ -32,6 +32,8 @@ type DshRemoteResult<T> = {
 interface DshStudioRemote {
   workspace(query: string): Promise<DshRemoteResult<Awaited<ReturnType<StudioManagementClient['workspace']>>>>;
   readKitWorkspace(name: string, version: string): Promise<DshRemoteResult<Awaited<ReturnType<StudioManagementClient['readKitWorkspace']>>>>;
+  readKitFiles(name: string, version: string): Promise<DshRemoteResult<Awaited<ReturnType<NonNullable<StudioManagementClient['readKitFiles']>>>>>;
+  readKitFile(name: string, version: string, path: string): Promise<DshRemoteResult<Awaited<ReturnType<NonNullable<StudioManagementClient['readKitFile']>>>>>;
   readBundleWorkspace(name: string, version?: string): Promise<DshRemoteResult<Awaited<ReturnType<StudioManagementClient['readBundleWorkspace']>>>>;
   readBundleFile(name: string, path: string, version?: string): Promise<DshRemoteResult<Awaited<ReturnType<StudioManagementClient['readBundleFile']>>>>;
 }

package/lib/client-adapter.js

@@ -45,6 +45,8 @@ function createDshStudioClient(remote) {
 				})
 			});
 		},
+		readKitFiles: (input) => unwrap("readKitFiles", remote.readKitFiles(input.name, input.version)),
+		readKitFile: (input) => unwrap("readKitFile", remote.readKitFile(input.name, input.version, input.path)),
 		readBundleWorkspace: (name, version) => unwrap("readBundleWorkspace", remote.readBundleWorkspace(name, version)),
 		readBundleFile: (input) => unwrap("readBundleFile", remote.readBundleFile(input.name, input.path, input.version))
 	});

package/lib/index.d.ts

@@ -51,6 +51,7 @@ declare class DshStudioManagementService extends TypertRemoteService {
   private readonly config;
   private management?;
   private bundles?;
+  private readonly configuredKitRoots;
   private accepting;
   private readonly inFlight;
   /**
@@ -67,6 +68,13 @@ declare class DshStudioManagementService extends TypertRemoteService {
   workspace(query: string): Promise<StudioWorkspaceView>;
   /** Read one exact installed Kit version's workspace and verify the returned identity matches. */
   readKitWorkspace(name: string, version: string): Promise<StudioKitWorkspaceResult>;
+  /** List all authored files of one exact installed Kit, including kit.yaml. */
+  readKitFiles(name: string, version: string): Promise<readonly string[]>;
+  /** Read one root-confined Kit file as bounded UTF-8 text. */
+  readKitFile(name: string, version: string, path: string): Promise<{
+    readonly content: string;
+  }>;
+  private kitFiles;
   /** Read one Bundle's read-only source workspace. */
   readBundleWorkspace(name: string, version?: string): Promise<StudioBundleWorkspaceResult>;
   /** Read one complete Bundle file byte-exactly as UTF-8 text. */

package/lib/index.js

@@ -1,8 +1,104 @@
 import { createRequire } from "node:module";
 import { Service } from "@deepseek-ai/cordis";
-import { dirname, isAbsolute, join, resolve } from "node:path";
 import { Remote, TypertRemoteService } from "@deepseek-ai/dsh-typert-protocol";
+import { DesignKitVersion } from "@yugoo-design/dsh-design-core";
 import { StudioBinaryContentError, StudioBundleSourceService, StudioManagementService, loadStudioKit, snapshotKit } from "@yugoo-design/dsh-design-studio";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+//#region src/kit-files.ts
+/** Installed source reads share the same DSH filesystem containment boundary. */
+const MAX_TEXT_BYTES = 1048576;
+const excludedDirectory = (name) => /^(?:\.git|node_modules)$/iu.test(name);
+/** A code survives the Remote gateway while the message remains useful in the viewer. */
+function kitFileError(code, message) {
+	return Object.assign(/* @__PURE__ */ new Error(`${code}: ${message}`), { code });
+}
+/** One read's installed resource root is the complete filesystem boundary, not its catalog id. */
+async function openInstalledSourceFiles(fs, root, kind = "Bundle") {
+	if (!isAbsolute(root)) throw new Error(`design studio dsh: installed ${kind} resource root must be absolute`);
+	const base = await fs.resolve(root);
+	if ((await fs.stat(base))?.type !== "directory") throw new Error(`design studio dsh: installed ${kind} resource root is not a directory`);
+	const target = async (path) => {
+		const resolved = await fs.resolve(path);
+		if (!fs.contains(base, resolved)) {
+			if (kind === "Kit") throw kitFileError("kit_file.path_forbidden", "Path escapes installed Kit resource root.");
+			throw new Error(`design studio dsh: path escapes installed ${kind} resource root`);
+		}
+		return resolved;
+	};
+	const code = (error) => typeof error === "object" && error !== null && "code" in error ? error.code : void 0;
+	return {
+		async readFile(path) {
+			if (typeof path !== "string" || /[\\:\u0000-\u001f\u007f]/u.test(path) || path.split("/").some((part) => !part || part === "." || part === ".." || excludedDirectory(part))) throw kitFileError("kit_file.path_forbidden", "Invalid Kit file path.");
+			try {
+				const resolved = await target(join(root, path));
+				const info = await fs.stat(resolved);
+				if (info?.type !== "file") throw kitFileError("kit_file.missing", "Kit file not found or not a regular file.");
+				if ((info.size ?? 0) > MAX_TEXT_BYTES) throw kitFileError("kit_file.too_large", "This file exceeds the 1 MiB text viewer limit.");
+				const bytes = await fs.readBytes(resolved, void 0, MAX_TEXT_BYTES);
+				let content;
+				try {
+					content = new TextDecoder("utf-8", {
+						fatal: true,
+						ignoreBOM: true
+					}).decode(bytes);
+				} catch {
+					throw kitFileError("kit_file.binary", "Kit file is binary or invalid UTF-8 text.");
+				}
+				if (content.includes("\0")) throw kitFileError("kit_file.binary", "Kit file is binary, not UTF-8 text.");
+				return { content };
+			} catch (error) {
+				if (code(error) === "FS_TOO_LARGE") throw kitFileError("kit_file.too_large", "This file exceeds the 1 MiB text viewer limit.");
+				if (code(error) === "FS_NOT_FOUND") throw kitFileError("kit_file.missing", "Kit file not found.");
+				if (code(error) === "FS_NOT_TEXT") throw kitFileError("kit_file.binary", "Kit file is binary or invalid UTF-8 text.");
+				throw error;
+			}
+		},
+		listKitRoots: async () => [],
+		async readText(path) {
+			try {
+				return await fs.readText(await target(path));
+			} catch (error) {
+				if (code(error) === "FS_NOT_FOUND") return void 0;
+				if (code(error) === "FS_NOT_TEXT") throw new StudioBinaryContentError(path);
+				throw error;
+			}
+		},
+		async listDir(path) {
+			try {
+				return (await fs.listDir(await target(path))).map((entry) => entry.name);
+			} catch (error) {
+				if (code(error) === "FS_NOT_FOUND" || code(error) === "FS_NOT_DIRECTORY") return [];
+				throw error;
+			}
+		},
+		async isDirectory(path) {
+			try {
+				return (await fs.stat(await target(path)))?.type === "directory";
+			} catch (error) {
+				if (code(error) === "FS_NOT_FOUND") return false;
+				throw error;
+			}
+		},
+		async listFiles(path) {
+			const files = [];
+			let visited = 0;
+			const walk = async (directory, prefix, depth) => {
+				if (depth > 32) throw new Error(`design studio dsh: ${kind} file tree exceeds depth limit`);
+				for (const entry of await fs.listDir(directory)) {
+					if (++visited > 2e4) throw new Error(`design studio dsh: ${kind} file tree exceeds entry limit`);
+					if (kind === "Kit" && excludedDirectory(entry.name)) continue;
+					if (!fs.contains(base, entry.target)) continue;
+					const relative = prefix ? `${prefix}/${entry.name}` : entry.name;
+					if (entry.type === "directory") await walk(entry.target, relative, depth + 1);
+					else if (entry.type === "file") files.push(relative);
+				}
+			};
+			await walk(await target(path), "", 0);
+			return files.sort();
+		}
+	};
+}
+//#endregion
 //#region src/kit-sources.ts
 /** Read-only Kit source access over the DSH host filesystem capability. */
 /**
@@ -132,6 +228,7 @@ var DshStudioManagementService = class extends TypertRemoteService {
 	config;
 	management;
 	bundles;
+	configuredKitRoots = /* @__PURE__ */ new Map();
 	accepting = true;
 	inFlight = /* @__PURE__ */ new Set();
 	/**
@@ -150,6 +247,7 @@ var DshStudioManagementService = class extends TypertRemoteService {
 			await Promise.allSettled([...this.inFlight]);
 			this.management = void 0;
 			this.bundles = void 0;
+			this.configuredKitRoots.clear();
 		}, "design-studio-dsh.readonly");
 		const catalog = Object.freeze({ snapshot: async () => Object.freeze({
 			kits: Object.freeze(this.host.design.listKits().map(snapshotKit).sort((left, right) => left.name.localeCompare(right.name) || left.version.localeCompare(right.version))),
@@ -159,9 +257,9 @@ var DshStudioManagementService = class extends TypertRemoteService {
 		const configs = this.config.kitSources ?? [];
 		if (configs.length === 0) return;
 		const roots = configs.map((entry) => resolveKitSourceRoot(entry, this.ctx.baseUrl));
-		this.bundles = await this.openBundleService(this.host.design.listKits(), roots);
+		this.bundles = await this.openBundleService(this.host.design.listKits(), roots, true);
 	}
-	async openBundleService(kits, roots) {
+	async openBundleService(kits, roots, recordKitRoots = false) {
 		const catalog = { snapshot: async () => ({ kits: kits.map(snapshotKit) }) };
 		const source = await openDshStudioBundleSource(this.host.fs, roots);
 		const kitNames = /* @__PURE__ */ new Map();
@@ -176,6 +274,7 @@ var DshStudioManagementService = class extends TypertRemoteService {
 			const previousKit = kitNames.get(kit.name);
 			if (previousKit !== void 0) throw new Error(`design studio dsh: Kit ${JSON.stringify(kit.name)} is declared by two kitSources roots: ${JSON.stringify(previousKit)} and ${JSON.stringify(root)}`);
 			kitNames.set(kit.name, root);
+			if (recordKitRoots) this.configuredKitRoots.set(`${kit.name}\0${kit.version}`, root);
 			for (const skill of kit.skills) {
 				const previousBundle = bundleNames.get(skill.name);
 				if (previousBundle !== void 0) throw new Error(`design studio dsh: Bundle ${JSON.stringify(skill.name)} is declared by two kitSources roots: ${JSON.stringify(previousBundle)} and ${JSON.stringify(root)}`);
@@ -213,7 +312,7 @@ var DshStudioManagementService = class extends TypertRemoteService {
 					if (!selected) return void 0;
 					const root = this.host.design.resolveBundleRoot(pin) ?? selected.definition.resourceRoot;
 					if (!root) return void 0;
-					files = await openInstalledBundleFiles(this.host.fs, root);
+					files = await openInstalledSourceFiles(this.host.fs, root);
 					return root;
 				},
 				readText: (path) => requireFiles().readText(path),
@@ -245,6 +344,42 @@ var DshStudioManagementService = class extends TypertRemoteService {
 			return result;
 		});
 	}
+	/** List all authored files of one exact installed Kit, including kit.yaml. */
+	readKitFiles(name, version) {
+		return this.run(async () => {
+			const { root, files } = await this.kitFiles(name, version);
+			return files.listFiles(root);
+		});
+	}
+	/** Read one root-confined Kit file as bounded UTF-8 text. */
+	readKitFile(name, version, path) {
+		return this.run(async () => (await this.kitFiles(name, version)).files.readFile(path));
+	}
+	async kitFiles(name, version) {
+		if (typeof name !== "string" || !name || typeof version !== "string" || !version) throw kitFileError("workspace.version_missing", "An exact Kit name and version are required.");
+		let exactVersion;
+		try {
+			exactVersion = DesignKitVersion(version);
+		} catch {
+			throw kitFileError("workspace.version_missing", "An exact Kit major.minor version is required.");
+		}
+		const kit = typeof this.host.design.resolveKit === "function" ? this.host.design.resolveKit({
+			kit: name,
+			version: exactVersion
+		}) : this.host.design.listKits().find((candidate) => candidate.name === name && candidate.version === version);
+		if (!kit || kit.name !== name || kit.version !== version) throw kitFileError("workspace.version_missing", `Kit ${JSON.stringify(name)}@${JSON.stringify(version)} is not installed.`);
+		const configured = this.configuredKitRoots.get(`${name}\0${version}`);
+		const root = this.config.followInstalledSources ? kit.sourceRoot ?? configured : configured;
+		if (!root) throw kitFileError("studio.source_not_configured", `No source root is configured for Kit ${JSON.stringify(name)}@${JSON.stringify(version)}.`);
+		try {
+			return {
+				root,
+				files: await openInstalledSourceFiles(this.host.fs, root, "Kit")
+			};
+		} catch (error) {
+			throw kitFileError("studio.source_unavailable", `Kit source is unavailable; the process may retain last-good content: ${String(error)}`);
+		}
+	}
 	/** Read one Bundle's read-only source workspace. */
 	readBundleWorkspace(name, version) {
 		return this.run(async () => {
@@ -289,62 +424,6 @@ var DshStudioManagementService = class extends TypertRemoteService {
 		return result;
 	}
 };
-/** One read's installed resource root is the complete filesystem boundary, not its catalog id. */
-async function openInstalledBundleFiles(fs, root) {
-	if (!isAbsolute(root)) throw new Error("design studio dsh: installed Bundle resource root must be absolute");
-	const base = await fs.resolve(root);
-	if ((await fs.stat(base))?.type !== "directory") throw new Error("design studio dsh: installed Bundle resource root is not a directory");
-	const target = async (path) => {
-		const resolved = await fs.resolve(path);
-		if (!fs.contains(base, resolved)) throw new Error("design studio dsh: path escapes installed Bundle resource root");
-		return resolved;
-	};
-	const code = (error) => typeof error === "object" && error !== null && "code" in error ? error.code : void 0;
-	return {
-		listKitRoots: async () => [],
-		async readText(path) {
-			try {
-				return await fs.readText(await target(path));
-			} catch (error) {
-				if (code(error) === "FS_NOT_FOUND") return void 0;
-				if (code(error) === "FS_NOT_TEXT") throw new StudioBinaryContentError(path);
-				throw error;
-			}
-		},
-		async listDir(path) {
-			try {
-				return (await fs.listDir(await target(path))).map((entry) => entry.name);
-			} catch (error) {
-				if (code(error) === "FS_NOT_FOUND" || code(error) === "FS_NOT_DIRECTORY") return [];
-				throw error;
-			}
-		},
-		async isDirectory(path) {
-			try {
-				return (await fs.stat(await target(path)))?.type === "directory";
-			} catch (error) {
-				if (code(error) === "FS_NOT_FOUND") return false;
-				throw error;
-			}
-		},
-		async listFiles(path) {
-			const files = [];
-			let visited = 0;
-			const walk = async (directory, prefix, depth) => {
-				if (depth > 32) throw new Error("design studio dsh: Bundle file tree exceeds depth limit");
-				for (const entry of await fs.listDir(directory)) {
-					if (++visited > 2e4) throw new Error("design studio dsh: Bundle file tree exceeds entry limit");
-					if (!fs.contains(base, entry.target)) continue;
-					const relative = prefix ? `${prefix}/${entry.name}` : entry.name;
-					if (entry.type === "directory") await walk(entry.target, relative, depth + 1);
-					else if (entry.type === "file") files.push(relative);
-				}
-			};
-			await walk(await target(path), "", 0);
-			return files.sort();
-		}
-	};
-}
 function sourceNotConfigured(name) {
 	return Object.freeze({ diagnostics: Object.freeze([Object.freeze({
 		code: "studio.source_not_configured",
@@ -372,6 +451,8 @@ function markRemote(name, method) {
 }
 markRemote("workspace", DshStudioManagementService.prototype.workspace);
 markRemote("readKitWorkspace", DshStudioManagementService.prototype.readKitWorkspace);
+markRemote("readKitFiles", DshStudioManagementService.prototype.readKitFiles);
+markRemote("readKitFile", DshStudioManagementService.prototype.readKitFile);
 markRemote("readBundleWorkspace", DshStudioManagementService.prototype.readBundleWorkspace);
 markRemote("readBundleFile", DshStudioManagementService.prototype.readBundleFile);
 //#endregion