@simplysm/sd-claude 14.0.65 → 14.0.66

package/claude/references/sd-simplysm14/apis/core-browser/README.md

@@ -0,0 +1,112 @@
+# @simplysm/core-browser
+
+브라우저 전용 보강 — `Element`/`HTMLElement` 프로토타입 확장(import 사이드 이펙트) + DOM/파일/네트워크/IndexedDB 헬퍼.
+
+> 이 패키지를 import 만 해도 `Element`/`HTMLElement` 프로토타입이 확장된다. SSR 환경에서는 import 자체를 피한다.
+
+## 사용 트리거 인덱스
+
+- **DOM 탐색/가시성** (`Element` 확장: `findAll`/`findFirst`/`prependChild`/`getParents`/`isOffsetElement`/`isVisible`) — DOM 트리 탐색·삽입·가시성 판정 필요 시.
+- **포커스/탭 이동** (`Element` 확장: `findTabbableParent`/`findFirstTabbableChild`) — 키보드 포커스 흐름 제어 시.
+- **레이아웃/스크롤** (`HTMLElement` 확장: `repaint`/`getRelativeOffset`/`scrollIntoViewIfNeeded`) — 드롭다운/팝업 위치 계산, 고정 헤더 가림 스크롤 보정 시.
+- **클립보드/측정 헬퍼** (`copyElement`/`pasteToElement`/`getBounds`, `ElementBounds`) — copy/paste 이벤트 처리, 다수 요소 경계 일괄 측정 시.
+- **파일 다이얼로그/다운로드** (`openFileDialog`/`downloadBlob`) — 파일 선택 UI, Blob 다운로드 트리거 시.
+- **진행률 fetch** (`fetchUrlBytes`, `DownloadProgress`) — 큰 바이너리 다운로드 + 진행률 콜백 필요 시.
+- **IndexedDB 저장소** (`IndexedDbStore`, `StoreConfig`) — 브라우저 영속 키/값 저장소 (트랜잭션 보장).
+- **IndexedDB 가상 파일시스템** (`IndexedDbVirtualFs`, `VirtualFsEntry`) — `IndexedDbStore` 위에 경로(`/a/b/c`) 기반 파일/디렉토리 모델링.
+
+## DOM 탐색/가시성 — `Element` 확장
+
+```ts
+el.findAll<T extends Element = Element>(selector: string): T[]            // 빈 선택자 → []
+el.findFirst<T extends Element = Element>(selector: string): T | undefined // 빈 선택자 → undefined
+el.prependChild<T extends Element>(child: T): T                            // 첫 자식으로 삽입
+el.getParents(): Element[]                                                  // 가까운 순서
+el.isOffsetElement(): boolean                                               // position: relative/absolute/fixed/sticky
+el.isVisible(): boolean                                                     // clientRects 존재 + visibility != hidden + opacity != "0"
+```
+
+## 포커스/탭 이동 — `Element` 확장
+
+```ts
+el.findTabbableParent(): HTMLElement | undefined       // tabbable 라이브러리 사용
+el.findFirstTabbableChild(): HTMLElement | undefined   // TreeWalker로 첫 매치
+```
+
+## 레이아웃/스크롤 — `HTMLElement` 확장
+
+```ts
+el.repaint(): void                                              // offsetHeight 접근으로 강제 reflow
+el.getRelativeOffset(parent: HTMLElement | string): { top; left } // CSS top/left 즉시 사용 가능. transform/border/스크롤 보정. 못 찾으면 ArgumentError
+el.scrollIntoViewIfNeeded(target: { top; left }, offset?): void // 상단/좌측 가림만 보정. 하단/우측은 브라우저 기본
+```
+
+`getRelativeOffset` 은 드롭다운/팝업의 absolute 위치 지정 표준 경로. `parent` 는 가장 가까운 offset parent 또는 selector.
+
+## 클립보드/측정 헬퍼
+
+```ts
+function copyElement(event: ClipboardEvent): void       // 대상 내 첫 input/textarea.value → clipboard
+function pasteToElement(event: ClipboardEvent): void    // clipboard → 첫 input/textarea.value 교체 + input 이벤트 dispatch
+function getBounds(els: Element[], timeout = 5000): Promise<ElementBounds[]> // IntersectionObserver 기반. 입력 순서 유지. timeout 초과 시 TimeoutError
+
+interface ElementBounds { target: Element; top: number; left: number; width: number; height: number; }
+```
+
+`copyElement`/`pasteToElement` 는 `<element @copy=... @paste=...>` 이벤트 핸들러로 직결. 커서/선택 영역은 무시하고 전체 값 교체.
+
+## 파일 다이얼로그/다운로드
+
+```ts
+function openFileDialog(options?: { accept?: string; multiple?: boolean }): Promise<File[] | undefined>
+//   취소 시 undefined, 빈 선택 시 undefined.
+function downloadBlob(blob: Blob, fileName: string): void
+//   파일명: sanitize-filename + 대괄호 제거. 빈 결과는 "download". ObjectURL 1초 후 해제.
+```
+
+## 진행률 fetch
+
+```ts
+interface DownloadProgress { receivedLength: number; contentLength: number; }
+function fetchUrlBytes(url: string, options?: { onProgress?: (p: DownloadProgress) => void }): Promise<Uint8Array>
+```
+
+`Content-Length` 가 있으면 사전 할당(메모리 효율) + 초과/부족 검출, 없으면 청크 수집 후 `bytes.concat`. HTTP 오류·본문 없음·길이 불일치는 모두 throw.
+
+## IndexedDB 저장소 — `IndexedDbStore`
+
+```ts
+interface StoreConfig { name: string; keyPath: string; }
+
+class IndexedDbStore {
+  constructor(dbName: string, dbVersion: number, storeConfigs: StoreConfig[]);
+  open(): Promise<IDBDatabase>;                                            // versionchange/close 시 자동 무효화
+  withStore<R>(name, mode: IDBTransactionMode, fn: (s: IDBObjectStore) => Promise<R>): Promise<R>; // fn throw 시 tx.abort
+  get<T>(name, key: IDBValidKey): Promise<T | undefined>;
+  put(name, value): Promise<void>;
+  delete(name, key: IDBValidKey): Promise<void>;
+  getAll<T>(name): Promise<T[]>;
+  close(): void;
+}
+```
+
+`open()` 은 중복 호출 안전(병행 호출 단일화). `withStore` 의 `fn` 내부 에러는 트랜잭션 abort 후 원본 에러로 reject.
+
+## IndexedDB 가상 파일시스템 — `IndexedDbVirtualFs`
+
+`IndexedDbStore` 위에 경로 키(`/a/b/c`) 기반 파일/디렉토리 모델. 데이터는 base64 문자열로 저장.
+
+```ts
+interface VirtualFsEntry { kind: "file" | "dir"; dataBase64?: string; }
+
+class IndexedDbVirtualFs {
+  constructor(db: IndexedDbStore, storeName: string, keyField: string);
+  getEntry(fullKey: string): Promise<VirtualFsEntry | undefined>;
+  putEntry(fullKey: string, kind: "file" | "dir", dataBase64?: string): Promise<void>;
+  deleteByPrefix(keyPrefix: string): Promise<boolean>;                  // 자기 자신 + "/" 하위 재귀 삭제
+  listChildren(prefix: string): Promise<{ name: string; isDirectory: boolean }[]>; // 직속 자식만, 중간 경로도 dir 로 노출
+  ensureDir(fullKeyBuilder: (path: string) => string, dirPath: string): Promise<void>; // 중간 디렉토리 모두 생성
+}
+```
+
+`fullKey`/`keyField`/`fullKeyBuilder` 분리로 멀티 테넌트(예: 사용자별 prefix) 키 스킴을 호출 측에서 결정.

