capy-mcp 1.0.2 → 1.0.4

package/README.md

@@ -6,9 +6,10 @@ It does not generate the preview page itself. It gives an AI coding agent the re
 
 ## What it exposes
 
-The server currently registers two MCP tools:
+The server currently registers three MCP tools:
 
 - `get_preview_brief`
+- `update_preview`
 - `get_design_system`
 
 The tool accepts:
@@ -29,6 +30,8 @@ The tool returns structured content with:
 
 `get_design_system` writes a stable JSON artifact, by default at `.capy/design-system.json`, and returns a summary plus the artifact contents. This file is meant to be the machine-readable source of truth that later coding sessions can load before making UI changes.
 
+`update_preview` writes `.capy/preview-state.json`, diffs the current repo against the prior snapshot, refreshes `.capy/design-system.json`, and returns an incremental `/preview` update brief. This works even if the repo is not using git.
+
 ## Install
 
 ```bash
@@ -62,8 +65,11 @@ Example stdio MCP config:
 import {
   buildDesignSystemArtifact,
   buildPreviewBrief,
+  buildPreviewStateSnapshot,
   detectFramework,
+  runPreviewUpdate,
   writeDesignSystemArtifact,
+  writePreviewStateSnapshot,
 } from "capy-mcp";
 
 const framework = await detectFramework(process.cwd());
@@ -72,6 +78,9 @@ const brief = await buildPreviewBrief(process.cwd(), {
 });
 const designSystem = await buildDesignSystemArtifact(process.cwd());
 await writeDesignSystemArtifact(process.cwd());
+const previewState = await buildPreviewStateSnapshot(process.cwd());
+await writePreviewStateSnapshot(process.cwd(), ".capy/preview-state.json", previewState);
+const update = await runPreviewUpdate(process.cwd());
 ```
 
 ## Local development

package/dist/brief.js

