@simplysm/sd-claude 14.0.97 → 14.0.99

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

@@ -1,19 +1,19 @@
 # @simplysm/core-browser — DOM 요소 확장
 
-DOM 요소를 다룰 때 함께 읽히는 묶음. `Element.prototype`/`HTMLElement.prototype` 에 등록되는 확장 메서드와, 이벤트 핸들러·다중 요소용 정적 함수(`copyElement`/`pasteToElement`/`getBounds`)로 구성. 패키지를 import 하면 프로토타입 메서드가 자동 등록되므로 별도 초기화는 필요 없다.
+DOM 요소를 다룰 때 함께 읽히는 묶음. `Element.prototype`/`HTMLElement.prototype` 에 등록되는 확장 메서드와, 이벤트 핸들러·다중 요소용 정적 함수(`copyElement`/`pasteToElement`/`getBounds`)로 구성. 패키지를 import 하면 브라우저 환경에서 프로토타입 메서드가 자동 등록되므로 별도 초기화는 필요 없다(node/SSR 에선 `typeof Element` 가드로 등록을 건너뜀).
 
 ## Element 확장 메서드
 
 `Element.prototype` 에 등록. import 만으로 활성화.
 
-- `findAll<TEl>(selector: string): TEl[]` — 선택자 일치 하위 요소를 배열로 반환. 선택자를 trim 한 결과가 빈 문자열이면 `[]`. `querySelectorAll` 결과를 NodeList 대신 배열로 받고 빈 선택자 예외를 회피할 때.
-- `findFirst<TEl>(selector: string): TEl | undefined` — 첫 일치 하위 요소 또는 `undefined`. 빈 선택자도 `undefined`, 미일치도 `undefined`. `querySelector` 의 `null` 을 `undefined` 로 정규화한 형태.
-- `prependChild<TEl>(child: TEl): TEl` — 자식을 첫 번째 위치(`insertBefore(child, firstElementChild)`)에 삽입하고 그 요소 반환. 맨 앞에 끼워 넣을 때.
-- `getParents(): Element[]` — 모든 조상 요소를 가까운 것부터 먼 순서로 배열 반환. 조상 체인 순회·특정 조상 포함 판정에.
-- `findTabbableParent(): HTMLElement | undefined` — `tabbable` 라이브러리 기준 첫 탭 이동 가능 조상. 없으면 `undefined`. 포커스 위임 대상을 위로 탐색할 때.
-- `findFirstTabbableChild(): HTMLElement | undefined` — TreeWalker 로 순회한 첫 탭 이동 가능 하위 요소. 없으면 `undefined`. 컨테이너 진입 시 자동 포커스 대상을 찾을 때.
-- `isOffsetElement(): boolean` — `getComputedStyle().position` 이 relative/absolute/fixed/sticky 중 하나면 true, 아니면 false. 절대배치 기준(offset parent) 역할 여부 판정에.
-- `isVisible(): boolean` — `getClientRects().length > 0` 이고 `visibility !== "hidden"` 이고 `opacity !== "0"` 를 모두 만족하면 true. 화면 표시 여부 판정에(display:none 은 clientRects 가 비어 false).
+- `findAll<TEl extends Element = Element>(selector: string): TEl[]` — 선택자 일치 하위 요소를 `querySelectorAll` 결과의 배열로 반환. 선택자를 `trim` 한 결과가 빈 문자열이면 `[]`. NodeList 대신 배열로 받고 빈/공백 선택자 예외를 회피할 때.
+- `findFirst<TEl extends Element = Element>(selector: string): TEl | undefined` — 첫 일치 하위 요소 또는 `undefined`. 빈/공백 선택자도 `undefined`, 미일치도 `undefined`. `querySelector` 의 `null` 을 `undefined` 로 정규화한 형태.
+- `prependChild<TEl extends Element>(child: TEl): TEl` — 자식을 첫 번째 위치(`insertBefore(child, firstElementChild)`)에 삽입하고 그 요소를 반환. 맨 앞에 끼워 넣을 때.
+- `getParents(): Element[]` — `parentNode` 를 타고 올라가며 모든 조상 Element 를 가까운 것부터 먼 순서로 배열 반환. 조상 체인 순회·특정 조상 포함 판정에.
+- `findTabbableParent(): HTMLElement | undefined` — `parentElement` 를 위로 타며 `tabbable` 라이브러리 기준 첫 탭 이동 가능 조상을 반환. 없으면 `undefined`. 포커스 위임 대상을 위로 탐색할 때.
+- `findFirstTabbableChild(): HTMLElement | undefined` — `TreeWalker(SHOW_ELEMENT)` 로 깊이 우선 순회한 첫 탭 이동 가능(`isTabbable`) 하위 요소. 없으면 `undefined`. 컨테이너 진입 시 자동 포커스 대상을 찾을 때.
+- `isOffsetElement(): boolean` — `getComputedStyle().position` 이 `relative`/`absolute`/`fixed`/`sticky` 중 하나면 `true`, 아니면(`static` 등) `false`. 절대배치 기준(offset parent) 역할 여부 판정에.
+- `isVisible(): boolean` — `getClientRects().length > 0` 이고 `visibility !== "hidden"` 이고 `opacity !== "0"` 를 모두 만족하면 `true`. 화면 표시 여부 판정에(`display:none` 은 clientRects 가 비어 `false`).
 
 ```ts
 import "@simplysm/core-browser";
@@ -25,11 +25,11 @@ const first = containerEl.findFirstTabbableChild();
 
 `HTMLElement.prototype` 에 등록. 위와 동일하게 import 만으로 활성화.
 
-- `repaint(): void` — `offsetHeight` 접근으로 강제 동기 레이아웃(reflow)을 유발해 즉시 리페인트. 스타일 변경 직후 즉각 반영을 강제할 때.
-- `getRelativeOffset(parent: HTMLElement | string): { top: number; left: number }` — 부모 기준 CSS `top`/`left` 좌표 계산. 뷰포트 위치(getBoundingClientRect)·부모 내부 스크롤(scrollTop/Left)·중간 요소 border 두께·CSS transform 까지 반영해, 드롭다운/팝업 위치 지정에 바로 쓸 수 있는 좌표를 반환. 부모를 못 찾으면(`HTMLElement` 아님) `ArgumentError` throw.
+- `repaint(): void` — `offsetHeight` 에 접근해 강제 동기 레이아웃(reflow)을 유발, 누적된 스타일 변경을 즉시 적용·리페인트시킨다. 스타일 변경 직후 즉각 반영을 강제할 때.
+- `getRelativeOffset(parent: HTMLElement | string): { top: number; left: number }` — 부모 기준 CSS `top`/`left` 좌표 계산. 뷰포트 위치(`getBoundingClientRect`)·부모 내부 스크롤(`scrollTop`/`scrollLeft`)·중간 요소 border 두께·CSS `transform`(`DOMMatrix` 로 보정)까지 반영해, 드롭다운/팝업 위치 지정에 바로 쓸 좌표를 반환. 부모가 `HTMLElement` 가 아니면(선택자 미일치 등) `ArgumentError` throw.
   - `parent: HTMLElement | string` — 기준 부모. 문자열이면 `this.closest(parent)` 로 조상 탐색, 요소면 직접 사용(예: `document.body`, `".container"`).
-- `scrollIntoViewIfNeeded(target, offset?): void` — 대상이 스크롤 영역의 상단/좌측 경계를 벗어났을 때만 그쪽으로 스크롤해 보이게 함. 하단/우측 방향은 처리하지 않고 브라우저 기본 포커스 스크롤에 위임. 고정 헤더/컬럼이 있는 테이블의 포커스 처리에.
-  - `target: { top: number; left: number }` — 컨테이너 내 대상 위치(offsetTop/offsetLeft 기준).
+- `scrollIntoViewIfNeeded(target: { top: number; left: number }, offset?: { top: number; left: number }): void` — 대상이 스크롤 영역의 상단/좌측 경계를 벗어났을 때만(`target.top - scrollTop < offset.top`) 그쪽으로 스크롤해 보이게 함. 하단/우측 방향은 처리하지 않고 브라우저 기본 포커스 스크롤에 위임. 고정 헤더/컬럼이 있는 테이블의 포커스 처리에.
+  - `target: { top: number; left: number }` — 컨테이너 내 대상 위치(`offsetTop`/`offsetLeft` 기준).
   - `offset?: { top: number; left: number }` — 가려지면 안 되는 영역 크기(고정 헤더 높이·고정 컬럼 너비). 기본 `{ top: 0, left: 0 }`.
 
 ```ts