package/claude/references/sd-simplysm14/apis/core-common/README.md

@@ -0,0 +1,53 @@
+# @simplysm/core-common
+
+공통 유틸리티(타입·에러·큐·이벤트·변환·확장 메서드·환경변수). simplysm 모든 패키지의 공용 기반.
+
+## 사용 트리거 인덱스
+
+- **에러 클래스** — throw 시 트리 메시지/원인 체인 필요할 때. `SdError`, `ArgumentError`, `NotImplementedError`, `TimeoutError`.
+- **날짜/시간/UUID/캐시 타입** — `DateTime`, `DateOnly`, `Time`, `Uuid`, `LazyGcMap` 사용 시. (자세히: [types.md](./types.md))
+- **큐·이벤트 features** — 디바운스·직렬 큐, 타입 안전 EventEmitter. (자세히: [features.md](./features.md))
+- **유틸리티 네임스페이스** — `obj`, `str`, `num`, `bytes`, `path`, `json`, `xml`, `wait`, `transfer`, `err`, `dt`, `primitive`. (자세히: [utils.md](./utils.md))
+- **Array/Set/Map 전역 확장 메서드** — `.single()`, `.toMap()`, `.toTree()`, `.distinct()`, `Set.adds()`, `Map.getOrCreate()` 등. (자세히: [extensions.md](./extensions.md))
+- **환경변수** — `env(key)`, `env(key, value)`, `parseBoolEnv(v)`. `process.env` 우선, fallback `import.meta.env`.
+- **템플릿 문자열 태그** — IDE 하이라이팅 + indent trim. `js`, `ts`, `html`, `tsql`, `mysql`, `pgsql`. 동작은 모두 동일(문자열 결합 + 들여쓰기 정규화).
+- **ZIP 처리** — `ZipArchive(data?)`: `get/exists/write/extractAll/compress/close`. 사용 후 반드시 `await archive.close()`.
+- **공통 타입** — `Bytes` (= `Uint8Array`), `PrimitiveTypeMap/Str/Type` (string/number/boolean/DateTime/DateOnly/Time/Uuid/Bytes), `DeepPartial<T>`, `Type<T>` (생성자 타입).
+
+## 에러 클래스
+
+```typescript
+new SdError(cause: Error, ...messages: string[])
+new SdError(...messages: string[])
+// 메시지는 역순 결합: "상위 => 하위 => 원인". cause stack을 현재 stack에 append.
+
+new ArgumentError(argObj)
+new ArgumentError(message, argObj)
+// 인자 객체를 YAML 형식으로 메시지에 포함.
+
+new NotImplementedError(message?)   // "미구현: <message>"
+new TimeoutError(count?, message?)  // "대기 시간 초과(N회 시도): <message>". wait.until 에서 자동 throw.
+```
+
+모두 `SdError` 상속. `name` 자동 설정.
+
+## 환경변수
+
+```typescript
+env("PORT")             // string | undefined (process.env → import.meta.env)
+env("PORT", "3000")     // void (process.env 에 기록, process 없으면 무시)
+parseBoolEnv(v)         // "true"|"1"|"yes"|"on" → true (대소문자 무시)
+```
+
+## 템플릿 문자열 태그
+
+```typescript
+import { js, ts, html, tsql, mysql, pgsql } from "@simplysm/core-common";
+
+const code = ts`
+  interface User { name: string; }
+`;
+// → "interface User { name: string; }" (앞뒤 빈 줄·공통 들여쓰기 제거)
+```
+
+모두 동일 함수, IDE 하이라이팅 차별화 목적.

