@framingui/mcp-server 0.5.6 → 0.6.1

package/README.md

@@ -102,9 +102,9 @@ npx @framingui/mcp-server init
 | -------------------------------- | --------------------- |
 | `npx @framingui/mcp-server`      | MCP stdio 서버 시작   |
 | `npx @framingui/mcp-server init` | 프로젝트 초기 설정    |
-| `framingui-mcp login`               | 브라우저 OAuth 로그인 |
-| `framingui-mcp logout`              | 로그아웃              |
-| `framingui-mcp status`              | 인증 상태 확인        |
+| `framingui-mcp login`            | 브라우저 OAuth 로그인 |
+| `framingui-mcp logout`           | 로그아웃              |
+| `framingui-mcp status`           | 인증 상태 확인        |
 
 ## Development Quick Start
 
@@ -824,9 +824,10 @@ packages/mcp-server/
 │   │   ├── preview-component.ts     # Component preview (SPEC-MCP-003)
 │   │   ├── list-screen-templates.ts # Template listing (SPEC-MCP-003)
 │   │   └── preview-screen-template.ts # Template preview (SPEC-MCP-003)
-│   ├── data/                  # Static data registries (SPEC-MCP-003)
-│   │   ├── component-registry.ts    # Component metadata registry
-│   │   └── component-metadata.json  # Static component metadata
+│   ├── data/                  # Data utilities (non-API helpers)
+│   │   ├── template-matcher.ts      # Template matching logic
+│   │   ├── hint-generator.ts        # AI hint generation
+│   │   └── recipe-resolver.ts       # Recipe resolution
 │   ├── storage/               # Blueprint storage
 │   │   ├── blueprint-storage.ts
 │   │   └── timestamp-manager.ts
@@ -883,43 +884,26 @@ packages/mcp-server/
 
 **Test Results**:
 
-- 22 test files
-- 214 test cases
+- 29 test files
+- 290 test cases
 - 100% pass rate
 - Zero failures
 
-## Integration with @framingui/core
+## Architecture: API-Based Data Sources (v0.6.0)
 
-All MCP tools reuse `@framingui/core` functions:
+Since v0.6.0, the MCP server fetches all data from the framingui.com API via `data-client.ts`. This removes `@framingui/core` and `@framingui/ui` from production dependencies, enabling truly standalone npm installation.
 
-**Blueprint & Theme Tools**:
+**Data Client** (`src/api/data-client.ts`):
 
-- `loadTheme()` - Theme loading
-- `listThemes()` - Theme enumeration
-- `createBlueprint()` - Blueprint creation
-- `validateBlueprint()` - Schema validation
-- `generateCSSVariables()` - CSS variable extraction
-- `render()` - Code generation
+- `fetchThemeList()`, `fetchTheme(id)` — Theme data
+- `fetchIconLibraries()`, `fetchIconLibrary(id)` — Icon libraries
+- `fetchTemplateList()`, `fetchTemplate(id)` — Screen templates
+- `fetchComponentList()`, `fetchComponent(id)` — Component catalog
+- `fetchTokenList(type?)` — Layout tokens
+- `fetchCSSVariables(themeId)` — CSS generation
+- `fetchScreenExamples()` — Screen examples
 
-**Screen Generation Tools** (SPEC-LAYOUT-002):
-
-- `validateScreenDefinition()` - Screen validation
-- `resolveScreen()` - Layout and component resolution
-- `generateStyledComponents()` - CSS-in-JS generation
-- `generateTailwindClasses()` - Tailwind CSS generation
-- `generateReactComponent()` - React component generation
-- `getAllShellTokens()` - Shell token listing
-- `getAllPageLayoutTokens()` - Page token listing
-- `getAllSectionPatternTokens()` - Section token listing
-
-**Component & Template Discovery** (SPEC-MCP-003):
-
-- `templateRegistry` from `@framingui` - Template metadata and search
-- Component metadata registry - Static component catalog with 30+ components
-- Component type definitions - TypeScript interfaces for props and variants
-- Template structure definitions - Skeleton, layout, and customization schemas
-
-**Zero code duplication** - Single source of truth maintained.
+All functions use `MemoryCache` (10-min TTL) with `getStale()` fallback for network resilience.
 
 ## Documentation
 
