diff --git a/API.md b/API.md
new file mode 100644
index 0000000..9bdd46d
--- /dev/null
+++ b/API.md
@@ -0,0 +1,367 @@
+# Fuzzly API Documentation
+
+Fuzzly는 한글 커맨드 팔레트를 위한 유연한 퍼지 검색 라이브러리입니다.
+
+## 설치
+
+```bash
+npm install fuzzly
+```
+
+## 기본 사용법
+
+### 간단한 문자열 검색
+
+```typescript
+import { search } from 'fuzzly';
+
+const items = ['값어치', '가치', '감사합니다'];
+const results = search('값', items);
+
+console.log(results);
+// [
+//   { item: '값어치', score: 0.95, matches: [...], index: 0 }
+// ]
+```
+
+### 객체 배열 검색
+
+```typescript
+import { search } from 'fuzzly';
+
+const commands = [
+  { name: '파일 열기', command: 'file.open' },
+  { name: '파일 닫기', command: 'file.close' },
+  { name: '새 파일', command: 'file.new' }
+];
+
+const results = search('파열', commands, {
+  keys: ['name']
+});
+
+// '파일 열기'를 찾습니다
+console.log(results[0].item.name); // '파일 열기'
+```
+
+## Public API
+
+### `search<T>(query: string, items: T[], options?: SearchOptions): SearchResult<T>[]`
+
+메인 검색 함수입니다. 아이템 배열에서 쿼리와 매칭되는 항목을 찾습니다.
+
+**Parameters:**
+- `query`: 검색어 문자열
+- `items`: 검색 대상 배열
+- `options`: 검색 옵션 (선택)
+
+**Returns:** 검색 결과 배열, 관련도순으로 정렬됨
+
+**Example:**
+```typescript
+const results = search('ㅇㅎㅇ', ['안녕하세요', '반갑습니다']);
+```
+
+### `matches<T>(query: string, item: T, options?: SearchOptions): boolean`
+
+단일 아이템이 쿼리와 매칭되는지 빠르게 확인합니다.
+
+**Example:**
+```typescript
+const items = ['값어치', '가치', '감사'];
+const filtered = items.filter(item => matches('값', item));
+```
+
+### `getMatchRanges<T>(query: string, item: T, options?: SearchOptions): MatchRange[] | null`
+
+단일 아이템에서 매칭된 위치 정보만 가져옵니다. 하이라이트 표시에 유용합니다.
+
+**Example:**
+```typescript
+const ranges = getMatchRanges('파열', '파일 열기');
+// 매칭된 범위를 사용해 텍스트 하이라이트
+```
+
+## SearchOptions
+
+검색 동작을 커스터마이즈하는 옵션들:
+
+```typescript
+interface SearchOptions {
+  keys?: string[] | ((item: any) => string)[];
+  allowTailSpillover?: boolean;
+  whitespaceMode?: 'boundary' | 'split' | 'literal';
+  threshold?: number;
+  sort?: boolean;
+  limit?: number;
+  caseSensitive?: boolean;
+}
+```
+
+### `keys`
+
+검색할 필드를 지정합니다. 문자열 배열이나 함수 배열을 사용할 수 있습니다.
+
+```typescript
+// 문자열 키
+search('query', items, { keys: ['name', 'description'] });
+
+// 함수 키
+search('query', items, {
+  keys: [
+    'name',
+    (item) => item.tags.join(' ')
+  ]
+});
+```
+
+### `allowTailSpillover`
+
+받침이 다음 글자의 초성으로 넘어가는 것을 허용할지 여부입니다. 타이핑 중 부분 입력에 유용합니다.
+
+- **기본값:** `true`
+- **예시:** `allowTailSpillover: true`일 때, "값"이 "값어치"와 매칭됩니다.
+
+```typescript
+search('값', ['값어치'], { allowTailSpillover: true });
+```
+
+### `whitespaceMode`
+
+쿼리의 공백을 어떻게 처리할지 결정합니다.
+
+- `'split'` (기본값): 공백으로 쿼리를 나누어 여러 토큰으로 처리 (AND 로직)
+- `'boundary'`: 공백을 경계로 처리 (spillover 불가)
+- `'literal'`: 공백을 그대로 매칭할 문자로 처리
+
+```typescript
+// 'split' 모드: "파일"과 "열기" 둘 다 매칭되어야 함
+search('파일 열기', items, { whitespaceMode: 'split' });
+
+// 'literal' 모드: 정확히 "파일 열기" 문자열 찾기
+search('파일 열기', items, { whitespaceMode: 'literal' });
+```
+
+### `threshold`
+
+매칭 품질 임계값 (0-1). 이 값보다 낮은 점수의 결과는 제외됩니다.
+
+- **기본값:** `0` (모든 매칭 허용)
+- **범위:** `0` (관대함) ~ `1` (엄격함)
+
+```typescript
+search('query', items, { threshold: 0.5 });
+```
+
+### `sort`
+
+결과를 관련도순으로 정렬할지 여부입니다.
+
+- **기본값:** `true`
+
+```typescript
+search('query', items, { sort: false }); // 원본 순서 유지
+```
+
+### `limit`
+
+반환할 최대 결과 수입니다.
+
+- **기본값:** `undefined` (모든 결과 반환)
+
+```typescript
+search('query', items, { limit: 10 }); // 상위 10개만 반환
+```
+
+### `caseSensitive`
+
+영문 대소문자 구분 여부입니다.
+
+- **기본값:** `false` (대소문자 구분 안 함)
+
+```typescript
+search('Open', items, { caseSensitive: false }); // 'open', 'OPEN', 'Open' 모두 매칭
+```
+
+## SearchResult
+
+검색 결과 객체:
+
+```typescript
+interface SearchResult<T> {
+  item: T;                                    // 매칭된 아이템
+  score: number;                              // 매칭 점수 (0-1, 높을수록 좋음)
+  matches: Array<MatchRange[] | undefined>;   // 필드별 매칭 범위
+  index: number;                              // 원본 배열의 인덱스
+}
+```
+
+### 매칭 범위를 사용한 하이라이트 예시
+
+```typescript
+const results = search('파열', ['파일 열기']);
+const result = results[0];
+
+if (result.matches[0]) {
+  const text = result.item;
+  const ranges = result.matches[0];
+  
+  // ranges를 사용해 하이라이트 처리
+  ranges.forEach(range => {
+    console.log(`매칭: ${text.slice(range.start, range.end)}`);
+  });
+}
+```
+
+## 고급 기능
+
+### 리터럴 검색
+
+따옴표로 감싸면 리터럴 검색이 됩니다:
+
+```typescript
+search('"값"', ['값어치', '가치']); // 정확히 "값" 문자열만 찾기
+```
+
+### 초성 검색
+
+한글 초성으로 검색할 수 있습니다:
+
+```typescript
+search('ㅇㅎㅇ', ['안녕하세요']); // 매칭됨
+search('ㄱㄴㄷ', ['가나다라']); // 매칭됨
+```
+
+### 복합 객체 검색
+
+여러 필드와 함수를 조합해 검색할 수 있습니다:
+
+```typescript
+interface Command {
+  name: string;
+  tags: string[];
+  metadata: { category: string };
+}
+
+const results = search('query', commands, {
+  keys: [
+    'name',
+    (cmd) => cmd.tags.join(' '),
+    (cmd) => cmd.metadata.category
+  ]
+});
+```
+
+## Low-level API
+
+더 세밀한 제어가 필요한 경우 저수준 API를 사용할 수 있습니다:
+
+```typescript
+import {
+  buildFuzzyQuery,
+  extractStrokes,
+  matchFuzzyStrokes,
+  matchLiteral,
+  buildMatchRanges
+} from 'fuzzly';
+
+// 1. 쿼리 빌드
+const query = buildFuzzyQuery('값');
+
+// 2. 텍스트를 스트로크로 변환
+const strokes = extractStrokes('값어치');
+
+// 3. 매칭 수행
+const matches = matchFuzzyStrokes(query, [strokes]);
+
+// 4. 매칭 범위 생성
+const ranges = buildMatchRanges([matches], [strokes]);
+```
+
+대부분의 경우 고수준 `search()` 함수를 사용하는 것이 권장됩니다.
+
+## 사용 예시
+
+### 커맨드 팔레트
+
+```typescript
+import { search } from 'fuzzly';
+
+const commands = [
+  { id: 'file.open', name: '파일 열기' },
+  { id: 'file.save', name: '파일 저장' },
+  { id: 'edit.copy', name: '복사' },
+  { id: 'edit.paste', name: '붙여넣기' }
+];
+
+function searchCommands(query: string) {
+  return search(query, commands, {
+    keys: ['name'],
+    limit: 5,
+    sort: true
+  });
+}
+
+// 사용
+const results = searchCommands('파저');
+// '파일 저장'이 최상단에 나옴
+```
+
+### 자동완성
+
+```typescript
+import { search } from 'fuzzly';
+
+function autocomplete(query: string, items: string[]) {
+  if (!query) return items.slice(0, 10);
+  
+  return search(query, items, {
+    limit: 10,
+    threshold: 0.3,
+    sort: true
+  }).map(r => r.item);
+}
+```
+
+### 필터링
+
+```typescript
+import { matches } from 'fuzzly';
+
+const allItems = ['값어치', '가치', '감사', '강아지'];
+const query = '가';
+
+const filtered = allItems.filter(item => matches(query, item));
+```
+
+## TypeScript 지원
+
+Fuzzly는 완전한 TypeScript 지원을 제공합니다:
+
+```typescript
+import { search, SearchOptions, SearchResult } from 'fuzzly';
+
+interface MyItem {
+  id: number;
+  name: string;
+}
+
+const items: MyItem[] = [
+  { id: 1, name: '항목1' },
+  { id: 2, name: '항목2' }
+];
+
+const results: SearchResult<MyItem>[] = search('항목', items, {
+  keys: ['name']
+});
+```
+
+## 성능 팁
+
+1. **객체 검색 시 `keys` 옵션 사용**: 검색할 필드를 명시하면 불필요한 검색을 피할 수 있습니다.
+2. **`limit` 옵션 활용**: 많은 결과가 예상되는 경우 limit를 설정하세요.
+3. **`sort: false` 고려**: 정렬이 필요없다면 비활성화해 성능을 향상시킬 수 있습니다.
+4. **`threshold` 조정**: 적절한 임계값으로 관련성 낮은 결과를 필터링하세요.
+
+## 라이선스
+
+ISC
diff --git a/IMPLEMENTATION_SUMMARY.md b/IMPLEMENTATION_SUMMARY.md
new file mode 100644
index 0000000..695b80f
--- /dev/null
+++ b/IMPLEMENTATION_SUMMARY.md
@@ -0,0 +1,215 @@
+# Public API Implementation Summary
+
+## Overview
+This PR implements a comprehensive, flexible, and intuitive public API for the fuzzly library, designed to work seamlessly in any project.
+
+## Key Features Implemented
+
+### 1. Main API Functions
+
+#### `search<T>(query: string, items: T[], options?: SearchOptions): SearchResult<T>[]`
+- Primary search function with full configurability
+- Returns sorted, scored results with match information
+- Supports both simple strings and complex objects
+- Type-safe with full TypeScript support
+
+#### `matches<T>(query: string, item: T, options?: SearchOptions): boolean`
+- Quick boolean check for filtering
+- Useful for array `.filter()` operations
+- Same options as search function
+
+#### `getMatchRanges<T>(query: string, item: T, options?: SearchOptions): MatchRange[] | null`
+- Returns only the match ranges for highlighting
+- Lightweight alternative when scoring isn't needed
+- Perfect for UI highlighting
+
+### 2. SearchOptions Interface
+
+Provides fine-grained control over search behavior:
+
+- **keys**: `(string | ((item: T) => string))[]` - Specify searchable fields
+- **allowTailSpillover**: `boolean` (default: true) - Korean consonant spillover
+- **whitespaceMode**: `'split' | 'boundary' | 'literal'` (default: 'split') - How to handle spaces
+- **threshold**: `number` (default: 0) - Minimum match quality (0-1)
+- **sort**: `boolean` (default: true) - Sort by relevance
+- **limit**: `number` (default: undefined) - Max results to return
+- **caseSensitive**: `boolean` (default: false) - Case sensitivity for English
+
+### 3. Smart Features
+
+#### Multi-field Search
+```typescript
+search('query', items, {
+  keys: [
+    'name',
+    'description',
+    (item) => item.tags.join(' ')
+  ]
+});
+```
+
+#### Multi-token Search
+```typescript
+search('파일 열기', items, { whitespaceMode: 'split' });
+// Both "파일" AND "열기" must match
+```
+
+#### Relevance Scoring
+- Base score from coverage ratio
+- Bonus for earlier matches
+- Bonus for consecutive character matches
+- Bonus for more match density
+
+#### Case Insensitive by Default
+- English text automatically lowercased
+- Configurable via `caseSensitive` option
+- Korean matching unaffected
+
+### 4. Return Value Structure
+
+```typescript
+interface SearchResult<T> {
+  item: T;                                    // Original item
+  score: number;                              // Match quality (0-1)
+  matches: Array<MatchRange[] | undefined>;   // Ranges per field
+  index: number;                              // Original array index
+}
+```
+
+## Testing
+
+- **43 comprehensive test cases** covering:
+  - Basic string search
+  - Object property search
+  - Multi-field search with functions
+  - All option combinations
+  - Edge cases (null, undefined, numbers, special chars)
+  - Korean fuzzy matching (초성)
+  - English case insensitivity
+  - Sorting and scoring behavior
+  - Helper functions (matches, getMatchRanges)
+
+- **All tests passing** ✅
+
+## Documentation
+
+### 1. API.md
+Complete API documentation in Korean with:
+- Installation instructions
+- Basic usage examples
+- Detailed option descriptions
+- Advanced use cases
+- Performance tips
+
+### 2. Updated README.md
+- Quick start guide
+- Key features overview
+- Link to full documentation
+
+### 3. examples.ts
+11 practical examples demonstrating:
+- Basic search
+- Command palette implementation
+- Autocomplete
+- Highlighting
+- Complex object search
+- All option variations
+
+## Backward Compatibility
+
+✅ **No breaking changes**
+- All existing low-level functions still exported
+- New high-level API is additive
+- Existing code continues to work
+
+## Build & Quality
+
+- ✅ TypeScript compilation successful
+- ✅ Full type definitions generated
+- ✅ ESM and CJS outputs
+- ✅ Code review feedback addressed
+- ✅ Security scan passed (0 vulnerabilities)
+
+## Design Principles
+
+### Flexibility
+- Works with strings, objects, nested data
+- Configurable via comprehensive options
+- Both simple and advanced use cases supported
+
+### Intuitiveness  
+- Sensible defaults (sort: true, caseSensitive: false)
+- Clear option names
+- Predictable behavior
+- Helpful TypeScript IntelliSense
+
+### Portability
+- No required configuration
+- Drop-in ready for any project
+- Works with any data structure
+- Framework agnostic
+
+### Type Safety
+- Full TypeScript support
+- Generic types for item preservation
+- Proper type guards
+- No unsafe `any` casts (except documented edge cases)
+
+## Usage Patterns Supported
+
+1. **Command Palette**
+   ```typescript
+   search('파열', commands, { keys: ['name'], limit: 5 })
+   ```
+
+2. **Autocomplete**
+   ```typescript
+   search(input, items, { threshold: 0.3, limit: 10 })
+   ```
+
+3. **Filtering**
+   ```typescript
+   items.filter(item => matches(query, item))
+   ```
+
+4. **Highlighting**
+   ```typescript
+   const ranges = getMatchRanges(query, text)
+   // Use ranges to highlight matched portions
+   ```
+
+5. **Multi-field Search**
+   ```typescript
+   search(query, items, {
+     keys: ['title', (item) => item.tags.join(' ')]
+   })
+   ```
+
+## Performance Considerations
+
+- Single-pass search algorithm
+- Early termination on non-matches
+- Optional result limiting
+- Optional sorting disable
+- Efficient range building
+
+## Future Enhancement Opportunities
+
+While not implemented in this PR (to keep changes minimal):
+- Fuzzy matching threshold tuning
+- Custom scoring functions
+- Async search for large datasets
+- Result caching
+- Search debouncing helper
+
+## Conclusion
+
+This PR delivers a production-ready, flexible public API that:
+- ✅ Works intuitively out of the box
+- ✅ Supports advanced customization
+- ✅ Maintains backward compatibility
+- ✅ Has comprehensive test coverage
+- ✅ Includes complete documentation
+- ✅ Passes all quality checks
+
+The API is ready to be used in any project without modification.
diff --git a/command-palette-example.ts b/command-palette-example.ts
new file mode 100644
index 0000000..a4bf9b8
--- /dev/null
+++ b/command-palette-example.ts
@@ -0,0 +1,311 @@
+/**
+ * Real-world Command Palette Example
+ * 
+ * This example demonstrates how to use fuzzly in a command palette UI
+ */
+
+import { search, type SearchResult } from './src/search';
+
+// ============================================================
+// Define Command Structure
+// ============================================================
+
+interface Command {
+  id: string;
+  name: string;
+  description: string;
+  category: string;
+  keywords: string[];
+  icon?: string;
+}
+
+// ============================================================
+// Sample Commands (like in VSCode or Sublime)
+// ============================================================
+
+const commands: Command[] = [
+  // File operations
+  {
+    id: 'file.new',
+    name: '새 파일',
+    description: '새로운 파일을 만듭니다',
+    category: '파일',
+    keywords: ['생성', 'create', 'new'],
+    icon: '📄'
+  },
+  {
+    id: 'file.open',
+    name: '파일 열기',
+    description: '기존 파일을 엽니다',
+    category: '파일',
+    keywords: ['불러오기', 'open', 'load'],
+    icon: '📂'
+  },
+  {
+    id: 'file.save',
+    name: '파일 저장',
+    description: '현재 파일을 저장합니다',
+    category: '파일',
+    keywords: ['세이브', 'save'],
+    icon: '💾'
+  },
+  {
+    id: 'file.saveAs',
+    name: '다른 이름으로 저장',
+    description: '파일을 새 이름으로 저장합니다',
+    category: '파일',
+    keywords: ['save as', 'export'],
+    icon: '💾'
+  },
+  
+  // Edit operations
+  {
+    id: 'edit.copy',
+    name: '복사',
+    description: '선택한 내용을 복사합니다',
+    category: '편집',
+    keywords: ['copy', 'duplicate'],
+    icon: '📋'
+  },
+  {
+    id: 'edit.paste',
+    name: '붙여넣기',
+    description: '클립보드 내용을 붙여넣습니다',
+    category: '편집',
+    keywords: ['paste', 'insert'],
+    icon: '📋'
+  },
+  {
+    id: 'edit.find',
+    name: '찾기',
+    description: '텍스트를 검색합니다',
+    category: '편집',
+    keywords: ['search', 'find'],
+    icon: '🔍'
+  },
+  {
+    id: 'edit.replace',
+    name: '찾아서 바꾸기',
+    description: '텍스트를 찾아 다른 텍스트로 바꿉니다',
+    category: '편집',
+    keywords: ['replace', 'change'],
+    icon: '🔄'
+  },
+  
+  // View operations
+  {
+    id: 'view.toggleSidebar',
+    name: '사이드바 토글',
+    description: '사이드바를 표시하거나 숨깁니다',
+    category: '보기',
+    keywords: ['sidebar', 'panel'],
+    icon: '📱'
+  },
+  {
+    id: 'view.fullscreen',
+    name: '전체 화면',
+    description: '전체 화면 모드로 전환합니다',
+    category: '보기',
+    keywords: ['fullscreen', 'maximize'],
+    icon: '⛶'
+  },
+  
+  // Git operations
+  {
+    id: 'git.commit',
+    name: '커밋',
+    description: '변경사항을 커밋합니다',
+    category: 'Git',
+    keywords: ['commit', 'save changes'],
+    icon: '✓'
+  },
+  {
+    id: 'git.push',
+    name: '푸시',
+    description: '변경사항을 원격 저장소로 푸시합니다',
+    category: 'Git',
+    keywords: ['push', 'upload'],
+    icon: '⬆'
+  },
+  {
+    id: 'git.pull',
+    name: '풀',
+    description: '원격 저장소에서 변경사항을 가져옵니다',
+    category: 'Git',
+    keywords: ['pull', 'fetch', 'download'],
+    icon: '⬇'
+  },
+];
+
+// ============================================================
+// Command Palette Search Function
+// ============================================================
+
+function searchCommands(query: string): SearchResult<Command>[] {
+  if (!query || query.trim() === '') {
+    // Return all commands when query is empty
+    return commands.map((cmd, index) => ({
+      item: cmd,
+      score: 1,
+      matches: [],
+      index
+    }));
+  }
+
+  return search(query, commands, {
+    // Search across multiple fields
+    keys: [
+      'name',           // Primary: command name
+      'description',    // Secondary: description
+      'category',       // Category for filtering
+      (cmd) => cmd.keywords.join(' ')  // Additional keywords
+    ],
+    
+    // Sort by relevance (best matches first)
+    sort: true,
+    
+    // Limit to top 10 results
+    limit: 10,
+    
+    // Allow tail spillover for Korean typing
+    allowTailSpillover: true,
+    
+    // Split query by spaces (multiple keywords)
+    whitespaceMode: 'split',
+    
+    // Case insensitive for English
+    caseSensitive: false,
+    
+    // Only show reasonably good matches
+    threshold: 0.1
+  });
+}
+
+// ============================================================
+// Display Results (Simulated UI)
+// ============================================================
+
+function displayResults(query: string) {
+  console.log('\n' + '='.repeat(60));
+  console.log(`Search: "${query}"`);
+  console.log('='.repeat(60));
+  
+  const results = searchCommands(query);
+  
+  if (results.length === 0) {
+    console.log('No results found.');
+    return;
+  }
+  
+  results.forEach((result, index) => {
+    const cmd = result.item;
+    const scoreBar = '█'.repeat(Math.floor(result.score * 20));
+    
+    console.log(`\n${index + 1}. ${cmd.icon || '•'} ${cmd.name}`);
+    console.log(`   ${cmd.description}`);
+    console.log(`   Category: ${cmd.category} | Score: ${scoreBar} ${result.score.toFixed(2)}`);
+  });
+}
+
+// ============================================================
+// Example Searches
+// ============================================================
+
+console.log('\n🎯 Fuzzly Command Palette Demo\n');
+
+// Example 1: Korean fuzzy search
+displayResults('파열');  // Should find "파일 열기"
+
+// Example 2: Korean initial consonant search (초성)
+displayResults('ㅍㅇㅂ');  // Should find "파일" related commands
+
+// Example 3: English search
+displayResults('save');  // Should find save-related commands
+
+// Example 4: Multi-word search
+displayResults('파일 저장');  // Should find "파일 저장"
+
+// Example 5: Category search
+displayResults('git');  // Should find Git commands
+
+// Example 6: Mixed Korean/English
+displayResults('복 copy');  // Should find "복사" (copy)
+
+// Example 7: Partial typing
+displayResults('ㅅㅇㄷ');  // Should find "사이드바"
+
+// Example 8: Description search
+displayResults('검색');  // Should find commands with "검색" in description
+
+console.log('\n' + '='.repeat(60));
+console.log('✅ Demo completed!');
+console.log('='.repeat(60) + '\n');
+
+// ============================================================
+// Real UI Integration Notes
+// ============================================================
+
+/*
+To integrate this in a real UI (React, Vue, etc.):
+
+1. Debounce the search input:
+   ```typescript
+   const debouncedSearch = debounce((query: string) => {
+     const results = searchCommands(query);
+     setResults(results);
+   }, 150);
+   ```
+
+2. Highlight matched text using result.matches:
+   ```typescript
+   function highlightMatches(text: string, ranges: MatchRange[]) {
+     // Split text into highlighted and non-highlighted segments
+     // Render with different styles
+   }
+   ```
+
+3. Handle keyboard navigation:
+   ```typescript
+   function handleKeyDown(e: KeyboardEvent) {
+     if (e.key === 'ArrowDown') selectNext();
+     if (e.key === 'ArrowUp') selectPrev();
+     if (e.key === 'Enter') executeSelected();
+   }
+   ```
+
+4. Execute command on selection:
+   ```typescript
+   function executeCommand(cmd: Command) {
+     console.log('Executing:', cmd.id);
+     // Route to actual command implementation
+   }
+   ```
+*/
+
+// ============================================================
+// Performance Tips
+// ============================================================
+
+/*
+For optimal performance:
+
+1. Cache extracted strokes:
+   - If searching the same dataset repeatedly
+   - Pre-extract strokes on data load
+
+2. Virtualize long lists:
+   - Only render visible results
+   - Use libraries like react-window
+
+3. Consider fuzzy threshold:
+   - Higher threshold = fewer results = faster
+   - Balance between coverage and performance
+
+4. Lazy load descriptions:
+   - Only include critical fields in initial search
+   - Load full details on selection
+
+5. Worker threads for large datasets:
+   - Move search to Web Worker
+   - Keep UI responsive during search
+*/
diff --git a/examples.ts b/examples.ts
new file mode 100644
index 0000000..0367843
--- /dev/null
+++ b/examples.ts
@@ -0,0 +1,224 @@
+/**
+ * Fuzzly Usage Examples
+ * 
+ * This file demonstrates various usage patterns of the Fuzzly library
+ */
+
+import { search, matches, getMatchRanges, type SearchOptions } from './src/search';
+
+// ============================================================
+// Example 1: Basic String Search
+// ============================================================
+
+console.log('=== Example 1: Basic String Search ===');
+const fruits = ['사과', '바나나', '수박', '포도', '딸기'];
+const results1 = search('사', fruits);
+console.log('Query: "사"');
+console.log('Results:', results1.map(r => r.item));
+
+// ============================================================
+// Example 2: Fuzzy Korean Search (초성)
+// ============================================================
+
+console.log('\n=== Example 2: Fuzzy Korean Search (초성) ===');
+const items = ['안녕하세요', '반갑습니다', '고맙습니다'];
+const results2 = search('ㅇㅎㅇ', items);
+console.log('Query: "ㅇㅎㅇ"');
+console.log('Results:', results2.map(r => r.item));
+
+// ============================================================
+// Example 3: Command Palette
+// ============================================================
+
+console.log('\n=== Example 3: Command Palette ===');
+
+interface Command {
+  id: string;
+  name: string;
+  description: string;
+}
+
+const commands: Command[] = [
+  { id: 'file.open', name: '파일 열기', description: '파일을 엽니다' },
+  { id: 'file.save', name: '파일 저장', description: '현재 파일을 저장합니다' },
+  { id: 'file.close', name: '파일 닫기', description: '현재 파일을 닫습니다' },
+  { id: 'edit.copy', name: '복사', description: '선택한 내용을 복사합니다' },
+  { id: 'edit.paste', name: '붙여넣기', description: '클립보드 내용을 붙여넣습니다' },
+];
+
+const results3 = search('파열', commands, {
+  keys: ['name', 'description']
+});
+console.log('Query: "파열"');
+console.log('Results:', results3.map(r => `${r.item.name} (score: ${r.score.toFixed(2)})`));
+
+// ============================================================
+// Example 4: Search with Options
+// ============================================================
+
+console.log('\n=== Example 4: Search with Options ===');
+
+const allCommands = [
+  { name: '파일 열기', cmd: 'file.open' },
+  { name: '파일 저장', cmd: 'file.save' },
+  { name: '파일 닫기', cmd: 'file.close' },
+  { name: '새 파일', cmd: 'file.new' },
+];
+
+const options: SearchOptions = {
+  keys: ['name'],
+  limit: 2,
+  sort: true,
+  threshold: 0.3
+};
+
+const results4 = search('파', allCommands, options);
+console.log('Query: "파" with limit: 2');
+console.log('Results:', results4.map(r => r.item.name));
+
+// ============================================================
+// Example 5: Using matches() Helper
+// ============================================================
+
+console.log('\n=== Example 5: Using matches() Helper ===');
+
+const allItems = ['값어치', '가치', '감사', '강아지'];
+const query = '가';
+
+const filtered = allItems.filter(item => matches(query, item));
+console.log(`Items matching "${query}":`, filtered);
+
+// ============================================================
+// Example 6: Highlighting Matches with getMatchRanges()
+// ============================================================
+
+console.log('\n=== Example 6: Highlighting Matches ===');
+
+const text = '파일 열기';
+const searchQuery = '파열';
+const ranges = getMatchRanges(searchQuery, text);
+
+if (ranges && ranges[0]) {
+  console.log(`Text: "${text}"`);
+  console.log(`Query: "${searchQuery}"`);
+  console.log('Match ranges:', ranges[0]);
+  
+  // Simple highlight example
+  let highlighted = text;
+  ranges[0].reverse().forEach(range => {
+    highlighted = 
+      highlighted.slice(0, range.start) + 
+      '[' + 
+      highlighted.slice(range.start, range.end) + 
+      ']' + 
+      highlighted.slice(range.end);
+  });
+  console.log('Highlighted:', highlighted);
+}
+
+// ============================================================
+// Example 7: Multi-token Search
+// ============================================================
+
+console.log('\n=== Example 7: Multi-token Search ===');
+
+const documents = [
+  { title: '안녕하세요 여러분', content: '이것은 테스트입니다' },
+  { title: '반갑습니다', content: '안녕하세요' },
+  { title: '테스트 문서', content: '여러분 안녕하세요' },
+];
+
+const results7 = search('안녕 여러', documents, {
+  keys: ['title', 'content'],
+  whitespaceMode: 'split' // Both tokens must match (AND logic)
+});
+console.log('Query: "안녕 여러" (both tokens must match)');
+console.log('Results:', results7.map(r => r.item.title));
+
+// ============================================================
+// Example 8: Case Insensitive English Search
+// ============================================================
+
+console.log('\n=== Example 8: Case Insensitive English Search ===');
+
+const actions = [
+  { name: 'Open File', id: 1 },
+  { name: 'CLOSE FILE', id: 2 },
+  { name: 'Save File', id: 3 },
+];
+
+const results8 = search('open', actions, {
+  keys: ['name'],
+  caseSensitive: false
+});
+console.log('Query: "open" (case insensitive)');
+console.log('Results:', results8.map(r => r.item.name));
+
+// ============================================================
+// Example 9: Literal Search with Quotes
+// ============================================================
+
+console.log('\n=== Example 9: Literal Search with Quotes ===');
+
+const texts = ['값어치', '가치', '값'];
+const results9a = search('값', texts); // Fuzzy search
+const results9b = search('"값"', texts); // Literal search
+
+console.log('Fuzzy search "값":', results9a.map(r => r.item));
+console.log('Literal search "값":', results9b.map(r => r.item));
+
+// ============================================================
+// Example 10: Complex Object Search with Function Keys
+// ============================================================
+
+console.log('\n=== Example 10: Complex Object Search ===');
+
+interface Article {
+  title: string;
+  tags: string[];
+  author: { name: string };
+}
+
+const articles: Article[] = [
+  {
+    title: '타입스크립트 입문',
+    tags: ['typescript', 'programming'],
+    author: { name: '김철수' }
+  },
+  {
+    title: '자바스크립트 기초',
+    tags: ['javascript', 'web'],
+    author: { name: '이영희' }
+  },
+  {
+    title: '프로그래밍 패턴',
+    tags: ['design', 'patterns'],
+    author: { name: '박민수' }
+  }
+];
+
+const results10 = search('타입', articles, {
+  keys: [
+    'title',
+    (article) => article.tags.join(' '),
+    (article) => article.author.name
+  ]
+});
+console.log('Query: "타입"');
+console.log('Results:', results10.map(r => r.item.title));
+
+// ============================================================
+// Example 11: Sorting and Scoring
+// ============================================================
+
+console.log('\n=== Example 11: Sorting and Scoring ===');
+
+const words = ['가', '가나', '가나다', '가나다라'];
+const results11 = search('가', words, { sort: true });
+
+console.log('Query: "가" (sorted by relevance)');
+results11.forEach(r => {
+  console.log(`  ${r.item} - score: ${r.score.toFixed(3)}`);
+});
+
+console.log('\n✅ All examples completed!');
diff --git a/package-lock.json b/package-lock.json
index 52420c3..c0136a7 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -842,7 +842,6 @@
       "integrity": "sha512-gWEkeiyYE4vqjON/+Obqcoeffmk0NF15WSBwSs7zwVA2bAbTaE0SJ7P0WNGoJn8uE7fiaV5a7dKYIJriEqOrmA==",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "undici-types": "~7.16.0"
       }
