@yugoo-design/dsh-design-studio 0.1.0 → 0.2.0

package/lib/instance-changes-CFLBPBdi.d.ts

@@ -0,0 +1,280 @@
+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;
+  /** Omitted means error, preserving existing error-only consumers. */
+  readonly severity?: 'warning';
+}
+/** The outcome of validating one Kit or Bundle definition. */
+interface StudioValidationReport {
+  /** True when the definition loads without errors; warnings do not block use. */
+  readonly valid: boolean;
+  /** Definition errors or non-blocking authoring warnings. */
+  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/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/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>>;
+  /** Explicit bounded synthetic files; never project artifacts or filesystem access. */
+  readonly artifacts?: Readonly<Record<string, string>>;
+}
+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/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;
+  /** Optional bilingual working-copy display name, independent of catalog/runtime identity. */
+  readonly title?: {
+    readonly zh: string;
+    readonly en: string;
+  };
+  /** 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;
+  /** Explicit standalone source, not an invented Kit or a fallback after Kit validation. */
+  readonly bundle?: StudioArchivePin;
+  /** 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>;
+}
+/** Parse a bounded JSON envelope; hashes include metadata and every original byte. */
+declare function readStudioContentArchive(source: string): StudioContentArchive;
+/** Capture only immutable host snapshots, preserving full exact referenced trees. */
+declare function exportStudioContentArchive(snapshot: StudioArchiveSource, input: StudioArchiveExportInput): Promise<string>;
+/** Capture saved source bytes, including incomplete working copies, without definition validation. */
+declare function exportStudioSourceArchive(snapshot: StudioArchiveSource, input: StudioArchiveExportInput): Promise<string>;
+interface StudioArchiveExportInput {
+  kind: 'kit' | 'bundle';
+  pin: StudioArchivePin;
+  title?: StudioContentArchive['title'];
+  provenance?: StudioContentArchive['provenance'];
+  dependencies?: readonly DesignBundleVersionPin[];
+}
+//#endregion
+//#region src/panel-drafts.d.ts
+interface StudioPanelDraftContent {
+  readonly kit: DesignKitVersionPin;
+  readonly bundle: DesignBundleVersionPin;
+  readonly baseSnapshot: string;
+  readonly panelSource: string;
+  readonly sampleSource: string;
+  /** Historical metadata only; never used to lock current authoring. */
+  readonly confirmed?: boolean;
+}
+interface StudioPanelDraftRecord extends StudioPanelDraftContent {
+  readonly id: string;
+  readonly revision: number;
+}
+type StudioPanelDraftSummary = Pick<StudioPanelDraftRecord, 'id' | 'revision' | 'kit' | 'bundle' | 'confirmed'>;
+interface StudioPanelDraftRepository {
+  read(id: string): Promise<StudioPanelDraftRecord>;
+  list(): Promise<readonly 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 captures complete current installed source bytes for an isolated Bundle trial. */
+  capture(kit: DesignKitVersionPin): Promise<StudioSourceSnapshot>;
+  open(id: string): Promise<StudioSourceSnapshot>;
+}
+//#endregion
+//#region src/instance-changes.d.ts
+declare const STUDIO_INSTANCE_CHANGE_LIMITS: Readonly<{
+  files: 64;
+  fileBytes: 1048576;
+  totalBytes: 4194304;
+  diffBytes: 8388608;
+  sampleBytes: 262144;
+}>;
+interface StudioInstanceFileChange {
+  readonly path: string;
+  /** UTF-8 replacement/addition; null explicitly removes a text file. */
+  readonly content: string | null;
+}
+interface StudioInstanceChangeRequest {
+  readonly id: string;
+  readonly expectedRevision: number;
+  readonly changes: readonly StudioInstanceFileChange[];
+  readonly bundle?: DesignBundleVersionPin;
+  readonly sampleSource?: string;
+}
+interface StudioInstanceFileDiff {
+  readonly path: string;
+  /** Missing means the file is added/removed; empty text remains an existing file. */
+  readonly before?: string;
+  readonly after?: string;
+}
+interface StudioInstanceCandidate {
+  readonly id: string;
+  readonly baseRevision: number;
+  readonly revision: number;
+  /** Binds the exact base, full candidate source, mount pins and preview sample. */
+  readonly digest: string;
+  readonly diff: readonly StudioInstanceFileDiff[];
+  /** Core definition passed; declarative Bundles and explicitly selected Kit previews also require a valid Panel/sample. */
+  readonly valid: boolean;
+  readonly diagnostics: readonly StudioDiagnostic[];
+  readonly preview?: StudioPanelPreview;
+}
+/** Draft is the default; validated requests require the exact prepared digest. */
+type StudioInstanceSaveChanges = StudioInstanceChangeRequest & ({
+  readonly mode?: 'draft';
+  readonly digest?: string;
+} | {
+  readonly mode: 'validated';
+  readonly digest: string;
+});
+interface StudioInstanceChangeReceipt {
+  readonly baseRevision: number;
+  readonly revision: number;
+  readonly digest: string;
+  readonly mode: 'draft' | 'validated';
+  /** Neither mode publishes or grants execution authority. */
+  readonly validation: 'not_requested' | 'definition_passed' | 'preview_passed';
+}
+/** Copy before any asynchronous host work so callers cannot mutate an in-flight edit. */
+declare function normalizeStudioInstanceChanges(value: StudioInstanceChangeRequest): StudioInstanceChangeRequest;
+//#endregion
+export { StudioDiagnostic as A, StudioPanelPreviewRequest as C, DesignBundleVersionPin as D, loadStudioKit as E, StudioValidationReport as M, DesignKitVersionPin as O, StudioPanelPreview as S, prepareStudioPanelPreview as T, StudioArchiveSource as _, StudioInstanceFileChange as a, exportStudioSourceArchive as b, normalizeStudioInstanceChanges as c, StudioPanelDraftRecord as d, StudioPanelDraftRepository as f, StudioArchivePin as g, StudioArchiveFile as h, StudioInstanceChangeRequest as i, StudioReadFs as j, StudioBinaryContentError as k, StudioDraftSources as l, StudioSourceSnapshot as m, StudioInstanceCandidate as n, StudioInstanceFileDiff as o, StudioPanelDraftSummary as p, StudioInstanceChangeReceipt as r, StudioInstanceSaveChanges as s, STUDIO_INSTANCE_CHANGE_LIMITS as t, StudioPanelDraftContent as u, StudioContentArchive as v, StudioPanelPreviewResult as w, readStudioContentArchive as x, exportStudioContentArchive as y };