@@ -3,6 +3,7 @@ import { buildProjectFacts } from "./project.js";
 const SECTION_ORDER = [
     "Foundations",
     "Colors",
+    "Icons",
     "Typography",
     "Spacing",
     "Inputs",
@@ -25,12 +26,18 @@ export async function buildPreviewBrief(projectRoot, input) {
             goal: input.task === "update_preview"
                 ? "Update the existing /preview surface incrementally based on the files or areas that changed."
                 : "Create a local /preview route that helps humans and agents inspect the app's real UI system quickly.",
-            layout: "vertical-scroll",
+            layout: "bidirectional-scroll",
             allowHorizontalRows: true,
             previewRoute: projectFacts.previewRoute,
             previewEntryFile: projectFacts.previewEntryFile,
             sections: SECTION_ORDER,
             useExistingComponentsFirst: true,
+            interactionFeatures: [
+                "Allow both vertical and horizontal scrolling when the preview surface benefits from a canvas-like layout.",
+                "Display icons used in the app in a dedicated section whenever they can be discovered from the repo.",
+                "Render color swatches in a consistent format with 6-character hex labels.",
+                "Use a pointer cursor and click-to-copy behavior for color hex values.",
+            ],
         },
         updateStrategy: buildUpdateStrategy(input.changedFiles),
         warnings,
@@ -80,10 +87,12 @@ function buildInspectionPlan(projectFacts) {
 function buildConstraints(framework) {
     const constraints = [
         "Do not invent colors, spacing, typography, or component APIs before inspecting the repo files listed in inspection_plan.",
-        "Build a vertically scrollable preview page.",
+        "Build a preview page that can support both vertical and horizontal scanning where useful.",
         "Use horizontal specimen rows only when they make scanning easier.",
         "Prefer existing components over creating preview-only components.",
         "Keep the page neat, easy to scan, and aligned with the app's current design language.",
+        "Include an icon inventory when the repo exposes app icons clearly enough to catalogue them.",
+        "Show colors in a uniform swatch format with normalized 6-character hex labels and click-to-copy affordance.",
     ];
     if (framework.needsConfirmation && framework.confirmationMessage) {
         constraints.push(framework.confirmationMessage);
@@ -119,7 +128,7 @@ function buildInstructions(projectFacts, input) {
         ? "Update the existing /preview route incrementally."
         : "Create the /preview route from scratch.";
     const userGoal = input.userGoal ? ` User goal: ${input.userGoal}.` : "";
-    return `${lead}${userGoal} Read the app shell first, then global styles, then component directories. After that, implement ${projectFacts.previewEntryFile} as a vertically scrollable preview surface using the repo's real design language and existing components.`;
+    return `${lead}${userGoal} Read the app shell first, then global styles, then component directories. After that, implement ${projectFacts.previewEntryFile} as a clean preview surface that supports both vertical and horizontal scanning when useful, includes a dedicated icon section when icons can be discovered, and renders colors as consistent swatches with 6-character hex labels plus click-to-copy behavior using a pointer cursor.`;
 }
 function uniqueCompact(values) {
     return Array.from(new Set(values.filter(Boolean)));

package/dist/design-system.js

@@ -15,25 +15,35 @@ export async function buildDesignSystemArtifact(projectRoot, input = {}) {
     });
     const cssVariables = await collectCssVariables(projectRoot, projectFacts.likelyStyleFiles);
     const components = await collectComponents(projectRoot, projectFacts);
+    const readFirst = buildReadFirst(previewBrief, components);
+    const bridges = await buildUsageBridges(projectRoot, projectFacts.likelyStyleFiles, components);
+    const gaps = buildGapNotes(projectFacts, components, cssVariables);
     const artifactPath = input.artifactPath ?? DEFAULT_ARTIFACT_PATH;
-    const sourceFiles = Array.from(new Set([
-        ...projectFacts.likelyStyleFiles,
-        ...components.map((component) => component.path),
-    ])).sort();
     return {
-        meta: {
+        forAgent: {
+            intent: input.mode === "update"
+                ? "Update /preview incrementally. Read the files below first, then touch only the sections affected by the changed files unless shared foundations changed."
+                : "Build or refine /preview. Read the files below first, then mirror the repo's existing UI language instead of inventing a new one.",
+            readFirst,
+            facts: buildAgentFacts(projectFacts, components, cssVariables),
+            bridges,
+            gaps,
+            updateHints: previewBrief.updateStrategy,
+        },
+        artifact: {
             generatedAt: new Date().toISOString(),
             mode: input.mode ?? "build",
             artifactPath,
+            changedFiles: input.changedFiles ?? [],
+        },
+        repo: {
             framework: framework.kind,
             routingStyle: framework.routingStyle,
             previewRoute: framework.previewRoute,
             previewEntryFile: framework.previewEntryFile,
             packageManager: framework.packageManager,
-            changedFiles: input.changedFiles ?? [],
-            sourceFiles,
         },
-        directories: {
+        scan: {
             componentDirs: projectFacts.likelyComponentDirs,
             pageDirs: projectFacts.likelyPageDirs,
             styleFiles: projectFacts.likelyStyleFiles,
@@ -41,31 +51,23 @@ export async function buildDesignSystemArtifact(projectRoot, input = {}) {
         },
         tokens: {
             cssVariables,
-            styleFiles: projectFacts.likelyStyleFiles,
+            themeSourceFiles: projectFacts.likelyStyleFiles,
+        },
+        components: {
+            count: components.length,
+            items: components,
         },
-        components,
         preview: {
             route: projectFacts.previewRoute,
             entryFile: projectFacts.previewEntryFile,
             sections: previewBrief.deliverableSpec.sections,
             updateStrategy: previewBrief.updateStrategy,
         },
-        guidance: {
-            summary: buildSummary(projectFacts, framework, components, cssVariables),
-            warnings: previewBrief.warnings,
-            instructions: [
-                "Read this file before making UI changes or updating /preview.",
-                "Prefer the listed components, tokens, and preview sections over inventing new UI structure.",
-                input.mode === "update"
-                    ? "When updating, inspect changedFiles first and only refresh affected sections unless foundations changed."
-                    : "If this artifact looks incomplete, inspect the listed sourceFiles before expanding it.",
-            ],
-        },
     };
 }
 export async function writeDesignSystemArtifact(projectRoot, input = {}) {
     const artifact = await buildDesignSystemArtifact(projectRoot, input);
-    const artifactFile = join(projectRoot, artifact.meta.artifactPath);
+    const artifactFile = join(projectRoot, artifact.artifact.artifactPath);
     await writeText(artifactFile, `${JSON.stringify(artifact, null, 2)}\n`);
     return artifact;
 }
@@ -126,14 +128,6 @@ async function collectComponents(projectRoot, projectFacts) {
     }));
     return componentRecords;
 }
-function buildSummary(projectFacts, framework, components, cssVariables) {
-    return [
-        `Framework: ${framework.label}.`,
-        `Preview target: ${projectFacts.previewEntryFile}.`,
-        `Found ${components.length} component candidates and ${cssVariables.length} CSS variables.`,
-        "Use this artifact as the canonical machine-readable UI map before editing the app or /preview.",
-    ].join(" ");
-}
 function extractExports(contents) {
     const exports = new Set();
     const patterns = [
@@ -174,3 +168,96 @@ function classifyCssVariable(name) {
 function lineNumberAt(contents, index) {
     return contents.slice(0, index).split("\n").length;
 }
+function buildReadFirst(previewBrief, components) {
+    const seen = new Set();
+    const readFirst = [];
+    const firstComponentByDir = new Map();
+    for (const component of components) {
+        const slashIndex = component.path.lastIndexOf("/");
+        if (slashIndex === -1)
+            continue;
+        const directory = component.path.slice(0, slashIndex);
+        if (!firstComponentByDir.has(directory)) {
+            firstComponentByDir.set(directory, component.path);
+        }
+    }
+    for (const step of previewBrief.inspectionPlan) {
+        for (const target of step.targets) {
+            const normalizedTarget = firstComponentByDir.get(target) ?? target;
+            if (seen.has(normalizedTarget))
+                continue;
+            seen.add(normalizedTarget);
+            readFirst.push({
+                path: normalizedTarget,
+                reason: step.reason,
+            });
+            if (readFirst.length >= 8) {
+                return readFirst;
+            }
+        }
+    }
+    return readFirst;
+}
+function buildAgentFacts(projectFacts, components, cssVariables) {
+    return [
+        `Use ${projectFacts.framework} conventions.`,
+        `Implement /preview at ${projectFacts.previewEntryFile}.`,
+        "Use repo-relative paths only.",
+        `Found ${components.length} component candidates and ${cssVariables.length} CSS variables.`,
+    ];
+}
+function buildGapNotes(projectFacts, components, cssVariables) {
+    const gaps = [];
+    if (components.length === 0) {
+        gaps.push("No components were detected. Grep src/components, src/ui, src/features, components, ui, or features before assuming the app has no reusable UI.");
+    }
+    if (cssVariables.length === 0 && projectFacts.likelyStyleFiles.length > 0) {
+        gaps.push(`No CSS variables were detected. Read ${projectFacts.likelyStyleFiles[0]} directly and look for literal classes, theme config, or inline color tokens.`);
+    }
+    if (projectFacts.likelyStyleFiles.length === 0) {
+        gaps.push("No global style files were detected. Inspect app shell files and component code directly for layout and color usage.");
+    }
+    return gaps;
+}
+async function buildUsageBridges(projectRoot, styleFiles, components) {
+    const bridges = [];
+    for (const relativePath of styleFiles) {
+        const fileContents = await readText(join(projectRoot, relativePath));
+        if (!fileContents)
+            continue;
+        if (fileContents.includes("hsl(var(--")) {
+            bridges.push(`Theme tokens are bridged through hsl(var(--...)) in ${relativePath}.`);
+            break;
+        }
+    }
+    const hexByFile = await collectHexLiterals(projectRoot, components);
+    for (const [path, hexValues] of hexByFile.slice(0, 3)) {
+        bridges.push(`Literal accents also appear in ${path}: ${hexValues.join(", ")}.`);
+    }
+    return bridges;
+}
+async function collectHexLiterals(projectRoot, components) {
+    const matches = [];
+    for (const component of components) {
+        const contents = await readText(join(projectRoot, component.path));
+        if (!contents)
+            continue;
+        const hexMatches = Array.from(contents.matchAll(/#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6})\b/g))
+            .map((match) => normalizeHex(match[0]))
+            .filter((value, index, values) => values.indexOf(value) === index);
+        if (hexMatches.length > 0) {
+            matches.push([component.path, hexMatches.slice(0, 4)]);
+        }
+    }
+    return matches;
+}
+function normalizeHex(hex) {
+    const normalized = hex.replace("#", "").toUpperCase();
+    if (normalized.length === 3) {
+        return `#${normalized
+            .split("")
+            .map((char) => `${char}${char}`)
+            .join("")}`;
+    }
+    return `#${normalized}`;
+}

package/dist/index.d.ts

@@ -2,4 +2,5 @@ export { buildPreviewBrief } from "./brief.js";
 export { buildDesignSystemArtifact, writeDesignSystemArtifact } from "./design-system.js";
 export { detectFramework } from "./framework.js";
 export { createServer, main } from "./server.js";
-export type { ComponentRecord, CssVariableRecord, DesignSystemArtifact, DesignSystemBuildInput, DeliverableSpec, FrameworkInfo, FrameworkKind, InspectionStep, PreviewBrief, ProjectFacts, RoutingStyle, } from "./types.js";
+export { buildPreviewStateSnapshot, runPreviewUpdate, writePreviewStateSnapshot } from "./update.js";
+export type { ComponentRecord, CssVariableRecord, DesignSystemArtifact, DesignSystemBuildInput, DeliverableSpec, FrameworkInfo, FrameworkKind, InspectionStep, PreviewBrief, PreviewStateSnapshot, PreviewUpdateInput, PreviewUpdateResult, ProjectFacts, RoutingStyle, } from "./types.js";

package/dist/index.js

@@ -2,3 +2,4 @@ export { buildPreviewBrief } from "./brief.js";
 export { buildDesignSystemArtifact, writeDesignSystemArtifact } from "./design-system.js";
 export { detectFramework } from "./framework.js";
 export { createServer, main } from "./server.js";
+export { buildPreviewStateSnapshot, runPreviewUpdate, writePreviewStateSnapshot } from "./update.js";

package/dist/server.js

@@ -4,10 +4,93 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { z } from "zod";
 import { buildPreviewBrief } from "./brief.js";
 import { writeDesignSystemArtifact } from "./design-system.js";
+import { runPreviewUpdate } from "./update.js";
+function buildPreviewBriefSchema() {
+    return {
+        project_facts: z.object({
+            framework: z.enum([
+                "next-app-router",
+                "next-pages-router",
+                "react-router",
+                "react-no-router",
+                "unknown",
+            ]),
+            routing_style: z.enum([
+                "app-router",
+                "pages-router",
+                "react-router",
+                "none",
+                "unknown",
+            ]),
+            preview_route: z.string(),
+            preview_entry_file: z.string(),
+            package_manager: z.enum(["npm", "pnpm", "yarn", "bun"]),
+            likely_component_dirs: z.array(z.string()),
+            likely_style_files: z.array(z.string()),
+            likely_page_dirs: z.array(z.string()),
+            likely_ui_dirs: z.array(z.string()),
+        }),
+        inspection_plan: z.array(z.object({
+            step: z.number(),
+            action: z.string(),
+            targets: z.array(z.string()),
+            reason: z.string(),
+        })),
+        constraints: z.array(z.string()),
+        deliverable_spec: z.object({
+            goal: z.string(),
+            layout: z.literal("bidirectional-scroll"),
+            allow_horizontal_rows: z.boolean(),
+            preview_route: z.string(),
+            preview_entry_file: z.string(),
+            sections: z.array(z.string()),
+            use_existing_components_first: z.boolean(),
+            interaction_features: z.array(z.string()),
+        }),
+        update_strategy: z.array(z.string()),
+        warnings: z.array(z.string()),
+        instructions: z.string(),
+    };
+}
+function toStructuredPreviewBrief(brief) {
+    return {
+        project_facts: {
+            framework: brief.projectFacts.framework,
+            routing_style: brief.projectFacts.routingStyle,
+            preview_route: brief.projectFacts.previewRoute,
+            preview_entry_file: brief.projectFacts.previewEntryFile,
+            package_manager: brief.projectFacts.packageManager,
+            likely_component_dirs: brief.projectFacts.likelyComponentDirs,
+            likely_style_files: brief.projectFacts.likelyStyleFiles,
+            likely_page_dirs: brief.projectFacts.likelyPageDirs,
+            likely_ui_dirs: brief.projectFacts.likelyUiDirs,
+        },
+        inspection_plan: brief.inspectionPlan.map((item) => ({
+            step: item.step,
+            action: item.action,
+            targets: item.targets,
+            reason: item.reason,
+        })),
+        constraints: brief.constraints,
+        deliverable_spec: {
+            goal: brief.deliverableSpec.goal,
+            layout: brief.deliverableSpec.layout,
+            allow_horizontal_rows: brief.deliverableSpec.allowHorizontalRows,
+            preview_route: brief.deliverableSpec.previewRoute,
+            preview_entry_file: brief.deliverableSpec.previewEntryFile,
+            sections: brief.deliverableSpec.sections,
+            use_existing_components_first: brief.deliverableSpec.useExistingComponentsFirst,
+            interaction_features: brief.deliverableSpec.interactionFeatures,
+        },
+        update_strategy: brief.updateStrategy,
+        warnings: brief.warnings,
+        instructions: brief.instructions,
+    };
+}
 export function createServer(projectRoot = process.cwd()) {
     const server = new McpServer({
         name: "capy",
-        version: "1.0.2",
+        version: "1.0.4",
     });
     server.registerTool("get_preview_brief", {
         title: "Get Preview Brief",
@@ -26,87 +109,69 @@ export function createServer(projectRoot = process.cwd()) {
                 .optional()
                 .describe("The user's request, so the returned instructions can stay aligned."),
         },
-        outputSchema: {
-            project_facts: z.object({
-                framework: z.enum([
-                    "next-app-router",
-                    "next-pages-router",
-                    "react-router",
-                    "react-no-router",
-                    "unknown",
-                ]),
-                routing_style: z.enum([
-                    "app-router",
-                    "pages-router",
-                    "react-router",
-                    "none",
-                    "unknown",
-                ]),
-                preview_route: z.string(),
-                preview_entry_file: z.string(),
-                package_manager: z.enum(["npm", "pnpm", "yarn", "bun"]),
-                likely_component_dirs: z.array(z.string()),
-                likely_style_files: z.array(z.string()),
-                likely_page_dirs: z.array(z.string()),
-                likely_ui_dirs: z.array(z.string()),
-            }),
-            inspection_plan: z.array(z.object({
-                step: z.number(),
-                action: z.string(),
-                targets: z.array(z.string()),
-                reason: z.string(),
-            })),
-            constraints: z.array(z.string()),
-            deliverable_spec: z.object({
-                goal: z.string(),
-                layout: z.literal("vertical-scroll"),
-                allow_horizontal_rows: z.boolean(),
-                preview_route: z.string(),
-                preview_entry_file: z.string(),
-                sections: z.array(z.string()),
-                use_existing_components_first: z.boolean(),
-            }),
-            update_strategy: z.array(z.string()),
-            warnings: z.array(z.string()),
-            instructions: z.string(),
-        },
+        outputSchema: buildPreviewBriefSchema(),
     }, async ({ task = "build_preview", changedFiles, userGoal }) => {
         const brief = await buildPreviewBrief(projectRoot, {
             task,
             changedFiles,
             userGoal,
         });
+        const structuredContent = toStructuredPreviewBrief(brief);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(structuredContent, null, 2),
+                },
+            ],
+            structuredContent,
+        };
+    });
+    server.registerTool("update_preview", {
+        title: "Update Preview",
+        description: "Diffs the current repo against Capy's last snapshot, refreshes the design-system artifact, and returns an incremental /preview update brief. Works even when the repo is not a git repository.",
+        inputSchema: {
+            snapshotPath: z
+                .string()
+                .default(".capy/preview-state.json")
+                .describe("Where Capy stores the previous file-hash snapshot relative to the repo root."),
+            designSystemPath: z
+                .string()
+                .default(".capy/design-system.json")
+                .describe("Where to refresh the machine-readable design-system artifact."),
+            changedFiles: z
+                .array(z.string())
+                .optional()
+                .describe("Optional manual override for changed files. If omitted, Capy diffs against its last snapshot."),
+            userGoal: z
+                .string()
+                .optional()
+                .describe("Optional user request to keep the update brief aligned with the task."),
+        },
+        outputSchema: {
+            snapshot_path: z.string(),
+            design_system_path: z.string(),
+            changed_files: z.array(z.string()),
+            baseline_created: z.boolean(),
+            used_manual_changed_files: z.boolean(),
+            warnings: z.array(z.string()),
+            preview_update_brief: z.object(buildPreviewBriefSchema()),
+        },
+    }, async ({ snapshotPath = ".capy/preview-state.json", designSystemPath = ".capy/design-system.json", changedFiles, userGoal, }) => {
+        const result = await runPreviewUpdate(projectRoot, {
+            snapshotPath,
+            designSystemPath,
+            changedFiles,
+            userGoal,
+        });
         const structuredContent = {
-            project_facts: {
-                framework: brief.projectFacts.framework,
-                routing_style: brief.projectFacts.routingStyle,
-                preview_route: brief.projectFacts.previewRoute,
-                preview_entry_file: brief.projectFacts.previewEntryFile,
-                package_manager: brief.projectFacts.packageManager,
-                likely_component_dirs: brief.projectFacts.likelyComponentDirs,
-                likely_style_files: brief.projectFacts.likelyStyleFiles,
-                likely_page_dirs: brief.projectFacts.likelyPageDirs,
-                likely_ui_dirs: brief.projectFacts.likelyUiDirs,
-            },
-            inspection_plan: brief.inspectionPlan.map((item) => ({
-                step: item.step,
-                action: item.action,
-                targets: item.targets,
-                reason: item.reason,
-            })),
-            constraints: brief.constraints,
-            deliverable_spec: {
-                goal: brief.deliverableSpec.goal,
-                layout: brief.deliverableSpec.layout,
-                allow_horizontal_rows: brief.deliverableSpec.allowHorizontalRows,
-                preview_route: brief.deliverableSpec.previewRoute,
-                preview_entry_file: brief.deliverableSpec.previewEntryFile,
-                sections: brief.deliverableSpec.sections,
-                use_existing_components_first: brief.deliverableSpec.useExistingComponentsFirst,
-            },
-            update_strategy: brief.updateStrategy,
-            warnings: brief.warnings,
-            instructions: brief.instructions,
+            snapshot_path: result.snapshotPath,
+            design_system_path: result.designSystemPath,
+            changed_files: result.changedFiles,
+            baseline_created: result.baselineCreated,
+            used_manual_changed_files: result.usedManualChangedFiles,
+            warnings: result.warnings,
+            preview_update_brief: toStructuredPreviewBrief(result.previewBrief),
         };
         return {
             content: [
@@ -159,7 +224,7 @@ export function createServer(projectRoot = process.cwd()) {
             preview_entry_file: z.string(),
             component_count: z.number(),
             css_variable_count: z.number(),
-            source_files: z.array(z.string()),
+            read_first: z.array(z.string()),
             warnings: z.array(z.string()),
             summary: z.string(),
         },
@@ -171,16 +236,16 @@ export function createServer(projectRoot = process.cwd()) {
             userGoal,
         });
         const structuredContent = {
-            artifact_path: artifact.meta.artifactPath,
-            framework: artifact.meta.framework,
-            routing_style: artifact.meta.routingStyle,
-            preview_route: artifact.meta.previewRoute,
-            preview_entry_file: artifact.meta.previewEntryFile,
-            component_count: artifact.components.length,
+            artifact_path: artifact.artifact.artifactPath,
+            framework: artifact.repo.framework,
+            routing_style: artifact.repo.routingStyle,
+            preview_route: artifact.repo.previewRoute,
+            preview_entry_file: artifact.repo.previewEntryFile,
+            component_count: artifact.components.count,
             css_variable_count: artifact.tokens.cssVariables.length,
-            source_files: artifact.meta.sourceFiles,
-            warnings: artifact.guidance.warnings,
-            summary: artifact.guidance.summary,
+            read_first: artifact.forAgent.readFirst.map((item) => item.path),
+            warnings: artifact.forAgent.gaps,
+            summary: artifact.forAgent.intent,
         };
         return {
             content: [

package/dist/types.d.ts

@@ -29,12 +29,13 @@ export interface InspectionStep {
 }
 export interface DeliverableSpec {
     goal: string;
-    layout: "vertical-scroll";
+    layout: "bidirectional-scroll";
     allowHorizontalRows: boolean;
     previewRoute: string;
     previewEntryFile: string;
     sections: string[];
     useExistingComponentsFirst: boolean;
+    interactionFeatures: string[];
 }
 export interface PreviewBrief {
     projectFacts: ProjectFacts;
@@ -65,19 +66,31 @@ export interface ComponentRecord {
     kind: "primitive" | "component" | "feature" | "unknown";
 }
 export interface DesignSystemArtifact {
-    meta: {
+    forAgent: {
+        intent: string;
+        readFirst: Array<{
+            path: string;
+            reason: string;
+        }>;
+        facts: string[];
+        bridges: string[];
+        gaps: string[];
+        updateHints: string[];
+    };
+    artifact: {
         generatedAt: string;
         mode: "build" | "update";
         artifactPath: string;
+        changedFiles: string[];
+    };
+    repo: {
         framework: FrameworkKind;
         routingStyle: RoutingStyle;
         previewRoute: string;
         previewEntryFile: string;
         packageManager: FrameworkInfo["packageManager"];
-        changedFiles: string[];
-        sourceFiles: string[];
     };
-    directories: {
+    scan: {
         componentDirs: string[];
         pageDirs: string[];
         styleFiles: string[];
@@ -85,18 +98,36 @@ export interface DesignSystemArtifact {
     };
     tokens: {
         cssVariables: CssVariableRecord[];
-        styleFiles: string[];
+        themeSourceFiles: string[];
+    };
+    components: {
+        count: number;
+        items: ComponentRecord[];
     };
-    components: ComponentRecord[];
     preview: {
         route: string;
         entryFile: string;
         sections: string[];
         updateStrategy: string[];
     };
-    guidance: {
-        summary: string;
-        warnings: string[];
-        instructions: string[];
-    };
+}
+export interface PreviewStateSnapshot {
+    generatedAt: string;
+    trackedFiles: Record<string, string>;
+}
+export interface PreviewUpdateInput {
+    snapshotPath?: string;
+    designSystemPath?: string;
+    changedFiles?: string[];
+    userGoal?: string;
+}
+export interface PreviewUpdateResult {
+    snapshotPath: string;
+    designSystemPath: string;
+    changedFiles: string[];
+    baselineCreated: boolean;
+    usedManualChangedFiles: boolean;
+    previewBrief: PreviewBrief;
+    designSystem: DesignSystemArtifact;
+    warnings: string[];
 }

package/dist/update.d.ts

@@ -0,0 +1,4 @@
+import type { PreviewUpdateInput, PreviewUpdateResult, PreviewStateSnapshot } from "./types.js";
+export declare function runPreviewUpdate(projectRoot: string, input?: PreviewUpdateInput): Promise<PreviewUpdateResult>;
+export declare function buildPreviewStateSnapshot(projectRoot: string): Promise<PreviewStateSnapshot>;
+export declare function writePreviewStateSnapshot(projectRoot: string, snapshotPath: string, snapshot: PreviewStateSnapshot): Promise<void>;

package/dist/update.js

@@ -0,0 +1,121 @@
+import { createHash } from "crypto";
+import { glob } from "glob";
+import { join } from "path";
+import { buildPreviewBrief } from "./brief.js";
+import { writeDesignSystemArtifact } from "./design-system.js";
+import { readText, toPosixPath, writeText } from "./files.js";
+const DEFAULT_SNAPSHOT_PATH = ".capy/preview-state.json";
+const DEFAULT_DESIGN_SYSTEM_PATH = ".capy/design-system.json";
+export async function runPreviewUpdate(projectRoot, input = {}) {
+    const snapshotPath = input.snapshotPath ?? DEFAULT_SNAPSHOT_PATH;
+    const designSystemPath = input.designSystemPath ?? DEFAULT_DESIGN_SYSTEM_PATH;
+    const usedManualChangedFiles = Array.isArray(input.changedFiles);
+    const diffResult = usedManualChangedFiles
+        ? {
+            baselineCreated: false,
+            changedFiles: uniqueSorted(input.changedFiles ?? []),
+            snapshot: await buildPreviewStateSnapshot(projectRoot),
+        }
+        : await detectChangedFilesFromSnapshot(projectRoot, snapshotPath);
+    const previewBrief = await buildPreviewBrief(projectRoot, {
+        task: "update_preview",
+        changedFiles: diffResult.changedFiles,
+        userGoal: input.userGoal,
+    });
+    const designSystem = await writeDesignSystemArtifact(projectRoot, {
+        artifactPath: designSystemPath,
+        mode: "update",
+        changedFiles: diffResult.changedFiles,
+        userGoal: input.userGoal,
+    });
+    await writePreviewStateSnapshot(projectRoot, snapshotPath, diffResult.snapshot);
+    const warnings = [...previewBrief.warnings];
+    if (diffResult.baselineCreated) {
+        warnings.unshift("No prior preview-state snapshot was found. Capy created a baseline snapshot, so this run cannot infer incremental changes automatically.");
+    }
+    if (usedManualChangedFiles) {
+        warnings.unshift("Using caller-provided changedFiles instead of auto-detected snapshot diffs.");
+    }
+    return {
+        snapshotPath,
+        designSystemPath,
+        changedFiles: diffResult.changedFiles,
+        baselineCreated: diffResult.baselineCreated,
+        usedManualChangedFiles,
+        previewBrief,
+        designSystem,
+        warnings,
+    };
+}
+export async function buildPreviewStateSnapshot(projectRoot) {
+    const trackedFiles = await glob(["**/*.{ts,tsx,js,jsx,css,scss,sass,less,vue,svelte}"], {
+        cwd: projectRoot,
+        nodir: true,
+        ignore: [
+            "**/node_modules/**",
+            "**/.next/**",
+            "**/dist/**",
+            "**/build/**",
+            "**/coverage/**",
+            "**/.git/**",
+            "**/.capy/**",
+        ],
+    });
+    const fileHashes = {};
+    for (const file of trackedFiles.map((item) => toPosixPath(item)).sort()) {
+        const contents = await readText(join(projectRoot, file));
+        if (contents === null)
+            continue;
+        fileHashes[file] = createHash("sha1").update(contents).digest("hex");
+    }
+    return {
+        generatedAt: new Date().toISOString(),
+        trackedFiles: fileHashes,
+    };
+}
+export async function writePreviewStateSnapshot(projectRoot, snapshotPath, snapshot) {
+    await writeText(join(projectRoot, snapshotPath), `${JSON.stringify(snapshot, null, 2)}\n`);
+}
+async function detectChangedFilesFromSnapshot(projectRoot, snapshotPath) {
+    const snapshot = await buildPreviewStateSnapshot(projectRoot);
+    const previous = await readSnapshot(projectRoot, snapshotPath);
+    if (!previous) {
+        return {
+            baselineCreated: true,
+            changedFiles: [],
+            snapshot,
+        };
+    }
+    const changedFiles = new Set();
+    const previousFiles = previous.trackedFiles;
+    const currentFiles = snapshot.trackedFiles;
+    for (const [path, hash] of Object.entries(currentFiles)) {
+        if (previousFiles[path] !== hash) {
+            changedFiles.add(path);
+        }
+    }
+    for (const path of Object.keys(previousFiles)) {
+        if (!(path in currentFiles)) {
+            changedFiles.add(path);
+        }
+    }
+    return {
+        baselineCreated: false,
+        changedFiles: Array.from(changedFiles).sort(),
+        snapshot,
+    };
+}
+async function readSnapshot(projectRoot, snapshotPath) {
+    const raw = await readText(join(projectRoot, snapshotPath));
+    if (!raw)
+        return null;
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+function uniqueSorted(values) {
+    return Array.from(new Set(values)).sort();
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "capy-mcp",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "description": "MCP server that inspects a repo, returns a structured /preview brief, and writes a design-system JSON artifact for AI coding agents",
   "type": "module",
   "main": "dist/index.js",