@@ -1099,7 +1098,6 @@
       "dev": true,
       "hasInstallScript": true,
       "license": "MIT",
-      "peer": true,
       "bin": {
         "esbuild": "bin/esbuild"
       },
@@ -1342,7 +1340,6 @@
       "integrity": "sha512-5gTmgEY/sqK6gFXLIsQNH19lWb4ebPDLA4SdLP7dsWkIXHWlG66oPuVvXSGFPppYZz8ZDZq0dYYrbHfBCVUb1Q==",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "engines": {
         "node": ">=12"
       },
@@ -1392,7 +1389,6 @@
         }
       ],
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "nanoid": "^3.3.11",
         "picocolors": "^1.1.1",
@@ -1715,7 +1711,6 @@
       "integrity": "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==",
       "dev": true,
       "license": "Apache-2.0",
-      "peer": true,
       "bin": {
         "tsc": "bin/tsc",
         "tsserver": "bin/tsserver"
@@ -1744,7 +1739,6 @@
       "integrity": "sha512-ITcnkFeR3+fI8P1wMgItjGrR10170d8auB4EpMLPqmx6uxElH3a/hHGQabSHKdqd4FXWO1nFIp9rRn7JQ34ACQ==",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "esbuild": "^0.25.0",
         "fdir": "^6.5.0",
diff --git a/readme.md b/readme.md
index f6000fd..724e5f7 100644
--- a/readme.md
+++ b/readme.md
@@ -4,6 +4,44 @@
 
 커맨드팔레트(어렴풋이 기억나는 글자나 초성 몇 개 입력-> 결과 추리기-> 바로 실행)에서의 사용이 목적이기 때문에:
 
+## 🚀 빠른 시작
+
+```typescript
+import { search } from 'fuzzly';
+
+// 간단한 문자열 검색
+const results = search('ㅇㅎㅇ', ['안녕하세요', '반갑습니다']);
+
+// 객체 배열 검색
+const commands = [
+  { name: '파일 열기', cmd: 'open' },
+  { name: '파일 닫기', cmd: 'close' }
+];
+const results = search('파열', commands, { keys: ['name'] });
+```
+
+**📖 완전한 API 문서는 [API.md](./API.md)를 참고하세요.**
+
+## 주요 기능
+
+### ✨ 유연한 Public API
+
+- **`search(query, items, options)`** - 메인 검색 함수 (옵션 설정 가능)
+- **`matches(query, item, options)`** - 빠른 매칭 체크
+- **`getMatchRanges(query, item, options)`** - 하이라이트용 매칭 범위 반환
+
+### 🎯 다양한 검색 옵션
+
+- **keys**: 검색할 필드 지정 (문자열 또는 함수)
+- **allowTailSpillover**: 받침 spillover 허용 여부
+- **whitespaceMode**: 공백 처리 방식 ('split' | 'boundary' | 'literal')
+- **threshold**: 매칭 품질 임계값
+- **sort**: 관련도순 정렬
+- **limit**: 결과 개수 제한
+- **caseSensitive**: 대소문자 구분
+
+### 🔍 검색 기능
+
 1. 완전한 단어나 글자를 기대하지 말고  
    사용자가 어렴풋이 기억하고 있는 글자나 초성을 순서대로(하지만 연속적일 필요는 없음) 입력하는 것 만으로  
    원하는 결과를 찾아낼 수 있어야 함.
@@ -15,11 +53,16 @@
    검색 결과는 키 입력 시마다 범위가 좁혀지는 방향으로만 가야함. 절대 늘어나면 안됨!
 
 3. 받침까지 입력이 된 글자 => 실제로 받침을 의도하지 않고 그 이 후 글자의 초성을 의도한 것일 수 있음.  
-   `"갑"`은 정말로 `"갑"`을 의도한 것이 아니라 `"가방"`을 의도한 것일 수 있다는 뜻.
-   혹은 더 나아가서 `"ㅂ"`이 바로 다음 글자가 그냥 그 뒤 어딘가의 아무 글자에 매칭되길 바랬을 수도 있음. 이게 흔한 커맨트팔레트의 기본 동작임.
+   `"갑"`은 정말로 `"갑"`을 의도한 것이 아니라  
+   `"가방"`을 입력하던 중간단계일 수 있다는 뜻.  
+   혹은 더 나아가서 `"ㅂ"`이 바로 다음 글자가 그냥 그 뒤 어딘가의 아무 글자에 매칭되길 바랬을 수도 있음. 이게 대부분의 커맨트팔레트 기본 동작임.
+
+## 기본적인 매칭 예:
 
 쿼리: `"코"`, `"콧"`, `"콤"`, `"못"` 등등  
-텍스트: 코스모스
+텍스트: 코스모스  
+받침을 다음 글자로 흘려보내는 매칭은 좀 더 고민해 봐야 함.  
+필요하긴 하지만 항상 적절한 것은 아님.
 
 쿼리: `"ㅇㅌㄹ"`, `"ㅇㅅㄹ"`, `"ㅇㅌㅅㅌㄹ"`  
 텍스트: 인터스텔라  
@@ -35,7 +78,7 @@ chatgpt는 각 입력단계마다 그 이후 가능한 문자들을 모두 추
 텍스트: `"안녕하세요"` => "**ㅇ**ㅏㄴㄴㅕㅇ**ㅎ**ㅏㅅㅔ**ㅇ**ㅛ"  
 그냥 쉽게 된다!
 
-하지만... 몇가지 문제들이 있긴 하다.
+하지만... 몇가지 신경써야 할 부분이 존재함.
 
 ### 문제 1: 사용자는 모음이나 받침을 특정해서 검색하지 않음.
 
@@ -45,11 +88,11 @@ chatgpt는 각 입력단계마다 그 이후 가능한 문자들을 모두 추
 쿼리가 `"가"`라면 `"가"`, `"각"`, `"강"` 등을 찾고 싶은거다.  
 즉 모음이 쿼리 내 글자에 포함되는 순간(즉 초성만 입력된 게 아니라면) 그 글자는  
 완전한 글자 검색을 의도한 것임. `"고아"`를 찾고 싶은게 아니다.  
-(단순 키 입력 단위 매치라면 `"고"`에서 `"ㄱ"`, `"아"`에서 `"ㅏ"`가 매치 성공함 => wrong)
+(단순 키 입력 단위 매치라면 `"고"`에서 `"ㄱ"`, `"아"`에서 `"ㅏ"`가 매치 성공함)
 
 ### 문제 2: 마지막 글자는 확정된 상태가 아님
 
-(사실 더 정확하게 하려면 마지막 글자가 아니라 브라우저의 composition 이벤트에 의해 조합 중인 글자를 찾아야 함? 쉽지 않음.)
+(사실 더 정확하게 하려면 마지막 글자가 아니라 브라우저의 composition 이벤트에 의해 조합 중인 글자를 찾아야 함. 쉽지 않음.)
 
 `"여름에는 냉면"`이라는 텍스트를 찾기 위해 `"여냉"`을 입력한다면 입력 단계는
 
@@ -59,7 +102,7 @@ chatgpt는 각 입력단계마다 그 이후 가능한 문자들을 모두 추
 
 각 입력 단계는 모두 `"여름에는 냉면"`이라는 텍스트가 매치가 되어야 함.  
 `"연"`까지 입력한 상태에서 받침 `"ㄴ"`은 종성의 역할을 해도 되지만 그게 실패할 경우(여기서는 실패함)  
-이후 글자들의 초성에도 매치시도를 해봐야 함. > spillover
+`"ㄴ"`은 흘려보내서 이후 글자들의 초성에도 매치시도를 해봐야 함(`spillover`).
 
 하지만 모음은 절대 다음 글자로 넘겨서 시도하면 안됨. 모음으로 시작되는 글자는 없으니까!
 
@@ -67,8 +110,21 @@ chatgpt는 각 입력단계마다 그 이후 가능한 문자들을 모두 추
 
 ### 문제 3: 기타 등등
 
-...
+공백 처리. 어렵다기 보다는 어느 쪽이 맞는 지 판단이 쉽지 않음.
+
+1. 공백을 그냥 리터럴로 여기고 대상 텍스트의 공백과 매치를 시킬지,
+1. 공백을 경계로 쪼개서 여러개의 검색어로 활용할 지,
+1. 단순히 spillover가 불가능한 경계를 나타낼 지(공백 이후로는 받침을 흘려보내지 않음),
+1. 아니면 그냥 완전히 무시할 지...
+
+진짜 왕왕 고민되는 문제...
+현재 공백을 경계로 쪼개서 다수의 검색어로 활용하게 하고  
+각 검색어들 간의 순서는 중요하지 않게 설계를 했지만  
+(사용자가 입력한 검색어의 결과가 너무 많은 경우 다른 검색어를 또 입력해서 결과를 좁힐 수 있게)  
+문제는 첫번째 검색어에 매치된 텍스트가 두번째 검색어에도 다시 매치될 경우  
+두번째 검색어는 아무 곳에도 매치되지 않은 듯 한 느낌을 받게 된다.  
+중복 매치된 텍스트를 특별히 강조시켜 줄 방법도 없고 그러고 싶지도 않다. 지저분해지니까.
 
-## 머리 속에서는 모두 해결했음. 코드로 한번 짜봐야함.
+vscode에서는 전체 검색어 trim 후 문자 사이의 공백들은 공백 문자 그대로 리터럴로 처리, 대상 텍스트에 공백과 매치를 시키는 것 같다.
 
 ...
diff --git a/src/compressMatchIndexes.ts b/src/compressMatchIndexes.ts
index b450356..93b7bd8 100644
--- a/src/compressMatchIndexes.ts
+++ b/src/compressMatchIndexes.ts
@@ -1,4 +1,4 @@
-import { MatchRange } from "./types";
+import type { MatchRange } from "./types";
 
 export function compressMatchIndexes(indexes: number[]): MatchRange[] {
     if (indexes.length === 0) return [];
diff --git a/src/index.ts b/src/index.ts
index c85fe02..aeb22ab 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -1,4 +1,25 @@
-// Types
+// ============================================================
+// Public API - Recommended for most use cases
+// ============================================================
+
+/**
+ * Main search API - flexible and easy to use
+ * @see search - Main search function with options
+ * @see matches - Quick boolean check if item matches
+ * @see getMatchRanges - Get highlight ranges for matched text
+ */
+export {
+    search,
+    matches,
+    getMatchRanges,
+    type SearchOptions,
+    type SearchResult
+} from "./search";
+
+// ============================================================
+// Core Types - Useful for advanced usage
+// ============================================================
+
 export type {
     FuzzyQuery,
     FuzzyChar,
@@ -7,13 +28,17 @@ export type {
     MatchRange
 } from "./types";
 
-// Core builders
+// ============================================================
+// Low-level API - For advanced customization
+// ============================================================
+
+/**
+ * Low-level building blocks
+ * Use these if you need fine-grained control over the search process
+ * Most users should use the high-level `search` function instead
+ */
 export { buildFuzzyQuery } from "./buildFuzzyQuery";
 export { extractStrokes } from "./extractStrokes";
-
-// Matching
 export { matchLiteral } from "./matchLiteral";
 export { matchFuzzyStrokes } from "./matchFuzzyStrokes";
-
-// Post-processing
 export { buildMatchRanges } from "./buildMatchRanges";
diff --git a/src/mergeMatches.ts b/src/mergeMatches.ts
index eef208b..d0d3e32 100644
--- a/src/mergeMatches.ts
+++ b/src/mergeMatches.ts
@@ -1,5 +1,5 @@
-import type { MatchRange, StrokeMatchMap } from "./types";
 import { compressMatchIndexes } from "./compressMatchIndexes";
+import type { MatchRange, StrokeMatchMap } from "./types";
 
 export function mergeMatches(
     perToken: StrokeMatchMap[]
diff --git a/src/search.ts b/src/search.ts
new file mode 100644
index 0000000..2e9bc48
--- /dev/null
+++ b/src/search.ts
@@ -0,0 +1,383 @@
+import { buildFuzzyQuery } from "./buildFuzzyQuery";
+import { extractStrokes } from "./extractStrokes";
+import { matchLiteral } from "./matchLiteral";
+import { matchFuzzyStrokes } from "./matchFuzzyStrokes";
+import { buildMatchRanges } from "./buildMatchRanges";
+import type { FuzzyStrokes, StrokeMatchMap, MatchRange } from "./types";
+
+/**
+ * Options for configuring search behavior
+ */
+export interface SearchOptions {
+    /**
+     * Fields to search within each item
+     * Can be field names (string) or accessor functions
+     */
+    keys?: (string | ((item: any) => string))[];
+
+    /**
+     * Whether to allow spillover of final consonants (받침) to next character
+     * Useful for partial input during typing
+     * @default true
+     */
+    allowTailSpillover?: boolean;
+
+    /**
+     * How to handle whitespace in query
+     * - 'boundary': whitespace acts as a boundary (no spillover)
+     * - 'split': split query into multiple tokens (AND logic)
+     * - 'literal': treat whitespace as literal character to match
+     * @default 'split'
+     */
+    whitespaceMode?: 'boundary' | 'split' | 'literal';
+
+    /**
+     * Threshold for match quality (0-1)
+     * Lower values are more permissive
+     * @default 0
+     */
+    threshold?: number;
+
+    /**
+     * Sort results by match quality
+     * @default true
+     */
+    sort?: boolean;
+
+    /**
+     * Maximum number of results to return
+     * @default undefined (return all matches)
+     */
+    limit?: number | undefined;
+
+    /**
+     * Case sensitivity for non-Korean text
+     * @default false
+     */
+    caseSensitive?: boolean;
+}
+
+/**
+ * Search result with match information
+ */
+export interface SearchResult<T = any> {
+    /** The matched item */
+    item: T;
+    
+    /** Match score (higher is better) */
+    score: number;
+    
+    /** Array of match ranges per field */
+    matches: Array<MatchRange[] | undefined>;
+    
+    /** Index of the item in original array */
+    index: number;
+}
+
+/**
+ * Internal resolved options (all required except limit)
+ */
+interface ResolvedSearchOptions {
+    keys: (string | ((item: any) => string))[];
+    allowTailSpillover: boolean;
+    whitespaceMode: 'boundary' | 'split' | 'literal';
+    threshold: number;
+    sort: boolean;
+    limit: number | undefined;
+    caseSensitive: boolean;
+}
+
+/**
+ * Internal search context
+ */
+interface SearchContext<T> {
+    items: T[];
+    options: ResolvedSearchOptions;
+    query: string;
+    queries: string[];
+}
+
+/**
+ * Main search function - searches through an array of items
+ * 
+ * @param query - Search query string
+ * @param items - Array of items to search through
+ * @param options - Search configuration options
+ * @returns Array of search results sorted by relevance
+ * 
+ * @example
+ * ```ts
+ * const results = search('값', ['값어치', '가치', '갑작스런']);
+ * // Returns matches for '값어치'
+ * 
+ * const items = [
+ *   { name: '파일 열기', cmd: 'open' },
+ *   { name: '파일 닫기', cmd: 'close' }
+ * ];
+ * const results = search('파열', items, { keys: ['name'] });
+ * // Returns match for '파일 열기'
+ * ```
+ */
+export function search<T = string>(
+    query: string,
+    items: T[],
+    options: SearchOptions = {}
+): SearchResult<T>[] {
+    if (!query || query.trim() === '') {
+        return [];
+    }
+
+    if (!items || items.length === 0) {
+        return [];
+    }
+
+    const ctx = createContext(items, query, options);
+    const results: SearchResult<T>[] = [];
+
+    for (let i = 0; i < items.length; i++) {
+        const result = searchItem(items[i], i, ctx);
+        if (result) {
+            results.push(result);
+        }
+    }
+
+    if (ctx.options.sort) {
+        results.sort((a, b) => b.score - a.score);
+    }
+
+    if (ctx.options.limit && ctx.options.limit > 0) {
+        return results.slice(0, ctx.options.limit);
+    }
+
+    return results;
+}
+
+/**
+ * Create search context with normalized options
+ */
+function createContext<T>(
+    items: T[],
+    query: string,
+    options: SearchOptions
+): SearchContext<T> {
+    const whitespaceMode = options.whitespaceMode ?? 'split';
+    const queries = whitespaceMode === 'split' 
+        ? query.trim().split(/\s+/).filter(q => q.length > 0)
+        : [query];
+
+    return {
+        items,
+        query,
+        queries,
+        options: {
+            keys: options.keys ?? [],
+            allowTailSpillover: options.allowTailSpillover ?? true,
+            whitespaceMode,
+            threshold: options.threshold ?? 0,
+            sort: options.sort ?? true,
+            limit: options.limit,
+            caseSensitive: options.caseSensitive ?? false,
+        }
+    };
+}
+
+/**
+ * Search a single item
+ */
+function searchItem<T>(
+    item: T,
+    index: number,
+    ctx: SearchContext<T>
+): SearchResult<T> | null {
+    const fields = extractFields(item, ctx.options.keys);
+    if (fields.length === 0) {
+        return null;
+    }
+
+    const parts = fields.map(f => extractStrokes(f));
+    const allMatches: StrokeMatchMap[] = [];
+    let totalMatchCount = 0;
+
+    // Try to match each query token
+    for (const queryToken of ctx.queries) {
+        // Apply case sensitivity
+        const normalizedQuery = ctx.options.caseSensitive 
+            ? queryToken 
+            : queryToken.toLowerCase();
+        
+        const fuzzyQuery = buildFuzzyQuery(normalizedQuery);
+        if (!fuzzyQuery) {
+            continue;
+        }
+
+        // Set allowTailSpillover for the last character of last query
+        if (ctx.options.allowTailSpillover && fuzzyQuery.chars.length > 0) {
+            fuzzyQuery.chars[fuzzyQuery.chars.length - 1].allowTailSpillover = true;
+        }
+
+        let tokenMatch: StrokeMatchMap | null = null;
+
+        // For case-insensitive search, normalize fields as well
+        const searchParts = ctx.options.caseSensitive 
+            ? parts 
+            : fields.map(f => extractStrokes(f.toLowerCase()));
+
+        if (fuzzyQuery.isLiteral) {
+            tokenMatch = matchLiteral(fuzzyQuery, searchParts);
+        } else {
+            tokenMatch = matchFuzzyStrokes(fuzzyQuery, searchParts);
+        }
+
+        if (!tokenMatch) {
+            // If any token doesn't match, the whole search fails (AND logic)
+            return null;
+        }
+
+        allMatches.push(tokenMatch);
+        
+        // Count total matches for scoring
+        for (const partMatches of tokenMatch) {
+            if (partMatches) {
+                totalMatchCount += partMatches.length;
+            }
+        }
+    }
+
+    // Build match ranges using original parts (for correct positioning)
+    const ranges = buildMatchRanges(allMatches, parts);
+    
+    // Calculate score
+    const score = calculateScore(fields, ranges, totalMatchCount);
+    
+    if (score < ctx.options.threshold) {
+        return null;
+    }
+
+    return {
+        item,
+        score,
+        matches: ranges,
+        index
+    };
+}
+
+/**
+ * Extract searchable fields from an item
+ */
+function extractFields<T>(item: T, keys: (string | ((item: T) => string))[]): string[] {
+    // If no keys specified, treat item as string
+    if (keys.length === 0) {
+        return [String(item)];
+    }
+
+    const fields: string[] = [];
+    for (const key of keys) {
+        if (typeof key === 'function') {
+            const value = key(item);
+            if (value) {
+                fields.push(String(value));
+            }
+        } else if (typeof key === 'string') {
+            // Type-safe property access with proper checking
+            const value = (item as Record<string, unknown>)?.[key];
+            if (value !== undefined && value !== null) {
+                fields.push(String(value));
+            }
+        }
+    }
+
+    return fields;
+}
+
+/**
+ * Calculate match score
+ * Higher score = better match
+ */
+function calculateScore(
+    fields: string[],
+    ranges: Array<MatchRange[] | undefined>,
+    totalMatchCount: number
+): number {
+    if (totalMatchCount === 0) {
+        return 0;
+    }
+
+    let totalLength = 0;
+    let matchedLength = 0;
+    let firstMatchPosition = Infinity;
+    let consecutiveBonus = 0;
+
+    for (let i = 0; i < fields.length; i++) {
+        totalLength += fields[i].length;
+        const fieldRanges = ranges[i];
+        
+        if (fieldRanges && fieldRanges.length > 0) {
+            // Track first match position
+            firstMatchPosition = Math.min(firstMatchPosition, fieldRanges[0].start);
+            
+            // Sum up matched character lengths
+            for (const range of fieldRanges) {
+                const rangeLength = range.end - range.start;
+                matchedLength += rangeLength;
+                
+                // Bonus for consecutive matches
+                if (rangeLength > 1) {
+                    consecutiveBonus += (rangeLength - 1) * 0.1;
+                }
+            }
+        }
+    }
+
+    // Base score: coverage ratio
+    let score = matchedLength / Math.max(totalLength, 1);
+    
+    // Bonus for earlier matches
+    if (firstMatchPosition < Infinity) {
+        score += (1 - firstMatchPosition / totalLength) * 0.2;
+    }
+    
+    // Bonus for consecutive matches
+    score += consecutiveBonus;
+    
+    // Bonus for more matches relative to field count
+    score += (totalMatchCount / Math.max(fields.length, 1)) * 0.1;
+
+    return Math.min(score, 1);
+}
+
+/**
+ * Simple filter function - returns true if item matches query
+ * Useful for quick filtering without needing match details
+ * 
+ * @example
+ * ```ts
+ * const items = ['값어치', '가치', '갑작스런'];
+ * const filtered = items.filter(item => matches('값', item));
+ * ```
+ */
+export function matches<T = string>(
+    query: string,
+    item: T,
+    options: SearchOptions = {}
+): boolean {
+    return search(query, [item], options).length > 0;
+}
+
+/**
+ * Get match ranges for a single item without scoring
+ * Useful when you just need highlight information
+ * 
+ * @example
+ * ```ts
+ * const ranges = getMatchRanges('파열', '파일 열기');
+ * // Use ranges to highlight matched portions
+ * ```
+ */
+export function getMatchRanges<T = string>(
+    query: string,
+    item: T,
+    options: SearchOptions = {}
+): Array<MatchRange[] | undefined> | null {
+    const results = search(query, [item], options);
+    return results.length > 0 ? results[0].matches : null;
+}
diff --git a/test/search.test.ts b/test/search.test.ts
new file mode 100644
index 0000000..d22026f
--- /dev/null
+++ b/test/search.test.ts
@@ -0,0 +1,377 @@
+import { describe, it, expect } from "vitest";
+import { search, matches, getMatchRanges, type SearchOptions } from "../src/search";
+
+describe("search API", () => {
+    describe("basic string search", () => {
+        it("should find exact match", () => {
+            const items = ["값어치", "가치", "나다"];
+            const results = search("값", items);
+            
+            // "값" matches "값어치" (exact start match)
+            expect(results.length).toBeGreaterThanOrEqual(1);
+            expect(results.some(r => r.item === "값어치")).toBe(true);
+        });
+
+        it("should find fuzzy matches", () => {
+            const items = ["안녕하세요", "안녕", "하세요"];
+            const results = search("ㅇㅎㅇ", items);
+            
+            expect(results.length).toBe(1);
+            expect(results[0].item).toBe("안녕하세요");
+        });
+
+        it("should return empty array for no matches", () => {
+            const items = ["가나다", "라마바"];
+            const results = search("xyz", items);
+            
+            expect(results).toEqual([]);
+        });
+
+        it("should return empty array for empty query", () => {
+            const items = ["가", "나"];
+            const results = search("", items);
+            
+            expect(results).toEqual([]);
+        });
+
+        it("should return empty array for empty items", () => {
+            const results = search("가", []);
+            
+            expect(results).toEqual([]);
+        });
+
+        it("should handle whitespace-only query", () => {
+            const items = ["가", "나"];
+            const results = search("   ", items);
+            
+            expect(results).toEqual([]);
+        });
+    });
+
+    describe("object search with keys", () => {
+        it("should search object properties", () => {
+            const items = [
+                { name: "파일 열기", cmd: "open" },
+                { name: "파일 닫기", cmd: "close" },
+                { name: "새 파일", cmd: "new" }
+            ];
+            
+            const results = search("파열", items, { keys: ["name"] });
+            
+            expect(results.length).toBe(1);
+            expect(results[0].item.name).toBe("파일 열기");
+        });
+
+        it("should search multiple keys", () => {
+            const items = [
+                { name: "열기", cmd: "open" },
+                { name: "닫기", cmd: "close" }
+            ];
+            
+            const results = search("open", items, { keys: ["name", "cmd"] });
+            
+            expect(results.length).toBe(1);
+            expect(results[0].item.cmd).toBe("open");
+        });
+
+        it("should handle function keys", () => {
+            const items = [
+                { title: "항목1", tags: ["tag1", "tag2"] },
+                { title: "항목2", tags: ["tag3"] }
+            ];
+            
+            const results = search("tag1", items, {
+                keys: [
+                    "title",
+                    (item) => item.tags.join(" ")
+                ]
+            });
+            
+            expect(results.length).toBe(1);
+            expect(results[0].item.title).toBe("항목1");
+        });
+
+        it("should handle missing properties gracefully", () => {
+            const items = [
+                { name: "있음" },
+                { other: "다른거" }
+            ];
+            
+            const results = search("있", items, { keys: ["name"] });
+            
+            expect(results.length).toBe(1);
+            expect(results[0].item.name).toBe("있음");
+        });
+    });
+
+    describe("allowTailSpillover option", () => {
+        it("should allow tail spillover by default", () => {
+            const items = ["값어치"];
+            const results = search("값", items);
+            
+            expect(results.length).toBe(1);
+        });
+
+        it("should respect allowTailSpillover: false", () => {
+            const items = ["돋음"];
+            const results = search("도", items, { allowTailSpillover: false });
+            
+            // With allowTailSpillover: false, "도" should not match "돋음"
+            expect(results.length).toBe(0);
+        });
+
+        it("should allow partial match with spillover enabled", () => {
+            const items = ["값진"];
+            const results = search("값", items, { allowTailSpillover: true });
+            
+            expect(results.length).toBe(1);
+        });
+    });
+
+    describe("whitespaceMode option", () => {
+        it("should split query by default", () => {
+            const items = ["안녕하세요 여러분"];
+            const results = search("안녕 여러", items);
+            
+            expect(results.length).toBe(1);
+        });
+
+        it("should handle split mode with unordered tokens", () => {
+            const items = ["파일 열기 명령"];
+            const results = search("명령 파일", items, { whitespaceMode: 'split' });
+            
+            // Both tokens must match
+            expect(results.length).toBe(1);
+        });
+
+        it("should treat literal whitespace with literal mode", () => {
+            const items = ["파일 열기", "파일열기"];
+            const results = search("\"파일 열기\"", items, { whitespaceMode: 'literal' });
+            
+            expect(results.length).toBe(1);
+            expect(results[0].item).toBe("파일 열기");
+        });
+    });
+
+    describe("sort option", () => {
+        it("should sort by relevance by default", () => {
+            const items = ["가나다", "가", "가나"];
+            const results = search("가", items);
+            
+            // Shorter/better matches should score higher
+            expect(results[0].item).toBe("가");
+        });
+
+        it("should not sort when sort: false", () => {
+            const items = ["가나다", "가", "가나"];
+            const results = search("가", items, { sort: false });
+            
+            expect(results.length).toBe(3);
+            // Results should be in original order
+            expect(results.map(r => r.item)).toEqual(["가나다", "가", "가나"]);
+        });
+    });
+
+    describe("limit option", () => {
+        it("should return all results by default", () => {
+            const items = ["가", "가나", "가나다", "가나다라"];
+            const results = search("가", items);
+            
+            expect(results.length).toBe(4);
+        });
+
+        it("should limit results when specified", () => {
+            const items = ["가", "가나", "가나다", "가나다라"];
+            const results = search("가", items, { limit: 2 });
+            
+            expect(results.length).toBe(2);
+        });
+
+        it("should handle limit larger than results", () => {
+            const items = ["가", "가나"];
+            const results = search("가", items, { limit: 10 });
+            
+            expect(results.length).toBe(2);
+        });
+    });
+
+    describe("score calculation", () => {
+        it("should include score in results", () => {
+            const items = ["값어치"];
+            const results = search("값", items);
+            
+            expect(results[0].score).toBeGreaterThan(0);
+            expect(results[0].score).toBeLessThanOrEqual(1);
+        });
+
+        it("should score exact matches higher", () => {
+            const items = ["가", "가나다"];
+            const results = search("가", items);
+            
+            const exactMatch = results.find(r => r.item === "가");
+            const partialMatch = results.find(r => r.item === "가나다");
+            
+            expect(exactMatch!.score).toBeGreaterThan(partialMatch!.score);
+        });
+
+        it("should score earlier matches higher", () => {
+            const items = ["나가", "가나"];
+            const results = search("가", items);
+            
+            const firstMatch = results.find(r => r.item === "가나");
+            const secondMatch = results.find(r => r.item === "나가");
+            
+            expect(firstMatch!.score).toBeGreaterThan(secondMatch!.score);
+        });
+    });
+
+    describe("matches result structure", () => {
+        it("should include match ranges", () => {
+            const items = ["안녕하세요"];
+            const results = search("안녕", items);
+            
+            expect(results[0].matches).toBeDefined();
+            expect(Array.isArray(results[0].matches)).toBe(true);
+        });
+
+        it("should include original index", () => {
+            const items = ["가", "나", "다"];
+            const results = search("나", items);
+            
+            expect(results[0].index).toBe(1);
+        });
+    });
+
+    describe("literal query with quotes", () => {
+        it("should handle literal search", () => {
+            const items = ["값어치", "가치"];
+            const results = search("\"값\"", items);
+            
+            expect(results.length).toBe(1);
+            expect(results[0].item).toBe("값어치");
+        });
+
+        it("should not match fuzzy with literal query", () => {
+            const items = ["가나다"];
+            const results = search("\"ㄱㄴㄷ\"", items);
+            
+            // Literal ㄱㄴㄷ won't match 가나다
+            expect(results.length).toBe(0);
+        });
+    });
+
+    describe("complex scenarios", () => {
+        it("should handle mixed Korean and English", () => {
+            const items = [
+                { name: "파일 Open", cmd: "file.open" },
+                { name: "파일 Close", cmd: "file.close" }
+            ];
+            
+            const results = search("파 op", items, { keys: ["name"] });
+            
+            expect(results.length).toBe(1);
+            expect(results[0].item.name).toBe("파일 Open");
+        });
+
+        it("should handle emoji", () => {
+            const items = ["😀 웃음", "😢 슬픔"];
+            const results = search("웃", items);
+            
+            expect(results.length).toBe(1);
+            expect(results[0].item).toBe("😀 웃음");
+        });
+
+        it("should handle empty strings in array", () => {
+            const items = ["", "가", "나"];
+            const results = search("가", items);
+            
+            expect(results.length).toBe(1);
+            expect(results[0].item).toBe("가");
+        });
+    });
+});
+
+describe("matches helper", () => {
+    it("should return true for matching item", () => {
+        expect(matches("값", "값어치")).toBe(true);
+    });
+
+    it("should return false for non-matching item", () => {
+        expect(matches("xyz", "가나다")).toBe(false);
+    });
+
+    it("should work with objects", () => {
+        const item = { name: "파일 열기" };
+        expect(matches("파열", item, { keys: ["name"] })).toBe(true);
+    });
+
+    it("should return false for empty query", () => {
+        expect(matches("", "가나다")).toBe(false);
+    });
+});
+
+describe("getMatchRanges helper", () => {
+    it("should return match ranges for matching item", () => {
+        const ranges = getMatchRanges("안녕", "안녕하세요");
+        
+        expect(ranges).not.toBeNull();
+        expect(Array.isArray(ranges)).toBe(true);
+    });
+
+    it("should return null for non-matching item", () => {
+        const ranges = getMatchRanges("xyz", "가나다");
+        
+        expect(ranges).toBeNull();
+    });
+
+    it("should work with objects", () => {
+        const item = { name: "파일 열기" };
+        const ranges = getMatchRanges("파열", item, { keys: ["name"] });
+        
+        expect(ranges).not.toBeNull();
+    });
+
+    it("should return null for empty query", () => {
+        const ranges = getMatchRanges("", "가나다");
+        
+        expect(ranges).toBeNull();
+    });
+});
+
+describe("edge cases", () => {
+    it("should handle undefined/null items gracefully", () => {
+        // Note: The API converts all items to strings via String() constructor
+        // null becomes "null" and undefined becomes "undefined"
+        // This is intentional for maximum flexibility
+        const items = [null, undefined, "가나다"];
+        const results = search("가", items as any);
+        
+        // Should find "가나다" and convert null/undefined to strings
+        expect(results.length).toBeGreaterThan(0);
+    });
+
+    it("should handle numeric items", () => {
+        // Note: Numeric items are converted to strings for searching
+        // This allows the API to work with any primitive type
+        const items = [123, 456, 789];
+        const results = search("123", items as any);
+        
+        expect(results.length).toBe(1);
+        expect(results[0].item).toBe(123);
+    });
+
+    it("should handle very long strings", () => {
+        const longString = "가".repeat(1000);
+        const items = [longString];
+        const results = search("가", items);
+        
+        expect(results.length).toBe(1);
+    });
+
+    it("should handle special characters", () => {
+        const items = ["!@#$%", "가!@#"];
+        const results = search("!@", items);
+        
+        expect(results.length).toBeGreaterThanOrEqual(1);
+    });
+});