@fragments-sdk/cli 0.6.0 → 0.7.1

package/src/viewer/vite-plugin.ts

@@ -1,5 +1,5 @@
 /**
- * Segments Vite Plugin
+ * Fragments Vite Plugin
  *
  * This plugin runs WITHIN the project's Vite context, giving it access to:
  * - All project dependencies (React, UI libraries, etc.)
@@ -8,9 +8,9 @@
  * - Project's tsconfig paths
  *
  * It provides:
- * - Virtual module for segment imports
+ * - Virtual module for fragment imports
  * - Viewer UI served at /fragments/
- * - HMR support for segment file changes
+ * - HMR support for fragment file changes
  */
 
 import type { Plugin, ViteDevServer, ResolvedConfig } from "vite";
@@ -18,7 +18,7 @@ import { resolve, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import { readFile } from "node:fs/promises";
 import { transform } from "esbuild";
-import type { SegmentsConfig, CompiledSegment } from "../core/index.js";
+import type { FragmentsConfig, CompiledFragment } from "../core/index.js";
 import { generateContext, BRAND } from "../core/index.js";
 import {
   findStorybookDir,
@@ -28,7 +28,7 @@ import {
 import svgr from "vite-plugin-svgr";
 import {
   generateRenderScript,
-  findSegmentByName,
+  findFragmentByName,
   getAvailableComponents,
   type RenderRequest,
 } from "./render-utils.js";
@@ -47,7 +47,7 @@ interface CompareRequest {
   variant?: string;
   /** Props to render with */
   props?: Record<string, unknown>;
-  /** Figma URL (optional if segment has figma link) */
+  /** Figma URL (optional if fragment has figma link) */
   figmaUrl?: string;
   /** Viewport dimensions */
   viewport?: { width: number; height: number };
@@ -131,30 +131,30 @@ async function getSharedRenderPool() {
   return { pool: sharedRenderPool, bufferToBase64Url: browserPoolModule.bufferToBase64Url };
 }
 
-export interface SegmentsPluginOptions {
-  /** Discovered segment files */
-  segmentFiles: Array<{
+export interface FragmentsPluginOptions {
+  /** Discovered fragment files */
+  fragmentFiles: Array<{
     absolutePath: string;
     relativePath: string;
   }>;
 
-  /** Segments configuration */
-  config: SegmentsConfig;
+  /** Fragments configuration */
+  config: FragmentsConfig;
 
   /** Project root directory */
   projectRoot: string;
 }
 
 /**
- * Create the Segments Vite plugin.
+ * Create the Fragments Vite plugin.
  * Returns an array of plugins to support SVGR and other transforms.
  */
-export function segmentsPlugin(options: SegmentsPluginOptions): Plugin[] {
-  const { segmentFiles, config, projectRoot } = options;
+export function fragmentsPlugin(options: FragmentsPluginOptions): Plugin[] {
+  const { fragmentFiles, config, projectRoot } = options;
 
   // Virtual module IDs
-  const VIRTUAL_SEGMENTS = `virtual:${BRAND.nameLower}`;
-  const VIRTUAL_SEGMENTS_RESOLVED = `\0virtual:${BRAND.nameLower}`;
+  const VIRTUAL_FRAGMENTS = `virtual:${BRAND.nameLower}`;
+  const VIRTUAL_FRAGMENTS_RESOLVED = `\0virtual:${BRAND.nameLower}`;
 
   const VIRTUAL_VIEWER_ENTRY = `virtual:${BRAND.nameLower}-viewer-entry`;
   const VIRTUAL_VIEWER_ENTRY_RESOLVED = `\0virtual:${BRAND.nameLower}-viewer-entry`;
@@ -171,11 +171,11 @@ export function segmentsPlugin(options: SegmentsPluginOptions): Plugin[] {
     ? findPreviewConfigPath(storybookDir)
     : null;
 
-  // Track segment files for HMR
-  const segmentFileSet = new Set(segmentFiles.map((f) => f.absolutePath));
+  // Track fragment files for HMR
+  const fragmentFileSet = new Set(fragmentFiles.map((f) => f.absolutePath));
 
   const mainPlugin: Plugin = {
-    name: "segments",
+    name: "fragments",
 
     // Add process.env shim and esbuild config for Storybook compatibility
     config() {
@@ -226,15 +226,15 @@ export function segmentsPlugin(options: SegmentsPluginOptions): Plugin[] {
               return;
             }
 
-            // Load segments to find the component
-            const loadedSegments = await loadSegmentsForRender(
-              segmentFiles,
+            // Load fragments to find the component
+            const loadedFragments = await loadFragmentsForRender(
+              fragmentFiles,
               projectRoot
             );
-            const segmentInfo = findSegmentByName(component, loadedSegments);
+            const fragmentInfo = findFragmentByName(component, loadedFragments);
 
-            if (!segmentInfo) {
-              const available = getAvailableComponents(loadedSegments);
+            if (!fragmentInfo) {
+              const available = getAvailableComponents(loadedFragments);
               res.writeHead(400, { "Content-Type": "application/json" });
               res.end(
                 JSON.stringify({
@@ -246,22 +246,22 @@ export function segmentsPlugin(options: SegmentsPluginOptions): Plugin[] {
               return;
             }
 
-            // Find the absolute path for the segment
-            const segmentFile = segmentFiles.find(
-              (f) => f.relativePath === segmentInfo.path
+            // Find the absolute path for the fragment
+            const fragmentFile = fragmentFiles.find(
+              (f) => f.relativePath === fragmentInfo.path
             );
-            if (!segmentFile) {
+            if (!fragmentFile) {
               res.writeHead(500, { "Content-Type": "application/json" });
               res.end(
-                JSON.stringify({ error: "Could not resolve segment file path" })
+                JSON.stringify({ error: "Could not resolve fragment file path" })
               );
               return;
             }
 
             // Generate render script
             const renderScript = generateRenderScript(
-              segmentFile.absolutePath,
-              segmentInfo.name,
+              fragmentFile.absolutePath,
+              fragmentInfo.name,
               props
             );
 
@@ -354,23 +354,23 @@ export function segmentsPlugin(options: SegmentsPluginOptions): Plugin[] {
               return;
             }
 
-            // Debug: Log segment files
+            // Debug: Log fragment files
             console.log("[Fragments] Compare request for:", component);
-            console.log("[Fragments] segmentFiles count:", segmentFiles.length);
-            console.log("[Fragments] First 3 segment files:", segmentFiles.slice(0, 3).map(f => f.relativePath));
+            console.log("[Fragments] fragmentFiles count:", fragmentFiles.length);
+            console.log("[Fragments] First 3 fragment files:", fragmentFiles.slice(0, 3).map(f => f.relativePath));
             console.log("[Fragments] projectRoot:", projectRoot);
 
-            // Load segments to find the component and its figma URL
-            const loadedSegments = await loadSegmentsForRender(
-              segmentFiles,
+            // Load fragments to find the component and its figma URL
+            const loadedFragments = await loadFragmentsForRender(
+              fragmentFiles,
               projectRoot
             );
-            console.log("[Fragments] loadedSegments count:", loadedSegments.length);
-            console.log("[Fragments] First 3 loaded:", loadedSegments.slice(0, 3).map(s => s.segment.meta.name));
-            const segmentInfo = findSegmentByName(component, loadedSegments);
+            console.log("[Fragments] loadedFragments count:", loadedFragments.length);
+            console.log("[Fragments] First 3 loaded:", loadedFragments.slice(0, 3).map(s => s.fragment.meta.name));
+            const fragmentInfo = findFragmentByName(component, loadedFragments);
 
-            if (!segmentInfo) {
-              const available = getAvailableComponents(loadedSegments);
+            if (!fragmentInfo) {
+              const available = getAvailableComponents(loadedFragments);
               res.writeHead(400, { "Content-Type": "application/json" });
               res.end(
                 JSON.stringify({
@@ -382,17 +382,17 @@ export function segmentsPlugin(options: SegmentsPluginOptions): Plugin[] {
               return;
             }
 
-            // Find full segment data to get figma URL
-            const fullSegmentData = await loadFullSegmentForCompare(
+            // Find full fragment data to get figma URL
+            const fullFragmentData = await loadFullFragmentForCompare(
               _server,
-              segmentFiles,
+              fragmentFiles,
               component,
               variant,
               projectRoot
             );
 
             // Determine which Figma URL to use (request > variant > meta)
-            const effectiveFigmaUrl = figmaUrl || fullSegmentData?.figmaUrl;
+            const effectiveFigmaUrl = figmaUrl || fullFragmentData?.figmaUrl;
 
             if (!effectiveFigmaUrl) {
               res.writeHead(400, { "Content-Type": "application/json" });
@@ -400,7 +400,7 @@ export function segmentsPlugin(options: SegmentsPluginOptions): Plugin[] {
                 JSON.stringify({
                   error: `No Figma URL for component '${component}'`,
                   suggestion:
-                    "Add 'figma' field to segment definition or provide figmaUrl in request",
+                    "Add 'figma' field to fragment definition or provide figmaUrl in request",
                 })
               );
               return;
@@ -418,14 +418,14 @@ export function segmentsPlugin(options: SegmentsPluginOptions): Plugin[] {
               return;
             }
 
-            // Find segment file for rendering
-            const segmentFile = segmentFiles.find(
-              (f) => f.relativePath === segmentInfo.path
+            // Find fragment file for rendering
+            const fragmentFile = fragmentFiles.find(
+              (f) => f.relativePath === fragmentInfo.path
             );
-            if (!segmentFile) {
+            if (!fragmentFile) {
               res.writeHead(500, { "Content-Type": "application/json" });
               res.end(
-                JSON.stringify({ error: "Could not resolve segment file path" })
+                JSON.stringify({ error: "Could not resolve fragment file path" })
               );
               return;
             }
@@ -449,8 +449,8 @@ export function segmentsPlugin(options: SegmentsPluginOptions): Plugin[] {
 
             // Generate render script and request ID for component capture
             const renderScript = generateRenderScript(
-              segmentFile.absolutePath,
-              segmentInfo.name,
+              fragmentFile.absolutePath,
+              fragmentInfo.name,
               props
             );
             const requestId =
@@ -765,12 +765,12 @@ export function segmentsPlugin(options: SegmentsPluginOptions): Plugin[] {
               return;
             }
 
-            // Load segment data
-            const loadedSegments = await loadSegmentsForRender(segmentFiles, projectRoot);
-            const segmentInfo = findSegmentByName(component, loadedSegments);
+            // Load fragment data
+            const loadedFragments = await loadFragmentsForRender(fragmentFiles, projectRoot);
+            const fragmentInfo = findFragmentByName(component, loadedFragments);
 
-            if (!segmentInfo) {
-              const available = getAvailableComponents(loadedSegments);
+            if (!fragmentInfo) {
+              const available = getAvailableComponents(loadedFragments);
               res.writeHead(400, { "Content-Type": "application/json" });
               res.end(JSON.stringify({
                 error: `Component '${component}' not found. Available: ${available.join(", ")}`,
@@ -778,13 +778,13 @@ export function segmentsPlugin(options: SegmentsPluginOptions): Plugin[] {
               return;
             }
 
-            // Find segment file for rendering
-            const segmentFile = segmentFiles.find(
-              (f) => f.relativePath === segmentInfo.path
+            // Find fragment file for rendering
+            const fragmentFile = fragmentFiles.find(
+              (f) => f.relativePath === fragmentInfo.path
             );
-            if (!segmentFile) {
+            if (!fragmentFile) {
               res.writeHead(500, { "Content-Type": "application/json" });
-              res.end(JSON.stringify({ error: "Could not resolve segment file path" }));
+              res.end(JSON.stringify({ error: "Could not resolve fragment file path" }));
               return;
             }
 
@@ -804,8 +804,8 @@ export function segmentsPlugin(options: SegmentsPluginOptions): Plugin[] {
 
             // Generate render script and capture with styles
             const renderScript = generateRenderScript(
-              segmentFile.absolutePath,
-              segmentInfo.name,
+              fragmentFile.absolutePath,
+              fragmentInfo.name,
               {}
             );
             const requestId = Date.now().toString(36) + Math.random().toString(36).slice(2);
@@ -913,16 +913,16 @@ export function segmentsPlugin(options: SegmentsPluginOptions): Plugin[] {
               | "json";
             const compact = url.searchParams.get("compact") === "true";
 
-            // Load all segments from BRAND.outFile
-            const compiledSegments = await loadSegmentsForContext(
+            // Load all fragments from BRAND.outFile
+            const compiledFragments = await loadFragmentsForContext(
               _server,
-              segmentFiles,
+              fragmentFiles,
               config,
               projectRoot
             );
 
             const { content, tokenEstimate } = generateContext(
-              compiledSegments,
+              compiledFragments,
               {
                 format,
                 compact,
@@ -1032,12 +1032,12 @@ export function segmentsPlugin(options: SegmentsPluginOptions): Plugin[] {
               return;
             }
 
-            // Load segment data
-            const loadedSegments = await loadSegmentsForRender(segmentFiles, projectRoot);
-            const segmentInfo = findSegmentByName(component, loadedSegments);
+            // Load fragment data
+            const loadedFragments = await loadFragmentsForRender(fragmentFiles, projectRoot);
+            const fragmentInfo = findFragmentByName(component, loadedFragments);
 
-            if (!segmentInfo) {
-              const available = getAvailableComponents(loadedSegments);
+            if (!fragmentInfo) {
+              const available = getAvailableComponents(loadedFragments);
               res.writeHead(400, { "Content-Type": "application/json" });
               res.end(JSON.stringify({
                 error: `Component '${component}' not found. Available: ${available.join(", ")}`,
@@ -1063,11 +1063,11 @@ export function segmentsPlugin(options: SegmentsPluginOptions): Plugin[] {
             // 2. Compare with Figma styles to find hardcoded values
             // 3. Generate patches for each hardcoded value
 
-            // Get source file path from segment
-            const segmentFile = segmentFiles.find(
-              (f) => f.relativePath === segmentInfo.path
+            // Get source file path from fragment
+            const fragmentFile = fragmentFiles.find(
+              (f) => f.relativePath === fragmentInfo.path
             );
-            const sourceFile = segmentFile?.relativePath || `${component}.tsx`;
+            const sourceFile = fragmentFile?.relativePath || `${component}.tsx`;
 
             // For demonstration, we'll create a placeholder response
             // In production, this would use style comparison + AST patching
@@ -1109,7 +1109,7 @@ export function segmentsPlugin(options: SegmentsPluginOptions): Plugin[] {
           return;
         }
 
-        if (req.url === "/segments" || req.url === "/fragments/") {
+        if (req.url === "/fragments" || req.url === "/fragments/") {
           // Redirect to /fragments/
           if (!req.url.endsWith("/")) {
             res.writeHead(302, { Location: "/fragments/" });
@@ -1138,8 +1138,8 @@ export function segmentsPlugin(options: SegmentsPluginOptions): Plugin[] {
 
     // Resolve virtual modules
     resolveId(id) {
-      if (id === VIRTUAL_SEGMENTS) {
-        return VIRTUAL_SEGMENTS_RESOLVED;
+      if (id === VIRTUAL_FRAGMENTS) {
+        return VIRTUAL_FRAGMENTS_RESOLVED;
       }
       if (id === VIRTUAL_VIEWER_ENTRY) {
         return VIRTUAL_VIEWER_ENTRY_RESOLVED;
@@ -1152,8 +1152,8 @@ export function segmentsPlugin(options: SegmentsPluginOptions): Plugin[] {
 
     // Load virtual modules
     load(id) {
-      if (id === VIRTUAL_SEGMENTS_RESOLVED) {
-        return generateSegmentsModule(segmentFiles, config, previewConfigPath);
+      if (id === VIRTUAL_FRAGMENTS_RESOLVED) {
+        return generateFragmentsModule(fragmentFiles, config, previewConfigPath);
       }
       if (id === VIRTUAL_VIEWER_ENTRY_RESOLVED) {
         return generateViewerEntry();
@@ -1164,11 +1164,11 @@ export function segmentsPlugin(options: SegmentsPluginOptions): Plugin[] {
       return null;
     },
 
-    // Handle HMR for segment files
+    // Handle HMR for fragment files
     handleHotUpdate({ file, server }) {
-      if (segmentFileSet.has(file)) {
-        // Invalidate the virtual segments module
-        const mod = server.moduleGraph.getModuleById(VIRTUAL_SEGMENTS_RESOLVED);
+      if (fragmentFileSet.has(file)) {
+        // Invalidate the virtual fragments module
+        const mod = server.moduleGraph.getModuleById(VIRTUAL_FRAGMENTS_RESOLVED);
         if (mod) {
           server.moduleGraph.invalidateModule(mod);
         }
@@ -1176,7 +1176,7 @@ export function segmentsPlugin(options: SegmentsPluginOptions): Plugin[] {
         // Send HMR update
         server.ws.send({
           type: "custom",
-          event: "segments:update",
+          event: "fragments:update",
           data: { file },
         });
 
@@ -1191,7 +1191,7 @@ export function segmentsPlugin(options: SegmentsPluginOptions): Plugin[] {
   // Uses the `load` hook instead of `transform` because we need to intercept
   // the file BEFORE Vite's import-analysis tries to parse it
   const jsxTransformPlugin: Plugin = {
-    name: "segments-jsx-transform",
+    name: "fragments-jsx-transform",
     enforce: "pre",
     async load(id) {
       // Only handle .js files that might contain JSX (like preview.js)
@@ -1247,7 +1247,7 @@ export function segmentsPlugin(options: SegmentsPluginOptions): Plugin[] {
       },
       include: "**/*.svg",
     }),
-    // Main segments plugin
+    // Main fragments plugin
     mainPlugin,
   ];
 }
@@ -1260,37 +1260,37 @@ function isStoryFile(filePath: string): boolean {
 }
 
 /**
- * Get the base component path from a segment or story file path.
- * e.g., "src/components/Button/Button.segment.tsx" -> "src/components/Button/Button"
+ * Get the base component path from a fragment or story file path.
+ * e.g., "src/components/Button/Button.fragment.tsx" -> "src/components/Button/Button"
  * e.g., "src/components/Button/Button.stories.tsx" -> "src/components/Button/Button"
  */
 function getBaseComponentPath(filePath: string): string {
-  return filePath.replace(/\.(segment|stories)\.(tsx?|jsx?)$/, "");
+  return filePath.replace(/\.(fragment|stories)\.(tsx?|jsx?)$/, "");
 }
 
 /**
- * Generate the virtual segments module.
- * Uses dynamic imports for lazy loading - segments are loaded on demand.
- * Supports both native .segment.tsx files and Storybook .stories.tsx files.
+ * Generate the virtual fragments module.
+ * Uses dynamic imports for lazy loading - fragments are loaded on demand.
+ * Supports both native .fragment.tsx files and Storybook .stories.tsx files.
  * Integrates Storybook preview config for global decorators, parameters, etc.
  *
- * MERGE STRATEGY: When both .segment.tsx and .stories.tsx exist for the same component:
+ * MERGE STRATEGY: When both .fragment.tsx and .stories.tsx exist for the same component:
  * - Use .stories.tsx for RENDERING (variants, props, etc.) - it's the source of truth
- * - Merge METADATA from .segment.tsx (Figma URLs, AI descriptions, usage guidelines)
+ * - Merge METADATA from .fragment.tsx (Figma URLs, AI descriptions, usage guidelines)
  * - This gives us the best of both worlds: working renders + rich metadata
  */
-function generateSegmentsModule(
-  segmentFiles: Array<{ absolutePath: string; relativePath: string }>,
-  config: SegmentsConfig,
+function generateFragmentsModule(
+  fragmentFiles: Array<{ absolutePath: string; relativePath: string }>,
+  config: FragmentsConfig,
   previewConfigPath: string | null
 ): string {
   // Group files by base component path to identify pairs
   const filesByBasePath = new Map<string, {
     storyFile?: { absolutePath: string; relativePath: string };
-    segmentFile?: { absolutePath: string; relativePath: string };
+    fragmentFile?: { absolutePath: string; relativePath: string };
   }>();
 
-  for (const file of segmentFiles) {
+  for (const file of fragmentFiles) {
     const basePath = getBaseComponentPath(file.relativePath);
     const isStory = isStoryFile(file.relativePath);
 
@@ -1299,25 +1299,25 @@ function generateSegmentsModule(
     if (isStory) {
       existing.storyFile = file;
     } else {
-      existing.segmentFile = file;
+      existing.fragmentFile = file;
     }
 
     filesByBasePath.set(basePath, existing);
   }
 
   // Generate loaders with metadata merge support
-  // Priority: stories for rendering, segment for metadata (Figma URLs, etc.)
+  // Priority: stories for rendering, fragment for metadata (Figma URLs, etc.)
   const loaders = Array.from(filesByBasePath.values())
     .map((files) => {
       // Determine which file to use for rendering
-      const primaryFile = files.storyFile || files.segmentFile;
+      const primaryFile = files.storyFile || files.fragmentFile;
       if (!primaryFile) return null;
 
       const isStory = !!files.storyFile;
 
-      // If we have both, include the segment file path for metadata merge
-      const metadataPath = (files.storyFile && files.segmentFile)
-        ? files.segmentFile.absolutePath
+      // If we have both, include the fragment file path for metadata merge
+      const metadataPath = (files.storyFile && files.fragmentFile)
+        ? files.fragmentFile.absolutePath
         : null;
 
       return `  {
@@ -1332,11 +1332,11 @@ function generateSegmentsModule(
 
   // Generate preview config import if available
   const previewImport = previewConfigPath
-    ? `import * as previewConfig from "virtual:segments-preview";`
+    ? `import * as previewConfig from "virtual:fragments-preview";`
     : "";
   const previewSetup = previewConfigPath
     ? `
-// Set global preview config before loading segments
+// Set global preview config before loading fragments
 setPreviewConfig({
   decorators: previewConfig.decorators,
   parameters: previewConfig.parameters,
@@ -1349,88 +1349,88 @@ setPreviewConfig({
     : "";
 
   return `
-import { storyModuleToSegment, setPreviewConfig } from "@fragments/core";
+import { storyModuleToFragment, setPreviewConfig } from "@fragments/core";
 ${previewImport}
 ${previewSetup}
-// Lazy segment loaders (supports both .segment.tsx and .stories.tsx)
-const segmentLoaders = [
+// Lazy fragment loaders (supports both .fragment.tsx and .stories.tsx)
+const fragmentLoaders = [
 ${loaders}
 ];
 
-// Cache for loaded segments
-const loadedSegments = new Map();
+// Cache for loaded fragments
+const loadedFragments = new Map();
 
 /**
- * Merge metadata from a segment file into a story-based segment.
+ * Merge metadata from a fragment file into a story-based fragment.
  * This preserves Figma URLs and other AI-agent focused data.
  */
-function mergeMetadata(segment, metadataModule) {
-  if (!metadataModule?.default) return segment;
+function mergeMetadata(fragment, metadataModule) {
+  if (!metadataModule?.default) return fragment;
 
   const metadata = metadataModule.default;
 
   // Merge meta-level Figma URL
-  if (metadata.meta?.figma && !segment.meta.figma) {
-    segment.meta.figma = metadata.meta.figma;
+  if (metadata.meta?.figma && !fragment.meta.figma) {
+    fragment.meta.figma = metadata.meta.figma;
   }
 
   // Merge description if not present
-  if (metadata.meta?.description && !segment.meta.description) {
-    segment.meta.description = metadata.meta.description;
+  if (metadata.meta?.description && !fragment.meta.description) {
+    fragment.meta.description = metadata.meta.description;
   }
 
   // Merge variant-level Figma URLs
-  if (metadata.variants && segment.variants) {
+  if (metadata.variants && fragment.variants) {
     for (const metaVariant of metadata.variants) {
-      const segmentVariant = segment.variants.find(v => v.name === metaVariant.name);
-      if (segmentVariant && metaVariant.figma && !segmentVariant.figma) {
-        segmentVariant.figma = metaVariant.figma;
+      const fragmentVariant = fragment.variants.find(v => v.name === metaVariant.name);
+      if (fragmentVariant && metaVariant.figma && !fragmentVariant.figma) {
+        fragmentVariant.figma = metaVariant.figma;
       }
     }
   }
 
-  return segment;
+  return fragment;
 }
 
-// Load all segments (for initial render)
-// Gracefully handles individual failures - one bad story won't break all segments
-export async function loadAllSegments() {
+// Load all fragments (for initial render)
+// Gracefully handles individual failures - one bad story won't break all fragments
+export async function loadAllFragments() {
   const results = await Promise.all(
-    segmentLoaders.map(async (loader) => {
+    fragmentLoaders.map(async (loader) => {
       try {
-        if (loadedSegments.has(loader.path)) {
-          const cached = loadedSegments.get(loader.path);
-          return cached ? { path: loader.path, segment: cached } : null;
+        if (loadedFragments.has(loader.path)) {
+          const cached = loadedFragments.get(loader.path);
+          return cached ? { path: loader.path, fragment: cached } : null;
         }
 
         const module = await loader.loader();
 
-        // Convert story modules to segments at runtime
-        let segment;
+        // Convert story modules to fragments at runtime
+        let fragment;
         if (loader.isStory) {
-          segment = storyModuleToSegment(module, loader.path);
-          // storyModuleToSegment returns null for stories without a component
-          if (!segment) {
-            loadedSegments.set(loader.path, null);
+          fragment = storyModuleToFragment(module, loader.path);
+          // storyModuleToFragment returns null for stories without a component
+          if (!fragment) {
+            loadedFragments.set(loader.path, null);
             return null;
           }
         } else {
-          segment = module.default;
+          fragment = module.default;
         }
 
-        // Merge metadata from corresponding segment file if available
+        // Merge metadata from corresponding fragment file if available
         if (loader.metadataLoader) {
           try {
             const metadataModule = await loader.metadataLoader();
-            segment = mergeMetadata(segment, metadataModule);
+            fragment = mergeMetadata(fragment, metadataModule);
           } catch (metaError) {
             // Metadata loading is optional - don't fail if it errors
             console.warn("[Fragments] Could not load metadata for " + loader.path + ":", metaError.message);
           }
         }
 
-        loadedSegments.set(loader.path, segment);
-        return { path: loader.path, segment };
+        loadedFragments.set(loader.path, fragment);
+        return { path: loader.path, fragment };
       } catch (error) {
         console.warn("[Fragments] Failed to load " + loader.path + ":", error.message);
         return null;
@@ -1441,62 +1441,62 @@ export async function loadAllSegments() {
   return results.filter(r => r !== null);
 }
 
-// Load a single segment by path
-export async function loadSegment(path) {
-  const loader = segmentLoaders.find(l => l.path === path);
+// Load a single fragment by path
+export async function loadFragment(path) {
+  const loader = fragmentLoaders.find(l => l.path === path);
   if (!loader) return null;
 
-  if (loadedSegments.has(path)) {
-    return loadedSegments.get(path);
+  if (loadedFragments.has(path)) {
+    return loadedFragments.get(path);
   }
 
   const module = await loader.loader();
 
-  // Convert story modules to segments at runtime
-  let segment;
+  // Convert story modules to fragments at runtime
+  let fragment;
   if (loader.isStory) {
-    segment = storyModuleToSegment(module, path);
+    fragment = storyModuleToFragment(module, path);
   } else {
-    segment = module.default;
+    fragment = module.default;
   }
 
-  // Merge metadata from corresponding segment file if available
-  if (loader.metadataLoader && segment) {
+  // Merge metadata from corresponding fragment file if available
+  if (loader.metadataLoader && fragment) {
     try {
       const metadataModule = await loader.metadataLoader();
-      segment = mergeMetadata(segment, metadataModule);
+      fragment = mergeMetadata(fragment, metadataModule);
     } catch (metaError) {
       console.warn("[Fragments] Could not load metadata for " + path + ":", metaError.message);
     }
   }
 
-  loadedSegments.set(path, segment);
-  return segment;
+  loadedFragments.set(path, fragment);
+  return fragment;
 }
 
-// For backwards compatibility, load all segments synchronously on import
+// For backwards compatibility, load all fragments synchronously on import
 // This is still lazy per-file but awaited at module load
-let segments = [];
-const segmentsPromise = loadAllSegments().then(s => { segments = s; return s; });
+let fragments = [];
+const fragmentsPromise = loadAllFragments().then(s => { fragments = s; return s; });
 
-export { segments, segmentsPromise };
+export { fragments, fragmentsPromise };
 export const config = ${JSON.stringify(config)};
 
 // HMR support
 if (import.meta.hot) {
   import.meta.hot.accept();
 
-  import.meta.hot.on("segments:update", (data) => {
+  import.meta.hot.on("fragments:update", (data) => {
     console.log("[Fragments] File updated:", data.file);
-    // Clear cache for the updated file (handles both .segment and .stories)
-    for (const [path, _] of loadedSegments) {
-      const basePath = path.replace(/\\.(segment|stories)\\.tsx?$/, '');
+    // Clear cache for the updated file (handles both .fragment and .stories)
+    for (const [path, _] of loadedFragments) {
+      const basePath = path.replace(/\\.(fragment|stories)\\.tsx?$/, '');
       if (data.file.includes(basePath)) {
-        loadedSegments.delete(path);
+        loadedFragments.delete(path);
       }
     }
     // Trigger re-render in viewer
-    window.dispatchEvent(new CustomEvent("segments:update"));
+    window.dispatchEvent(new CustomEvent("fragments:update"));
   });
 }
 `;
@@ -1507,38 +1507,38 @@ if (import.meta.hot) {
  */
 function generateViewerEntry(): string {
   return `
-import { segments, config } from "virtual:segments";
+import { fragments, config } from "virtual:fragments";
 
 // Re-export for viewer
-export { segments, config };
+export { fragments, config };
 
 // Initialize viewer
-console.log("[Fragments] Loaded", segments.length, "segment(s)");
+console.log("[Fragments] Loaded", fragments.length, "fragment(s)");
 `;
 }
 
 /**
- * Load segments for context generation.
+ * Load fragments for context generation.
  * Uses BRAND.outFile to avoid SSR module loading issues with React CJS modules.
  */
-async function loadSegmentsForContext(
+async function loadFragmentsForContext(
   _server: ViteDevServer,
-  _segmentFiles: Array<{ absolutePath: string; relativePath: string }>,
-  _config: SegmentsConfig,
+  _fragmentFiles: Array<{ absolutePath: string; relativePath: string }>,
+  _config: FragmentsConfig,
   configDir?: string
-): Promise<CompiledSegment[]> {
+): Promise<CompiledFragment[]> {
   const { join } = await import("node:path");
 
   // Read from outFile (avoids SSR issues with React CJS)
-  const segmentsJsonPath = join(configDir || process.cwd(), BRAND.outFile);
+  const fragmentsJsonPath = join(configDir || process.cwd(), BRAND.outFile);
 
   try {
-    const content = await readFile(segmentsJsonPath, "utf-8");
+    const content = await readFile(fragmentsJsonPath, "utf-8");
     const data = JSON.parse(content) as {
-      segments: Record<string, CompiledSegment>;
+      fragments: Record<string, CompiledFragment>;
     };
 
-    return Object.values(data.segments || {});
+    return Object.values(data.fragments || {});
   } catch (error) {
     console.warn(
       `[${BRAND.name}] Failed to load ${BRAND.outFile} for context:`,
@@ -1571,7 +1571,7 @@ async function serveViewerHTML(res: any, server: ViteDevServer): Promise<void> {
   } catch (error) {
     console.error("[Fragments] Error serving viewer:", error);
     res.writeHead(500, { "Content-Type": "text/plain" });
-    res.end("Error loading Segments viewer");
+    res.end("Error loading Fragments viewer");
   }
 }
 
@@ -1623,30 +1623,30 @@ async function parseJsonBody(req: any): Promise<unknown> {
 }
 
 /**
- * Load segments for render from BRAND.outFile or by building on-the-fly.
+ * Load fragments for render from BRAND.outFile or by building on-the-fly.
  * This avoids SSR issues with React components.
  */
-async function loadSegmentsForRender(
-  segmentFiles: Array<{ absolutePath: string; relativePath: string }>,
+async function loadFragmentsForRender(
+  fragmentFiles: Array<{ absolutePath: string; relativePath: string }>,
   configDir: string
-): Promise<Array<{ path: string; segment: { meta: { name: string } } }>> {
+): Promise<Array<{ path: string; fragment: { meta: { name: string } } }>> {
   const { join } = await import("node:path");
 
   // Try to read from the project directory
-  const segmentsJsonPath = join(configDir, BRAND.outFile);
+  const fragmentsJsonPath = join(configDir, BRAND.outFile);
 
   try {
-    const content = await readFile(segmentsJsonPath, "utf-8");
+    const content = await readFile(fragmentsJsonPath, "utf-8");
     const data = JSON.parse(content) as {
-      segments: Record<string, { filePath: string; meta: { name: string } }>;
+      fragments: Record<string, { filePath: string; meta: { name: string } }>;
     };
 
     // Convert to the expected format if we have entries
-    const segmentEntries = Object.values(data.segments || {});
-    if (segmentEntries.length > 0) {
-      return segmentEntries.map((segment) => ({
-        path: segment.filePath,
-        segment: { meta: { name: segment.meta.name } },
+    const fragmentEntries = Object.values(data.fragments || {});
+    if (fragmentEntries.length > 0) {
+      return fragmentEntries.map((fragment) => ({
+        path: fragment.filePath,
+        fragment: { meta: { name: fragment.meta.name } },
       }));
     }
     // Fall through to file-based extraction if outFile is empty
@@ -1655,20 +1655,20 @@ async function loadSegmentsForRender(
   }
 
   // Extract component names from file paths (fallback)
-  return segmentFiles.map((f) => {
+  return fragmentFiles.map((f) => {
     let name: string;
     if (isStoryFile(f.relativePath)) {
       // Extract name from path like "src/components/Button/Button.stories.tsx"
       const match = f.relativePath.match(/\/([^/]+)\.stories\./);
       name = match ? match[1] : f.relativePath;
     } else {
-      // Extract name from path like "src/components/Button/Button.segment.tsx"
-      const match = f.relativePath.match(/\/([^/]+)\.segment\./);
+      // Extract name from path like "src/components/Button/Button.fragment.tsx"
+      const match = f.relativePath.match(/\/([^/]+)\.fragment\./);
       name = match ? match[1] : f.relativePath;
     }
     return {
       path: f.relativePath,
-      segment: { meta: { name } },
+      fragment: { meta: { name } },
     };
   });
 }
@@ -1942,12 +1942,12 @@ async function captureRenderWithStyles(
 }
 
 /**
- * Load full segment data to get figma URL from segment or variant.
+ * Load full fragment data to get figma URL from fragment or variant.
  * Uses BRAND.outFile to avoid SSR module loading issues with React CJS modules.
  */
-async function loadFullSegmentForCompare(
+async function loadFullFragmentForCompare(
   _server: ViteDevServer,
-  _segmentFiles: Array<{ absolutePath: string; relativePath: string }>,
+  _fragmentFiles: Array<{ absolutePath: string; relativePath: string }>,
   componentName: string,
   variantName?: string,
   configDir?: string
@@ -1955,12 +1955,12 @@ async function loadFullSegmentForCompare(
   const { join } = await import("node:path");
 
   // Try to read from outFile (avoids SSR issues with React CJS)
-  const segmentsJsonPath = join(configDir || process.cwd(), BRAND.outFile);
+  const fragmentsJsonPath = join(configDir || process.cwd(), BRAND.outFile);
 
   try {
-    const content = await readFile(segmentsJsonPath, "utf-8");
+    const content = await readFile(fragmentsJsonPath, "utf-8");
     const data = JSON.parse(content) as {
-      segments: Record<
+      fragments: Record<
         string,
         {
           meta: { name: string; figma?: string };
@@ -1969,22 +1969,22 @@ async function loadFullSegmentForCompare(
       >;
     };
 
-    const segment = data.segments[componentName];
-    if (!segment) {
+    const fragment = data.fragments[componentName];
+    if (!fragment) {
       return null;
     }
 
     // Priority: variant.figma > meta.figma
-    if (variantName && segment.variants) {
-      const variant = segment.variants.find((v) => v.name === variantName);
+    if (variantName && fragment.variants) {
+      const variant = fragment.variants.find((v) => v.name === variantName);
       if (variant?.figma) {
         return { figmaUrl: variant.figma };
       }
     }
 
     // Fall back to meta.figma
-    if (segment.meta.figma) {
-      return { figmaUrl: segment.meta.figma };
+    if (fragment.meta.figma) {
+      return { figmaUrl: fragment.meta.figma };
     }
 
     return null;