openuispec 0.2.11 → 0.2.13

package/drift/index.ts

@@ -73,6 +73,33 @@ export interface ExplainResult {
   files: FileExplanation[];
 }
 
+// ── shared layer types ───────────────────────────────────────────────
+
+export interface SharedLayerConfig {
+  name: string;
+  platforms: string[];
+  language: string;
+  root: string;           // resolved absolute path
+  paths: Record<string, string>;
+  tracks: string[];       // spec categories to track for drift
+  scope: string;          // what code belongs in this layer
+}
+
+export interface SharedLayerState {
+  spec_version: string;
+  snapshot_at: string;
+  layer_name: string;
+  generated_by_target: string;
+  baseline?: BaselineRef;
+  files: Record<string, FileEntry>;
+}
+
+export interface SharedLayerDriftResult {
+  layer: SharedLayerConfig;
+  drift: DriftResult;
+  state: SharedLayerState | null;
+}
+
 // ── helpers ───────────────────────────────────────────────────────────
 
 export function listFiles(dir: string, ext: string): string[] {
@@ -166,16 +193,43 @@ export function discoverSpecFiles(projectDir: string): string[] {
   return files;
 }
 
-function categorize(relPath: string): string {
-  if (relPath === "openuispec.yaml") return "Manifest";
+/** Classify a relative spec path into a lowercase category. */
+export function specCategory(relPath: string): string {
+  if (relPath === "openuispec.yaml") return "manifest";
   const dir = dirname(relPath);
-  if (dir === "tokens") return "Tokens";
-  if (dir === "screens") return "Screens";
-  if (dir === "flows") return "Flows";
-  if (dir === "platform") return "Platform";
-  if (dir === "locales") return "Locales";
-  if (dir === "contracts") return "Contracts";
-  return "Other";
+  if (dir === "tokens") return "tokens";
+  if (dir === "screens") return "screens";
+  if (dir === "flows") return "flows";
+  if (dir === "platform") return "platform";
+  if (dir === "locales") return "locales";
+  if (dir === "contracts") return "contracts";
+  return "other";
+}
+
+function categorize(relPath: string): string {
+  const cat = specCategory(relPath);
+  return cat.charAt(0).toUpperCase() + cat.slice(1);
+}
+
+/** Returns true when a DriftResult contains any changes. */
+export function hasDriftChanges(d: DriftResult): boolean {
+  return d.changed.length > 0 || d.added.length > 0 || d.removed.length > 0;
+}
+
+/** Hash spec files into FileEntry records keyed by relative path. */
+export function buildFileEntries(
+  projectDir: string,
+  files: string[]
+): { entries: Record<string, FileEntry>; stubs: number } {
+  const entries: Record<string, FileEntry> = {};
+  let stubs = 0;
+  for (const f of files) {
+    const rel = relative(projectDir, f);
+    const status = hasStatusSemantics(rel) ? readStatus(f) : "ready";
+    entries[rel] = { hash: hashFile(f), status };
+    if (status === "stub") stubs++;
+  }
+  return { entries, stubs };
 }
 
 function runGit(args: string[], cwd: string): string | null {
@@ -536,6 +590,158 @@ function normalizeEntry(value: string | FileEntry): FileEntry {
   return value;
 }
 
+// ── shared layers ────────────────────────────────────────────────────
+
+/** Parse `generation.shared` from the manifest and resolve roots to absolute paths. */
+export function readSharedLayers(projectDir: string): SharedLayerConfig[] {
+  const manifest = readManifest(projectDir);
+  const shared = manifest.generation?.shared;
+  if (!shared || typeof shared !== "object") return [];
+
+  return Object.entries(shared).map(([name, config]) => {
+    const cfg = config as Record<string, any>;
+    return {
+      name,
+      platforms: Array.isArray(cfg.platforms) ? cfg.platforms : [],
+      language: typeof cfg.language === "string" ? cfg.language : "",
+      root: resolve(projectDir, cfg.root ?? "."),
+      paths: typeof cfg.paths === "object" && cfg.paths !== null ? cfg.paths : {},
+      tracks: Array.isArray(cfg.tracks) ? cfg.tracks : [],
+      scope: typeof cfg.scope === "string" ? cfg.scope : "",
+    };
+  });
+}
+
+/** Return shared layers whose `platforms` array includes the given target. */
+export function sharedLayersForTarget(projectDir: string, target: string): SharedLayerConfig[] {
+  return readSharedLayers(projectDir).filter((layer) => layer.platforms.includes(target));
+}
+
+/** Returns the state file path for a shared layer. */
+export function sharedLayerStatePath(layer: SharedLayerConfig): string {
+  return join(layer.root, `.openuispec-shared-${layer.name}.json`);
+}
+
+/** Read an existing shared layer state file, or null if it doesn't exist. */
+export function readSharedLayerState(layer: SharedLayerConfig): SharedLayerState | null {
+  try {
+    return JSON.parse(readFileSync(sharedLayerStatePath(layer), "utf-8"));
+  } catch {
+    return null;
+  }
+}
+
+/** Filter spec files to only those in the given categories. */
+function filterSpecFilesByCategories(
+  projectDir: string,
+  files: string[],
+  categories: string[]
+): string[] {
+  const catSet = new Set(categories);
+  return files.filter((f) => catSet.has(specCategory(relative(projectDir, f))));
+}
+
+/** Create a snapshot of spec state for a shared layer. */
+export function createSharedSnapshot(
+  cwd: string,
+  layerName: string,
+  generatedByTarget: string
+): SnapshotResult {
+  const projectDir = findProjectDir(cwd);
+  const layers = readSharedLayers(projectDir);
+  const layer = layers.find((l) => l.name === layerName);
+  if (!layer) {
+    throw new Error(`Shared layer "${layerName}" not found in generation.shared`);
+  }
+
+  const manifest = readManifest(projectDir);
+  const allFiles = discoverSpecFiles(projectDir);
+  const files = filterSpecFilesByCategories(projectDir, allFiles, layer.tracks);
+  const baseline = captureBaseline(projectDir, allFiles);
+
+  const { entries, stubs: stubCount } = buildFileEntries(projectDir, files);
+
+  const state: SharedLayerState = {
+    spec_version: manifest.spec_version ?? "0.1",
+    snapshot_at: new Date().toISOString(),
+    layer_name: layerName,
+    generated_by_target: generatedByTarget,
+    baseline,
+    files: entries,
+  };
+
+  const outPath = sharedLayerStatePath(layer);
+  writeFileSync(outPath, JSON.stringify(state, null, 2) + "\n");
+
+  return {
+    target: `shared:${layerName}`,
+    snapshot_at: state.snapshot_at,
+    files_hashed: Object.keys(entries).length,
+    stubs: stubCount,
+    state_path: relative(cwd, outPath),
+    baseline: formatBaseline(baseline),
+  };
+}
+
+/** Compute drift for a shared layer against its saved state. */
+export function computeSharedDrift(
+  projectDir: string,
+  layer: SharedLayerConfig
+): SharedLayerDriftResult {
+  const state = readSharedLayerState(layer);
+  if (!state) {
+    return {
+      layer,
+      drift: { changed: [], added: [], removed: [], unchanged: [] },
+      state: null,
+    };
+  }
+
+  const allFiles = discoverSpecFiles(projectDir);
+  const files = filterSpecFilesByCategories(projectDir, allFiles, layer.tracks);
+  const { entries: current } = buildFileEntries(projectDir, files);
+
+  const drift: DriftResult = { changed: [], added: [], removed: [], unchanged: [] };
+
+  for (const [rel, entry] of Object.entries(current)) {
+    const snapshotEntry = state.files[rel]
+      ? normalizeEntry(state.files[rel] as string | FileEntry)
+      : null;
+    if (!snapshotEntry) {
+      drift.added.push(rel);
+    } else if (snapshotEntry.hash !== entry.hash) {
+      drift.changed.push(rel);
+    } else {
+      drift.unchanged.push(rel);
+    }
+  }
+
+  for (const rel of Object.keys(state.files)) {
+    if (!(rel in current)) {
+      drift.removed.push(rel);
+    }
+  }
+
+  return { layer, drift, state };
+}
+
+/** Read `generation.structure[target]` from the manifest. */
+export function readTargetStructure(
+  projectDir: string,
+  target: string
+): { root: string; paths: Record<string, string>; scope: string } | null {
+  const manifest = readManifest(projectDir);
+  const structure = manifest.generation?.structure?.[target];
+  if (!structure || typeof structure !== "object" || typeof structure.root !== "string") {
+    return null;
+  }
+  return {
+    root: resolve(projectDir, structure.root),
+    paths: typeof structure.paths === "object" && structure.paths !== null ? structure.paths : {},
+    scope: typeof structure.scope === "string" ? structure.scope : "",
+  };
+}
+
 // ── snapshot ──────────────────────────────────────────────────────────
 
 export interface SnapshotResult {
@@ -561,16 +767,7 @@ export function createSnapshot(cwd: string, target: string): SnapshotResult {
   const manifest = readManifest(projectDir);
   const files = discoverSpecFiles(projectDir);
   const baseline = captureBaseline(projectDir, files);
-
-  const entries: Record<string, FileEntry> = {};
-  let stubCount = 0;
-
-  for (const f of files) {
-    const rel = relative(projectDir, f);
-    const status = hasStatusSemantics(rel) ? readStatus(f) : "ready";
-    entries[rel] = { hash: hashFile(f), status };
-    if (status === "stub") stubCount++;
-  }
+  const { entries, stubs: stubCount } = buildFileEntries(projectDir, files);
 
   const state: StateFile = {
     spec_version: manifest.spec_version ?? "0.1",
@@ -583,6 +780,20 @@ export function createSnapshot(cwd: string, target: string): SnapshotResult {
   const outPath = stateFilePath(projectDir, projectName, target);
   writeFileSync(outPath, JSON.stringify(state, null, 2) + "\n");
 
+  // Auto-snapshot shared layers with tracks for this target if their state file doesn't exist yet
+  const sharedLayers = sharedLayersForTarget(projectDir, target);
+  for (const layer of sharedLayers) {
+    if (layer.tracks.length === 0) continue;
+    const layerStatePath = sharedLayerStatePath(layer);
+    if (!existsSync(layerStatePath) && existsSync(layer.root)) {
+      try {
+        createSharedSnapshot(cwd, layer.name, target);
+      } catch {
+        // Non-fatal: shared layer snapshot is best-effort during target snapshot
+      }
+    }
+  }
+
   return {
     target,
     snapshot_at: state.snapshot_at,
@@ -619,6 +830,7 @@ export interface CheckResult {
   stubDrift: DriftResult;
   statuses: Record<string, string>;
   explanation?: ExplainResult;
+  shared_layer_drift?: SharedLayerDriftResult[];
 }
 
 export function computeDrift(
@@ -627,13 +839,7 @@ export function computeDrift(
   includeAll: boolean
 ): CheckResult {
   const files = discoverSpecFiles(projectDir);
-
-  const current: Record<string, FileEntry> = {};
-  for (const f of files) {
-    const rel = relative(projectDir, f);
-    const status = hasStatusSemantics(rel) ? readStatus(f) : "ready";
-    current[rel] = { hash: hashFile(f), status };
-  }
+  const { entries: current } = buildFileEntries(projectDir, files);
 
   const drift: DriftResult = { changed: [], added: [], removed: [], unchanged: [] };
   const stubDrift: DriftResult = { changed: [], added: [], removed: [], unchanged: [] };
@@ -688,6 +894,15 @@ export function loadTargetDrift(
     result.explanation = explainDrift(projectDir, result);
   }
 
+  // Include shared layer drift for this target (only layers with tracks configured)
+  const sharedLayers = sharedLayersForTarget(projectDir, target);
+  const trackingLayers = sharedLayers.filter((l) => l.tracks.length > 0);
+  if (trackingLayers.length > 0) {
+    result.shared_layer_drift = trackingLayers.map((layer) =>
+      computeSharedDrift(projectDir, layer)
+    );
+  }
+
   return { projectDir, projectName, statePath, result };
 }
 

package/examples/taskflow/README.md

@@ -87,7 +87,7 @@ taskflow/
 
 Pass the entire `taskflow/` directory as context to an AI code generator with the prompt:
 
-> Generate a native {ios|android|web} application from this OpenUISpec. Follow all contract state machines, apply token ranges for the target platform, and implement the navigation flows as defined. Use the platform adaptation file for target-specific overrides.
+> Generate a native {ios|android|web} application from this OpenUISpec. Follow all contract UI states, apply token ranges for the target platform, and implement the navigation flows as defined. Use the platform adaptation file for target-specific overrides.
 
 The AI should produce:
 1. Compilable platform code (Swift/Kotlin/TypeScript)

package/mcp-server/index.ts

@@ -147,9 +147,12 @@ server.registerTool(
       const baselineReminder = baselinePending
         ? " ⚠ Baseline pending — remind user to run `openuispec drift --snapshot --target " + target + "` when satisfied."
         : "";
+      const sharedHint = result.shared_layers?.length
+        ? ` ℹ ${result.shared_layers.length} shared layer(s) detected — check shared_layers for generation guidance.`
+        : "";
       const hint = (include_specs
         ? "next_tool: openuispec_check (after generating code)"
-        : "next_tool: openuispec_read_specs (load spec contents for generation)") + baselineReminder;
+        : "next_tool: openuispec_read_specs (load spec contents for generation)") + baselineReminder + sharedHint;
       return toolResult(result, hint);
     } catch (err) {
       return toolError(err);
@@ -676,6 +679,25 @@ server.registerTool(
   }
 );
 
+// ── locale key lookup (supports both flat dotted keys and nested objects) ──
+
+function lookupLocaleKey(content: Record<string, unknown>, key: string): { found: boolean; value: unknown } {
+  // 1. Try flat (literal) key first: { "nav.tasks": "Tasks" }
+  if (key in content) {
+    return { found: true, value: content[key] };
+  }
+  // 2. Try nested path: { nav: { tasks: "Tasks" } }
+  const parts = key.split(".");
+  let current: unknown = content;
+  for (const part of parts) {
+    if (current === null || current === undefined || typeof current !== "object" || Array.isArray(current)) {
+      return { found: false, value: undefined };
+    }
+    current = (current as Record<string, unknown>)[part];
+  }
+  return current !== undefined ? { found: true, value: current } : { found: false, value: undefined };
+}
+
 // ── tool: openuispec_get_locale ─────────────────────────────────────
 
 server.registerTool(
@@ -710,9 +732,8 @@ server.registerTool(
       if (keys && keys.length > 0) {
         const filtered: Record<string, unknown> = {};
         for (const key of keys) {
-          if (key in content) {
-            filtered[key] = content[key];
-          }
+          const { found, value } = lookupLocaleKey(content, key);
+          if (found) filtered[key] = value;
         }
         return toolResult({ locale, path: relative(projectDir, filePath), content: filtered });
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openuispec",
-  "version": "0.2.11",
+  "version": "0.2.13",
   "license": "MIT",
   "type": "module",
   "description": "A semantic UI specification format for AI-native, platform-native app development",

package/prepare/index.ts

@@ -21,10 +21,17 @@ import {
   readManifest,
   readProjectName,
   readStatus,
+  hasDriftChanges,
+  readSharedLayerState,
+  readTargetStructure,
   resolveOutputDir,
+  sharedLayersForTarget,
+  specCategory,
+  computeSharedDrift,
   type FileExplanation,
   type ExplainResult,
   type SemanticChange,
+  type SharedLayerConfig,
 } from "../drift/index.js";
 
 interface PrepareItem {
@@ -116,6 +123,20 @@ interface PrepareBootstrapBundle {
   reference_examples: string[];
 }
 
+interface SharedLayerInfo {
+  name: string;
+  platforms: string[];
+  language: string;
+  root: string;
+  paths: Record<string, string>;
+  scope: string;
+  tracks: string[];
+  already_generated: boolean;
+  generated_by_target: string | null;
+  has_drift: boolean;
+  guidance: string;
+}
+
 interface SpecFileContent {
   path: string;
   category: string;
@@ -148,6 +169,7 @@ export interface PrepareResult {
   changes_available: boolean;
   explanation_note?: string;
   items: PrepareItem[];
+  shared_layers?: SharedLayerInfo[];
   bootstrap?: PrepareBootstrapBundle;
   spec_contents?: SpecFileContent[];
   next_steps: string[];
@@ -321,13 +343,88 @@ function resolveBackendRoot(projectDir: string, manifest: Record<string, any>):
   return resolve(projectDir, backendRoot);
 }
 
-function categorizeSpecFile(relPath: string): string {
-  if (relPath === "openuispec.yaml") return "manifest";
-  const group = relPath.split("/")[0];
-  return group || "other";
+// Use specCategory from drift/index.ts (imported above) instead of a local duplicate.
+const categorizeSpecFile = specCategory;
+
+function buildSharedLayerInfos(projectDir: string, target: string, layers?: SharedLayerConfig[]): SharedLayerInfo[] {
+  const resolvedLayers = layers ?? sharedLayersForTarget(projectDir, target);
+  if (resolvedLayers.length === 0) return [];
+
+  return resolvedLayers.map((layer) => {
+    const state = readSharedLayerState(layer);
+    const alreadyGenerated = state !== null;
+
+    // Only compute hash-based drift when tracks are configured
+    let hasDrift = false;
+    if (layer.tracks.length > 0) {
+      const driftResult = computeSharedDrift(projectDir, layer);
+      hasDrift = driftResult.state !== null && hasDriftChanges(driftResult.drift);
+    }
+
+    let guidance: string;
+    if (alreadyGenerated && !hasDrift) {
+      guidance = `Shared code already generated by ${state!.generated_by_target} — read existing code, don't regenerate.`;
+    } else if (alreadyGenerated && hasDrift) {
+      guidance = `Generated by ${state!.generated_by_target} but spec has drifted — review shared code for needed updates.`;
+    } else {
+      guidance = `Generate shared layer alongside ${target} platform code.`;
+    }
+
+    return {
+      name: layer.name,
+      platforms: layer.platforms,
+      language: layer.language,
+      root: layer.root,
+      paths: layer.paths,
+      scope: layer.scope,
+      tracks: layer.tracks,
+      already_generated: alreadyGenerated,
+      generated_by_target: state?.generated_by_target ?? null,
+      has_drift: hasDrift,
+      guidance,
+    };
+  });
+}
+
+function collectSharedLayerPaths(layers: SharedLayerConfig[]): string[] {
+  const paths: string[] = [];
+  for (const layer of layers) {
+    paths.push(layer.root);
+    for (const p of Object.values(layer.paths)) {
+      paths.push(resolve(layer.root, p));
+    }
+  }
+  return paths;
 }
 
-function suggestCodeRoots(target: string, outputDir: string): string[] {
+function dedupeExistingPaths(candidates: string[]): string[] {
+  const seen = new Set<string>();
+  return candidates
+    .map((c) => resolve(c))
+    .filter((c) => existsSync(c))
+    .filter((c) => {
+      if (seen.has(c)) return false;
+      seen.add(c);
+      return true;
+    });
+}
+
+function suggestCodeRoots(target: string, outputDir: string, projectDir?: string, sharedLayers?: SharedLayerConfig[]): string[] {
+  const layers = sharedLayers ?? (projectDir ? sharedLayersForTarget(projectDir, target) : []);
+
+  // When generation.structure is defined for the target, use it instead of heuristics
+  if (projectDir) {
+    const structure = readTargetStructure(projectDir, target);
+    if (structure) {
+      const candidates = [
+        structure.root,
+        ...Object.values(structure.paths).map((p) => resolve(structure.root, p)),
+        ...collectSharedLayerPaths(layers),
+      ];
+      return dedupeExistingPaths(candidates);
+    }
+  }
+
   const candidates: string[] = [];
 
   if (target === "web") {
@@ -345,15 +442,8 @@ function suggestCodeRoots(target: string, outputDir: string): string[] {
     candidates.push(outputDir);
   }
 
-  const seen = new Set<string>();
-  return candidates
-    .map((candidate) => resolve(candidate))
-    .filter((candidate) => existsSync(candidate))
-    .filter((candidate) => {
-      if (seen.has(candidate)) return false;
-      seen.add(candidate);
-      return true;
-    });
+  candidates.push(...collectSharedLayerPaths(layers));
+  return dedupeExistingPaths(candidates);
 }
 
 function walkFiles(root: string, files: string[], depth = 0): void {
@@ -511,7 +601,7 @@ function buildBootstrapNotes(category: string, target: string, specStatus: strin
   return notes;
 }
 
-function generationRules(target: string, outputDir: string, manifest: Record<string, any>): string[] {
+function generationRules(target: string, outputDir: string, manifest: Record<string, any>, sharedLayers?: SharedLayerInfo[]): string[] {
   const outputFormat = manifest.generation?.output_format?.[target] ?? {};
   const rules = [
     "Read openuispec.yaml first, then follow the referenced spec files instead of inventing structure from memory.",
@@ -528,6 +618,31 @@ function generationRules(target: string, outputDir: string, manifest: Record<str
     );
   }
 
+  if (sharedLayers && sharedLayers.length > 0) {
+    for (const layer of sharedLayers) {
+      if (layer.already_generated) {
+        rules.push(
+          `Shared layer "${layer.name}" already generated by ${layer.generated_by_target}. Read the existing code under ${layer.root} instead of regenerating it.`
+        );
+      } else {
+        rules.push(
+          `Generate shared layer "${layer.name}" (${layer.language}) under ${layer.root} alongside ${target} platform code.`
+        );
+      }
+      if (layer.scope) {
+        rules.push(
+          `Shared layer "${layer.name}" scope: ${layer.scope}`
+        );
+      }
+    }
+  }
+
+  // Include target structure scope when defined
+  const structure = manifest.generation?.structure?.[target];
+  if (structure?.scope) {
+    rules.push(`Target "${target}" scope: ${structure.scope}`);
+  }
+
   return rules;
 }
 
@@ -1070,8 +1185,10 @@ function buildBootstrapPrepareResult(cwd: string, target: string, includeContent
   const platformDef = readPlatformDefinition(projectDir, manifest, target);
   const platformConfig = buildPlatformConfig(target, platformDef);
   const outputFormat = manifest.generation?.output_format?.[target] ?? {};
-  const codeRoots = suggestCodeRoots(target, outputDir);
+  const sharedLayerConfigs = sharedLayersForTarget(projectDir, target);
+  const codeRoots = suggestCodeRoots(target, outputDir, projectDir, sharedLayerConfigs);
   const missingDecisions = missingPlatformDecisions(target, platformDef);
+  const sharedLayerInfos = buildSharedLayerInfos(projectDir, target, sharedLayerConfigs);
   const backendRoot = resolveBackendRoot(projectDir, manifest);
   const backendContextReady = true; // backend is optional — not a generation blocker
   const pendingUserConfirmation = platformConfig.stack_confirmation.requires_user_confirmation;
@@ -1140,6 +1257,7 @@ function buildBootstrapPrepareResult(cwd: string, target: string, includeContent
     changes_available: false,
     explanation_note: "No snapshot exists yet. This is a first-time generation bundle.",
     items: [],
+    ...(sharedLayerInfos.length > 0 ? { shared_layers: sharedLayerInfos } : {}),
     ...(includeContents ? { spec_contents: readAllSpecContents(projectDir) } : {}),
     bootstrap: {
       output_exists: existsSync(outputDir),
@@ -1157,7 +1275,7 @@ function buildBootstrapPrepareResult(cwd: string, target: string, includeContent
         supported_locales: manifest.i18n?.supported_locales ?? [],
       },
       spec_files: bootstrapSpecFiles(projectDir, target),
-      generation_rules: generationRules(target, outputDir, manifest),
+      generation_rules: generationRules(target, outputDir, manifest, sharedLayerInfos),
       generation_constraints: generationConstraints(target, platformConfig),
       generation_warnings: generationWarnings(target, platformConfig),
       reference_examples: referenceExamples(),
@@ -1169,8 +1287,10 @@ function buildBootstrapPrepareResult(cwd: string, target: string, includeContent
 function buildUpdatePrepareResult(cwd: string, target: string, includeContents: boolean = false): PrepareResult {
   const { projectDir, projectName, result } = loadTargetDrift(cwd, target, false, true);
   const outputDir = resolveOutputDir(projectDir, projectName, target);
-  const codeRoots = suggestCodeRoots(target, outputDir);
+  const sharedLayerConfigs = sharedLayersForTarget(projectDir, target);
+  const codeRoots = suggestCodeRoots(target, outputDir, projectDir, sharedLayerConfigs);
   const manifest = readManifest(projectDir);
+  const sharedLayerInfos = buildSharedLayerInfos(projectDir, target, sharedLayerConfigs);
   const platformDef = readPlatformDefinition(projectDir, manifest, target);
   const platformConfig = buildPlatformConfig(target, platformDef);
   const outputFormat = manifest.generation?.output_format?.[target] ?? {};
@@ -1211,6 +1331,7 @@ function buildUpdatePrepareResult(cwd: string, target: string, includeContents:
     changes_available: result.explanation?.available ?? false,
     explanation_note: result.explanation?.note,
     items,
+    ...(sharedLayerInfos.length > 0 ? { shared_layers: sharedLayerInfos } : {}),
     ...(includeContents ? { spec_contents: readAllSpecContents(projectDir) } : {}),
     next_steps: nextSteps,
   };

package/schema/custom-contract.schema.json

@@ -30,7 +30,7 @@
         },
         "states": {
           "type": "object",
-          "description": "State machine definition — each key is a state name",
+          "description": "UI interaction states (e.g. idle, active, disabled, loading, error) — each key is a state name. These are visual/interaction states, not business logic states.",
           "additionalProperties": {
             "$ref": "https://openuispec.rsteam.uz/schema/custom-contract.schema.json#/$defs/state_def"
           }
@@ -165,7 +165,7 @@
     },
     "state_def": {
       "type": "object",
-      "description": "A single state in the state machine",
+      "description": "A single UI interaction state",
       "properties": {
         "semantic": {
           "type": "string"