@@ -41,19 +41,19 @@ scrollEl.scrollIntoViewIfNeeded({ top: cellTop, left: cellLeft }, { top: headerH
 
 이벤트 핸들러로 붙이거나 다중 요소를 한 번에 처리하는 함수. 프로토타입 확장이 아니라 named export 이므로 직접 import.
 
-- `copyElement(event: ClipboardEvent): void` — copy 이벤트 핸들러용. 이벤트 타겟 내 첫 `input/textarea` 의 `value` 를 클립보드 `text/plain` 으로 기록하고 `preventDefault`. clipboardData 가 없거나 타겟이 Element 가 아니거나 input 이 없으면 무동작.
+- `copyElement(event: ClipboardEvent): void` — copy 이벤트 핸들러용. 이벤트 타겟 내 첫 `input/textarea` 의 `value` 를 클립보드 `text/plain` 으로 기록하고 `preventDefault`. `clipboardData` 가 없거나 타겟이 Element 가 아니거나 input/textarea 가 없으면 무동작(기본 동작 유지).
   - `event: ClipboardEvent` — copy 이벤트 객체. `el.addEventListener("copy", copyElement)` 로 등록.
-- `pasteToElement(event: ClipboardEvent): void` — paste 이벤트 핸들러용. 타겟 내 첫 `input/textarea` 의 전체 `value` 를 클립보드 텍스트로 교체하고 `input` 이벤트 dispatch(`bubbles: true`) 후 `preventDefault`. 커서 위치·선택 영역은 무시하고 전체를 치환.
+- `pasteToElement(event: ClipboardEvent): void` — paste 이벤트 핸들러용. 타겟 내 첫 `input/textarea` 의 전체 `value` 를 클립보드 `text/plain` 텍스트로 교체하고 `input` 이벤트를 dispatch(`bubbles: true`)한 뒤 `preventDefault`. 커서 위치·선택 영역은 무시하고 전체를 치환. 조건 미충족 시 무동작.
   - `event: ClipboardEvent` — paste 이벤트 객체. `el.addEventListener("paste", pasteToElement)` 로 등록.
-- `getBounds(els: Element[], timeout?: number): Promise<ElementBounds[]>` — `IntersectionObserver` 로 여러 요소의 뷰포트 기준 경계를 한 번에 측정. 중복은 제거하고 입력 순서대로 정렬해 반환. 빈 배열이면 즉시 `[]`. 모든 요소 관측 완료 시 resolve, 제한시간 초과 시 `TimeoutError` throw(어느 경우든 finally 에서 observer disconnect).
+- `getBounds(els: Element[], timeout?: number): Promise<ElementBounds[]>` — `IntersectionObserver` 로 여러 요소의 뷰포트 기준 경계를 한 번에 측정. 중복 요소는 제거하고 입력 순서대로 정렬해 반환. 빈 배열이면 즉시 `[]`. 모든 요소 관측 완료 시 resolve, 제한시간 초과 시 `TimeoutError` 로 reject(어느 경우든 `finally` 에서 observer `disconnect`).
   - `els: Element[]` — 측정 대상. 중복은 제거되고 결과는 입력 순서로 정렬됨.
   - `timeout?: number` — 제한시간(ms). 기본 `5000`. 초과 시 `TimeoutError`.
 - `ElementBounds` (반환 항목 타입):
   - `target: Element` — 측정된 요소.
-  - `top: number` — 뷰포트 기준 상단 위치(boundingClientRect.top).
-  - `left: number` — 뷰포트 기준 좌측 위치(boundingClientRect.left).
-  - `width: number` — 요소 너비(boundingClientRect.width).
-  - `height: number` — 요소 높이(boundingClientRect.height).
+  - `top: number` — 뷰포트 기준 상단 위치(`boundingClientRect.top`).
+  - `left: number` — 뷰포트 기준 좌측 위치(`boundingClientRect.left`).
+  - `width: number` — 요소 너비(`boundingClientRect.width`).
+  - `height: number` — 요소 높이(`boundingClientRect.height`).
 
 ```ts
 inputEl.addEventListener("copy", copyElement);

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

@@ -1,10 +1,10 @@
 # @simplysm/core-browser — IndexedDB 영속화
 
-브라우저 IndexedDB 를 다룰 때 함께 읽히는 묶음. `IndexedDbStore` 는 연결·트랜잭션·KV CRUD 를 담당하고, `IndexedDbVirtualFs` 는 그 위에 경로 키 기반 가상 파일트리(entry put/get, prefix 삭제, 자식 나열, 디렉터리 보장)를 얹는다.
+브라우저 IndexedDB 를 다룰 때 함께 읽히는 묶음. `IndexedDbStore` 는 연결·트랜잭션·키-값 CRUD 를 담당하고, `IndexedDbVirtualFs` 는 그 한 스토어를 경로 키 기반 가상 파일트리(entry put/get, prefix 삭제, 자식 나열, 디렉터리 보장)로 다룬다.
 
 ## IndexedDbStore
 
-IndexedDB 연결을 지연 오픈·재사용하고, 스토어 단위 트랜잭션과 기본 KV 작업을 비동기로 감싼 클래스.
+IndexedDB 연결을 지연 오픈·재사용하고, 스토어 단위 트랜잭션과 기본 키-값 작업을 비동기로 감싼 클래스.
 
 ```ts
 const store = new IndexedDbStore("appDb", 1, [{ name: "files", keyPath: "key" }]);
@@ -19,30 +19,30 @@ store.close();
 
 - `new IndexedDbStore(dbName: string, dbVersion: number, storeConfigs: StoreConfig[])` — DB 이름·버전·스토어 설정으로 생성(연결은 지연, 첫 작업 시 오픈).
   - `dbName: string` — IndexedDB 데이터베이스 이름.
-  - `dbVersion: number` — DB 버전. 올리면 `onupgradeneeded` 에서 누락 스토어를 생성. 스키마(스토어 추가) 변경 시 증가.
+  - `dbVersion: number` — DB 버전. 올리면 `onupgradeneeded` 에서 누락 스토어를 생성. 스토어 추가 시 증가.
   - `storeConfigs: StoreConfig[]` — 생성할 오브젝트 스토어 목록.
 - `StoreConfig` — 스토어 설정 항목.
   - `name: string` — 오브젝트 스토어 이름. upgrade 시 미존재면 `createObjectStore` 로 생성.
   - `keyPath: string` — 스토어 keyPath(레코드에서 키로 쓸 속성명).
-- `open(): Promise<IDBDatabase>` — 연결을 열어 반환. 이미 열렸으면 캐시 반환, 진행 중이면 같은 Promise 공유(중복 오픈 방지). `onupgradeneeded` 시 없는 스토어만 생성. `onversionchange`/`onclose` 시 내부 캐시(`_db`/`_opening`)를 해제해 다음 호출에 재오픈. `onblocked` 면 `Error("다른 연결에 의해 데이터베이스가 차단되었습니다")`, `onerror` 면 원본 에러로 reject. CRUD 가 자동 호출하므로 직접 호출 불필요.
-- `withStore<TResult>(storeName, mode, fn): Promise<TResult>` — 트랜잭션 1건 안에서 `fn(store)` 실행 후 완료까지 대기. `fn` 이 throw 하면 `tx.abort()` 후 그 에러로 reject(롤백), 정상이면 `oncomplete` 시 결과 resolve, `onerror` 면 `tx.error` 로 reject. 커서 등 저수준 IDB 작업을 감쌀 때.
+- `open(): Promise<IDBDatabase>` — 연결을 열어 반환. 이미 열렸으면 캐시(`_db`) 반환, 진행 중이면 같은 Promise(`_opening`) 공유(중복 오픈 방지). `onupgradeneeded` 시 없는 스토어만 생성. `onversionchange`/`onclose` 시 내부 캐시를 해제해 다음 호출에 재오픈. `onblocked` 면 `Error("다른 연결에 의해 데이터베이스가 차단되었습니다")`, `onerror` 면 원본 `req.error` 로 reject. CRUD 가 자동 호출하므로 직접 호출 불필요.
+- `withStore<TResult>(storeName: string, mode: IDBTransactionMode, fn: (store: IDBObjectStore) => Promise<TResult>): Promise<TResult>` — 트랜잭션 1건 안에서 `fn(store)` 를 먼저 await 한 뒤 완료까지 대기. `fn` 이 throw 하면 `tx.abort()` 후 그 에러로 reject(롤백), 정상이면 `oncomplete` 시 결과 resolve, `onerror` 면 `tx.error` 로 reject. 커서 등 저수준 IDB 작업을 감쌀 때.
   - `storeName: string` — 트랜잭션 대상 스토어.
   - `mode: IDBTransactionMode` — `"readonly"`(읽기 전용) | `"readwrite"`(읽기·쓰기) | `"versionchange"`(스키마 변경). 쓰기 작업이면 `"readwrite"`.
   - `fn: (store: IDBObjectStore) => Promise<TResult>` — 스토어를 받아 작업하는 콜백.
-- `get<TValue>(storeName, key): Promise<TValue | undefined>` — 키로 단건 조회. 미존재 시 `undefined`(결측 그대로 반환).
-- `put(storeName, value): Promise<void>` — 레코드 upsert. value 에 keyPath 속성이 포함돼야 함.
-- `delete(storeName, key): Promise<void>` — 키로 단건 삭제.
-- `getAll<TItem>(storeName): Promise<TItem[]>` — 스토어 전체 레코드 배열 반환.
-- `close(): void` — 연결을 닫고 내부 캐시 해제. 다음 작업 시 재오픈. 페이지 정리 시 호출.
+- `get<TValue>(storeName: string, key: IDBValidKey): Promise<TValue | undefined>` — 키로 단건 조회. 미존재 시 `undefined`(결측 그대로 반환).
+- `put(storeName: string, value: unknown): Promise<void>` — 레코드 upsert. `value` 에 keyPath 속성이 포함돼야 함.
+- `delete(storeName: string, key: IDBValidKey): Promise<void>` — 키로 단건 삭제.
+- `getAll<TItem>(storeName: string): Promise<TItem[]>` — 스토어 전체 레코드 배열 반환.
+- `close(): void` — 연결을 닫고 내부 캐시(`_db`/`_opening`) 해제. 다음 작업 시 자동 재오픈. 페이지 정리 시 호출.
 
 주의:
 
-- `withStore` 의 fn 이 throw 하면 트랜잭션 전체가 abort — 다건 쓰기를 하나의 `withStore` 안에 묶으면 원자성이 보장된다.
+- `withStore` 의 `fn` 이 throw 하면 트랜잭션 전체가 abort — 다건 쓰기를 하나의 `withStore` 안에 묶으면 원자성이 보장된다.
 - 버전 변경(`onupgradeneeded`)은 누락 스토어 생성만 한다 — 기존 스토어 스키마 변경·인덱스 추가는 별도 처리가 필요하다.
 
 ## IndexedDbVirtualFs
 
-`IndexedDbStore` 의 한 스토어를 경로 키 기반 가상 파일시스템처럼 다루는 래퍼. 키는 `keyField` 속성에 들어가는 전체 경로 문자열이고, 각 레코드는 `VirtualFsEntry`(파일/디렉터리 + 선택적 base64 데이터).
+`IndexedDbStore` 의 한 스토어를 경로 키 기반 가상 파일시스템처럼 다루는 래퍼. 키는 `keyField` 속성에 들어가는 전체 경로 문자열이고, 각 레코드는 `VirtualFsEntry`(파일/디렉터리 + 선택적 base64 데이터). 범위 조회는 `IDBKeyRange.bound(prefix, prefix + "￿")` 커서 기반.
 
 ```ts
 const fs = new IndexedDbVirtualFs(store, "files", "key");
@@ -60,17 +60,17 @@ const ok = await fs.deleteByPrefix("/root/a"); // 하위 전체 삭제, 삭제
   - `keyField: string` — 레코드에서 경로 키를 담는 속성명(스토어 keyPath 와 일치해야 함).
 - `VirtualFsEntry` — 저장 엔트리 타입.
   - `kind: "file" | "dir"` — 엔트리 종류. `"file"` = 파일, `"dir"` = 디렉터리. 자식 나열·디렉터리 판정에 사용.
-  - `dataBase64?: string` — 파일 내용 base64. 디렉터리거나 빈 파일이면 생략(undefined).
-- `getEntry(fullKey): Promise<VirtualFsEntry | undefined>` — 전체 경로 키로 단건 조회. 미존재 시 `undefined`.
-- `putEntry(fullKey, kind, dataBase64?): Promise<void>` — 엔트리 저장. `keyField` 에 `fullKey`, 그리고 `kind`/`dataBase64` 를 함께 기록.
+  - `dataBase64?: string` — 파일 내용 base64. 디렉터리거나 데이터를 안 넘기면 생략(undefined).
+- `getEntry(fullKey: string): Promise<VirtualFsEntry | undefined>` — 전체 경로 키로 단건 조회. 미존재 시 `undefined`.
+- `putEntry(fullKey: string, kind: "file" | "dir", dataBase64?: string): Promise<void>` — 엔트리 저장(upsert). `keyField` 에 `fullKey`, 그리고 `kind`/`dataBase64` 를 함께 기록.
   - `fullKey: string` — 저장할 전체 경로 키.
   - `kind: "file" | "dir"` — 저장할 엔트리 종류.
   - `dataBase64?: string` — 파일 데이터(base64). 디렉터리면 생략.
-- `deleteByPrefix(keyPrefix): Promise<boolean>` — 커서로 키가 `keyPrefix` 자신이거나 `keyPrefix + "/"` 로 시작하는 엔트리를 전부 삭제(같은 접두어를 가진 다른 형제 경로 오삭제 방지). 하나라도 지웠으면 `true`, 없으면 `false`. 디렉터리 트리 통째 삭제에.
-- `listChildren(prefix): Promise<{ name: string; isDirectory: boolean }[]>` — `prefix` 직계 자식만 집계. 키에서 prefix 제거 후 첫 세그먼트를 이름으로 삼고, 하위 세그먼트가 더 있거나 엔트리 `kind === "dir"` 면 디렉터리로 판정. 디렉터리 목록 표시용(재귀 아님).
+- `deleteByPrefix(keyPrefix: string): Promise<boolean>` — 커서로 키가 `keyPrefix` 자신이거나 `keyPrefix + "/"` 로 시작하는 엔트리를 전부 삭제(같은 접두어를 가진 형제 경로 오삭제 방지). 하나라도 지웠으면 `true`, 없으면 `false`. 디렉터리 트리 통째 삭제에.
+- `listChildren(prefix: string): Promise<{ name: string; isDirectory: boolean }[]>` — `prefix` 직계 자식만 집계. 키에서 `prefix` 를 제거한 나머지의 첫 세그먼트를 이름으로 삼고, 하위 세그먼트가 더 있거나 엔트리 `kind === "dir"` 면 디렉터리로 판정(중복 세그먼트는 Map 으로 1회만). 디렉터리 목록 표시용(재귀 아님).
   - 반환 항목 `name: string` — 직계 자식 이름(첫 경로 세그먼트).
   - 반환 항목 `isDirectory: boolean` — 디렉터리 여부.
-- `ensureDir(fullKeyBuilder, dirPath): Promise<void>` — `dirPath` 상의 각 중간 디렉터리를 부모부터 누적 경로마다 없으면 생성. `dirPath === "/"` 면 루트 1건만 생성. 단일 `withStore("readwrite")` 트랜잭션으로 처리(원자적). 파일 쓰기 전 상위 디렉터리 보장에.
+- `ensureDir(fullKeyBuilder: (path: string) => string, dirPath: string): Promise<void>` — `dirPath` 상의 각 중간 디렉터리를 부모부터 누적 경로마다 없으면(`store.get` 으로 확인) 생성. `dirPath === "/"` 면 루트 1건만 생성. 전체를 단일 `withStore("readwrite")` 트랜잭션으로 처리(원자적). 파일 쓰기 전 상위 디렉터리 보장에.
   - `fullKeyBuilder: (path: string) => string` — 누적 경로(예: `/a`, `/a/b`)를 실제 저장 key 로 변환하는 콜백.
   - `dirPath: string` — 보장할 디렉터리 경로(`/` 구분). 빈 세그먼트는 무시.
 

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

@@ -1,37 +1,37 @@
 # @simplysm/core-common
 
-브라우저·Node 공용 기반 유틸. 날짜/시간 값 타입, 에러 클래스, 배열/Set/Map 확장, 객체 조작, 직렬화(json/xml/bytes/transfer), 비동기 큐·이벤트·대기, 로거·환경변수·원시타입 매핑을 제공.
+브라우저·Node 공용 기반 유틸. 날짜/시간 값 타입, 에러 클래스, 배열/Set/Map 프로토타입 확장, 객체 조작, 직렬화(json/xml/bytes/transfer), 비동기 큐·이벤트·대기, 문자열/숫자/경로 유틸, 로거·환경변수·원시타입 매핑을 제공.
 
 ## 사용 트리거 인덱스
 
-- **에러 클래스** — 원인 체인을 묶은 에러를 throw 하거나 catch 에서 메시지를 추출할 때. 자세히: [errors.md](./errors.md)
-- **날짜/시간 값 타입 (DateTime·DateOnly·Time·Uuid)** — 불변 날짜/시간/식별자 값을 만들고 파싱·산술·포맷할 때. 자세히: [value-types.md](./value-types.md)
-- **배열/Set/Map 확장** — `arr.single/groupBy/toMap/distinct/orderBy/diffs/toTree` 등 프로토타입 확장 메서드와 `Set.adds/toggle`, `Map.getOrCreate/update` 를 쓸 때. 자세히: [collection-ext.md](./collection-ext.md)
-- **객체 조작 (obj 네임스페이스)** — `obj.clone/equal/merge/merge3/pick/omit/getChainValue/keys/entries` 등 깊은 복사·비교·병합·체인 접근이 필요할 때. 자세히: [obj.md](./obj.md)
+- **에러 클래스 (SdError·ArgumentError·NotImplementedError·TimeoutError)** — 원인 체인을 묶은 에러를 throw 하거나 `err.message` 를 안전 추출할 때. 자세히: [errors.md](./errors.md)
+- **날짜/시간 값 타입 (DateTime·DateOnly·Time·Uuid)** — 불변 날짜/시간/식별자 값을 만들고 파싱·산술·포맷·주차계산할 때. 자세히: [value-types.md](./value-types.md)
+- **배열/Set/Map 확장** — `arr.single/groupBy/toMap/toTree/distinct/orderBy/diffs/oneWayDiffs/merge` 등 프로토타입 확장 메서드와 `Set.adds/toggle`, `Map.getOrCreate/update` 를 쓸 때. 자세히: [collection-ext.md](./collection-ext.md)
+- **객체 조작 (obj 네임스페이스)** — `obj.clone/equal/merge/merge3/pick/omit/getChainValue/keys/entries/map` 등 깊은 복사·비교·병합·체인 접근이 필요할 때. 자세히: [obj.md](./obj.md)
 - **직렬화 (json·xml·bytes·transfer)** — 커스텀 타입(DateTime/Uuid/Map/Error 등) 포함 객체를 JSON/XML 문자열, hex/base64, Worker 전송 형태로 변환할 때. 자세히: [serialization.md](./serialization.md)
 - **비동기 런타임 (큐·이벤트·대기·LazyGcMap)** — `DebounceQueue`/`SerialQueue` 로 호출 흐름을 제어하거나, `EventEmitter` 로 타입 안전 이벤트를 다루거나, `wait.until/time`, 자동 만료 Map 이 필요할 때. 자세히: [async-runtime.md](./async-runtime.md)
 - **str (문자열 유틸)** — 한국어 조사 선택, 전각→반각, 케이스 변환, 빈문자열 판별, 삽입. (아래 인라인)
 - **num (숫자 유틸)** — 비숫자 제거 후 정수/실수 파싱, 0/null 판별, 천단위 포맷. (아래 인라인)
 - **path (POSIX 경로 유틸)** — 브라우저용 join/basename/extname. (아래 인라인)
-- **dt (날짜 포맷 헬퍼)** — `DateTime`/`DateOnly`/`Time` 의 `toFormatString` 이 내부적으로 쓰는 C# 스타일 포맷 문자열 변환. (아래 인라인)
 - **primitive (원시타입 추론)** — 런타임 값에서 `PrimitiveTypeStr` 추론. (아래 인라인)
 - **template-strings (코드 하이라이팅 태그)** — `js/ts/html/tsql/mysql/pgsql` 템플릿 태그로 들여쓰기 정규화. (아래 인라인)
-- **ZipArchive** — ZIP 바이트를 읽고 파일 단위로 추출·추가·재압축할 때. (아래 인라인)
 - **env / createLogger** — 환경변수 읽기·쓰기, 모듈 레벨 안전 lazy 로거 생성. (아래 인라인)
 - **공용 타입 (common.types)** — `PrimitiveType`/`PrimitiveTypeStr`/`PrimitiveTypeMap`/`Bytes`/`DeepPartial`/`Type`. (아래 인라인)
 
+> `dt` (날짜 포맷 헬퍼) 네임스페이스도 `import { dt }` 로 노출되지만, 보통 `DateTime`/`DateOnly`/`Time` 의 `toFormatString` 을 통해 간접 사용한다. 포맷 토큰 표는 [value-types.md](./value-types.md) 참조.
+
 ## str (문자열 유틸)
 
 `import { str } from "@simplysm/core-common"` 네임스페이스.
 
-- `getKoreanSuffix(text: string, type: "을"|"은"|"이"|"와"|"랑"|"로"|"라"): string` — 마지막 글자 받침 유무로 한국어 조사를 선택. type 은 조사 쌍 식별자: `"을"`=을/를, `"은"`=은/는, `"이"`=이/가, `"와"`=과/와, `"랑"`=이랑/랑, `"로"`=으로/로(받침이 ㄹ이면 "로"), `"라"`=이라/라. 한글이 아니거나 빈 문자열이면 받침 없는 형태 반환. 동적 메시지 조립 시 사용.
-- `replaceFullWidth(str: string): string` — 전각 영문·숫자·공백·괄호를 반각으로 치환. 외부 입력(엑셀·스캐너) 정규화 시.
+- `getKoreanSuffix(text: string, type: "을"|"은"|"이"|"와"|"랑"|"로"|"라"): string` — 마지막 글자 받침 유무로 한국어 조사를 선택. type 은 조사 쌍 식별자: `"을"`=을/를, `"은"`=은/는, `"이"`=이/가, `"와"`=과/와, `"랑"`=이랑/랑, `"로"`=으로/로(받침이 ㄹ이면 "로"), `"라"`=이라/라. 한글(0xAC00~0xD7A3)이 아니거나 빈 문자열이면 받침 없는 형태 반환. 동적 메시지 조립 시 사용.
+- `replaceFullWidth(str: string): string` — 전각 영문(Ａ-Ｚ/ａ-ｚ)·숫자(０-９)·공백·괄호(（）)를 반각으로 치환. 외부 입력(엑셀·스캐너) 정규화 시.
 - `toPascalCase(str: string): string` — `-`/`_`/`.` 구분자 뒤 글자와 첫 글자를 대문자화. 식별자 변환 시.
 - `toCamelCase(str: string): string` — 구분자 뒤 글자는 대문자화하되 첫 글자는 소문자화.
 - `toKebabCase(str: string): string` — 대문자 앞에 `-` 삽입 후 소문자화. 연속 대문자도 글자별 분리(`XMLParser`→`x-m-l-parser`), 기존 `-`/`_` 구분자는 유지.
 - `toSnakeCase(str: string): string` — `toKebabCase` 와 동일 규칙이되 구분자가 `_`.
 - `isNullOrEmpty(str: string | undefined): str is "" | undefined` — null/undefined/빈문자열이면 true 인 타입 가드. else 분기에서 비어있지 않은 string 으로 좁혀짐.
-- `insert(str: string, index: number, insertString: string): string` — index 위치에 문자열 삽입한 새 문자열.
+- `insert(str: string, index: number, insertString: string): string` — index 위치(0 기준)에 문자열 삽입한 새 문자열.
 
 ```ts
 import { str } from "@simplysm/core-common";
@@ -40,13 +40,13 @@ const label = "사과" + str.getKoreanSuffix("사과", "을") + " 담았습니
 
 ## num (숫자 유틸)
 
-`import { num } from "@simplysm/core-common"` 네임스페이스. 파싱 계열은 비숫자 문자(0-9·`-`·`.` 외)를 먼저 제거하므로 `"010-1234"` 같은 입력도 받음(선행 `-`만 부호로 유지).
+`import { num } from "@simplysm/core-common"` 네임스페이스. 파싱 계열은 비숫자 문자(0-9·`-`·`.` 외)를 먼저 제거하므로 `"010-1234"` 같은 입력도 받음(선행 `-`만 부호로 유지, 중간 `-` 는 제거).
 
-- `parseInt(text: unknown): number | undefined` — 정수 파싱. number 면 `Math.trunc`, 소수 문자열이면 정수부만, 파싱 불가면 undefined.
+- `parseInt(text: unknown): number | undefined` — 정수 파싱. number 면 `Math.trunc`, 소수 문자열이면 정수부만, 빈 문자열·`"-"`·파싱 불가면 undefined.
 - `parseFloat(text: unknown): number | undefined` — 실수 파싱. number 는 그대로, 파싱 불가면 undefined.
 - `parseRoundedInt(text: unknown): number | undefined` — `parseFloat` 후 `Math.round`. 반올림 정수가 필요할 때.
 - `isNullOrEmpty(val: number | undefined): val is 0 | undefined` — null/undefined/0 이면 true 인 타입 가드. else 분기에서 0 아닌 number 로 좁혀짐.
-- `format(val, digit?: { max?: number; min?: number }): string | undefined` — 천단위 구분자 포맷. `max`=최대 소수 자릿수, `min`=최소 소수 자릿수(부족분 0 채움). val 이 undefined 면 undefined 반환.
+- `format(val: number | undefined, digit?: { max?: number; min?: number }): string | undefined` — `toLocaleString` 기반 천단위 구분자 포맷. `max`=최대 소수 자릿수, `min`=최소 소수 자릿수(부족분 0 채움). val 이 undefined 면 undefined 반환.
 
 ```ts
 import { num } from "@simplysm/core-common";
@@ -56,29 +56,21 @@ num.parseInt("010-1234-5678");    // 1012345678
 
 ## path (POSIX 경로 유틸)
 
-`import { path } from "@simplysm/core-common"` 네임스페이스. POSIX 슬래시 경로만 지원(Windows 백슬래시 미지원). 브라우저·Capacitor 환경용 Node `path` 대체.
+`import { path } from "@simplysm/core-common"` 네임스페이스. POSIX 슬래시(`/`) 경로만 지원(Windows 백슬래시 미지원). 브라우저·Capacitor 환경용 Node `path` 대체.
 
-- `join(...segments: string[]): string` — 슬래시로 결합하며 중간 세그먼트의 앞뒤 슬래시·빈 세그먼트 제거.
+- `join(...segments: string[]): string` — 슬래시로 결합하며 첫 세그먼트는 끝 슬래시만, 이후 세그먼트는 앞뒤 슬래시·빈 세그먼트 제거.
 - `basename(filePath: string, ext?: string): string` — 마지막 세그먼트 추출. `ext` 가 끝과 일치하면 제거.
-- `extname(filePath: string): string` — 마지막 `.` 이후 확장자(`.` 포함). 숨김파일(`.gitignore`)은 빈 문자열.
-
-## dt (날짜 포맷 헬퍼)
-
-`import { dt } from "@simplysm/core-common"` 네임스페이스. 보통 `DateTime`/`DateOnly`/`Time` 의 `toFormatString` 을 통해 간접 사용.
-
-- `format(formatString: string, args: { year?, month?, day?, hour?, minute?, second?, millisecond?, timezoneOffsetMinutes? }): string` — C# 스타일 포맷 토큰 치환. 토큰: `yyyy/yy`(연), `MM/M`(월), `ddd`(요일 한글)/`dd/d`(일), `tt`(AM/PM), `hh/h`(12시간)/`HH/H`(24시간), `mm/m`(분), `ss/s`(초), `fff/ff/f`(밀리초), `zzz/zz/z`(타임존 오프셋). 전달되지 않은 구성요소의 토큰은 치환되지 않음.
-- `normalizeMonth(year, month, day): { year; month; day }` — 1-12 범위 밖 월을 연도로 이월하고, 대상 월 일수를 넘는 일은 말일로 보정.
-- `convert12To24(rawHour: number, isPM: boolean): number` — 12시간제(1-12)+오전/오후를 24시간제(0-23)로 변환.
+- `extname(filePath: string): string` — 마지막 `.` 이후 확장자(`.` 포함). 숨김파일(`.gitignore` 처럼 앞 `.`)은 빈 문자열.
 
 ## primitive (원시타입 추론)
 
 `import { primitive } from "@simplysm/core-common"` 네임스페이스.
 
-- `typeStr(value): PrimitiveTypeStr` — 런타임 값에서 `"string"|"number"|"boolean"|"DateTime"|"DateOnly"|"Time"|"Uuid"|"Bytes"` 중 해당 문자열 반환. 지원하지 않는 타입이면 `ArgumentError` throw. ORM/직렬화에서 값 타입을 문자열 키로 다룰 때.
+- `typeStr(value): PrimitiveTypeStr` — 런타임 값에서 `"string"|"number"|"boolean"|"DateTime"|"DateOnly"|"Time"|"Uuid"|"Bytes"`(Uint8Array→`"Bytes"`) 중 해당 문자열 반환. 지원하지 않는 타입이면 `ArgumentError` throw. ORM/직렬화에서 값 타입을 문자열 키로 다룰 때.
 
 ## template-strings (코드 하이라이팅 태그)
 
-`import { js, ts, html, tsql, mysql, pgsql } from "@simplysm/core-common"`. 모두 동일 동작 — 보간값을 문자열로 합친 뒤 공통 최소 들여쓰기를 제거하고 앞뒤 빈 줄을 잘라냄. 함수별 차이는 IDE 하이라이팅 언어 힌트뿐(js/ts/html/T-SQL/MySQL/PostgreSQL). 런타임 검증·이스케이프는 하지 않음.
+`import { js, ts, html, tsql, mysql, pgsql } from "@simplysm/core-common"`. 모두 동일 동작 — 보간값을 문자열로 합친 뒤 공통 최소 들여쓰기를 제거하고 앞뒤 빈 줄을 잘라냄(보간값이 null/undefined 면 빈 문자열). 함수별 차이는 IDE 하이라이팅 언어 힌트뿐(js/ts/html/T-SQL/MySQL/PostgreSQL). 런타임 검증·이스케이프는 하지 않음.
 
 ```ts
 import { ts } from "@simplysm/core-common";
@@ -89,27 +81,6 @@ const code = ts`
 `; // 앞 공통 들여쓰기 제거된 문자열
 ```
 
-## ZipArchive
-
-`import { ZipArchive } from "@simplysm/core-common"`. `@zip.js/zip.js` 래퍼. 읽기/쓰기를 한 인스턴스로 다루며 추출 결과를 내부 캐시에 보관. 사용 후 `close()` 필수.
-
-- `new ZipArchive(data?: Blob | Bytes)` — `data` 생략 시 새 빈 아카이브, 주면 읽기용 리더 구성(`Uint8Array`→`Uint8ArrayReader`, `Blob`→`BlobReader`).
-- `extractAll(progressCallback?: (p: ZipArchiveProgress) => void): Promise<Map<string, Bytes | undefined>>` — 전체 파일 추출. 콜백 인자 `ZipArchiveProgress` 필드: `fileName`=현재 파일명, `totalSize`=전체 비압축 크기, `extractedSize`=누적 추출 크기.
-- `get(fileName: string): Promise<Bytes | undefined>` — 단일 파일 추출(없으면 undefined). 캐시 우선.
-- `exists(fileName: string): Promise<boolean>` — 파일 존재 여부.
-- `write(fileName: string, bytes: Bytes): void` — 캐시에 파일 등록(아직 압축 안 함).
-- `compress(): Promise<Bytes>` — 캐시(및 원본 추출분)를 ZIP 바이트로 압축. 내부적으로 `extractAll()` 호출하므로 전체가 메모리에 로드됨.
-- `close(): Promise<void>` — 리더 닫고 캐시 비움.
-
-```ts
-const zip = new ZipArchive(zipBytes);
-try {
-  const content = await zip.get("file.txt");
-} finally {
-  await zip.close();
-}
-```
-
 ## env / createLogger
 
 `import { env, parseBoolEnv, createLogger } from "@simplysm/core-common"`.
@@ -117,7 +88,7 @@ try {
 - `env(key: string): string | undefined` — 환경변수 읽기. `process.env` 우선, 없으면 `import.meta.env` fallback(Node 에선 보통 undefined).
 - `env(key: string, value: string): void` — `process.env[key]` 에 쓰기(process 없는 런타임이면 무시).
 - `parseBoolEnv(value: unknown): boolean` — `"true"/"1"/"yes"/"on"`(대소문자 무시)이면 true, 그 외 false. 환경변수 boolean 해석 시.
-- `createLogger(tag: string): ConsolaInstance` — consola 태그 로거를 첫 메서드 접근 시점까지 지연 생성하는 Proxy. 모듈 레벨에서 선언해도 이후 `setupConsola` 의 level/reporters 변경이 반영됨. 모듈 최상단에 로거를 두고 싶을 때 `consola.withTag()` 직접 호출 대신 사용.
+- `createLogger(tag: string): ConsolaInstance` — consola 태그 로거를 첫 메서드 접근 시점까지 지연 생성하는 Proxy. 모듈 레벨에서 선언해도 이후 `setupConsola` 의 level/reporters 변경이 child 인스턴스에 반영됨. `consola.withTag()` 직접 호출 대신 사용(로깅 표준 매뉴얼 강제). tag 형식은 `<도메인>:<역할>` 또는 단일 토큰.
 
 ```ts
 import { createLogger, env, parseBoolEnv } from "@simplysm/core-common";
@@ -134,4 +105,4 @@ if (parseBoolEnv(env("DEV"))) logger.debug("dev mode");
 - `PrimitiveTypeStr = keyof PrimitiveTypeMap` — 위 매핑의 key 유니온.
 - `PrimitiveType = PrimitiveTypeMap[PrimitiveTypeStr] | undefined` — 모든 원시 값 유니온(undefined 포함).
 - `DeepPartial<TObject>` — 원시타입은 그대로 두고 객체/배열만 재귀적으로 optional 화. 부분 패치 입력 타입에.
-- `Type<TInstance>` — `new (...args) => TInstance` 생성자 타입. 팩토리·DI·`instanceof` 분기에서 클래스를 값으로 받을 때.
+- `Type<TInstance>` — `new (...args: unknown[]) => TInstance` 생성자 타입. 팩토리·DI·`instanceof` 분기에서 클래스를 값으로 받을 때.

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

@@ -1,19 +1,21 @@
-# @simplysm/core-common — 비동기 런타임 (큐·이벤트·대기·LazyGcMap)
+# @simplysm/core-common — async-runtime
 
-호출 흐름 제어(디바운스/직렬 큐), 타입 안전 이벤트(EventEmitter), 대기 헬퍼(wait), 자동 만료 Map(LazyGcMap). 비동기 작업 조율·이벤트 배선·타이머 자원 정리가 필요할 때 함께 참조. 큐와 EventEmitter 는 `dispose()` 로 자원을 정리해야 함.
+호출 흐름 제어(디바운스/직렬 큐), 타입 안전 이벤트(`EventEmitter`), 대기 헬퍼(`wait`), 자동 만료 Map(`LazyGcMap`). 큐와 `EventEmitter`/`LazyGcMap` 은 `dispose()`(또는 LazyGcMap 은 `dispose`)로 타이머·리스너 자원을 정리해야 함. `import { DebounceQueue, SerialQueue, EventEmitter, LazyGcMap, wait } from "@simplysm/core-common"`.
+
+큐 실행 중 발생한 에러는 `"error"` 이벤트로 발행되며, 리스너가 없으면 `createLogger` 로 로그 출력된다.
 
 ## EventEmitter
 
 ```ts
-class EventEmitter<TEvents extends { [K in keyof TEvents]: unknown } = Record<string, unknown>> {}
+class EventEmitter<TEvents extends Record<keyof TEvents, unknown> = Record<string, unknown>>
 ```
 
 `EventTarget` 기반 타입 안전 이벤트 이미터(브라우저·Node 공용). `TEvents` 는 이벤트명→데이터 타입 맵.
 
-- `on(type, listener: (data: TEvents[type]) => void): void` — 리스너 등록(같은 리스너 중복 등록은 무시).
+- `on(type, listener: (data) => void): void` — 리스너 등록. 같은 이벤트에 같은 리스너 중복 등록은 무시.
 - `off(type, listener): void` — 리스너 제거.
-- `emit(type, ...args): void` — 발행. 데이터 타입이 `void` 면 인자 없이 호출.
-- `listenerCount(type): number` — 해당 이벤트의 리스너 수.
+- `emit(type, ...args): void` — 발행. 데이터 타입이 `void` 면 인자 생략, 아니면 데이터 1개 전달.
+- `listenerCount(type): number` — 해당 이벤트의 등록 리스너 수.
 - `dispose(): void` — 모든 리스너 제거.
 
 ```ts
@@ -22,89 +24,98 @@ class MyEmitter extends EventEmitter<MyEvents> {}
 const em = new MyEmitter();
 em.on("data", (d) => console.log(d)); // d: string
 em.emit("data", "hello");
-em.emit("done"); // void 는 인자 없이
+em.emit("done");                       // void 는 인자 없이
 ```
 
 ## DebounceQueue
 
 ```ts
-class DebounceQueue extends EventEmitter<{ error: SdError }> {
-  constructor(delay?: number);
-}
+class DebounceQueue extends EventEmitter<{ error: SdError }>
+constructor(delay?: number)
 ```
 
-연속 호출 시 **마지막 요청만** 실행하는 디바운스 큐. 입력 자동완성·연속 상태 변경 일괄 처리에.
+짧은 시간 내 여러 호출 중 **마지막 요청만** 실행, 이전 요청은 무시.
 
-- `constructor(delay?)` — `delay`(ms) 생략 시 다음 이벤트 루프에 즉시 실행.
-- `run(fn: () => void | Promise<void>): void` — 큐에 등록. 대기 중 함수가 있으면 교체. 실행 중에 도착한 요청은 디바운스 없이 현재 실행 직후 즉시 처리(누락 방지 의도).
-- `dispose(): void` — 대기 함수·타이머 정리(EventEmitter dispose 포함).
-- 작업 throw 시 `"error"` 리스너가 있으면 `SdError` 로 emit, 없으면 내부 로거로 출력.
-
-## SerialQueue
+- `new DebounceQueue(delay?)` — `delay`(ms) 생략 시 다음 이벤트 루프에 즉시 실행.
+- `run(fn: () => void | Promise<void>): void` — 큐에 함수 등록(이전 대기 함수는 교체). 실행 중에 들어온 요청은 디바운스 지연 없이 현재 실행 직후 즉시 처리(의도적 설계 — 실행 중 도착 요청 누락 방지).
+- `dispose(): void` — 대기 함수·타이머 정리 후 상위 `EventEmitter.dispose` 호출.
+- `"error"` 이벤트(`SdError`) — `run` 으로 실행한 함수가 throw 하면 발행. 리스너 없으면 로그.
 
 ```ts
-class SerialQueue extends EventEmitter<{ error: SdError }> {
-  constructor(gap?: number);
-}
+const q = new DebounceQueue(300);
+q.on("error", (e) => console.error(e));
+input.addEventListener("input", () => q.run(() => search(input.value)));
 ```
 
-큐에 등록된 함수를 **순차 실행**(이전 완료 후 다음). 에러가 나도 후속 작업은 계속.
-
-- `constructor(gap = 0)` — 각 작업 사이 간격(ms).
-- `run(fn: () => void | Promise<void>): void` — 큐에 추가하고 실행 시작.
-- `dispose(): void` — 대기 큐 비움(실행 중 작업은 완료됨, EventEmitter dispose 포함).
-- 작업 throw 시 `"error"` 리스너가 있으면 `SdError` emit, 없으면 내부 로거 출력.
+## SerialQueue
 
 ```ts
-const q = new SerialQueue();
-q.run(async () => { await save(a); });
-q.run(async () => { await save(b); }); // a 완료 후 실행
+class SerialQueue extends EventEmitter<{ error: SdError }>
+constructor(gap?: number)
 ```
 
-## wait (`import { wait } from "@simplysm/core-common"`)
+등록된 함수를 **순차** 실행(앞 작업 완료 후 다음 시작). 한 작업이 throw 해도 후속 작업은 계속 실행.
 
-- `until(forwarder: () => boolean | Promise<boolean>, milliseconds = 100, maxCount?): Promise<void>` — 조건이 true 가 될 때까지 `milliseconds` 간격으로 폴링. 첫 평가에서 true 면 즉시 반환. `maxCount` 지정 시 초과하면 `TimeoutError` throw(미지정이면 무제한).
-- `time(millisecond: number): Promise<void>` — 지정 시간만큼 대기(`setTimeout` Promise 화).
+- `new SerialQueue(gap?)` — `gap`(ms, 기본 0) 은 각 작업 사이 간격(`wait.time` 으로 대기).
+- `run(fn: () => void | Promise<void>): void` — 큐에 추가하고 처리 시작.
+- `dispose(): void` — 대기 큐 비움(실행 중 작업은 완료됨) 후 상위 `EventEmitter.dispose`.
+- `"error"` 이벤트(`SdError`) — 작업 throw 시 발행. 리스너 없으면 로그.
 
 ```ts
-import { wait } from "@simplysm/core-common";
-await wait.until(() => isReady, 100, 50); // 100ms 간격, 50회 초과 시 TimeoutError
-await wait.time(300);
+const q = new SerialQueue();
+q.run(async () => { await save(1); });
+q.run(async () => { await save(2); }); // 1 완료 후 실행
 ```
 
 ## LazyGcMap
 
 ```ts
-class LazyGcMap<TKey, TValue> {
-  constructor(options: {
-    gcInterval?: number;
-    expireTime: number;
-    onExpire?: (key: TKey, value: TValue) => void | Promise<void>;
-  });
-}
+class LazyGcMap<TKey, TValue>
+constructor(options: {
+  gcInterval?: number;
+  expireTime: number;
+  onExpire?: (key: TKey, value: TValue) => void | Promise<void>;
+})
 ```
 
-LRU 접근 시간 기반 자동 만료 Map. 지정 시간 동안 접근 없으면 GC 타이머가 삭제. 캐시·세션 보관에. **사용 후 `dispose()` 필수**(아니면 GC 타이머가 계속 돌아 메모리 누수).
+LRU 방식 자동 만료 Map. 접근 시 마지막 접근 시간을 갱신하고, `expireTime`(ms) 동안 접근 없으면 자동 삭제. **사용 후 반드시 `dispose()` 호출**(안 하면 GC 타이머가 계속 돌아 메모리 누수).
+
+옵션:
 
-생성자 옵션:
-- `expireTime: number` — 마지막 접근 후 이 ms 가 지나면 만료(필수).
-- `gcInterval?: number` — GC 주기(ms). 생략 시 `expireTime/10`(최소 1000).
-- `onExpire?: (key, value) => void | Promise<void>` — 만료 시 콜백(비동기 가능). 콜백 throw 시 로그 출력 후 계속 진행.
+- `expireTime: number` — 만료 시간(ms). 마지막 접근 후 이 시간 경과 시 삭제.
+- `gcInterval?: number` — GC 주기(ms). 기본값 `max(expireTime / 10, 1000)`.
+- `onExpire?: (key, value) => void | Promise<void>` — 만료 시 콜백. 비동기 가능, 콜백이 throw 하면 로그 후 계속.
 
 메서드:
-- `get(key)` — 조회 + 접근 시간 갱신(LRU). `has(key)` — 존재 확인(시간 갱신 안 함).
-- `set(key, value)` — 저장 + 접근 시간 설정, GC 타이머 시작.
-- `getOrCreate(key, factory)` — 없으면 `factory()` 로 생성·저장. dispose 후 호출 시 throw.
-- `delete(key)` — 삭제(비면 GC 중지). `clear()` — 전체 삭제(인스턴스 재사용 가능). `dispose()` — 정리 후 사용 불가.
-- `size` — 항목 수. `values()/keys()/entries()` — 이터레이터.
-- GC 는 중복 실행 방지(이전 GC 가 끝나야 다음). 만료 콜백 중 같은 key 로 `set` 되면 재등록 항목은 삭제하지 않음(항목 참조 동일성으로 판정).
+
+- `size` — 항목 수.
+- `has(key)` — 존재 여부(접근 시간 갱신 안 함).
+- `get(key): TValue | undefined` — 조회(접근 시간 갱신, LRU).
+- `set(key, value): void` — 저장(GC 타이머 시작).
+- `delete(key): boolean` — 삭제(비면 타이머 중지).
+- `getOrCreate(key, factory): TValue` — 없으면 `factory()` 로 생성·저장. dispose 후 호출하면 `Error`.
+- `clear(): void` — 전부 삭제(인스턴스는 재사용 가능).
+- `dispose(): void` — 타이머 중지 + 데이터 삭제(인스턴스 사용 종료).
+- `values()/keys()/entries()` — Iterator.
 
 ```ts
 const cache = new LazyGcMap<string, Session>({ expireTime: 60000 });
 try {
-  cache.set("u1", session);
-  const s = cache.getOrCreate("u2", () => loadSession("u2"));
+  cache.set("sid", session);
+  cache.getOrCreate("sid2", () => createSession());
 } finally {
   cache.dispose();
 }
 ```
+
+## wait
+
+`import { wait } from "@simplysm/core-common"` 네임스페이스.
+
+- `wait.until(forwarder: () => boolean | Promise<boolean>, milliseconds?, maxCount?): Promise<void>` — 조건이 true 가 될 때까지 대기. `milliseconds`(기본 100) 간격으로 재확인. 첫 호출에서 true 면 즉시 반환. `maxCount` 지정 시 그 횟수 초과하면 `TimeoutError(count)` throw(미지정이면 무제한).
+- `wait.time(millisecond: number): Promise<void>` — 지정 시간(ms) 대기(`setTimeout` 래퍼).
+
+```ts
+await wait.until(() => isReady, 100, 50); // 100ms 간격, 최대 50회
+await wait.time(500);
+```