package/claude/references/sd-simplysm14/apis/core-common/extensions.md

@@ -0,0 +1,123 @@
+# @simplysm/core-common — extensions
+
+`index.ts` 가 import 되면 자동으로 `Array.prototype`, `Set.prototype`, `Map.prototype` 에 메서드를 정의 (`enumerable: false`).
+
+## Array (Readonly — 새 배열/값 반환)
+
+### 조회
+
+```typescript
+arr.single(pred?)              // 0 or 1개. 2개 이상이면 ArgumentError. 없으면 undefined.
+arr.first(pred?)               // pred 면 find, 없으면 [0]
+arr.last(pred?)                // pred 면 역방향 find, 없으면 [length-1]
+arr.filterExists()             // null/undefined 제거 → NonNullable<T>[]
+arr.ofType("string"|"number"|"boolean"|"DateTime"|"DateOnly"|"Time"|"Uuid"|"Bytes")
+arr.ofType(SomeClass)          // instanceof 또는 constructor 일치
+```
+
+### 비동기
+
+```typescript
+await arr.filterAsync(asyncPred)        // 순차
+await arr.mapAsync(asyncSelector)       // 순차
+await arr.mapManyAsync(asyncSelector)   // 순차 + 평탄화
+await arr.parallelAsync(fn)             // Promise.all (하나 reject 시 전체 reject)
+```
+
+### 매핑·평탄화
+
+```typescript
+arr.mapMany()                  // 중첩 배열 1단계 flatten + filterExists
+arr.mapMany(selector)          // 매핑 후 flatten
+```
+
+### 변환
+
+```typescript
+arr.groupBy(keyFn)                              // [{ key, values }, ...] (객체 key 시 O(n²), 원시 key 는 O(n))
+arr.groupBy(keyFn, valueFn)
+arr.toMap(keyFn) / toMap(keyFn, valFn)          // 중복 key 시 ArgumentError
+await arr.toMapAsync(...)
+arr.toArrayMap(keyFn[, valFn])                  // Map<K, V[]>  (원시 key 권장 — O(n))
+arr.toSetMap(keyFn[, valFn])                    // Map<K, Set<V>>
+arr.toMapValues(keyFn, (items) => aggregated)
+arr.toObject(strKeyFn[, valFn])                 // 중복 key 시 ArgumentError
+arr.toTree("id", "parentId")                    // 평면 → 트리 ({...item, children: []}), O(n).
+                                                //   parentKey 가 null/undefined 면 루트.
+```
+
+### 중복·정렬
+
+```typescript
+arr.distinct()                                  // 깊은 equal 비교 (객체 array 는 O(n²))
+arr.distinct(true)                              // matchAddress: 참조 비교 (Set 기반, O(n))
+arr.distinct({ matchAddress?, keyFn? })         // keyFn 권장 — O(n)
+arr.orderBy(selector?)                          // 오름차순. string/number/DateTime/DateOnly/Time/undefined 지원
+arr.orderByDesc(selector?)
+arr.shuffle()                                   // Fisher-Yates
+```
+
+### 비교·병합
+
+```typescript
+arr.diffs(target)                               // INSERT/DELETE/UPDATE 결과
+arr.diffs(target, { keys: ["id"], excludes? })  // key 기반 매칭 (Map 인덱싱 O(n+m))
+arr.diffs(target, { excludes: [...] })
+   // 결과 타입:
+   //   { source: undefined, target: T }  // INSERT
+   //   { source: T, target: undefined }  // DELETE
+   //   { source: T, target: T }          // UPDATE
+
+arr.oneWayDiffs(orgItems | Map, keyPropOrFn, {
+  includeSame?, excludes?, includes?,
+})
+   // 결과: { type: "create"|"update"|"same", item, orgItem }
+
+arr.merge(target[, { keys?, excludes? }])       // diffs 후 source 기반에 target 병합·신규 push
+```
+
+### 집계
+
+```typescript
+arr.sum(selector?)             // 숫자 아니면 ArgumentError. 빈 배열 → 0.
+arr.min(selector?) / max(selector?)   // string|number. 빈 배열 → undefined
+```
+
+### TreeArray 타입
+
+```typescript
+type TreeArray<T> = T & { children: TreeArray<T>[] };
+```
+
+## Array (Mutable — 원본 변경, `@mutates`)
+
+```typescript
+arr.distinctThis(options?)             // 원본에서 중복 제거 (역순 splice, O(n))
+arr.orderByThis(selector?) / orderByDescThis(selector?)
+arr.insert(index, ...items)
+arr.remove(itemOrSelector)             // 일치 항목 모두 제거. 역순 순회.
+arr.toggle(item)                       // 있으면 remove, 없으면 push
+arr.clear()
+```
+
+모두 `this` 반환 (체이닝 가능, `clear/distinctThis/orderBy*This` 는 변경된 자기 자신).
+
+## Set
+
+```typescript
+set.adds(...values)                            // 다중 add, this 반환
+set.toggle(value)                              // 자동 토글
+set.toggle(value, "add" | "del")               // 강제 추가/제거
+```
+
+## Map
+
+```typescript
+map.getOrCreate(key, defaultValue)             // 없으면 set 후 반환
+map.getOrCreate(key, () => expensiveCompute()) // 팩토리 (값이 함수이면 항상 호출됨 — 함수 값을 저장하려면 `() => fn` 으로 한 번 더 감쌀 것)
+map.update(key, (v|undefined) => newV)         // 없는 key 도 호출됨 (카운터·배열 push 패턴)
+```
+
+## ComparableType
+
+`orderBy*` 의 selector 반환 타입: `string | number | boolean | DateTime | DateOnly | Time | undefined`.