@@ -1021,7 +1005,7 @@ MIT
 
 ---
 
-**Version**: 3.0.0 (stdio-based MCP standard + Component & Template Discovery)
-**Last Updated**: 2026-02-01
-**SPEC**: SPEC-MCP-002 v2.0.0, SPEC-LAYOUT-002 Phase 4, SPEC-MCP-003 v1.0.0
-**Total Tools**: 13 (9 existing + 4 new discovery tools)
+**Version**: 0.6.0 (API-based data sources — no workspace dependencies)
+**Last Updated**: 2026-03-06
+**SPEC**: SPEC-MCP-002 v2.0.0, SPEC-LAYOUT-002 Phase 4, SPEC-MCP-003 v1.0.0, SPEC-MCP-007 v1.0.0
+**Total Tools**: 17

package/dist/__tests__/cache.test.d.ts

@@ -0,0 +1,6 @@
+/**
+ * MemoryCache 테스트
+ * SPEC-MCP-007:S-004 - getStale() 메서드: TTL 만료 후에도 캐시 값 반환
+ */
+export {};
+//# sourceMappingURL=cache.test.d.ts.map

package/dist/__tests__/cache.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/cache.test.ts"],"names":[],"mappings":"AAAA;;;GAGG"}

package/dist/__tests__/cache.test.js

@@ -0,0 +1,86 @@
+/**
+ * MemoryCache 테스트
+ * SPEC-MCP-007:S-004 - getStale() 메서드: TTL 만료 후에도 캐시 값 반환
+ */
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+// vitest에서 .js 확장자는 dist 파일을 참조할 수 있으므로 .ts 확장자로 직접 import
+// eslint-disable-next-line @typescript-eslint/ban-ts-comment
+// @ts-ignore
+import { MemoryCache } from '../auth/cache.ts';
+describe('MemoryCache', () => {
+    let cache;
+    beforeEach(() => {
+        cache = new MemoryCache();
+        vi.useRealTimers();
+    });
+    describe('set / get (기본 동작)', () => {
+        it('TTL 이내에 get()으로 값을 반환한다', () => {
+            cache.set('key1', 'value1', 10_000);
+            expect(cache.get('key1')).toBe('value1');
+        });
+        it('존재하지 않는 키에 대해 null을 반환한다', () => {
+            expect(cache.get('non-existent')).toBeNull();
+        });
+        it('TTL 만료 후 get()은 null을 반환한다', () => {
+            vi.useFakeTimers();
+            cache.set('key2', 'expired', 1_000);
+            // TTL(1초) 이후로 시간 이동
+            vi.advanceTimersByTime(1_001);
+            expect(cache.get('key2')).toBeNull();
+            vi.useRealTimers();
+        });
+    });
+    describe('getStale()', () => {
+        it('TTL 이내에 getStale()은 값을 반환한다', () => {
+            cache.set('key3', 'fresh', 10_000);
+            expect(cache.getStale('key3')).toBe('fresh');
+        });
+        it('TTL 만료 후에도 getStale()은 값을 반환한다 (stale 허용)', () => {
+            vi.useFakeTimers();
+            cache.set('key4', 'stale-value', 500);
+            // TTL 만료
+            vi.advanceTimersByTime(1_000);
+            // getStale()은 만료 후에도 값을 반환해야 한다
+            // 주의: get()을 먼저 호출하면 만료된 항목이 삭제됨
+            expect(cache.getStale('key4')).toBe('stale-value');
+            // get()은 만료된 항목을 삭제하고 null을 반환한다
+            const freshCache = new MemoryCache();
+            freshCache.set('key4b', 'stale-value-b', 500);
+            vi.advanceTimersByTime(1_000);
+            expect(freshCache.get('key4b')).toBeNull();
+            // get() 호출 후에는 항목이 삭제되어 getStale()도 null 반환
+            expect(freshCache.getStale('key4b')).toBeNull();
+            vi.useRealTimers();
+        });
+        it('키가 설정된 적 없으면 getStale()은 null을 반환한다', () => {
+            expect(cache.getStale('never-set')).toBeNull();
+        });
+        it('delete() 후 getStale()은 null을 반환한다', () => {
+            cache.set('key5', 'to-delete', 10_000);
+            cache.delete('key5');
+            expect(cache.getStale('key5')).toBeNull();
+        });
+    });
+    describe('delete / clear', () => {
+        it('delete()로 특정 키를 제거한다', () => {
+            cache.set('key6', 'val6', 10_000);
+            cache.delete('key6');
+            expect(cache.get('key6')).toBeNull();
+        });
+        it('clear()로 모든 캐시를 비운다', () => {
+            cache.set('a', 'aa', 10_000);
+            cache.set('b', 'bb', 10_000);
+            cache.clear();
+            expect(cache.size()).toBe(0);
+        });
+    });
+    describe('size()', () => {
+        it('항목 추가 수만큼 size()가 증가한다', () => {
+            expect(cache.size()).toBe(0);
+            cache.set('s1', 'v1', 10_000);
+            cache.set('s2', 'v2', 10_000);
+            expect(cache.size()).toBe(2);
+        });
+    });
+});
+//# sourceMappingURL=cache.test.js.map

