@yugoo-design/dsh-design-studio 0.0.0-stage → 0.1.0-beta.2

package/lib/index.d.ts

@@ -0,0 +1,738 @@
+import { DesignKit, DesignSkill, KitResourceContent } from "@yugoo-design/dsh-design-core";
+//#region src/types.d.ts
+/**
+ * Host-neutral Design Studio ports and read-model vocabulary.
+ *
+ * The Studio is a pure domain library: every filesystem operation goes through
+ * an injected port so each Agent Host adapter (DSH, Codex, Claude Code, SDK
+ * Pilot) supplies its own native file operations. Nothing here imports an
+ * Agent Host runtime, Cordis, or `node:fs`. Installed content remains read-only;
+ * editable drafts use separate injected snapshot and persistence ports.
+ */
+/**
+ * Read-only filesystem surface the Studio needs to enumerate and validate
+ * Kits. Structurally compatible with the Design Core `KitFsLike` loader port.
+ */
+interface StudioReadFs {
+  /** Read one UTF-8 text file; `undefined` when absent. */
+  readText(path: string): Promise<string | undefined>;
+  /** Optional attached-resource text/opaque projection; never used for definition slots. */
+  readResource?(path: string): Promise<KitResourceContent | undefined>;
+  /** List one directory's entry names. */
+  listDir(path: string): Promise<string[]>;
+  /** Whether a path is a directory; adapters without it fall back to read probes. */
+  isDirectory?(path: string): Promise<boolean>;
+  /** Resolve symlinks for confinement checks. */
+  realPath?(path: string): Promise<string>;
+}
+/** One explicit Studio diagnostic (a stable code plus a locatable message). */
+interface StudioDiagnostic {
+  /** Stable diagnostic code, e.g. `kit.load`. */
+  readonly code: string;
+  /** Human-readable, locatable message. */
+  readonly message: string;
+  /** The Kit or Bundle the diagnostic is about, when known. */
+  readonly subject?: string;
+}
+/** The outcome of validating one Kit or Bundle definition. */
+interface StudioValidationReport {
+  /** True when the definition loaded with no diagnostics. */
+  readonly valid: boolean;
+  /** Explicit diagnostics; empty exactly when {@link valid} is true. */
+  readonly diagnostics: readonly StudioDiagnostic[];
+}
+/** Exact identity of one published Kit version. */
+interface DesignKitVersionPin {
+  /** Published Kit name. */
+  readonly name: string;
+  /** Exact declared Kit version (`major.minor`). */
+  readonly version: string;
+}
+/** Exact identity of one published Bundle version. */
+interface DesignBundleVersionPin {
+  /** Published Bundle name. */
+  readonly name: string;
+  /** Explicit declared Bundle version (`major.minor`). */
+  readonly version: string;
+}
+/**
+ * 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.
+ */
+declare class StudioBinaryContentError extends Error {
+  /** The path whose content is not UTF-8 text. */
+  readonly path: string;
+  /** @param path - absolute path of the non-text file. */
+  constructor(path: string);
+}
+//#endregion
+//#region src/snapshot.d.ts
+/** One Bundle addressed by its declared version. */
+interface DesignBundleSnapshot {
+  /** Bundle id, unique within its Kit. */
+  readonly name: string;
+  /** Explicit declared Bundle version (`major.minor`). */
+  readonly version: string;
+  /**
+   * The Core-compiled, frozen in-process Bundle definition. This is a live
+   * object for in-process read-back, not a persistable catalog record; it must
+   * not be serialized as catalog JSON, and the Design Core loader remains the
+   * authority for producing it.
+   */
+  readonly definition: DesignSkill;
+}
+/** One Kit addressed by its declared version. */
+interface DesignKitSnapshot {
+  /** Kit / mindset id, unique across the installation. */
+  readonly name: string;
+  /** Explicit declared Kit version (`major.minor`). */
+  readonly version: string;
+  /**
+   * The Core-compiled, frozen in-process Kit definition. This is a live object
+   * for in-process read-back, not a persistable catalog record; it must not be
+   * serialized as catalog JSON (runtime pack and compiled functions included),
+   * and the Design Core loader remains the authority for producing it.
+   */
+  readonly definition: DesignKit;
+  /** The Bundles this Kit exposes, in catalog order. */
+  readonly bundles: readonly DesignBundleSnapshot[];
+}
+/** An immutable, version-addressed view of the installed Kits. */
+interface DesignCatalogSnapshot {
+  /** The installed Kits, sorted by name. */
+  readonly kits: readonly DesignKitSnapshot[];
+  /**
+   * Independent compiled Bundle versions, including versions with no Kit mounts.
+   * When supplied, this is the complete Bundle catalog; Kit membership only
+   * contributes reverse references. Omission supports directory-loader adapters
+   * while they are migrated to independent content resolution.
+   */
+  readonly bundles?: readonly DesignBundleSnapshot[];
+}
+/** Supplies a current Core-compiled catalog snapshot to Studio read models. */
+interface StudioCatalogSnapshotPort {
+  /** @returns the current immutable installed Kit snapshot. */
+  snapshot(): Promise<DesignCatalogSnapshot>;
+}
+/**
+ * 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.
+ */
+declare function snapshotKit(kit: DesignKit): DesignKitSnapshot;
+//#endregion
+//#region src/load.d.ts
+/**
+ * Load a Kit with authority derived from the Studio-controlled directory.
+ * @param fs - Studio file-ops port.
+ * @param kitRoot - absolute Kit directory.
+ * @returns the assembled Kit.
+ */
+interface StudioKitLoadOptions {
+  readonly sourceId?: string;
+  readonly bundles?: readonly {
+    name: string;
+    version: string;
+    rootDir: string;
+    sourceId: string;
+  }[];
+}
+declare function loadStudioKit(fs: StudioReadFs, kitRoot: string, options?: StudioKitLoadOptions): Promise<DesignKit>;
+//#endregion
+//#region src/validate.d.ts
+/**
+ * Validate one Kit definition at `kitRoot`.
+ * @param fs - injected read file-ops port.
+ * @param kitRoot - absolute directory holding the Kit.
+ * @returns a report; empty diagnostics exactly when the Kit loads.
+ */
+declare function validateKit(fs: StudioReadFs, kitRoot: string): Promise<StudioValidationReport>;
+/**
+ * Validate one Bundle definition inside an existing Kit.
+ *
+ * Reports missing required slots, then loads the Kit and attributes any loader
+ * content error or a missing Mindset-catalog reference to the Bundle.
+ * @param fs - injected read file-ops port.
+ * @param kitRoot - absolute directory of the containing Kit.
+ * @param name - the Bundle id (its `skills/<name>/` directory).
+ * @returns a report; empty diagnostics exactly when the Bundle loads as part of the Kit.
+ */
+declare function validateBundle(fs: StudioReadFs, kitRoot: string, name: string): Promise<StudioValidationReport>;
+//#endregion
+//#region src/panel-preview.d.ts
+/** One editor revision and its isolated sample, not a runtime publication. */
+interface StudioPanelPreviewRequest {
+  readonly kit: DesignKitVersionPin;
+  readonly bundle: DesignBundleVersionPin;
+  readonly revision: number;
+  readonly panelSource: string;
+  readonly sampleSource: string;
+}
+/** Runtime-interpreter input derived from a validated draft revision. */
+interface StudioPanelPreview {
+  readonly revision: number;
+  /** Absent only for a real independently loaded Bundle preview. */
+  readonly kit?: DesignKitVersionPin;
+  readonly bundle: DesignBundleVersionPin;
+  /** Loader-resolved YAML, including the installed Bundle's translations. */
+  readonly panelYaml: string;
+  readonly sample: Readonly<Record<string, unknown>>;
+}
+interface StudioPanelPreviewResult {
+  readonly preview?: StudioPanelPreview;
+  readonly diagnostics: readonly StudioDiagnostic[];
+}
+/**
+ * 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.
+ */
+declare function prepareStudioPanelPreview(source: StudioReadFs, kitRoot: string, request: StudioPanelPreviewRequest, loadOptions?: StudioKitLoadOptions): Promise<StudioPanelPreviewResult>;
+//#endregion
+//#region src/panel-drafts.d.ts
+interface StudioPanelDraftContent {
+  readonly kit: DesignKitVersionPin;
+  readonly bundle: DesignBundleVersionPin;
+  readonly baseSnapshot: string;
+  readonly panelSource: string;
+  readonly sampleSource: string;
+  /** A confirmed snapshot is locked, but is NOT published into the Kit catalog. */
+  readonly confirmed: boolean;
+}
+interface StudioPanelDraftRecord extends StudioPanelDraftContent {
+  readonly id: string;
+  readonly revision: number;
+}
+type StudioPanelDraftSummary = Pick<StudioPanelDraftRecord, 'id' | 'revision' | 'kit' | 'bundle' | 'confirmed'>;
+interface StudioPanelDraftRepository {
+  create(content: StudioPanelDraftContent): Promise<StudioPanelDraftRecord>;
+  read(id: string): Promise<StudioPanelDraftRecord>;
+  list(): Promise<readonly StudioPanelDraftRecord[]>;
+  /** Atomic, cross-process CAS: must fail without writing if revision differs. */
+  replace(id: string, expectedRevision: number, content: StudioPanelDraftContent): Promise<StudioPanelDraftRecord>;
+}
+interface StudioSourceSnapshot {
+  readonly id: string;
+  readonly fs: StudioReadFs;
+  readonly root: string;
+  /** Bounded closure root; the Kit and independently retained Bundles may be siblings. */
+  readonly storageRoot?: string;
+  readonly loadOptions?: StudioKitLoadOptions;
+}
+interface StudioDraftSources {
+  /** Host resolves exact installed pin, captures all source bytes and retains them. */
+  capture(kit: DesignKitVersionPin): Promise<StudioSourceSnapshot>;
+  open(id: string): Promise<StudioSourceSnapshot>;
+}
+interface StudioPanelDraftEdit {
+  readonly id: string;
+  readonly expectedRevision: number;
+  readonly panelSource: string;
+  readonly sampleSource: string;
+}
+/** Shared semantics used by host adapters; no filesystem or runtime tool access. */
+declare class StudioPanelDraftService {
+  private readonly repository;
+  private readonly sources;
+  constructor(repository: StudioPanelDraftRepository, sources: StudioDraftSources);
+  list(): Promise<readonly StudioPanelDraftSummary[]>;
+  read(id: string): Promise<StudioPanelDraftRecord>;
+  create(input: {
+    kit: DesignKitVersionPin;
+    bundle: DesignBundleVersionPin;
+    sampleSource?: string;
+  }): Promise<StudioPanelDraftRecord>;
+  /** Open only the retained snapshot; imported/template pins need not be installed. */
+  createFromSnapshot(input: {
+    snapshotId: string;
+    kit: DesignKitVersionPin;
+    bundle: DesignBundleVersionPin;
+    sampleSource?: string;
+  }): Promise<StudioPanelDraftRecord>;
+  private createRetained;
+  /** Saving incomplete source is allowed; confirmation requires successful compilation. */
+  save(input: StudioPanelDraftEdit): Promise<StudioPanelDraftRecord>;
+  /** Compile an unsaved editor revision without persisting or touching any project. */
+  preview(input: StudioPanelDraftEdit & {
+    revision: number;
+  }): Promise<StudioPanelPreviewResult>;
+  confirm(input: {
+    id: string;
+    expectedRevision: number;
+  }): Promise<{
+    draft?: StudioPanelDraftRecord;
+  } & StudioPanelPreviewResult>;
+  /** Start another editable revision, sharing the immutable base bytes. */
+  fork(id: string): Promise<StudioPanelDraftRecord>;
+}
+//#endregion
+//#region src/kit-drafts.d.ts
+interface StudioKitDraftContent {
+  readonly baseKit: DesignKitVersionPin;
+  readonly baseSnapshot: string;
+  /** Exact immutable mounts. Bundle working copies are edited independently. */
+  readonly mounts: readonly DesignBundleVersionPin[];
+  readonly mindsetSource: string;
+  /** null removes the optional Kit-owned relation vocabulary. */
+  readonly relationsSource: string | null;
+  readonly confirmed: boolean;
+}
+interface StudioKitDraftRecord extends StudioKitDraftContent {
+  readonly id: string;
+  readonly revision: number;
+}
+interface StudioKitDraftRepository {
+  create(content: StudioKitDraftContent): Promise<StudioKitDraftRecord>;
+  read(id: string): Promise<StudioKitDraftRecord>;
+  list(): Promise<readonly StudioKitDraftRecord[]>;
+  /** Atomic CAS across writers; conflicts and confirmed records must not be overwritten. */
+  replace(id: string, expectedRevision: number, content: StudioKitDraftContent): Promise<StudioKitDraftRecord>;
+}
+interface StudioKitDraftEdit {
+  readonly id: string;
+  readonly expectedRevision: number;
+  readonly mindsetSource: string;
+  readonly relationsSource: string | null;
+}
+interface StudioKitDraftValidation extends StudioValidationReport {
+  readonly revision: number;
+  /** A candidate identity, not a published/catalog-resolvable version. */
+  readonly candidateKit?: DesignKitVersionPin;
+}
+declare class StudioKitDraftService {
+  private readonly repository;
+  private readonly sources;
+  constructor(repository: StudioKitDraftRepository, sources: StudioDraftSources);
+  list(): Promise<readonly Pick<StudioKitDraftRecord, 'id' | 'revision' | 'baseKit' | 'confirmed'>[]>;
+  read(id: string): Promise<StudioKitDraftRecord>;
+  create(input: {
+    kit: DesignKitVersionPin;
+  }): Promise<StudioKitDraftRecord>;
+  /** Adopt retained, independently validated content; never resolve an installed pin. */
+  createFromSnapshot(input: {
+    snapshotId: string;
+    kit: DesignKitVersionPin;
+  }): Promise<StudioKitDraftRecord>;
+  private createRetained;
+  /** Invalid intermediate edits can be retained, but cannot be confirmed. */
+  save(input: StudioKitDraftEdit): Promise<StudioKitDraftRecord>;
+  private compile;
+  validate(input: {
+    id: string;
+    expectedRevision: number;
+  }): Promise<StudioKitDraftValidation>;
+  preview(input: {
+    id: string;
+    expectedRevision: number;
+    bundle: DesignBundleVersionPin;
+    sampleSource: string;
+  }): Promise<StudioPanelPreviewResult>;
+  confirm(input: {
+    id: string;
+    expectedRevision: number;
+  }): Promise<StudioKitDraftValidation & {
+    draft?: StudioKitDraftRecord;
+  }>;
+  fork(id: string): Promise<StudioKitDraftRecord>;
+}
+//#endregion
+//#region src/content-archive.d.ts
+interface StudioArchivePin {
+  readonly name: string;
+  readonly version: string;
+}
+interface StudioArchiveFile {
+  readonly path: string;
+  readonly base64: string;
+  readonly bytes: number;
+  readonly sha256: string;
+}
+interface StudioContentArchive {
+  readonly format: 'studio-content-archive/v1';
+  readonly kind: 'kit' | 'bundle';
+  readonly pin: StudioArchivePin;
+  /** Declared provenance, not verified authorship or redistribution permission. */
+  readonly provenance: {
+    readonly source: string;
+    readonly license: string;
+  };
+  /** Kit membership pins in catalog order; Bundle explicitly declared requirements. */
+  readonly dependencies: readonly DesignBundleVersionPin[];
+  readonly files: readonly StudioArchiveFile[];
+  /** SHA-256 of the canonical envelope excluding this field; not a signature. */
+  readonly sha256: string;
+}
+interface StudioArchiveBundleSource extends StudioArchivePin {
+  readonly sourceId: string;
+  readonly snapshot: StudioArchiveSource;
+}
+interface StudioArchiveSource {
+  readonly sourceId?: string;
+  /** Trusted immutable Bundle snapshots, never paths supplied by an archive. */
+  readonly bundles?: readonly StudioArchiveBundleSource[];
+  readonly root: string;
+  readonly fs: StudioReadFs;
+  /** Host supplies a complete, immutable regular-file snapshot; no live fallback. */
+  listFiles(): Promise<readonly string[]>;
+  /** Byte-preserving read. Host rejects links and non-regular files before reading. */
+  readBytes(path: string): Promise<Uint8Array>;
+}
+interface StudioPreparedContentImport {
+  readonly archive: StudioContentArchive;
+  /** Files relative to Kit root, or standalone Bundle root, respectively. */
+  readonly files: readonly StudioArchiveFile[];
+  /** Independently retainable content, only populated after definition validation. */
+  readonly contents: readonly {
+    readonly kind: 'kit' | 'bundle';
+    readonly pin: StudioArchivePin;
+    readonly files: readonly StudioArchiveFile[];
+  }[];
+  readonly executionGranted: false;
+  /** Includes scripts and provider/driver references; host approval is separate. */
+  readonly requiresTrustReview: boolean;
+  readonly validation: {
+    readonly valid: boolean;
+    readonly diagnostics: readonly StudioDiagnostic[];
+  };
+}
+/** Parse a bounded JSON envelope; hashes include metadata and every original byte. */
+declare function readStudioContentArchive(source: string): StudioContentArchive;
+/** No writes, extraction, permission restoration, script execution, installation or publication. */
+declare function prepareStudioContentImport(source: string, options?: {
+  validationContext?: StudioArchiveSource | {
+    root: string;
+    fs: StudioReadFs;
+  };
+}): Promise<StudioPreparedContentImport>;
+/** Capture only immutable host snapshots, preserving full exact referenced trees. */
+declare function exportStudioContentArchive(snapshot: StudioArchiveSource, input: {
+  kind: 'kit' | 'bundle';
+  pin: StudioArchivePin;
+  provenance: StudioContentArchive['provenance'];
+  dependencies?: readonly DesignBundleVersionPin[];
+}): Promise<string>;
+//#endregion
+//#region src/management.d.ts
+/** One browser-safe published Kit pin. */
+interface StudioKitView {
+  /** Published Kit identity. */
+  readonly name: string;
+  /** Exact declared Kit version. */
+  readonly version: string;
+  /** Optional display copy, projected from the exact Kit definition. */
+  readonly description?: string;
+  readonly displayDescription?: Readonly<{
+    zh: string;
+    en: string;
+  }>;
+}
+/** One browser-safe Bundle catalog entry with exact reverse dependencies. */
+interface StudioBundleView extends DesignBundleVersionPin {
+  readonly title?: Readonly<{
+    zh: string;
+    en: string;
+  }>;
+  readonly displayDescription?: Readonly<{
+    zh: string;
+    en: string;
+  }>;
+  /** Human routing description. */
+  readonly description: string;
+  /** Exact published Kit versions selecting this Bundle version. */
+  readonly usedBy: readonly StudioKitView[];
+}
+/** Complete JSON-only view model for the Studio management surface. */
+interface StudioWorkspaceView {
+  /** Trimmed catalog query applied to {@link bundles}. */
+  readonly query: string;
+  /** Published Kit version pins. */
+  readonly kits: readonly StudioKitView[];
+  /** Flat Bundle version results, including reverse Kit dependencies. */
+  readonly bundles: readonly StudioBundleView[];
+}
+/** Structured management failure safe to serialize through any host transport. */
+interface StudioManagementFailure {
+  /** Stable failure category rendered by shared Studio clients. */
+  readonly code: 'request_failed';
+  /** User-facing diagnostic. */
+  readonly message: string;
+}
+/** One read-only Bundle mount with exact reverse Kit references. */
+interface StudioBundleMountView {
+  readonly title?: Readonly<{
+    zh: string;
+    en: string;
+  }>;
+  readonly displayDescription?: Readonly<{
+    zh: string;
+    en: string;
+  }>;
+  /** Mounted Bundle name. */
+  readonly name: string;
+  /** Exact mounted Bundle version. */
+  readonly version: string;
+  /** One-line Bundle description. */
+  readonly description: string;
+  /** Every installed Kit version mounting this exact Bundle version. */
+  readonly mountedBy: readonly StudioKitView[];
+}
+/** One Core-loader-compiled auxiliary resource of a Kit version, by exact path. */
+interface StudioResourceRefView {
+  /** Exact compiled resource path (loader authority; never guessed). */
+  readonly path: string;
+  /** UTF-8 byte length of the compiled resource content. */
+  readonly bytes: number;
+}
+/** One validated Kit relation extension exposed for initial Studio inspection. */
+interface StudioRelationView {
+  readonly type: string;
+  readonly meaning: string;
+  readonly direction: 'forward' | 'symmetric';
+  readonly label: {
+    readonly zh: string;
+    readonly en: string;
+  };
+  readonly description: {
+    readonly zh: string;
+    readonly en: string;
+  };
+  readonly domain?: readonly string[];
+  readonly range?: readonly string[];
+  readonly inverse?: string;
+  readonly cardinality?: Readonly<{
+    from: 'one' | 'many';
+    to: 'one' | 'many';
+  }>;
+  readonly reasoning?: Readonly<{
+    impact?: boolean;
+    causal?: boolean;
+    transitive?: boolean;
+  }>;
+  readonly evidence?: Readonly<{
+    minimum: 'explicit' | 'inferred';
+  }>;
+}
+/** Exact version-pinned relation extension summary compiled by Design Core. */
+interface StudioRelationVocabularyView {
+  readonly schemaVersion: 1;
+  readonly pin: string;
+  readonly relations: readonly StudioRelationView[];
+}
+/** Read-only installed-Kit workspace: exact source plus catalog facts. */
+interface StudioKitWorkspaceView {
+  /** Kit identity. */
+  readonly name: string;
+  /** Exact installed Kit version. */
+  readonly version: string;
+  /** Human description from the mindset frontmatter; empty when absent. */
+  readonly description: string;
+  readonly displayDescription?: Readonly<{
+    zh: string;
+    en: string;
+  }>;
+  /** Complete raw mindset.md source, including frontmatter, byte-identical to the installation. */
+  readonly mindsetSource: string;
+  /** Mounted Bundles in catalog order with reverse Kit references. */
+  readonly mounts: readonly StudioBundleMountView[];
+  /** Loader-compiled auxiliary resources, sorted by path. */
+  readonly resources: readonly StudioResourceRefView[];
+  /** Optional extension entry. Editing remains disabled until Studio gains versioned drafts. */
+  readonly relationVocabulary: StudioRelationVocabularyView;
+}
+/** Read result for one installed Kit workspace: a view or actionable diagnostics. */
+interface StudioKitWorkspaceResult {
+  /** Frozen workspace view; present exactly when diagnostics are empty. */
+  readonly workspace?: StudioKitWorkspaceView;
+  /** Frozen resolution diagnostics. */
+  readonly diagnostics: readonly StudioDiagnostic[];
+}
+/**
+ * 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.
+ */
+declare class StudioManagementService {
+  #private;
+  /** @param catalog - current authoritative installed Kit snapshot provider. */
+  constructor(catalog: StudioCatalogSnapshotPort);
+  /**
+   * 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.
+   */
+  workspace(query?: string): Promise<StudioWorkspaceView>;
+  /**
+   * 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.
+   */
+  readKitWorkspace(name: string, version: string): Promise<StudioKitWorkspaceResult>;
+}
+//#endregion
+//#region src/composition.d.ts
+/** One immutable Bundle version with exact reverse Kit dependencies. */
+interface StudioBundleVersionEntry extends DesignBundleVersionPin {
+  /** Core-compiled definition retained by reference; source is never copied. */
+  readonly definition: DesignSkill;
+  /** Exact published Kit versions that select this Bundle version. */
+  readonly usedBy: readonly DesignKitVersionPin[];
+}
+/** Frozen flat Bundle catalog plus the published Kit versions it derives from. */
+interface StudioCompositionCatalog {
+  /** Bundle versions sorted by name then version. */
+  readonly bundles: readonly StudioBundleVersionEntry[];
+  /** Published Kit version pins sorted by name then version. */
+  readonly kits: readonly DesignKitVersionPin[];
+}
+/**
+ * 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.
+ */
+declare function buildStudioCompositionCatalog(snapshot: DesignCatalogSnapshot): StudioCompositionCatalog;
+/**
+ * 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.
+ */
+declare function searchStudioBundles(catalog: StudioCompositionCatalog, query: string): readonly StudioBundleVersionEntry[];
+//#endregion
+//#region src/bundle-source.d.ts
+/**
+ * Read-only physical source operations the Bundle workspace needs from its
+ * Agent Host. The members are structurally compatible with {@link StudioReadFs}
+ * so the Design Core loader runs directly against the port. Path confinement
+ * (traversal, `.git`, symlink escape, regular files only) is the adapter's
+ * responsibility; the service independently rejects unsafe path shapes.
+ */
+interface StudioBundleSourcePort {
+  /** Resolve an exact independent source; never infer ownership from a Kit. */
+  resolveBundleRoot?(pin: {
+    name: string;
+    version: string;
+  }): Promise<string | undefined>;
+  /** Every authored Kit source root; each holds `mindset.md` and `skills/`. */
+  listKitRoots(): Promise<readonly string[]>;
+  /** Read one UTF-8 text file; `undefined` when absent. Throws {@link StudioBinaryContentError} for non-text content. */
+  readText(path: string): Promise<string | undefined>;
+  /** List one directory's entry names; empty when absent. */
+  listDir(path: string): Promise<string[]>;
+  /** Whether one path is a directory. */
+  isDirectory(path: string): Promise<boolean>;
+  /** Every regular file below one directory, as sorted slash-separated relative paths. */
+  listFiles(path: string): Promise<readonly string[]>;
+}
+/** One readable UTF-8 file in a Bundle workspace file tree. */
+interface StudioBundleFileRefView {
+  /** Slash-separated path relative to the Bundle root. */
+  readonly path: string;
+  /** UTF-8 byte length of the file content. */
+  readonly bytes: number;
+}
+/** Panel classification of one Bundle's presentation declaration. */
+interface StudioBundlePanelView {
+  /** `native` Panels are provider-owned code, read-only in the Studio; `declarative` Panels are Bundle-authored data. */
+  readonly kind: 'native' | 'declarative';
+  /** Declared renderer identity. */
+  readonly renderer?: string;
+}
+/** Validator summary derived from the compiled validation document. */
+interface StudioBundleValidationSummary {
+  /** Number of declared validation rules. */
+  readonly rules: number;
+  /** Sorted unique runtime validation driver identities referenced by rules; empty for driver-free rules. */
+  readonly drivers: readonly string[];
+}
+/** Read model of one authored Bundle: physical files plus compiled summaries. */
+interface StudioBundleWorkspaceView {
+  /** Bundle id (its `skills/<name>/` directory name). */
+  readonly name: string;
+  /** Declared Bundle version, reconciled against the compiled catalog. */
+  readonly version: string;
+  /** Kit name declaring this Bundle in its catalog. */
+  readonly kit?: string;
+  /** One-line Bundle description. */
+  readonly description: string;
+  readonly displayDescription?: Readonly<{
+    zh: string;
+    en: string;
+  }>;
+  /** Every readable UTF-8 file below the Bundle root, sorted by path. */
+  readonly files: readonly StudioBundleFileRefView[];
+  /** Parsed skill.yaml manifest, JSON-projected. */
+  readonly manifest?: Readonly<Record<string, unknown>>;
+  /** Parsed schema.yaml document, JSON-projected. */
+  readonly schema?: Readonly<Record<string, unknown>>;
+  /** Validation rule and driver summary. */
+  readonly validation?: StudioBundleValidationSummary;
+  /** Panel classification; absent when the Bundle declares no presentation. */
+  readonly panel?: StudioBundlePanelView;
+}
+/** The read result of one Bundle workspace. */
+interface StudioBundleWorkspaceResult {
+  /** The workspace view; undefined when resolution or reconciliation fails. */
+  readonly workspace?: StudioBundleWorkspaceView;
+  /** Resolution, reconciliation, or load diagnostics. */
+  readonly diagnostics: readonly StudioDiagnostic[];
+}
+/** One complete Bundle file read byte-exactly as UTF-8 text. */
+interface StudioBundleFileView {
+  /** Slash-separated path relative to the Bundle root. */
+  readonly path: string;
+  /** Complete UTF-8 file content. */
+  readonly content: string;
+}
+/** The read result of one Bundle file. */
+interface StudioBundleFileResult {
+  /** The file; undefined when it is missing, unsafe, or not text. */
+  readonly file?: StudioBundleFileView;
+  /** Resolution diagnostics. */
+  readonly diagnostics: readonly StudioDiagnostic[];
+}
+/**
+ * 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.
+ */
+declare class StudioBundleSourceService {
+  #private;
+  /**
+   * @param catalog - current authoritative installed Kit snapshot provider.
+   * @param source - host-supplied read-only physical source operations.
+   */
+  constructor(catalog: StudioCatalogSnapshotPort, source: StudioBundleSourcePort);
+  /**
+   * 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.
+   */
+  readBundleWorkspace(name: string, version?: string): Promise<StudioBundleWorkspaceResult>;
+  /**
+   * 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.
+   */
+  readBundleFile(input: {
+    name: string;
+    path: string;
+    version?: string;
+  }): Promise<StudioBundleFileResult>;
+}
+//#endregion
+export { type DesignBundleSnapshot, type DesignBundleVersionPin, type DesignCatalogSnapshot, type DesignKitSnapshot, type DesignKitVersionPin, type StudioArchiveFile, type StudioArchivePin, type StudioArchiveSource, StudioBinaryContentError, type StudioBundleFileRefView, type StudioBundleFileResult, type StudioBundleFileView, type StudioBundleMountView, type StudioBundlePanelView, type StudioBundleSourcePort, StudioBundleSourceService, type StudioBundleValidationSummary, type StudioBundleVersionEntry, type StudioBundleView, type StudioBundleWorkspaceResult, type StudioBundleWorkspaceView, type StudioCatalogSnapshotPort, type StudioCompositionCatalog, type StudioContentArchive, type StudioDiagnostic, type StudioDraftSources, type StudioKitDraftContent, type StudioKitDraftEdit, type StudioKitDraftRecord, type StudioKitDraftRepository, StudioKitDraftService, type StudioKitDraftValidation, type StudioKitView, type StudioKitWorkspaceResult, type StudioKitWorkspaceView, type StudioManagementFailure, StudioManagementService, type StudioPanelDraftContent, type StudioPanelDraftEdit, type StudioPanelDraftRecord, type StudioPanelDraftRepository, StudioPanelDraftService, type StudioPanelDraftSummary, type StudioPanelPreview, type StudioPanelPreviewRequest, type StudioPanelPreviewResult, type StudioPreparedContentImport, type StudioReadFs, type StudioRelationView, type StudioRelationVocabularyView, type StudioResourceRefView, type StudioSourceSnapshot, type StudioValidationReport, type StudioWorkspaceView, buildStudioCompositionCatalog, exportStudioContentArchive, loadStudioKit, prepareStudioContentImport, prepareStudioPanelPreview, readStudioContentArchive, searchStudioBundles, snapshotKit, validateBundle, validateKit };