package/claude/references/sd-simplysm14/apis/core-common/features.md

@@ -0,0 +1,46 @@
+# @simplysm/core-common — features
+
+비동기 큐와 타입 안전 이벤트 이미터.
+
+## EventEmitter\<TEvents\>
+
+브라우저·Node 공용 (내부 `EventTarget`). 타입 안전.
+
+```typescript
+interface MyEvents { data: string; error: Error; done: void; }
+class MyEmitter extends EventEmitter<MyEvents> {}
+
+const e = new MyEmitter();
+e.on("data", (d) => ...);       // d: string
+e.emit("data", "hello");
+e.emit("done");                 // void 이벤트는 인자 없이
+e.off("data", handler);
+e.listenerCount("data");        // 등록된 수
+e.dispose();                    // 모든 리스너 제거
+```
+
+같은 이벤트에 같은 리스너 중복 등록은 무시.
+
+## DebounceQueue extends EventEmitter\<{ error: SdError }\>
+
+연속 호출 중 마지막 작업만 실행.
+
+```typescript
+const q = new DebounceQueue(300);   // 300ms 지연 (생략 시 다음 이벤트 루프)
+q.run(fn);                          // 이전 대기 함수 교체
+q.on("error", (e) => ...);          // 작업 throw 시. 리스너 없으면 logger.error
+q.dispose();                        // 타이머·대기 함수 정리
+```
+
+실행 도중 들어온 새 요청은 지연 없이 실행 완료 직후 즉시 처리 (놓침 방지).
+
+## SerialQueue extends EventEmitter\<{ error: SdError }\>
+
+순차 실행, 작업 사이 간격 옵션.
+
+```typescript
+const q = new SerialQueue(0);       // gap ms (기본 0)
+q.run(asyncFn);                     // 큐에 추가, 자동 실행
+q.on("error", ...);                 // 에러는 다음 작업에 영향 X (계속 실행)
+q.dispose();                        // 대기 큐 비움 (현재 작업은 완료됨)
+```