package/dist/__tests__/cache.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.test.js","sourceRoot":"","sources":["../../src/__tests__/cache.test.ts"],"names":[],"mappings":"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"}

package/dist/__tests__/data-client.test.d.ts

@@ -0,0 +1,13 @@
+/**
+ * data-client.ts 테스트 (v2 - ApiResult 기반)
+ * SPEC-MCP-007 Phase 2 - fetchTemplateList, fetchTemplate, fetchComponentList,
+ * fetchComponent, fetchTokenList, fetchCSSVariables, fetchScreenExamples
+ *
+ * 테스트 시나리오:
+ * 1. 캐시 미스: fetch 호출 → ApiResult 성공 반환
+ * 2. API 실패 + 캐시 없음: ApiResult 에러 반환
+ * 3. 인증 없음: fetch 호출 없이 NOT_AUTHENTICATED 에러 반환
+ * 4. URL 파라미터 전달 확인
+ */
+export {};
+//# sourceMappingURL=data-client.test.d.ts.map

package/dist/__tests__/data-client.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"data-client.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/data-client.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG"}

package/dist/__tests__/data-client.test.js

@@ -0,0 +1,415 @@
+/**
+ * data-client.ts 테스트 (v2 - ApiResult 기반)
+ * SPEC-MCP-007 Phase 2 - fetchTemplateList, fetchTemplate, fetchComponentList,
+ * fetchComponent, fetchTokenList, fetchCSSVariables, fetchScreenExamples
+ *
+ * 테스트 시나리오:
+ * 1. 캐시 미스: fetch 호출 → ApiResult 성공 반환
+ * 2. API 실패 + 캐시 없음: ApiResult 에러 반환
+ * 3. 인증 없음: fetch 호출 없이 NOT_AUTHENTICATED 에러 반환
+ * 4. URL 파라미터 전달 확인
+ */
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+// ─────────────────────────────────────────────────────────────────────────────
+// vi.mock 호이스팅: factory 안에서 참조할 mock 함수를 vi.hoisted()로 선언
+// ─────────────────────────────────────────────────────────────────────────────
+const { mockGetAuthData, mockGetRawApiKey, mockResolveFraminguiApiUrl } = vi.hoisted(() => ({
+    mockGetAuthData: vi.fn(),
+    mockGetRawApiKey: vi.fn(),
+    mockResolveFraminguiApiUrl: vi.fn(),
+}));
+// data-client.ts가 .js 확장자로 import하므로 mock도 동일 경로 사용
+vi.mock('../auth/state.js', () => ({
+    getAuthData: mockGetAuthData,
+    getRawApiKey: mockGetRawApiKey,
+}));
+vi.mock('../utils/api-url.js', () => ({
+    resolveFraminguiApiUrl: mockResolveFraminguiApiUrl,
+}));
+vi.mock('../utils/logger.js', () => ({
+    info: vi.fn(),
+    error: vi.fn(),
+}));
+// MemoryCache를 mock으로 교체 - 캐시가 항상 miss인 상태로 테스트
+vi.mock('../auth/cache.js', () => {
+    return {
+        MemoryCache: vi.fn().mockImplementation(() => ({
+            get: vi.fn().mockReturnValue(null),
+            getStale: vi.fn().mockReturnValue(null),
+            set: vi.fn(),
+            delete: vi.fn(),
+            clear: vi.fn(),
+            size: vi.fn().mockReturnValue(0),
+        })),
+    };
+});
+// global fetch 목업
+const mockFetch = vi.fn();
+global.fetch = mockFetch;
+// ─────────────────────────────────────────────────────────────────────────────
+// 테스트 대상 import
+// ─────────────────────────────────────────────────────────────────────────────
+import { fetchTemplateList, fetchTemplate, fetchComponentList, fetchComponent, fetchTokenList, fetchCSSVariables, fetchScreenExamples, } from '../api/data-client.js';
+// ─────────────────────────────────────────────────────────────────────────────
+// 헬퍼
+// ─────────────────────────────────────────────────────────────────────────────
+function makeOkResponse(body) {
+    return {
+        ok: true,
+        status: 200,
+        json: vi.fn().mockResolvedValue(body),
+    };
+}
+function makeErrorResponse(status, body) {
+    return {
+        ok: false,
+        status,
+        statusText: 'Error',
+        json: vi.fn().mockResolvedValue(body),
+    };
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// 공통 beforeEach
+// ─────────────────────────────────────────────────────────────────────────────
+beforeEach(() => {
+    vi.clearAllMocks();
+    mockGetAuthData.mockReturnValue({ valid: true });
+    mockGetRawApiKey.mockReturnValue('tk_live_test_key_00000000000000000000000000000000000000000000000000000000000000000');
+    mockResolveFraminguiApiUrl.mockReturnValue({ apiUrl: 'https://framingui.com' });
+});
+// ─────────────────────────────────────────────────────────────────────────────
+// fetchTemplateList
+// ─────────────────────────────────────────────────────────────────────────────
+describe('fetchTemplateList()', () => {
+    it('API 성공 시 ok: true와 템플릿 목록을 반환한다', async () => {
+        const templates = [
+            {
+                id: 'dashboard',
+                name: 'Dashboard',
+                category: 'web',
+                description: '',
+                requiredComponentsCount: 3,
+            },
+        ];
+        mockFetch.mockResolvedValueOnce(makeOkResponse({ success: true, templates }));
+        const result = await fetchTemplateList();
+        expect(result.ok).toBe(true);
+        if (result.ok) {
+            expect(result.data).toHaveLength(1);
+            expect(result.data[0].id).toBe('dashboard');
+        }
+        expect(mockFetch).toHaveBeenCalledOnce();
+    });
+    it('category 파라미터를 쿼리스트링으로 전달한다', async () => {
+        mockFetch.mockResolvedValueOnce(makeOkResponse({ success: true, templates: [] }));
+        await fetchTemplateList({ category: 'mobile' });
+        const calledUrl = mockFetch.mock.calls[0][0];
+        expect(calledUrl).toContain('category=mobile');
+    });
+    it('search 파라미터를 쿼리스트링으로 전달한다', async () => {
+        mockFetch.mockResolvedValueOnce(makeOkResponse({ success: true, templates: [] }));
+        await fetchTemplateList({ search: 'login' });
+        const calledUrl = mockFetch.mock.calls[0][0];
+        expect(calledUrl).toContain('search=login');
+    });
+    it('API 응답 success: false 시 에러를 반환한다', async () => {
+        mockFetch.mockResolvedValueOnce(makeOkResponse({ success: false, error: 'not found' }));
+        const result = await fetchTemplateList();
+        expect(result.ok).toBe(false);
+        if (!result.ok) {
+            expect(result.error.code).toBe('SERVER_ERROR');
+        }
+    });
+    it('fetch 네트워크 오류 시 NETWORK_ERROR를 반환한다', async () => {
+        mockFetch.mockRejectedValueOnce(new Error('Network error'));
+        const result = await fetchTemplateList();
+        expect(result.ok).toBe(false);
+        if (!result.ok) {
+            expect(result.error.code).toBe('NETWORK_ERROR');
+        }
+    });
+    it('인증 없는 상태에서 NOT_AUTHENTICATED를 반환한다', async () => {
+        mockGetAuthData.mockReturnValue(null);
+        const result = await fetchTemplateList();
+        expect(result.ok).toBe(false);
+        if (!result.ok) {
+            expect(result.error.code).toBe('NOT_AUTHENTICATED');
+        }
+        expect(mockFetch).not.toHaveBeenCalled();
+    });
+});
+// ─────────────────────────────────────────────────────────────────────────────
+// fetchTemplate
+// ─────────────────────────────────────────────────────────────────────────────
+describe('fetchTemplate()', () => {
+    it('API 성공 시 ok: true와 템플릿 상세를 반환한다', async () => {
+        const template = { id: 'dashboard', name: 'Dashboard', sections: [] };
+        mockFetch.mockResolvedValueOnce(makeOkResponse({ success: true, template }));
+        const result = await fetchTemplate('dashboard');
+        expect(result.ok).toBe(true);
+        if (result.ok) {
+            expect(result.data.id).toBe('dashboard');
+        }
+    });
+    it('API 응답 success: false 시 에러를 반환한다', async () => {
+        mockFetch.mockResolvedValueOnce(makeOkResponse({ success: false, error: 'not found' }));
+        const result = await fetchTemplate('nonexistent');
+        expect(result.ok).toBe(false);
+    });
+    it('fetch 네트워크 오류 시 NETWORK_ERROR를 반환한다', async () => {
+        mockFetch.mockRejectedValueOnce(new Error('timeout'));
+        const result = await fetchTemplate('dashboard');
+        expect(result.ok).toBe(false);
+        if (!result.ok) {
+            expect(result.error.code).toBe('NETWORK_ERROR');
+        }
+    });
+    it('ID가 URL 인코딩되어 전달된다', async () => {
+        mockFetch.mockResolvedValueOnce(makeOkResponse({ success: true, template: { id: 'my template' } }));
+        await fetchTemplate('my template');
+        const calledUrl = mockFetch.mock.calls[0][0];
+        expect(calledUrl).toContain('my%20template');
+    });
+});
+// ─────────────────────────────────────────────────────────────────────────────
+// fetchComponentList
+// ─────────────────────────────────────────────────────────────────────────────
+describe('fetchComponentList()', () => {
+    it('API 성공 시 ok: true와 컴포넌트 목록을 반환한다', async () => {
+        const components = [
+            {
+                id: 'button',
+                name: 'Button',
+                category: 'core',
+                tier: 1,
+                description: '',
+                variantsCount: 6,
+                hasSubComponents: false,
+            },
+        ];
+        mockFetch.mockResolvedValueOnce(makeOkResponse({ success: true, components }));
+        const result = await fetchComponentList();
+        expect(result.ok).toBe(true);
+        if (result.ok) {
+            expect(result.data).toHaveLength(1);
+            expect(result.data[0].id).toBe('button');
+        }
+    });
+    it('API 응답 success: false 시 에러를 반환한다', async () => {
+        mockFetch.mockResolvedValueOnce(makeOkResponse({ success: false }));
+        const result = await fetchComponentList();
+        expect(result.ok).toBe(false);
+    });
+    it('fetch 네트워크 오류 시 NETWORK_ERROR를 반환한다', async () => {
+        mockFetch.mockRejectedValueOnce(new Error('Network error'));
+        const result = await fetchComponentList();
+        expect(result.ok).toBe(false);
+        if (!result.ok) {
+            expect(result.error.code).toBe('NETWORK_ERROR');
+        }
+    });
+});
+// ─────────────────────────────────────────────────────────────────────────────
+// fetchComponent
+// ─────────────────────────────────────────────────────────────────────────────
+describe('fetchComponent()', () => {
+    it('API 성공 시 ok: true와 컴포넌트 상세를 반환한다', async () => {
+        const component = {
+            id: 'button',
+            name: 'Button',
+            category: 'core',
+            tier: 1,
+            description: 'Button desc',
+            variantsCount: 6,
+            hasSubComponents: false,
+            props: [],
+            variants: [],
+        };
+        mockFetch.mockResolvedValueOnce(makeOkResponse({ success: true, component }));
+        const result = await fetchComponent('button');
+        expect(result.ok).toBe(true);
+        if (result.ok) {
+            expect(result.data.id).toBe('button');
+            expect(result.data.props).toBeDefined();
+        }
+    });
+    it('API 응답 success: false 시 에러를 반환한다', async () => {
+        mockFetch.mockResolvedValueOnce(makeOkResponse({ success: false, error: 'not found' }));
+        const result = await fetchComponent('nonexistent');
+        expect(result.ok).toBe(false);
+    });
+    it('fetch 네트워크 오류 시 NETWORK_ERROR를 반환한다', async () => {
+        mockFetch.mockRejectedValueOnce(new Error('timeout'));
+        const result = await fetchComponent('button');
+        expect(result.ok).toBe(false);
+        if (!result.ok) {
+            expect(result.error.code).toBe('NETWORK_ERROR');
+        }
+    });
+});
+// ─────────────────────────────────────────────────────────────────────────────
+// fetchTokenList
+// ─────────────────────────────────────────────────────────────────────────────
+describe('fetchTokenList()', () => {
+    it('type=all 요청 시 ok: true와 shells/pages/sections를 반환한다', async () => {
+        const responseBody = {
+            success: true,
+            shells: [{ id: 'shell.web.dashboard' }],
+            pages: [{ id: 'page.dashboard' }],
+            sections: [{ id: 'section.container' }],
+            metadata: { total: 3 },
+        };
+        mockFetch.mockResolvedValueOnce(makeOkResponse(responseBody));
+        const result = await fetchTokenList('all');
+        expect(result.ok).toBe(true);
+        if (result.ok) {
+            expect(result.data.metadata.total).toBe(3);
+            expect(result.data.shells).toHaveLength(1);
+            expect(result.data.pages).toHaveLength(1);
+            expect(result.data.sections).toHaveLength(1);
+        }
+    });
+    it('type=shell 쿼리파라미터가 전달된다', async () => {
+        mockFetch.mockResolvedValueOnce(makeOkResponse({ success: true, shells: [], metadata: { total: 0 } }));
+        await fetchTokenList('shell');
+        const calledUrl = mockFetch.mock.calls[0][0];
+        expect(calledUrl).toContain('type=shell');
+    });
+    it('API 응답 success: false 시 에러를 반환한다', async () => {
+        mockFetch.mockResolvedValueOnce(makeOkResponse({ success: false }));
+        const result = await fetchTokenList('all');
+        expect(result.ok).toBe(false);
+    });
+    it('tokenType 미지정 시 type=all로 요청된다', async () => {
+        mockFetch.mockResolvedValueOnce(makeOkResponse({ success: true, metadata: { total: 0 } }));
+        await fetchTokenList();
+        const calledUrl = mockFetch.mock.calls[0][0];
+        expect(calledUrl).toContain('type=all');
+    });
+});
+// ─────────────────────────────────────────────────────────────────────────────
+// fetchCSSVariables
+// ─────────────────────────────────────────────────────────────────────────────
+describe('fetchCSSVariables()', () => {
+    it('API 성공 시 ok: true와 CSS 문자열을 반환한다', async () => {
+        const css = ':root { --color-brand-500: oklch(0.5 0.2 240); }';
+        mockFetch.mockResolvedValueOnce(makeOkResponse({ success: true, css }));
+        const result = await fetchCSSVariables('square-minimalism');
+        expect(result.ok).toBe(true);
+        if (result.ok) {
+            expect(result.data).toBe(css);
+            expect(result.data).toContain(':root');
+        }
+    });
+    it('API 응답 success: false 시 에러를 반환한다', async () => {
+        mockFetch.mockResolvedValueOnce(makeOkResponse({ success: false, error: 'not found' }));
+        const result = await fetchCSSVariables('nonexistent');
+        expect(result.ok).toBe(false);
+    });
+    it('fetch 네트워크 오류 시 NETWORK_ERROR를 반환한다', async () => {
+        mockFetch.mockRejectedValueOnce(new Error('timeout'));
+        const result = await fetchCSSVariables('square-minimalism');
+        expect(result.ok).toBe(false);
+        if (!result.ok) {
+            expect(result.error.code).toBe('NETWORK_ERROR');
+        }
+    });
+    it('themeId와 /css 경로가 URL에 포함된다', async () => {
+        mockFetch.mockResolvedValueOnce(makeOkResponse({ success: true, css: ':root {}' }));
+        await fetchCSSVariables('dark-boldness');
+        const calledUrl = mockFetch.mock.calls[0][0];
+        expect(calledUrl).toContain('dark-boldness');
+        expect(calledUrl).toContain('/css');
+    });
+});
+// ─────────────────────────────────────────────────────────────────────────────
+// fetchScreenExamples
+// ─────────────────────────────────────────────────────────────────────────────
+describe('fetchScreenExamples()', () => {
+    it('API 성공 시 ok: true와 스크린 예제 목록을 반환한다', async () => {
+        const examples = [
+            { name: 'Team Grid', description: 'Grid layout', definition: { id: 'team-grid' } },
+            { name: 'Login Form', description: 'Auth screen', definition: { id: 'login-screen' } },
+        ];
+        mockFetch.mockResolvedValueOnce(makeOkResponse({ success: true, examples }));
+        const result = await fetchScreenExamples();
+        expect(result.ok).toBe(true);
+        if (result.ok) {
+            expect(result.data).toHaveLength(2);
+            expect(result.data[0].name).toBe('Team Grid');
+            expect(result.data[1].definition.id).toBe('login-screen');
+        }
+    });
+    it('API 응답 success: false 시 에러를 반환한다', async () => {
+        mockFetch.mockResolvedValueOnce(makeOkResponse({ success: false }));
+        const result = await fetchScreenExamples();
+        expect(result.ok).toBe(false);
+    });
+    it('fetch 네트워크 오류 시 NETWORK_ERROR를 반환한다', async () => {
+        mockFetch.mockRejectedValueOnce(new Error('Network error'));
+        const result = await fetchScreenExamples();
+        expect(result.ok).toBe(false);
+        if (!result.ok) {
+            expect(result.error.code).toBe('NETWORK_ERROR');
+        }
+    });
+    it('응답 예제에 name, description, definition이 포함된다', async () => {
+        const examples = [
+            {
+                name: 'Dashboard',
+                description: 'Analytics',
+                definition: { id: 'dashboard-overview', shell: 'shell.web.dashboard' },
+            },
+        ];
+        mockFetch.mockResolvedValueOnce(makeOkResponse({ success: true, examples }));
+        const result = await fetchScreenExamples();
+        expect(result.ok).toBe(true);
+        if (result.ok) {
+            expect(result.data[0]).toHaveProperty('name');
+            expect(result.data[0]).toHaveProperty('description');
+            expect(result.data[0]).toHaveProperty('definition');
+            expect(result.data[0].definition.shell).toBe('shell.web.dashboard');
+        }
+    });
+});
+// ─────────────────────────────────────────────────────────────────────────────
+// HTTP 에러 코드 분류 테스트
+// ─────────────────────────────────────────────────────────────────────────────
+describe('HTTP 에러 코드 분류', () => {
+    it('401 응답 시 AUTH_FAILED 에러를 반환한다', async () => {
+        mockFetch.mockResolvedValueOnce(makeErrorResponse(401, { error: 'unauthorized' }));
+        const result = await fetchTemplate('pebble');
+        expect(result.ok).toBe(false);
+        if (!result.ok) {
+            expect(result.error.code).toBe('AUTH_FAILED');
+            expect(result.error.status).toBe(401);
+        }
+    });
+    it('403 응답 시 FORBIDDEN 에러를 반환한다', async () => {
+        mockFetch.mockResolvedValueOnce(makeErrorResponse(403, { error: 'Theme "pebble" is not included in your license.' }));
+        const result = await fetchTemplate('pebble');
+        expect(result.ok).toBe(false);
+        if (!result.ok) {
+            expect(result.error.code).toBe('FORBIDDEN');
+            expect(result.error.message).toContain('not included');
+        }
+    });
+    it('429 응답 시 RATE_LIMITED 에러를 반환한다', async () => {
+        mockFetch.mockResolvedValueOnce(makeErrorResponse(429, { error: 'Too many requests' }));
+        const result = await fetchTemplate('pebble');
+        expect(result.ok).toBe(false);
+        if (!result.ok) {
+            expect(result.error.code).toBe('RATE_LIMITED');
+        }
+    });
+    it('500 응답 시 SERVER_ERROR 에러를 반환한다', async () => {
+        mockFetch.mockResolvedValueOnce(makeErrorResponse(500, { error: 'Internal server error' }));
+        const result = await fetchTemplate('pebble');
+        expect(result.ok).toBe(false);
+        if (!result.ok) {
+            expect(result.error.code).toBe('SERVER_ERROR');
+            expect(result.error.status).toBe(500);
+        }
+    });
+});
+//# sourceMappingURL=data-client.test.js.map