package/claude/references/sd-simplysm14/apis/core-common/types.md

@@ -0,0 +1,114 @@
+# @simplysm/core-common — types
+
+날짜·시간·UUID·만료 캐시 타입.
+
+## DateTime (불변)
+
+밀리초 정밀도, 로컬 타임존. 모든 변환/산술 메서드는 새 인스턴스 반환.
+
+```typescript
+new DateTime()                                    // 현재
+new DateTime(year, month, day, h?, m?, s?, ms?)   // month 는 1-12
+new DateTime(tick)                                // ms epoch
+new DateTime(date)                                // Date 복사
+DateTime.parse(str)                               // "yyyy-MM-dd HH:mm:ss" / "yyyyMMddHHmmss" /
+                                                  //   "yyyy-MM-dd AM|PM HH:mm:ss" / "오전|오후" / ISO 8601
+                                                  //   실패 시 ArgumentError
+```
+
+Getters: `year/month/day/hour/minute/second/millisecond/tick/dayOfWeek/timezoneOffsetMinutes/isValid` (month 는 1-12, dayOfWeek 는 0-6 일~토).
+
+변환: `setYear/setMonth/setDay/setHour/setMinute/setSecond/setMillisecond` — 새 인스턴스. `setMonth` 는 대상 월 일수 초과 시 마지막 일로 클램프. `setDay` 는 JS Date 동작에 따라 월 경계 자동 조정.
+
+산술: `addYears/addMonths/addDays/addHours/addMinutes/addSeconds/addMilliseconds`.
+
+포맷: `toFormatString(formatStr)` ([date-format 토큰](#date-format-토큰)). `toString()` = `"yyyy-MM-ddTHH:mm:ss.fffzzz"`.
+
+## DateOnly (불변)
+
+날짜만(yyyy-MM-dd), 로컬 타임존.
+
+```typescript
+new DateOnly()                       // 오늘
+new DateOnly(year, month, day)
+new DateOnly(tick) / new DateOnly(date)
+DateOnly.parse(str)                  // "yyyy-MM-dd" / "yyyyMMdd" (타임존 무관) /
+                                     //   ISO 8601 (UTC → 로컬 변환). 실패 시 ArgumentError
+```
+
+Getters: `year/month/day/tick/dayOfWeek/isValid`.
+변환·산술: `setYear/setMonth/setDay`, `addYears/addMonths/addDays`.
+포맷: `toFormatString`, `toString()` = `"yyyy-MM-dd"`.
+
+주차 API (ISO 8601 기본: 월요일 시작, 첫 주 최소 4일):
+
+```typescript
+d.getWeekSeqOfYear(weekStartDay=1, minDaysInFirstWeek=4)  // { year, weekSeq }
+d.getWeekSeqOfMonth(...)                                  // { year, monthSeq, weekSeq }
+d.getWeekSeqStartDate(...)                                // DateOnly
+d.getBaseYearMonthSeqForWeekSeq(...)                      // { year, monthSeq }
+DateOnly.getDateByYearWeekSeq({ year, month?, weekSeq }, ...) // 해당 주 시작일
+```
+
+## Time (불변)
+
+시간만(HH:mm:ss.fff). 24h 순환 — 음수/24h+ 자동 정규화.
+
+```typescript
+new Time()                              // 현재 시각의 시간 부분
+new Time(hour, minute, second?, ms?)
+new Time(tick) / new Time(date)
+Time.parse(str)                         // "HH:mm:ss[.fff]" / "AM|PM HH:mm:ss[.fff]" / ISO 8601 시간 부분
+```
+
+Getters/Setters/Add 메서드는 DateTime 시간부와 유사. `addHours/Minutes/Seconds/Milliseconds` 는 24h 순환.
+
+## Uuid
+
+UUID v4, `crypto.getRandomValues` 기반.
+
+```typescript
+Uuid.generate()                  // 새 v4
+new Uuid("xxxxxxxx-...")         // 형식 검증, 실패 시 ArgumentError
+Uuid.fromBytes(bytes16)          // 16바이트 → Uuid (길이 ≠ 16 시 ArgumentError)
+u.toString()                     // "xxxxxxxx-xxxx-..."
+u.toBytes()                      // 16바이트 Uint8Array
+```
+
+## LazyGcMap
+
+LRU 자동 만료 Map. **사용 후 반드시 `dispose()` 호출** — 안 하면 GC 타이머가 살아 메모리 누수.
+
+```typescript
+const m = new LazyGcMap<K, V>({
+  expireTime: 60_000,           // 마지막 접근 이후 ms
+  gcInterval?: 6_000,           // 기본: expireTime/10, 최소 1000ms
+  onExpire?: (k, v) => ... ,    // 비동기 가능, 에러는 로그
+});
+
+m.size; m.has(k); m.get(k); m.set(k, v); m.delete(k); m.clear(); m.dispose();
+m.getOrCreate(k, factory);                 // dispose 후 호출 시 throw
+m.keys() / m.values() / m.entries();       // Iterator
+```
+
+`get`/`getOrCreate` 만 접근시간 갱신(LRU). `has` 는 갱신 X. GC 실행 중 같은 key 재등록 시 새 항목 보존.
+
+## date-format 토큰
+
+`DateTime/DateOnly/Time#toFormatString(formatStr)` 에서 사용. C# 호환.
+
+| 토큰 | 의미 | 예 |
+|------|------|----|
+| `yyyy`/`yy` | 연도 4/2자리 | 2024 / 24 |
+| `MM`/`M` | 월 패딩/미패딩 | 01 / 1 |
+| `ddd` | 한글 요일 | 일~토 |
+| `dd`/`d` | 일 패딩/미패딩 | 01 / 1 |
+| `tt` | AM/PM | AM |
+| `hh`/`h` | 12시간 패딩/미패딩 | 01 / 1 |
+| `HH`/`H` | 24시간 패딩/미패딩 | 14 / 14 |
+| `mm`/`m` | 분 | 30 / 30 |
+| `ss`/`s` | 초 | 45 / 45 |
+| `fff`/`ff`/`f` | 밀리초 3/2/1자리 | 123 / 12 / 1 |
+| `zzz`/`zz`/`z` | 타임존 ±HH:mm / ±HH / ±H | +09:00 |
+
+긴 토큰이 먼저 매칭 → 부분 매칭 방지.

package/claude/references/sd-simplysm14/apis/core-common/utils.md

@@ -0,0 +1,158 @@
+# @simplysm/core-common — utils
+
+네임스페이스 import: `import { obj, str, num, bytes, path, json, xml, wait, transfer, err, dt, primitive } from "@simplysm/core-common";`
+
+## obj — 객체 조작
+
+### 복사·비교·병합
+
+```typescript
+obj.clone(src)                                        // 깊은 복사. 순환 참조·DateTime/DateOnly/Time/Uuid/
+                                                      //   Uint8Array/Date/RegExp/Error(cause)/Map/Set 지원.
+                                                      //   함수/Symbol 은 참조 유지, WeakMap/WeakSet 미지원.
+obj.equal(a, b, opt?)                                 // 깊은 동등. opt: { topLevelIncludes?, topLevelExcludes?,
+                                                      //   ignoreArrayIndex?, shallow? }
+                                                      //   include/exclude 는 최상위 객체 키에만 적용. shallow=true 면 1단계 참조 비교.
+obj.merge(source, target, opt?)                       // 깊은 병합 (불변, 새 객체). opt:
+                                                      //   { arrayProcess?: "replace"|"concat", useDelTargetNull? }
+obj.merge3(source, origin, target, optionsObj?)       // 3-way merge. { conflict, result }
+                                                      //   optionsObj 는 key별 { keys?, excludes?, ignoreArrayIndex? }
+```
+
+### 키 조작
+
+```typescript
+obj.omit(o, ["k1","k2"])
+obj.omitByFilter(o, (k) => k.startsWith("_"))
+obj.pick(o, ["k1","k2"])
+obj.keys(o) / obj.entries(o) / obj.fromEntries(pairs)  // 타입 안전 Object.* 래퍼
+obj.map(o, (k, v) => [newK | null, newV])              // entry 변환 (newK=null 이면 원래 키 유지)
+```
+
+### 체인 경로 (`"a.b[0].c"` 형식)
+
+```typescript
+obj.getChainValue(o, "a.b[0].c")
+obj.getChainValue(o, "a.b[0].c", true)   // optional: 중간 null 만나면 undefined
+obj.setChainValue(o, "a.b.c", v)         // 중간 객체 자동 생성
+obj.deleteChainValue(o, "a.b.c")
+obj.getChainValueByDepth(o, key, depth, optional?)  // 같은 key 로 N단계 하강
+```
+
+### 변환 (원본 변형 — `@mutates`)
+
+```typescript
+obj.clearUndefined(o)     // null/undefined 값 키 제거
+obj.clear(o)              // 모든 키 제거
+obj.nullToUndefined(o)    // 재귀, null → undefined
+obj.unflatten({ "a.b.c": 1 })  // → { a: { b: { c: 1 } } }
+```
+
+### 타입 유틸
+
+```typescript
+obj.UndefToOptional<T>    // { a: string|undefined } → { a?: string|undefined }
+obj.OptionalToUndef<T>    // { a?: string } → { a: string|undefined }
+```
+
+## str — 문자열
+
+```typescript
+str.getKoreanSuffix(text, "을"|"은"|"이"|"와"|"랑"|"로"|"라")
+                                  // 받침 유무로 조사 결정. "로" 는 ㄹ 받침이면 "로".
+str.replaceFullWidth(s)           // 전각 영숫자/공백/괄호 → 반각
+str.toPascalCase(s) / toCamelCase(s) / toKebabCase(s) / toSnakeCase(s)
+                                  // case 함수는 기존 -/_ 구분자 보존, 연속 대문자 개별 분리 ("XMLParser" → "x-m-l-parser")
+str.isNullOrEmpty(s)              // null|undefined|"" 타입 가드
+str.insert(s, idx, insertStr)
+```
+
+## num — 숫자
+
+```typescript
+num.parseInt(text)        // 비숫자 제거 후 정수 파싱. 선행 - 만 음수 부호, 중간 - 제거. 소수점은 trunc.
+num.parseFloat(text)
+num.parseRoundedInt(text) // float 후 반올림
+num.isNullOrEmpty(v)      // null|undefined|0 타입 가드
+num.format(v, { max?, min? })  // 천 단위 + 소수점 자릿수. toLocaleString 기반
+```
+
+## bytes — Uint8Array
+
+```typescript
+bytes.concat([a, b, ...])
+bytes.toHex(u8) / bytes.fromHex(hex)            // 소문자 hex. 홀수 길이/잘못된 문자 시 ArgumentError
+bytes.toBase64(u8) / bytes.fromBase64(b64)      // 표준 base64 (+/, = 패딩). 공백 자동 제거
+```
+
+## path — POSIX 경로 (브라우저용)
+
+```typescript
+path.join(...segs)            // 슬래시만 지원, 백슬래시 X
+path.basename(p, ext?)
+path.extname(p)               // 숨김 파일(".gitignore")은 빈 문자열
+```
+
+## json — 커스텀 타입 지원 JSON
+
+```typescript
+json.stringify(obj, { space?, replacer?, redactBytes? })
+                              // Date/DateTime/DateOnly/Time/Uuid/Set/Map/Error/Uint8Array 를 { __type__, data } 로.
+                              //   redactBytes=true 면 Uint8Array 내용을 "__hidden__"로 (parse 복원 불가).
+                              //   순환 참조 시 TypeError. 전역 prototype 미수정 (Worker 안전).
+json.parse<T>(str)            // __type__ 마커 복원. 모든 null → undefined (simplysm null-free 규칙).
+                              //   에러 시 SdError. DEV 환경에서만 메시지에 전체 JSON 포함.
+```
+
+## xml — fast-xml-parser 래퍼
+
+```typescript
+xml.parse(str, { stripTagPrefix? })
+   // 결과: 속성은 `$` 객체, 텍스트는 `_` 키, 자식 요소는 배열 (루트 제외).
+   //   stripTagPrefix=true 면 "ns:tag" → "tag" (속성은 유지).
+xml.stringify(obj, options?)  // fast-xml-parser XmlBuilderOptions
+```
+
+## wait — 대기
+
+```typescript
+await wait.time(ms)
+await wait.until(() => cond, intervalMs=100, maxCount?)   // maxCount 초과 시 TimeoutError
+```
+
+## transfer — Worker 전송
+
+`structuredClone` 미지원 타입 처리. Date/DateTime/DateOnly/Time/Uuid/RegExp/Error(cause/code/detail)/Uint8Array/Map/Set/Array/Object.
+
+```typescript
+const { result, transferList } = transfer.encode(data);
+worker.postMessage(result, transferList);          // Uint8Array.buffer 가 transferList 에 zero-copy
+const decoded = transfer.decode(event.data);
+```
+
+순환 참조 시 `TypeError("순환 참조 감지됨: <path>")`. 같은 객체 다중 참조는 인코딩 결과 캐싱.
+
+## err — 에러 메시지
+
+```typescript
+err.message(unknownErr)   // Error 면 .message, 아니면 String(err)
+```
+
+## dt — date-format 저수준
+
+`DateTime/DateOnly/Time#toFormatString` 내부에서 사용. 직접 사용 드묾.
+
+```typescript
+dt.format(formatStr, { year?, month?, day?, hour?, minute?, second?, millisecond?, timezoneOffsetMinutes? })
+   // 토큰은 types.md 의 "date-format 토큰" 참조
+dt.normalizeMonth(year, month, day)    // 월 1-12 정규화 + 일 클램프
+dt.convert12To24(rawHour, isPM)        // 12시간 → 24시간
+```
+
+## primitive — 런타임 타입 추론
+
+```typescript
+primitive.typeStr(value)
+// string/number/boolean/DateTime/DateOnly/Time/Uuid/Bytes 중 하나 반환.
+// 미지원 타입은 ArgumentError.
+```

package/claude/references/sd-simplysm14/apis/core-node/README.md

@@ -0,0 +1,12 @@
+## @simplysm/core-node
+
+Node.js 전용 유틸·기능 묶음. 파일 IO/glob, 경로 변환, 자식 프로세스 spawn, 파일 시스템 감시, consola 리포터 셋업, worker_threads 타입 안전 래퍼.
+
+## 사용 트리거 인덱스
+
+- **`fsx` 네임스페이스** — 파일/디렉토리 존재 확인·생성·복사·삭제·읽기·쓰기·JSON·glob·재귀 유틸. 자세히: [fsx.md](./fsx.md)
+- **`pathx` 네임스페이스** — POSIX 경로 변환, 하위 경로 판정, 디렉토리 치환, target 필터링. 자세히: [pathx.md](./pathx.md)
+- **`cpx` 네임스페이스** — 시스템 인코딩 감지 + 자식 프로세스 spawn/spawnSync (인코딩 자동 디코딩, exitCode 기반 reject). 자세히: [cpx.md](./cpx.md)
+- **`FsWatcher`** — chokidar 기반 디바운스/이벤트 병합 + Windows EPERM 자동 복구 파일 감시. 자세히: [fs-watcher.md](./fs-watcher.md)
+- **`setupConsola` / `PrettyReporter` / `createFileReporter` / `withMaxLevel`** — Node 앱 consola 셋업, 컬러 콘솔/JSON 파일 회전 리포터. 자세히: [consola.md](./consola.md)
+- **`Worker` / `createWorker` / `WorkerProxy` / `WorkerModule` / `PromisifyMethods`** — worker_threads 위 타입 안전 RPC 래퍼 (메서드 호출 + 이벤트 send/on). 자세히: [worker.md](./worker.md)