@simplysm/sd-claude 14.0.72 → 14.0.73

package/claude/references/sd-simplysm14/README.md

@@ -48,8 +48,8 @@ ORM 호출, 파일 변환, 비즈니스 로직 등은 위 두 사유에 해당
 - **lint** — ESLint flat config 작성 시 `@simplysm/lint/eslint-recommended` 프리셋 또는 `@simplysm/lint/eslint-plugin` 개별 규칙 import. 자세히: [apis/lint/README.md](./apis/lint/README.md)
 - **orm-common** — Dialect 독립 ORM 코어. `DbContext` 서브클래싱 + Table/View/Procedure 빌더 + `expr` AST + `Queryable` 체이닝으로 SQL 을 만들고 dialect QueryBuilder 로 렌더. 자세히: [apis/orm-common/README.md](./apis/orm-common/README.md)
 - **orm-node** — Node 환경에서 `DbContext` 를 MSSQL/MySQL/PostgreSQL 실 연결에 붙이는 어댑터(`createOrm`), raw SQL/bulk insert (`createDbConn`). 자세히: [apis/orm-node/README.md](./apis/orm-node/README.md)
-- **sd-claude** — `.claude/` 자산 배포 및 `sd-claude` CLI 만 제공. 라이브러리 코드 API 없음(npm 배포 전용). 자세히: [apis/sd-claude/README.md](./apis/sd-claude/README.md)
-- **sd-cli** — `sd.config.ts` 작성 타입, Vitest 의 Angular AOT plugin(`sdAngularPlugin`), TS 패키지 증분 컴파일 엔진(`SdTsCompiler`). 자세히: [apis/sd-cli/README.md](./apis/sd-cli/README.md)
+- **sd-claude** — simplysm 표준 Claude 자산(스킬·룰·훅) 동기화 및 Claude 계정 저장/전환 CLI(`sd-claude auth save`/`switch`). 라이브러리 코드 API 없음. 자세히: [apis/sd-claude/README.md](./apis/sd-claude/README.md)
+- **sd-cli** — simplysm 빌드/배포 오케스트레이션 CLI. 서브커맨드(`check`/`watch`/`dev`/`device`/`build`/`publish`/`replace-deps`/`init`), `sd.config.ts` 작성 타입, Vitest 의 Angular AOT plugin(`sdAngularPlugin`), TS 패키지 증분 컴파일 엔진(`SdTsCompiler`). 자세히: [apis/sd-cli/README.md](./apis/sd-cli/README.md)
 - **service-client** — `@simplysm/service-server` 와 WebSocket 으로 통신하는 클라이언트. RPC·이벤트 구독·파일 업/다운로드·원격 ORM 실행을 단일 `ServiceClient` 에서 제공(Node/브라우저 공용). 자세히: [apis/service-client/README.md](./apis/service-client/README.md)
 - **service-common** — 서버/클라이언트가 공유하는 서비스 프로토콜·메시지·서비스 인터페이스·앱 구조·이벤트 정의. 자세히: [apis/service-common/README.md](./apis/service-common/README.md)
 - **service-server** — Fastify + WebSocket 위에 서비스(`defineService`)·JWT 인증(`auth`)·빌트인 ORM/AutoUpdate/AppStructure·V1 레거시 호환을 부트스트랩(`createServiceServer().listen()`). 자세히: [apis/service-server/README.md](./apis/service-server/README.md)

package/claude/references/sd-simplysm14/apis/angular/README.md

@@ -4,29 +4,29 @@ Angular 21 기반 클라이언트 UI 라이브러리. 폼/리스트/시트/모
 
 ## 사용 트리거 인덱스
 
-- **앱 부트스트랩** — `provideSdAngular`, `SdAngularConfigProvider`, `setupBgTheme`, `SdSystemLogProvider`. 앱 부트스트랩/루트 컴포넌트에서 1회.
-- **테마 (`SdThemeProvider`, `SdThemeSelector`)** — dark/fontSize 토글. `provideSdAngular`가 localStorage 자동 연동.
-- **라우팅/페이지 컨텍스트** — 자세히: [routing.md](./routing.md). `SdRouterLink`, `injectViewTypeSignal`, `setupCanDeactivate` 등.
-- **앱 구조/메뉴/권한** — 자세히: [app-structure.md](./app-structure.md). `SdAppStructureProvider`, `injectPermsSignal`, `SdMenu`.
-- **모달** — 자세히: [modal.md](./modal.md). `SdModalProvider`, `SdModal`, `SdPromptModal`/`SdConfirmModal`, `SdAddressSearchModal`.
-- **토스트** — 자세히: [toast.md](./toast.md). `SdToastProvider`(info/success/warning/danger/notify/try).
-- **버튼류** — 자세히: [buttons.md](./buttons.md). `SdButton`, `SdAnchor`, `SdAdditionalButton`, `SdModalSelectButton`.
-- **입력/폼 컨트롤** — 자세히: [forms.md](./forms.md). `SdForm`, `SdTextfield`/`SdTextarea`/`SdNumpad`/`SdRange`/`SdDateRangePicker`, `SdCheckbox`/`SdSwitch`/`SdCheckboxGroup(Item)`.
-- **드롭다운/셀렉트** — 자세히: [select-dropdown.md](./select-dropdown.md). `SdDropdown(Popup)`, `SdSelect(Item|Button)`.
-- **레이아웃 (사이드바/탑바)** — 자세히: [layout.md](./layout.md). `SdSidebar*`, `SdTopbar*`.
-- **시트(테이블)** — 자세히: [sheet.md](./sheet.md). `SdSheet`, `SdSheetColumn`, `SdSheetColumnCellTemplate`, `SdSheetConfig*`.
-- **CRUD 화면 골격** — 자세히: [crud.md](./crud.md). `SdBaseContainer`, `SdCrudList`, `SdCrudDetail`.
-- **서버 공유 데이터 (`SharedData*` + 선택 컨트롤)** — 자세히: [shared-data.md](./shared-data.md). `SdSharedDataProvider`, `SdSharedDataSelect(Button|List)`, `matchesSearchText`.
-- **선택/확장/정렬 매니저 훅** — 자세히: [selection-managers.md](./selection-managers.md). `useSelectionManager`, `useExpandingManager`, `useSortingManager`.
-- **칸반 보드** — 자세히: [kanban.md](./kanban.md). `SdKanbanBoard`, `SdKanban`, `SdKanbanLane`.
-- **시각 컴포넌트 (라벨/노트/프로그레스/달력/바코드/차트)** — 자세히: [visual.md](./visual.md).
-- **인프라 프로바이더 (서비스 클라이언트/파일 다이얼로그/스토리지/시스템 설정/인쇄)** — 자세히: [infrastructure.md](./infrastructure.md).
-- **`SdBusyContainer` / `SdBusyProvider`** — busy 오버레이. `provideSdAngular`가 라우터 navigation 동안 globalBusyCount 자동 증감.
-- **`SdPermissionTable`** — `SdPermission<TModule>[]` 트리를 `Record<string, boolean>` 모델로 편집하는 권한표.
-- **`SdStatePreset` / `SdStatePresetDef`** — 화면 상태(`state`)를 키별 프리셋으로 저장/복원. `SdSystemConfigProvider` 활용.
-- **`SdTiptapEditor`** — Tiptap 기반 리치 에디터. `value`, `extensions`, `validatorFn`.
-- **유틸 디렉티브/파이프 등** — 인라인 항목 참조.
-- **유틸 타입/함수** — 인라인 항목 참조.
+- **앱 부트스트랩** — 루트 컴포넌트에서 `provideSdAngular`로 zoneless·테마·에러 핸들러·`.capture/.passive/.once` 이벤트 변형·라우터 navigation busy 자동 등록. `SdAngularConfigProvider`(clientName), `setupBgTheme`(body 배경 토글), `SdSystemLogProvider`(severity별 로그 후크). 본문 인라인.
+- **테마** — `SdThemeProvider`(dark/fontSize 신호 + localStorage 자동 영속화), `SdThemeSelector`(토글 UI). 본문 인라인.
+- **라우팅/페이지 컨텍스트** — 페이지 코드(`a.b.c`)·뷰 타입(`page|modal|control`)·새창 navigation·`SdRouterLink`·canDeactivate 헬퍼. 자세히: [routing.md](./routing.md).
+- **앱 구조/메뉴/권한** — 서버 `AppStructureService` 트리를 받아 메뉴/권한 신호로 노출. `SdAppStructureProvider`·`injectPermsSignal`·`SdMenu`/`SdFlatMenu`/`SdPermission`. 자세히: [app-structure.md](./app-structure.md).
+- **모달** — 프로그래밍 `SdModalProvider.showAsync` 또는 선언형 `<sd-modal>`. 내장 `SdPromptModal`/`SdConfirmModal`/`SdAddressSearchModal`. 자세히: [modal.md](./modal.md).
+- **토스트** — `SdToastProvider`로 info/success/warning/danger 전역 알림 + 커스텀 컴포넌트 `notify` + 에러 자동 처리 `try`. 자세히: [toast.md](./toast.md).
+- **버튼류** — 일반 `SdButton`, 링크형 `SdAnchor`, 본문+부가 `SdAdditionalButton`, 모달 검색 선택 `SdModalSelectButton`. 자세히: [buttons.md](./buttons.md).
+- **입력/폼 컨트롤** — `<sd-form>` 안에 텍스트/숫자/날짜/체크박스 류 컨트롤. `SdTextfield`, `SdTextarea`, `SdNumpad`, `SdRange`, `SdDateRangePicker`, `SdCheckbox`/`SdSwitch`/`SdCheckboxGroup(Item)`. 자세히: [forms.md](./forms.md).
+- **드롭다운/셀렉트** — 트리거+팝업 `SdDropdown(Popup)`, 옵션 선택 `SdSelect(Item|Button)`. 자세히: [select-dropdown.md](./select-dropdown.md).
+- **레이아웃 (사이드바/탑바)** — 풀 화면 `<sd-sidebar-container>` 와 상단바 컨테이너. `SdSidebar*`, `SdTopbar*`. 자세히: [layout.md](./layout.md).
+- **시트(테이블)** — 가상 스크롤 데이터 그리드. 컬럼 정의·정렬·페이징·선택·확장 트리·설정 모달 내장. `SdSheet`, `SdSheetColumn`, `SdSheetColumnCellTemplate`, `SdSheetConfigModal`. 자세히: [sheet.md](./sheet.md).
+- **CRUD 화면 골격** — 페이지/모달 공통 컨테이너 + 리스트/디테일 골격. `SdBaseContainer`, `SdCrudList`, `SdCrudDetail`. 자세히: [crud.md](./crud.md).
+- **서버 공유 데이터 (코드성 마스터)** — 부서·거래처 등 키 기반 등록·구독·자동 부분 갱신. `SdSharedDataProvider`, `SdSharedDataSelect(Button|List)`, `matchesSearchText`. 자세히: [shared-data.md](./shared-data.md).
+- **선택/확장/정렬 매니저 훅** — `<sd-sheet>`/`<sd-select>` 내부 로직을 외부 컴포넌트에서 재사용. `useSelectionManager`, `useExpandingManager`, `useSortingManager`. 자세히: [selection-managers.md](./selection-managers.md).
+- **칸반 보드** — 드래그·드롭 카드 보드. `SdKanbanBoard`, `SdKanban`, `SdKanbanLane`. 자세히: [kanban.md](./kanban.md).
+- **시각 컴포넌트** — 라벨 `SdLabel`, 알림 박스 `SdNote`, 진행률 `SdProgress`, 월별 달력 `SdCalendar`, 바코드 `SdBarcode`, ECharts 래퍼 `SdEcharts`. 자세히: [visual.md](./visual.md).
+- **인프라 프로바이더** — 서비스 클라이언트 팩토리 `SdServiceClientFactoryProvider`, 파일 다이얼로그 `SdFileDialogProvider`, localStorage 래퍼 `SdLocalStorageProvider`, 시스템 설정 `SdSystemConfigProvider` + `injectSdSystemConfigResource`, 인쇄/PDF `SdPrintProvider`, 글로벌 에러 핸들러/이벤트 플러그인. 자세히: [infrastructure.md](./infrastructure.md).
+- **`SdBusyContainer` / `SdBusyProvider`** — busy 오버레이 컴포넌트와 전역 busy 카운트. 본문 인라인.
+- **`SdPermissionTable`** — 권한 트리 편집 표. `SdPermission<TModule>[]` 입력 → `Record<string, boolean>` 모델. 본문 인라인.
+- **`SdStatePreset` / `SdStatePresetDef`** — 화면 상태 프리셋 저장/복원. 본문 인라인.
+- **`SdTiptapEditor`** — 리치 텍스트 에디터. 본문 인라인.
+- **유틸 디렉티브/파이프** — 이벤트(`SdResize`/`SdIntersection`/`SdEvents`)·단축키(`SdCommandDirective`)·표시 효과(`SdRipple`/`SdShowEffect`)·검증(`SdInvalid`)·템플릿(`SdTypedTemplate`/`SdItemOfTemplate`)·포맷(`FormatPipe`)·spacer(`SdGap`)·접힘(`SdCollapse`/`SdCollapseIcon`)·탭(`SdTab`/`SdTabItem`)·리스트(`SdList`/`SdListItem`)·페이저(`SdPagination`)·signal 헬퍼(`mark`/`setSafeStyle`/`setupModelHook`). 본문 인라인.
+- **유틸 타입** — `DirectiveInputSignals`/`UndefToOptional`/`WithOptional`/`SelectModalOutputResult`. 본문 인라인.
 
 ## 앱 부트스트랩
 
@@ -36,60 +36,63 @@ bootstrapApplication(AppComponent, {
 });
 ```
 
-- `provideSdAngular({ clientName })`: zoneless CD, NgIcons config, 글로벌 에러 핸들러(`SdGlobalErrorHandlerPlugin`), `SdOptionEventPlugin`(이벤트 `.capture`/`.passive`/`.once`), 테마 dark/fontSize ↔ localStorage 동기화, SwUpdate 폴링, Router navigation 중 `SdBusyProvider.globalBusyCount` 자동 ±1.
+- `provideSdAngular({ clientName })`: zoneless CD, NgIcons config, 글로벌 에러 핸들러(`SdGlobalErrorHandlerPlugin`), `SdOptionEventPlugin`(이벤트 `.capture`/`.passive`/`.once`), 테마 dark/fontSize ↔ localStorage 동기화, SwUpdate 폴링(실패 시 백오프 5분→1시간), Router navigation 중 `SdBusyProvider.globalBusyCount` 자동 ±1.
 - `SdAngularConfigProvider.clientName`: localStorage 키 prefix·service client name 으로 사용. `provideSdAngular` 옵션에서 설정됨.
-- `SdSystemLogProvider.writeFn?`: severity별 로그 후크 등록(서버 전송 등). 자동으로 console에도 출력.
-- `setupBgTheme({ theme?, lightness? })`: 컴포넌트 constructor 내에서 호출. body `--background-color` CSS 변수 토글, 파괴 시 자동 복원.
+- `SdSystemLogProvider.writeFn?: (severity: "error"|"warn"|"log", ...data) => Promise<void> | void`: severity별 로그 후크 등록(서버 전송 등). 호출 시 console에도 항상 출력.
+- `setupBgTheme({ theme?, lightness? })`: 컴포넌트 constructor 내에서 호출. body `--background-color` CSS 변수 토글, destroy 시 자동 복원. `theme: "primary"|"secondary"|"info"|"success"|"warning"|"danger"|"gray"|"blue-gray"`, `lightness: "lightest"|"lighter"` (default `"lightest"`).
 
 ## 테마
 
-- `SdThemeProvider`: `dark = signal<boolean>`, `fontSize = signal<number>` (presets `[12,14,16,20,24,28]`), `increaseFontSize()`/`decreaseFontSize()`. dark면 body에 `sd-theme-dark` 클래스, fontSize는 html `font-size` 적용. `provideSdAngular`가 localStorage 영속화.
-- `SdThemeSelector`: 토글 UI 컴포넌트.
+- `SdThemeProvider`: `dark = signal<boolean>`, `fontSize = signal<number>` (presets `[12,14,16,20,24,28]`), `increaseFontSize()`/`decreaseFontSize()`. dark=true 시 body에 `sd-theme-dark` 클래스, fontSize는 html `font-size` 적용. `provideSdAngular`가 localStorage 영속화.
+- `SdThemeSelector`: dropdown 형 토글 UI (글자 크기 ± 버튼 + dark 스위치). 별도 입력 없음.
 
 ## SdBusyContainer / SdBusyProvider
 
-`<sd-busy-container [busy] [message] [type] [progressPercent]>`. type: `"spinner" | "bar" | "cube"`. `busy=true` 동안 keydown 차단.
-`SdBusyProvider.globalBusyCount = signal(0)`. > 0이면 body 전면 오버레이.
+`<sd-busy-container [busy] [message] [type] [progressPercent]>`. type: `"spinner" | "bar" | "cube"` (default = `SdBusyProvider.type()` = `"bar"`). `busy=true` 동안 keydown 차단.
+
+`SdBusyProvider`:
+- `globalBusyCount = signal(0)`. > 0이면 body 전면 오버레이.
+- `type = signal<SdBusyType>("bar")`: 전역 busy 컨테이너의 기본 type. 변경 시 즉시 반영.
 
 ## SdPermissionTable
 
-`<sd-permission-table [items] [(value)] [disabled]>`. `items: SdPermission<TModule>[]` (`SdAppStructureUtils.getPermissions` 결과), `value: Record<string, boolean>` (코드.use|edit 형식).
+`<sd-permission-table [items] [(value)] [disabled]>`. `items: SdPermission<TModule>[]` (`SdAppStructureUtils.getPermissions` 결과), `value: Record<string, boolean>` (`<fullCode>.use|edit` 형식). 트리 접기/펼치기 + 그룹 일괄 토글.
 
 ## SdStatePreset
 
-`<sd-state-preset [key] [(state)] [size]>`. `state` 를 `SdSystemConfigProvider` 키 `key` 아래 프리셋 배열로 저장/로드. 별 아이콘 클릭 → 이름 입력 모달 → 저장.
+`<sd-state-preset [key] [(state)] [size]>`. `key` 신호 아래 `SdStatePresetDef[]` = `{ name, state }[]` 를 `SdSystemConfigProvider` 에 저장. 별 아이콘 클릭 → 이름 프롬프트 → 추가. 각 프리셋 클릭 시 `state.set(obj.clone(preset.state))`.
 
 ## SdTiptapEditor
 
-`<sd-tiptap-editor [(value)] [disabled] [readonly] [required] [placeholder] [validatorFn] [extensions]>`. value=HTML string. `extensions?: AnyExtension[]` 으로 Tiptap 확장 주입.
+`<sd-tiptap-editor [(value)] [disabled] [readonly] [required] [placeholder] [validatorFn] [extensions]>`. value=HTML string. 기본 extensions: StarterKit + TextStyle + Color + Highlight + TextAlign + Image + Underline. `extensions?: AnyExtension[]` 으로 Tiptap 확장 주입(기본 위에 추가).
 
 ## 유틸 디렉티브/파이프
 
 이벤트·표시 보조용. constructor injection 또는 셀렉터 attach.
 
 - `SdOptionEventPlugin`: `(click.capture)`, `(scroll.passive)`, `(touchmove.capture.passive)`, `(transitionend.once)` 등 `.capture/.passive/.once` 변형 이벤트 바인딩 활성화. `provideSdAngular`로 자동 등록.
-- `SdResizeDirective` (`[sdResize]`): RO 기반 size 변화 emit (`{ heightChanged, widthChanged, target, contentRect }`).
-- `SdIntersectionDirective` (`[sdIntersection]`): IO entry emit.
-- `SdEvents`: 다양한 native event의 `.capture`/`.passive`/`.once` output 디렉티브 (예: `(scroll.passive)`, `(touchstart.passive)`).
-- `SdCommandDirective`: `[sdRefreshCommand]`/`[sdSaveCommand]`/`[sdInsertCommand]` — Ctrl+Alt+L/Ctrl+S/Insert 단축키 emit. 최상위 열린 모달 또는 모달이 없을 때만 처리.
+- `SdResizeDirective` (`[sdResize]`): ResizeObserver 기반 size 변화 emit (`SdResizeEvent { heightChanged, widthChanged, target, contentRect }`). requestAnimationFrame 디바운스.
+- `SdIntersectionDirective` (`[sdIntersection]`): IntersectionObserver entry emit (`SdIntersectionEvent { entry }`).
+- `SdEvents`: 다양한 native event의 `.capture`/`.passive`/`.once` output 디렉티브 (예: `(scroll.passive)`, `(touchstart.passive)`, `(focus.capture)`, `(transitionend.once)`).
+- `SdCommandDirective` (`[sdRefreshCommand]`/`[sdSaveCommand]`/`[sdInsertCommand]`): Ctrl+Alt+L/Ctrl+S/Insert 단축키 emit. 최상위 열린 모달 내부 또는 모달 없는 페이지일 때만 처리.
 - `SdRipple` (`[sdRipple]="bool"`) / `setupRipple(enableFn?)`: pointerdown 시 원형 ripple.
 - `SdShowEffect` (`[sdShowEffect]="bool"` + `[sdShowEffectType]="'l2r'|'t2b'"`) / `setupRevealOnShow`: viewport intersection 시 fade-in.
-- `SdInvalid` (`[sdInvalid]="msg"`) / `setupInvalid(getMsg)`: hidden input의 customValidity 로 form 검증 + 표시 인디케이터.
-- `SdTypedTemplate` (`<ng-template [typed]>`): template context 타입 추론용 (typeToken).
-- `SdItemOfTemplate` (`<ng-template [itemOf]>`, ctx `{ $implicit, item, index, depth }`) — 컬렉션 컴포넌트 항목 템플릿.
-- `FormatPipe` (`{{ v | format:fmt }}`): `DateTime`/`DateOnly`는 `toFormatString(fmt)`, string은 `X` 자리표시(예: `'XXX-XXXX-XXXX'`).
-- `SdGap`: spacer. `height|width|widthEm` 또는 `heightPx|widthPx`. 단위 키: `xxs|xs|sm|default|lg|xl|xxl`.
-- `SdCollapse [open]` / `SdCollapseIcon`: 접힘.
+- `SdInvalid` (`[sdInvalid]="msg"`) / `setupInvalid(getMsg)`: hidden input의 customValidity 로 form 검증 + 좌상단 빨간 점 인디케이터.
+- `SdTypedTemplate` (`<ng-template [typed]="typeToken">`): template context 타입 추론용.
+- `SdItemOfTemplate` (`<ng-template [itemOf]="items">`, ctx `SdItemOfTemplateContext { $implicit, item, index, depth }`) — 컬렉션 컴포넌트(`SdSelect`/`SdCalendar` 등) 항목 템플릿.
+- `FormatPipe` (`{{ v | format:fmt }}`): `DateTime`/`DateOnly`는 `toFormatString(fmt)`, string은 `X` 자리표시(예: `'XXX-XXXX-XXXX'`, `|` 로 다중 길이).
+- `SdGap`: spacer. `height|width` 단위 키(`xxs|xs|sm|default|lg|xl|xxl`), `heightPx|widthPx|widthEm` 픽셀/em. 값 0이면 `display:none`.
+- `SdCollapse [open]` / `SdCollapseIcon [open] [openRotate=90] [icon]`: 접힘 패널/아이콘.
 - `SdTab [(value)]`/`SdTabItem [value]`: 탭.
-- `SdList`/`SdListItem`: 리스트. `SdListItem` `layout: "accordion"|"flat"`, `selectedIcon`, `contentStyle/Class`.
-- `SdPagination [(currentPage)] [totalPageCount] [visiblePageCount=10]`.
+- `SdList [inset]`/`SdListItem [layout="accordion"|"flat"] [open] [selected] [selectedIcon] [readonly] [contentStyle/Class]` + `<ng-template #toolTpl>` (옵션 도구 영역).
+- `SdPagination [(currentPage)] [totalPageCount] [visiblePageCount=10]`. 그룹 단위 페이지 이동.
 - `mark(signal)`: array/object signal의 in-place mutation 후 shallow copy로 trigger.
 - `setSafeStyle(renderer, el, partial)`: renderer.setStyle 일괄.
-- `setupModelHook(model, canFn)`: WritableSignal의 set/update를 `canFn(value) -> boolean | Promise<boolean>`로 가로채기. constructor 내에서 호출.
+- `setupModelHook(model, canFnSignal)`: WritableSignal의 set/update를 `canFn(value) -> boolean | Promise<boolean>`로 가로채기. `canFn` 자체가 `Signal<...>` 형식 (`input<(v)=>...>()` 그대로 전달). constructor 내에서 호출.
 
 ## 유틸 타입/기타
 
-- `DirectiveInputSignals<T>`: 컴포넌트의 InputSignal 프로퍼티만 추출(`{ name: T }`). undefined 필드는 optional.
+- `DirectiveInputSignals<T>`: 컴포넌트의 InputSignal 프로퍼티만 추출(`{ name: T }`). undefined 포함 필드는 optional.
 - `UndefToOptional<T>`: undefined 포함 필드를 optional 로 변환.
 - `WithOptional<T, K>`: 특정 키만 optional 로.
 - `SelectModalOutputResult<TKey> = { selectedKeys: TKey[] }`: 모달 선택 결과.

package/claude/references/sd-simplysm14/apis/angular/buttons.md

@@ -10,7 +10,7 @@
 
 ## `<sd-anchor>`
 
-링크형 클릭 요소. `disabled`, `theme`(`primary|secondary|...|blue-gray`, default `primary`). tabindex 자동.
+링크형 클릭 요소. `disabled`, `theme`(`primary|secondary|...|blue-gray`, default `primary`). 비활성 시 tabindex 제거.
 
 ```html
 <sd-anchor [theme]="'danger'" (click)="del()">삭제</sd-anchor>
@@ -18,7 +18,14 @@
 
 ## `<sd-additional-button>`
 
-본문 + 우측 부가 버튼 슬롯. `size`.
+본문 영역 + 우측 부가 버튼 슬롯(`<sd-anchor>`, `<sd-button>` projection). `size: "sm"|"lg"`, `inset`.
+
+```html
+<sd-additional-button>
+  본문 내용
+  <sd-button (click)="...">+</sd-button>
+</sd-additional-button>
+```
 
 ## `<sd-modal-select-button>`
 
@@ -32,6 +39,8 @@
   [modalOptions]="{ resizable: true }"
   [required]="true"
   [disabled]="false"
+  [size]="'sm'"
+  [inset]="false"
   [searchIcon]="customIcon">
   {{ displayLabel() }}
 </sd-modal-select-button>
@@ -39,4 +48,5 @@
 
 - `SdSelectModal<TKey>` = `SdModalContentDef<SelectModalOutputResult<TKey>>` + `selectMode: InputSignal<"single"|"multi"|undefined>` + `selectedKeys: InputSignal<TKey[]>`.
 - `SdSelectModalInfo<T>` = `SdModalInfo<T, "selectMode"|"selectedKeys">`.
-- erase 아이콘 클릭 시 `value` 초기화(`undefined` 또는 `[]`).
+- value 가 있고 required 가 아니면 좌측에 erase 아이콘 노출 → 클릭 시 초기화(single 은 `undefined`, multi 는 `[]`).
+- 검색 버튼 클릭 → `SdModalProvider.showAsync` 호출, 결과 `{ selectedKeys }` 를 `selectMode` 에 맞춰 `value` 에 반영.

package/claude/references/sd-simplysm14/apis/angular/forms.md

@@ -13,7 +13,7 @@
 
 - 내부에 hidden submit 버튼 자동 삽입(Enter 키 submit 지원).
 - `requestSubmit()` 메서드 노출.
-- invalid 시 reportValidity → `formInvalid` emit.
+- invalid 시 `reportValidity` → `formInvalid` emit, valid 시 `formSubmit` emit.
 
 ## `<sd-textfield<K>>`
 
@@ -25,23 +25,28 @@
 
 `SdTextfieldTypes`: `number→number`, `text|password|color|email|format→string`, `date|month|year→DateOnly`, `datetime|datetime-sec→DateTime`, `time|time-sec→Time`. `sdTextfieldTypes` 배열로 키 목록 enum.
 
-주요 input: `value` (model), `type` (required), `placeholder`, `title`, `inputStyle/Class`, `disabled/readonly/required` (booleanAttribute), `min/max/minlength/maxlength`, `pattern`, `validatorFn(value) => string | undefined` (커스텀 메시지), `format`, `step`, `autocomplete`, `minDigits`, `size`, `theme`.
+주요 input: `value` (model), `type` (required), `placeholder`, `title`, `inputStyle/Class`, `disabled/readonly/required` (booleanAttribute), `min/max/minlength/maxlength`, `pattern`, `validatorFn(value) => string | undefined` (커스텀 메시지), `format`, `step`, `autocomplete`, `useNumberComma` (default `true` — 숫자 표시 시 천단위 콤마), `minDigits` (display 시 최소 자릿수), `size`(`"sm"|"lg"`), `inline`, `inset`, `theme`.
+
+readonly/disabled 상태에서는 `<input>` 비표시(`_contents` div만 노출).
 
 ## `<sd-textarea>`
 
-`[(value)]: string`, `placeholder`, `title`, `minRows=1`, `size`, `validatorFn`, `theme`, `inputStyle/Class`.
+`[(value)]: string`, `placeholder`, `title`, `minRows=1` (행수는 값 줄바꿈 수와 minRows 중 큰 값), `disabled/readonly/required`, `inline`, `inset`, `size`, `validatorFn`, `theme`, `inputStyle/Class`.
 
 ## `<sd-numpad>`
 
-숫자 키패드. `[(value)]: number`, `placeholder`.
+숫자 키패드. `[(value)]: number`, `text = signal<string|undefined>` (내부 표시값), `placeholder`, `required`, `inputDisabled` (입력란만 비활성), `useEnterButton` (ENT 버튼 노출), `useMinusButton` (- 버튼 노출), `(enterButtonClick)` 출력.
 
 ## `<sd-range<K>>`
 
-`type: K` (TextfieldTypes 키), `[(from)]`, `[(to)]: SdTextfieldTypes[K]`, `inputStyle`.
+`type: K` (TextfieldTypes 키), `[(from)]`, `[(to)]: SdTextfieldTypes[K]`, `required`, `disabled`, `inputStyle`. `to.min`은 `from` 으로 강제.
 
 ## `<sd-date-range-picker>`
 
-`[(periodType)]: "일"|"월"|"범위" = "범위"`, `[(from)]: DateOnly`, `[(to)]: DateOnly`.
+`[(periodType)]: "일"|"월"|"범위" = "범위"`, `[(from)]: DateOnly`, `[(to)]: DateOnly`, `required`.
+- `"일"`: 단일 date 입력. `to`는 `from` 따라감.
+- `"월"`: month 입력. `from`은 1일, `to`는 말일 자동 설정.
+- `"범위"`: from~to date 양쪽 입력. from > to 시 to를 from으로 보정.
 
 ## `<sd-checkbox>` / `<sd-switch>`
 
@@ -50,14 +55,20 @@
 <sd-switch [(value)]="enabled" [size]="'sm'" />
 ```
 
-`value: boolean` (model), `canChangeFn(value) => boolean | Promise<boolean>` — false 면 변경 차단. `radio` (checkbox만), `disabled`, `size`, `inline`, `inset`, `theme`, `contentStyle` (checkbox).
+`value: boolean` (model), `canChangeFn(value) => boolean | Promise<boolean>` — false 면 변경 차단 (`setupModelHook` 사용). 공통: `disabled`, `size`, `inline`, `inset`, `theme`. checkbox 추가: `radio` (radio 모드 — 다시 클릭해도 false 안 됨), `icon` (체크 아이콘 변경, default `tablerCheck`), `contentStyle`, `theme` 에 `"white"` 옵션 추가(시트 헤더용).
 
 ## `<sd-checkbox-group<T>>` / `<sd-checkbox-group-item<T>>`
 
-`<sd-checkbox-group [(value)]="selected"> <sd-checkbox-group-item [value]="opt">{{opt}}</sd-checkbox-group-item> ... </sd-checkbox-group>`. value: `T[]` (다중).
+```html
+<sd-checkbox-group [(value)]="selected">
+  <sd-checkbox-group-item [value]="opt" *ngFor="let opt of options">{{ opt }}</sd-checkbox-group-item>
+</sd-checkbox-group>
+```
+
+`SdCheckboxGroup`: `value: T[]` (model, default `[]`), `disabled`. `SdCheckboxGroupItem`: `value: T` (required), `inline`.
 
 ## 검증
 
-- 컨트롤 내부에서 `setupInvalid(getMessage)` 사용 (cf. directives). 빈 문자열이면 valid.
+- 컨트롤 내부에서 `setupInvalid(getMessage)` 사용 — 빈 문자열이면 valid, 그 외 메시지는 invalid 사유. 좌상단 빨간 점 인디케이터.
 - `validatorFn` 은 컨트롤 입력값을 검사해 메시지 반환.
 - `SdForm` submit 시 자동으로 reportValidity 호출 + invalid 인디케이터 표시.

package/claude/references/sd-simplysm14/apis/angular/kanban.md

@@ -5,6 +5,7 @@
 ```html
 <sd-kanban-board [(selectedValues)]="selected" (drop)="onDrop($event)">
   <sd-kanban-lane [value]="laneA" [busy]="loading">
+    <ng-template #titleTpl>레인 A</ng-template>
     <sd-kanban [value]="card" [draggable]="true" [selectable]="true">{{ card.title }}</sd-kanban>
   </sd-kanban-lane>
 </sd-kanban-board>
@@ -14,15 +15,17 @@
 
 - `selectedValues = model<T[]>([])`.
 - `drop = output<SdKanbanBoardDropInfo<L, T>>` (`{ sourceKanbanValue?, targetLaneValue?, targetKanbanValue? }`).
-- `dragKanban = signal<SdKanbanDragRef | undefined>` — 자식이 드래그 시작 시 설정.
+- `dragKanban = signal<SdKanbanDragRef | undefined>` — 자식이 드래그 시작 시 설정. document `dragend` 시 자동 해제.
 
 ## `<sd-kanban-lane<L, T>>`
 
-`value: L`, `busy`, `useCollapse`, `collapse` (model). drop target 구현.
+`value: L`, `busy`, `useCollapse`, `collapse` (model, default `false`). drop target 구현. `useCollapse=true` 면 토글 아이콘 노출. 자식 `kanbanControls.filter(selectable)` 가 있으면 전체선택 체크박스 노출.
+
+content templates: `<ng-template #titleTpl>` (헤더 영역), `<ng-template #toolTpl>` (전체선택 우측 도구 영역).
 
 ## `<sd-kanban<L, T>>`
 
-`value: T`, `draggable`, `selectable`, `contentClass`. drag ref + drop target 둘 다 구현(카드 위에 드롭 가능).
+`value: T`, `draggable`, `selectable`, `contentClass`. drag ref + drop target 둘 다 구현(카드 위에 드롭 가능). Shift+클릭 시 `selectable=true` 인 경우 `selectedValues` 토글.
 
 ## 타입
 

package/claude/references/sd-simplysm14/apis/angular/layout.md

@@ -5,37 +5,43 @@
 ```html
 <sd-sidebar-container>
   <sd-sidebar>
-    <sd-sidebar-user [userMenu]="userMenu">유저영역</sd-sidebar-user>
+    <sd-sidebar-user [userMenu]="userMenu">유저영역 컨텐츠</sd-sidebar-user>
     <sd-sidebar-menu [menus]="menus" [layout]="'accordion'" [getMenuIsSelectedFn]="isSel" />
   </sd-sidebar>
   <ng-content />
 </sd-sidebar-container>
 ```
 
-- `SdSidebarContainer`: `toggle = signal(false)`. Router NavigationStart 시 자동 false.
-- `SdSidebar`: 부모 container의 toggle 추종.
-- `SdSidebarMenu`: `menus: SdMenu[]`, `layout: "accordion"|"flat"`, `getMenuIsSelectedFn?`.
-- `SdSidebarUser`: `userMenu?: SdSidebarUserMenu`.
+- `SdSidebarContainer`: `toggle = signal(false)`. 데스크탑은 토글 시 본문 left padding 제거, 모바일(`max-width:520px`)에서는 사이드바가 슬라이드. Router `NavigationStart` 이벤트에 자동 false (페이지 이동 시 자동 닫힘).
+- `SdSidebar`: 부모 container의 toggle 추종. content projection.
+- `SdSidebarMenu`: `menus: SdMenu[]`, `layout: "accordion"|"flat"` (미지정 시 `menus.length <= 3` 이면 `"flat"`, 아니면 `"accordion"` 자동), `getMenuIsSelectedFn?: (menu) => boolean`. 자식 메뉴는 항상 `"accordion"`. `menu.url != null` 이면 클릭 시 새창 open.
+- `SdSidebarUser`: `userMenu?: SdSidebarUserMenu` + 상단 영역 content projection. userMenu.title 클릭 시 메뉴 항목 펼침/접기.
 
 ```typescript
-interface SdSidebarUserMenu { /* see source */ }
+interface SdSidebarUserMenu {
+  title: string;
+  menus: { title: string; onClick: () => void }[];
+}
 ```
 
 ## 탑바
 
 ```html
 <sd-topbar-container>
-  <sd-topbar [sidebarContainer]="sc">
+  <sd-topbar>
+    <h4>{{ title }}</h4>
     <sd-topbar-menu [menus]="menus" />
-    <sd-topbar-user [menus]="userMenus" />
+    <sd-topbar-user [menus]="userMenus">유저표시</sd-topbar-user>
   </sd-topbar>
+  <ng-content />
 </sd-topbar-container>
 ```
 
-- `SdTopbar`: `sidebarContainer?: SdSidebarContainer` 입력(미지정 시 inject 시도). 햄버거 버튼이 `sc.toggle` 토글.
-- `SdTopbarMenu`: `menus: SdMenu[]`, `getMenuIsSelectedFn?`.
-- `SdTopbarUser`: `menus: SdTopbarUserMenu[]` (required).
+- `SdTopbarContainer`: flex-column 100% 컨테이너.
+- `SdTopbar`: `sidebarContainer?: SdSidebarContainer` 입력(미지정 시 inject 시도). 사이드바 있으면 햄버거 버튼 노출 → 클릭 시 `sc.toggle` 토글.
+- `SdTopbarMenu`: `menus: SdMenu[]`, `getMenuIsSelectedFn?`. 각 최상위 menu는 dropdown 으로 노출. leaf 클릭 후 dropdown 자동 닫힘.
+- `SdTopbarUser`: `menus: SdTopbarUserMenu[]` (required, `{ title, onClick }[]`) + 트리거 영역 content projection. dropdown 으로 menus 표시, 클릭 후 자동 close.
 
 ## 메뉴 데이터
 
-`SdMenu` (`./app-structure.md` 참조)을 그대로 입력. 선택 상태는 `getIsMenuSelected(menu, fullPageCode, customFn?)` 또는 `getMenuIsSelectedFn` 으로.
+`SdMenu` (`./app-structure.md` 참조)을 그대로 입력. 선택 상태는 `getIsMenuSelected(menu, fullPageCode, customFn?)` 또는 `getMenuIsSelectedFn` 으로. leaf 메뉴는 `getMenuRouterLinkOption(menu)` 으로 `[sdRouterLink]` 옵션 자동 생성.

package/claude/references/sd-simplysm14/apis/angular/modal.md

@@ -45,8 +45,8 @@ interface SdModalContentDef<O> {
 
 ```typescript
 const am = inject(SdActivatedModalProvider, { optional: true });
-am?.modalComponent();    // SdModal 인스턴스 (title() 등)
-am?.contentComponent();  // 컨텐츠 인스턴스
+am?.modalComponent();    // signal<SdModal> (title() 등)
+am?.contentComponent();  // signal<T> 컨텐츠 인스턴스
 am.canDeactivateFn = () => isClean();   // 닫기 차단 (false 반환 시)
 ```
 

package/claude/references/sd-simplysm14/apis/angular/routing.md

@@ -5,11 +5,12 @@ Angular Router 위에 페이지 코드(`a.b.c` 형식)·뷰 타입·새창 네
 ## `SdRouterLink` 디렉티브
 
 ```html
-<a [sdRouterLink]="{ link: '/home/order/list', params: { id }, queryParams, outletName, window: { width, height } }">go</a>
+<a [sdRouterLink]="{ link: '/home/order/list', params: { id }, queryParams, outletName, window: { width: 800, height: 600 } }">go</a>
 ```
 
-- 일반 클릭 → `router.navigate`. Ctrl/Shift 클릭 또는 새창 모드(`isWindow`)일 때 → `SdNavigateWindowProvider.open` 으로 새 창. Alt+click 무시.
+- 일반 클릭 → `router.navigate`. Ctrl/Shift 클릭 또는 현재가 새창 컨텍스트(`SdNavigateWindowProvider.isWindow`)일 때 → `SdNavigateWindowProvider.open` 으로 새 창. Alt+click 무시.
 - `outletName` 지정 시 named outlet 으로 navigate.
+- `window: { width, height }` 옵션은 isWindow 컨텍스트에서 새 창 features 로만 사용 (Ctrl/Shift 새창에는 미적용).
 
 ## `SdNavigateWindowProvider`
 

package/claude/references/sd-simplysm14/apis/angular/selection-managers.md

@@ -15,12 +15,13 @@ const sm = useSelectionManager({
 sm.hasSelectable; sm.isAllSelected;
 sm.getSelectable(item);    // true | string(reason) | undefined
 sm.select(item); sm.deselect(item); sm.toggle(item); sm.toggleAll();
-sm.isSelected(item); sm.getCanChangeFn(item);
+sm.isSelected(item); sm.getCanChangeFn(item);   // () => boolean (체크박스 canChangeFn 으로 직결)
 ```
 
 - `single`이면 select 시 기존 키 대체. `multi` 면 추가.
 - 키 비교는 `obj.equal` (`@simplysm/core-common`).
 - `trackByFn` 반환이 `null`이면 선택 불가.
+- `hasSelectable`은 `selectMode != null` 여부 (선택 가능 모드인지). 선택 가능한 아이템 존재 여부는 `isAllSelected` 로직에서 자동 처리.
 
 ## `useExpandingManager<T>(binding)`
 

package/claude/references/sd-simplysm14/apis/angular/sheet.md

@@ -25,7 +25,7 @@
 
 ## `<sd-sheet<TItem>>` 입력/출력
 
-- inputs: `key`, `items`, `trackByFn`, `selectMode`, `autoSelect: "click"|"focus"`, `getItemSelectableFn`, `getChildrenFn` (트리), `useAutoSort`, `visiblePageCount=10`, `totalPageCount`, `itemsPerPage`, `focusMode: "row"|"cell" = "cell"`, `inset`, `contentStyle`, `getItemCellClassFn`, `getItemCellStyleFn`, `hideConfigBar`, `columnControlsInput` (외부 정의된 컬럼 추가).
+- inputs: `key`, `items`, `trackByFn`, `selectMode`, `autoSelect: "click"|"focus"`, `getItemSelectableFn`, `getChildrenFn` (트리), `useAutoSort`, `visiblePageCount=10`, `totalPageCount`, `itemsPerPage`, `focusMode: "row"|"cell" = "cell"`, `inset`, `contentStyle`, `getItemCellClassFn`, `getItemCellStyleFn`, `hideConfigBar`, `columnControlsInput: readonly SdSheetColumn[]` (외부 정의된 컬럼 추가, `<sd-sheet-column>` 자식 + 이 입력을 합쳐 처리).
 - outputs: `itemKeydown: SdSheetItemKeydownEventParam<T> { item, event }`, `cellKeydown: SdSheetCellKeydownEventParam<T> { item, key, event }`.
 - models: `selectedKeys: unknown[]`, `expandedItems: TItem[]`, `sorts: SortingDef[]`, `currentPage: number`.
 - `key` 지정 시 설정 모달(`SdSheetConfigModal`)로 너비/숨김/고정/순서를 `SdSystemConfigProvider`에 영속화.

package/claude/references/sd-simplysm14/apis/angular/visual.md

@@ -4,31 +4,46 @@
 
 ## `<sd-label>`
 
-배지 형 라벨. `theme`(테마 컬러), `color` (커스텀), `clickable`. content projection.
+배지 형 라벨. `theme`(테마 컬러), `color` (커스텀 background), `clickable`. content projection.
 
 ## `<sd-note>`
 
-알림 박스 형. `theme`, `size`, `inset`. content projection.
+알림 박스 형. `theme`, `size: "sm"|"lg"`, `inset`. content projection.
 
 ## `<sd-progress>`
 
 ```html
-<sd-progress [theme]="'primary'" [value]="60" [size]="'sm'" [inset]="false" />
+<sd-progress [theme]="'primary'" [value]="0.6" [size]="'sm'" [inset]="false" />
 ```
 
-`theme` (required), `value: number` (0-100, required), `size`, `inset`.
+`theme` (required), `value: number` (required, **0~1 비율**), `size`, `inset`. 표시 텍스트는 `value | percent: "1.0-2"`, 진행바 폭은 `value*100%` (0~100 클램프).
 
 ## `<sd-calendar<T>>`
 
-월별 달력 렌더. 
+월별 달력 렌더. 6행 × 7열 고정. `<ng-template itemOf>` 로 각 셀의 아이템 렌더.
 
-- 필수: `items: T[]`, `getItemDateFn: (item, idx) => DateOnly`.
+```html
+<sd-calendar [items]="events" [getItemDateFn]="byDate" [yearMonth]="curMonth">
+  <ng-template [itemOf]="events" let-item="item">
+    <div>{{ item.title }}</div>
+  </ng-template>
+</sd-calendar>
+```
+
+- 필수 input: `items: T[]`, `getItemDateFn: (item, idx) => DateOnly`.
 - `yearMonth = input(new DateOnly().setDay(1))` (해당 월).
 - `weekStartDay = 0`, `minDaysInFirstWeek = 1`.
+- 필수 content: `<ng-template [itemOf]="items">` (`SdItemOfTemplate`, ctx: `$implicit/item/index/depth`).
 
 ## `<sd-barcode>`
 
-`bwip-js` 래퍼. `type: BarcodeType` (required), `value: string`. `BarcodeType` 은 bwip-js 지원 심볼로지 union (`code128`, `qrcode`, `ean13`, ... — `sd-barcode.ts` 참조).
+`bwip-js` 래퍼. `type: BarcodeType` (required), `value: string`. `BarcodeType` 은 bwip-js 지원 심볼로지 union (`code128`, `qrcode`, `ean13`, ... — 전체 목록은 `sd-barcode.ts` 참조).
+
+```html
+<sd-barcode [type]="'qrcode'" [value]="data" />
+```
+
+내부적으로 `bwipjs.toSVG`로 생성 후 `bypassSecurityTrustHtml`. value 빈 문자열/렌더 실패 시 빈 출력.
 
 ## `<sd-echarts>`
 
@@ -38,4 +53,7 @@ ECharts 5/6 래퍼.
 <sd-echarts [option]="option" [notMerge]="false" [loading]="false" />
 ```
 
-`option: echarts.EChartsOption` (required).
+- `option: echarts.EChartsOption` (required) — 변경 시 `chart.setOption(option, { notMerge })`.
+- `notMerge` (default `false`).
+- `loading` (default `false`) — `showLoading`/`hideLoading` 토글.
+- `hostDirectives: SdResizeDirective` 로 호스트 리사이즈 감지 → `chart.resize()`. renderer `"svg"` 고정.

package/claude/references/sd-simplysm14/apis/capacitor-plugin-file-system/README.md

@@ -19,7 +19,7 @@ await FileSystem.requestPermissions(): Promise<void>   // Android 11+: 설정
 
 // 경로/URI
 await FileSystem.getStoragePath(type: StorageType): Promise<string>
-await FileSystem.getUri(filePath: string): Promise<string>   // FileProvider URI
+await FileSystem.getUri(filePath: string): Promise<string>   // 네이티브: FileProvider URI / Web: Blob URL (사용 후 `URL.revokeObjectURL` 필수)
 
 // 디렉토리
 await FileSystem.readdir(dirPath: string): Promise<FileInfo[]>

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

@@ -6,14 +6,45 @@
 
 ## 사용 트리거 인덱스
 
-- **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` 확장:
+
+- **`findAll`** — `el` 하위에서 선택자 일치 요소 전부 배열로 받을 때.
+- **`findFirst`** — `el` 하위에서 선택자 일치 첫 요소만 받을 때 (`querySelector` 의 `null` 대신 `undefined`).
+- **`prependChild`** — 자식 목록의 맨 앞으로 삽입할 때.
+- **`getParents`** — 가까운 부모부터 위로 거슬러 올라가는 조상 배열이 필요할 때.
+- **`isOffsetElement`** — 어떤 요소가 자식 absolute 의 기준이 되는지(`position: relative/absolute/fixed/sticky`) 판정할 때.
+- **`isVisible`** — 화면에 실제로 보이는지(클라이언트 영역 + `visibility` + `opacity`) 판정할 때.
+
+포커스/탭 이동 — `Element` 확장:
+
+- **`findTabbableParent`** — 현재 요소를 감싸는 가장 가까운 tabbable 부모를 찾을 때 (모달·툴팁의 포커스 트랩 호스트 추적).
+- **`findFirstTabbableChild`** — 컨테이너에 진입했을 때 처음 포커스할 자식을 찾을 때.
+
+레이아웃/스크롤 — `HTMLElement` 확장:
+
+- **`repaint`** — 스타일 변경 후 즉시 동기 reflow 가 필요할 때.
+- **`getRelativeOffset`** — 드롭다운/팝업을 부모 기준 absolute 좌표로 띄울 때 (스크롤·border·transform 보정 포함).
+- **`scrollIntoViewIfNeeded`** — 고정 헤더/컬럼에 가려진 셀을 위/왼쪽으로만 보정 스크롤할 때.
+
+클립보드/측정 헬퍼:
+
+- **`copyElement`** — `<el @copy>` 이벤트 핸들러로 내부 첫 input/textarea 값을 클립보드로 보낼 때.
+- **`pasteToElement`** — `<el @paste>` 이벤트 핸들러로 클립보드 값을 내부 첫 input/textarea 에 전체 교체할 때.
+- **`getBounds`** / **`ElementBounds`** — 다수 요소의 뷰포트 경계를 `IntersectionObserver` 로 한 번에 측정할 때 (입력 순서 유지·타임아웃 보장).
+
+파일 다이얼로그/다운로드:
+
+- **`openFileDialog`** — 사용자에게 파일 선택 UI 를 띄워 `File[]` 을 받을 때 (취소·빈 선택은 `undefined`).
+- **`downloadBlob`** — 메모리 상의 `Blob` 을 사용자 다운로드로 흘려보낼 때 (파일명 sanitize).
+
+진행률 fetch:
+
+- **`fetchUrlBytes`** / **`DownloadProgress`** — 큰 바이너리를 `Uint8Array` 로 받으며 진행률 콜백을 받을 때.
+
+IndexedDB:
+
+- **`IndexedDbStore`** / **`StoreConfig`** — 브라우저 영속 키/값 저장소가 필요할 때 (트랜잭션·재진입 안전 `open`).
+- **`IndexedDbVirtualFs`** / **`VirtualFsEntry`** — 위 저장소 위에 경로(`/a/b/c`) 기반 파일/디렉토리 트리를 올릴 때.
 
 ## DOM 탐색/가시성 — `Element` 확장
 

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

@@ -4,15 +4,52 @@
 
 ## 사용 트리거 인덱스
 
-- **에러 클래스** — 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>` (생성자 타입).
+- **에러 클래스** — throw 시 트리 메시지/원인 체인 필요할 때. (자세히: 아래 [에러 클래스](#에러-클래스))
+  - `SdError` — 일반 에러 (cause 체인, "상위 => 하위" 메시지)
+  - `ArgumentError` — 인자 검증 실패 (인자 객체를 YAML 로 메시지에 첨부)
+  - `NotImplementedError` — 미구현 분기/추상 메서드
+  - `TimeoutError` — 대기 시간 초과 (`wait.until` 에서 자동 throw)
+- **날짜·시간·UUID·캐시 타입** (자세히: [types.md](./types.md))
+  - `DateTime` — 불변 날짜+시간 (밀리초 정밀도, 로컬 타임존). 변환·산술·포맷.
+  - `DateOnly` — 불변 날짜만 (`yyyy-MM-dd`). ISO 8601 주차(`getWeekSeqOfYear`/`Month`).
+  - `Time` — 불변 시간만 (`HH:mm:ss.fff`, 24h 순환).
+  - `Uuid` — UUID v4 (`Uuid.generate()`), bytes 변환.
+  - `LazyGcMap` — 마지막 접근 후 N ms 만료 LRU Map. **`dispose()` 필수**.
+- **큐·이벤트 features** (자세히: [features.md](./features.md))
+  - `EventEmitter<TEvents>` — 타입 안전 이벤트 (브라우저·Node 공용).
+  - `DebounceQueue` — 연속 호출 중 마지막만 실행 (입력 자동완성·일괄 상태 변경).
+  - `SerialQueue` — 순차 실행 (작업 사이 gap 옵션, 에러 발생 후에도 계속 실행).
+- **유틸리티 네임스페이스** (자세히: [utils.md](./utils.md))
+  - `obj` — 객체 깊은 복사/비교/병합(`clone`/`equal`/`merge`), 3-way merge, `omit`/`pick`/`map`, 체인 경로(`"a.b[0].c"`) get/set/delete, `unflatten`, `clearUndefined`.
+  - `str` — 한글 조사(`getKoreanSuffix`), 전각→반각(`replaceFullWidth`), case 변환(`toPascalCase`/`toCamelCase`/`toKebabCase`/`toSnakeCase`), `isNullOrEmpty`, `insert`.
+  - `num` — 비숫자 섞인 문자열 파싱(`parseInt`/`parseFloat`/`parseRoundedInt`), `isNullOrEmpty`(0 포함 타입 가드), 천 단위 + 소수점 포맷(`format`).
+  - `bytes` — `Uint8Array` 결합(`concat`), hex/base64 인코딩·디코딩.
+  - `path` — POSIX 경로 join/basename/extname (브라우저용, 슬래시 전용).
+  - `json` — 커스텀 타입(Date/DateTime/DateOnly/Time/Uuid/Set/Map/Error/Uint8Array) 마커 직렬화 `stringify`/`parse`, null→undefined 복원.
+  - `xml` — fast-xml-parser 래퍼 `parse`/`stringify`, `stripTagPrefix` 옵션.
+  - `wait` — `wait.time(ms)`, `wait.until(cond, interval, maxCount)` (초과 시 `TimeoutError`).
+  - `transfer` — Worker postMessage 용 `encode`/`decode`, `Uint8Array.buffer` zero-copy transferList.
+  - `err` — 미지의 에러를 메시지 문자열로(`err.message`).
+  - `dt` — date-format 저수준 `format`/`normalizeMonth`/`convert12To24` (`DateTime`/`DateOnly`/`Time` 내부용, 직접 사용 드묾).
+  - `primitive` — 런타임 값 타입 추론(`primitive.typeStr`) → `PrimitiveTypeStr`.
+- **Array/Set/Map 전역 확장 메서드** — `index.ts` import 시 자동 적용. (자세히: [extensions.md](./extensions.md))
+  - Array 조회: `.single()` (0/1개 단언), `.first()`/`.last()` (조건부 find), `.filterExists()` (null 제거), `.ofType()`.
+  - Array 비동기: `.filterAsync()`/`.mapAsync()`/`.mapManyAsync()` (순차), `.parallelAsync()` (`Promise.all`).
+  - Array 변환: `.groupBy()`, `.toMap()`, `.toArrayMap()`, `.toSetMap()`, `.toObject()`, `.toTree("id", "parentId")`.
+  - Array 중복·정렬: `.distinct({ keyFn })`, `.orderBy()`/`.orderByDesc()`, `.shuffle()`.
+  - Array 비교·병합: `.diffs(target, { keys })` (INSERT/DELETE/UPDATE), `.oneWayDiffs()`, `.merge()`.
+  - Array 집계: `.sum()`, `.min()`, `.max()`.
+  - Array mutable: `.distinctThis()`, `.orderByThis()`, `.insert()`, `.remove()`, `.toggle()`, `.clear()`.
+  - Set: `.adds(...)`, `.toggle(value, "add"|"del"?)`.
+  - Map: `.getOrCreate(key, defaultOrFactory)`, `.update(key, (v) => newV)`.
+- **환경변수** — `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()`** 필수. (자세히: 아래 [ZIP 처리](#zip-처리))
+- **공통 타입** (자세히: 아래 [공통 타입](#공통-타입))
+  - `Bytes` — `Uint8Array` 별칭 (Node `Buffer` 대체).
+  - `PrimitiveTypeMap`/`PrimitiveTypeStr`/`PrimitiveType` — string/number/boolean/DateTime/DateOnly/Time/Uuid/Bytes 매핑 (orm-common 공유).
+  - `DeepPartial<T>` — 재귀 optional (원시 타입은 그대로).
+  - `Type<T>` — 클래스 생성자 타입 (DI·팩토리 패턴).
 
 ## 에러 클래스
 
@@ -51,3 +88,44 @@ const code = ts`
 ```
 
 모두 동일 함수, IDE 하이라이팅 차별화 목적.
+
+## ZIP 처리
+
+```typescript
+import { ZipArchive } from "@simplysm/core-common";
+
+// 읽기
+const archive = new ZipArchive(zipBytes);   // Blob 또는 Uint8Array
+try {
+  const content = await archive.get("file.txt");           // Bytes | undefined
+  const exists = await archive.exists("file.txt");         // boolean
+  const all = await archive.extractAll(onProgress?);       // Map<fileName, Bytes|undefined>
+} finally {
+  await archive.close();                                   // 필수
+}
+
+// 쓰기
+const archive = new ZipArchive();
+archive.write("file.txt", bytes);
+const zipBytes = await archive.compress();    // 내부적으로 extractAll → 전체 메모리 로드
+await archive.close();
+```
+
+`extractAll` 진행률 콜백: `{ fileName, totalSize, extractedSize }`. `compress()` 는 전체 파일을 메모리에 로드하므로 대용량 ZIP 주의.
+
+## 공통 타입
+
+```typescript
+type Bytes = Uint8Array;                          // Buffer 대체
+
+type PrimitiveTypeMap = {                          // orm-common 공유
+  string: string; number: number; boolean: boolean;
+  DateTime: DateTime; DateOnly: DateOnly; Time: Time;
+  Uuid: Uuid; Bytes: Bytes;
+};
+type PrimitiveTypeStr = keyof PrimitiveTypeMap;
+type PrimitiveType = PrimitiveTypeMap[PrimitiveTypeStr] | undefined;
+
+type DeepPartial<T>;                              // 재귀 optional, 원시 타입 유지
+interface Type<T> extends Function { new (...args: unknown[]): T; }
+```

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

@@ -8,5 +8,14 @@ Node.js 전용 유틸·기능 묶음. 파일 IO/glob, 경로 변환, 자식 프
 - **`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)
+- **consola 셋업** — Node 앱 진입점에서 로깅 환경(콘솔/파일) 구성. 자세히: [consola.md](./consola.md)
+  - **`setupConsola`** — 진입점 1회 호출. dev/prod·`SD_DEBUG`·`cli` 조합으로 리포터 자동 구성.
+  - **`PrettyReporter`** — 색상·아이콘·tag·stack/cause 정리 포함 콘솔 출력 리포터.
+  - **`createFileReporter`** — `<cwd>/.logs/app.<날짜>.log` JSON 회전 + 보존 기간 정리.
+  - **`withMaxLevel`** — 기존 리포터에 level 상한 필터 씌우기 (dev 콘솔에서 debug 가리기 등).
+- **Worker 래퍼** — worker_threads 위 타입 안전 RPC (메서드 호출 + 이벤트 + 워커 stdout 메인 전달). 자세히: [worker.md](./worker.md)
+  - **`Worker.create`** — 메인 측. 워커 파일을 띄우고 메서드 직접 호출 가능한 Proxy 반환.
+  - **`createWorker`** — 워커 측. `methods` 등록 + `send(event, data)` 로 이벤트 발행. `export default` 필수.
+  - **`WorkerProxy<TModule>`** — `Worker.create` 반환 타입. 워커 모듈 타입 추론에 사용.
+  - **`WorkerModule`** — 워커 default export 의 구조 인터페이스 (`__methods`/`__events`). 직접 구현 불필요.
+  - **`PromisifyMethods<T>`** — 메서드 반환을 `Promise<Awaited<R>>` 로 감싸는 매핑 타입. `WorkerProxy` 내부 사용.

package/claude/references/sd-simplysm14/apis/excel/README.md

@@ -4,11 +4,25 @@ OOXML(xlsx) 워크북을 lazy-load 로 읽고 쓰는 클래스 묶음. ZIP 내
 
 ## 사용 트리거 인덱스
 - **`ExcelWorkbook`** — xlsx 바이트/Blob 을 열거나 새 워크북을 만들 때. 사용 후 `close()` 필수.
-- **`ExcelWorksheet`** — 시트 단위로 셀/행/열 접근, 데이터테이블 입출력, 틀 고정/줌, 조건부 서식, 이미지 삽입.
-- **`ExcelCell` / `ExcelRow` / `ExcelCol`** — 단일 셀 값·수식·스타일·병합, 행/열 전체 셀 일괄 접근, 열 너비.
+- **`ExcelWorkbook.setDefaultStyle`** — 워크북 전역(폰트·정렬·numFmt 등) 셀 표준을 한번에 적용.
+- **`ExcelWorksheet`** — 시트 단위 셀 접근의 진입점. 이름·범위 조회.
+- **`getDataTable` / `setDataMatrix` / `setRecords`** — 시트와 레코드 배열(또는 2D 매트릭스) 간 입출력.
+- **`copyCell` / `copyRow` / `copyCellStyle` / `copyRowStyle` / `insertCopyRow`** — 셀/행 복제·삽입(템플릿 시트 채울 때).
+- **`setZoom` / `freezeAt`** — 시트 뷰 보기 설정(확대·틀 고정).
+- **`setTabColor`** — 시트 탭 색 ARGB 지정.
+- **`addConditionalFormat`** — 셀/범위에 조건부 서식 규칙 적용.
+- **`addImage`** — 시트에 이미지(png/jpg 등) 삽입.
+- **`ExcelCell`** — 단일 셀의 값·수식·스타일·병합.
+- **`ExcelRow`** — 행 단위 셀 일괄 접근.
+- **`ExcelCol`** — 열 단위 셀 접근 + 열 너비 설정.
 - **`ExcelWrapper`** — Zod 스키마로 헤더·타입을 정의해 레코드 배열로 read/write.
 - **`ExcelUtils`** — `"A1"`↔좌표, 범위 주소, Excel 직렬 날짜 ↔ 타임스탬프, numFmt 변환.
-- **타입 (`ExcelValueType`, `ExcelStyleOptions`, `ExcelFont`, `ExcelConditionalRule` 등)** — 입력 옵션·반환값 정의.
+- **`ExcelValueType`** — 셀에 넣고 뺄 수 있는 값의 union (number/string/boolean/DateOnly/DateTime/Time/undefined).
+- **`ExcelStyleOptions`** — `setStyle` / `setDefaultStyle` 입력 옵션 (배경·테두리·정렬·numFmt·폰트).
+- **`ExcelFont`** — `ExcelStyleOptions.font` 의 폰트 속성(크기·family·bold·italic·underline·color·strike).
+- **`ExcelConditionalRule` / `ExcelConditionalRuleStyle`** — `addConditionalFormat` 의 규칙·강조 스타일 타입.
+- **`ExcelAddressPoint` / `ExcelAddressRangePoint`** — 0 기반 좌표 / 범위 좌표.
+- **`ExcelNumberFormat` / `ExcelBorderPosition` / `ExcelHorizontalAlign` / `ExcelVerticalAlign` / `ExcelFontUnderline`** — 스타일 옵션의 enum literal 들.
 
 ## ExcelWorkbook
 ```typescript

package/claude/references/sd-simplysm14/apis/lint/README.md

@@ -6,6 +6,15 @@ Simplysm 컨벤션용 ESLint 플러그인 패키지. 커스텀 규칙 묶음(`./
 
 - **`./eslint-recommended` (default export)** — 프로젝트 `eslint.config.{js,mjs,cjs}` 에서 그대로 spread 해 simplysm 표준 lint 규칙을 적용할 때.
 - **`./eslint-plugin` (default export)** — recommended 를 사용하지 않고 개별 규칙만 골라 쓰거나, 다른 flat config 에서 `@simplysm/<rule>` 로 참조할 때.
+  - **`ng-no-async-effect`** — Angular `effect()` 콜백을 async 로 작성하지 않게 막을 때.
+  - **`ng-template-no-strict-null-check`** — Angular 템플릿에서 `=== null|undefined` 대신 `== null` 로 통일시킬 때.
+  - **`ng-template-no-todo-comments`** — Angular 템플릿 내 `<!-- TODO: ... -->` 를 빌드 경고로 남길 때.
+  - **`ng-template-sd-require-binding-attrs`** — `sd-*` 컴포넌트에 plain attribute 못 쓰게 하고 property binding 으로 강제할 때.
+  - **`no-hard-private`** — `#field` 대신 TypeScript `private _field` 스타일을 강제할 때.
+  - **`no-subpath-imports-from-simplysm`** — `@simplysm/<pkg>/src/...` 직접 import 를 차단할 때.
+  - **`ts-no-throw-not-implemented-error`** — `NotImplementedError` 잔존을 빌드 경고로 표면화할 때.
+  - **`ts-no-unused-injects`** — Angular `inject()` 로 받은 미사용 필드를 정리할 때.
+  - **`ts-no-unused-protected-readonly`** — Angular 컴포넌트 인라인 템플릿/클래스 어느 쪽에서도 안 쓰는 `protected readonly` 필드를 정리할 때.
 
 ## `./eslint-recommended`
 

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

@@ -9,16 +9,41 @@ Dialect 독립 ORM 코어. `DbContext` 상속으로 테이블/뷰/프로시저
 - **`Queryable` / `queryable()`** — `DbContext` 에 등록된 테이블/뷰에서 SELECT/INSERT/UPDATE/DELETE/UPSERT 빌더 체이닝, JOIN/include/recursive CTE/UNION/search 할 때. 자세히: [queryable.md](./queryable.md)
 - **`Executable` / `executable()`** — 등록된 프로시저 호출 결과 받을 때. 자세히: [executable.md](./executable.md)
 - **`expr` namespace + `ExprUnit`/`WhereExprUnit`** — `where`/`select`/`groupBy`/`having`/`update` 콜백 안에서 비교·논리·문자열·날짜·집계·윈도우·CASE·subquery 등 SQL 표현식 만들 때. dialect 독립 AST. 자세히: [expr.md](./expr.md)
-- **`parseSearchQuery(text)`** — `Queryable.search()` 내부에서 쓰는 OR/`+`AND/`-`NOT/`"…"`/`*` 구문 파서. 직접 LIKE 패턴이 필요할 때만 외부 사용.
-- **`QueryBuilder` (`createQueryBuilder(dialect)`, `QueryBuilderBase`, `ExprRendererBase`, `*QueryBuilder`, `*ExprRenderer`)** — executor 측에서 `QueryDef` 를 dialect SQL 로 렌더할 때. 응용 코드는 직접 호출 X.
-- **`QueryDef` 타입군 (`./types/query-def`)** — executor·테스트에서 빌더가 만든 AST 를 직접 다룰 때. `QueryDef`, `SelectQueryDef`, `InsertQueryDef`, ..., `QueryDefObjectName`, `DDL_TYPES`, `DdlType`.
-- **`Expr` 타입군 (`./types/expr`)** — Expr AST 노드 타입(`ExprColumn`/`ExprValue`/`ExprRaw`/`ExprEq`/...`ExprWindow`/`ExprSubquery`). `DateUnit`. ExprRenderer 구현·검사에서 사용.
-- **`DataType` / `ColumnPrimitive*` (`./types/column`)** — SQL DataType union(`int`/`bigint`/`varchar`/`datetime`/`uuid`/...) 과 TS 타입 매핑(`ColumnPrimitiveMap`/`ColumnPrimitiveStr`/`ColumnPrimitive`/`ColumnMeta`). `dataTypeStrToColumnPrimitiveStr` 상수, `InferColumnPrimitiveFromDataType<T>` / `inferColumnPrimitiveStr(value)` 런타임 추론.
-- **`Dialect` / `dialects` / `DataRecord` / `DbContextExecutor` / `ResultMeta` / `IsolationLevel` / `Migration` / `QueryBuildResult` (`./types/db`)** — executor 구현·DbContext 외부 인터페이스. `Migration[]` 은 DbContext 서브클래스의 `migrations` 프로퍼티로 오버라이드해 `initialize()` 에서 적용.
-- **`DbContextBase` / `DbContextStatus` / `DbContextDdlMethods` (`./types/db-context-def`)** — 외부에서 DbContext 를 인터페이스로 다룰 때 (Queryable/Executable/ViewBuilder 가 의존).
-- **`DbTransactionError` / `DbErrorCode`** — executor 가 트랜잭션 에러를 표준화해 throw, 호출측은 `instanceof` 로 분기. 코드: `NO_ACTIVE_TRANSACTION`, `TRANSACTION_ALREADY_STARTED`, `DEADLOCK`, `LOCK_TIMEOUT`.
-- **`parseResults(rows, meta)` / `pickResultSets(rawResults, buildResult)` (`./utils/*`)** — executor 측 raw 결과 가공. `parseResults` 는 flat row → 중첩 객체(JOIN 그룹핑 + 타입 파싱). `pickResultSets(raw, { resultSetIndex, resultSetStride })` 는 다중 결과 셋에서 필요한 셋만 추출 (예: MySQL 배치 INSERT 의 OUTPUT SELECT).
-- **`_Migration` / `SD_BUILDER`** — 내부용. `_Migration` 은 `_migration(code PK)` 시스템 테이블, `SD_BUILDER` 는 `queryable()`/`executable()` 팩토리 함수에 붙는 메타 심볼 (`initialize()` 가 DbContext 의 프로퍼티에서 builder 를 회수할 때 사용).
+- **`parseSearchQuery(text)`** — `Queryable.search()` 내부에서 쓰는 OR/`+`AND/`-`NOT/`"…"`/`*` 구문 파서. 직접 LIKE 패턴이 필요할 때만 외부 사용. (`ParsedSearchQuery` = `{ or, must, not }`)
+- **`createQueryBuilder(dialect)`** — `Dialect` 문자열로 dialect 별 QueryBuilder 인스턴스 받을 때 (executor 진입점).
+- **`QueryBuilderBase` / `ExprRendererBase`** — 커스텀 dialect 구현을 위해 상속 베이스 필요할 때.
+- **`MysqlQueryBuilder` / `MssqlQueryBuilder` / `PostgresqlQueryBuilder`** (와 대응 `*ExprRenderer`) — 특정 dialect 인스턴스를 직접 new 하거나 `instanceof` 분기할 때. 일반은 `createQueryBuilder` 사용.
+- **`QueryDef` (union) + `QueryDefObjectName` (`./types/query-def`)** — executor 가 받는 query AST 의 union 타입 / 모든 DDL/DML 이 공통으로 쓰는 `{database?, schema?, name}` 형태의 DB 객체 식별자.
+- **`SelectQueryDef`, `InsertQueryDef`, `InsertIfNotExistsQueryDef`, `InsertIntoQueryDef`, `UpdateQueryDef`, `DeleteQueryDef`, `UpsertQueryDef`, `SelectQueryDefJoin`, `CudOutputDef`** — DML AST 노드를 직접 만들거나 검사할 때 (executor·테스트).
+- **DDL QueryDef (`Create*` / `Drop*` / `Rename*` / `Add*` / `Modify*` / `Truncate*` / `Clear*` / `Schema*` / `ExecProc*` 등)** — 스키마 변경/프로시저 호출 AST 를 직접 다룰 때 (`getXxxQueryDef()` 반환 타입과 일치).
+- **`DDL_TYPES` (배열) / `DdlType` (union)** — query 가 DDL 인지 런타임/타입 레벨에서 검사할 때. 트랜잭션 내 DDL 차단 가드에서 사용.
+- **`Expr` (union) / `WhereExpr` (union)** — SELECT·ORDER BY·SET 콜백이 모두 받는 일반 표현식 AST 와, WHERE·HAVING 전용 boolean 표현식 AST. ExprRenderer 가 dispatch 하는 대상.
+- **개별 Expr 노드 (`ExprColumn`, `ExprValue`, `ExprRaw`, `ExprEq`, `ExprLike`, `ExprConcat`, `ExprDateDiff`, `ExprSwitch`, `ExprCount`, `ExprWindow`, `ExprSubquery` …)** — Expr renderer 구현, AST 검사, 디버깅 시 개별 노드 타입 필요할 때. 응용 코드는 `expr.*` 헬퍼만 사용.
+- **`WinFn` (union) / `WinSpec` / `WinFn*` 개별 노드** — Window 함수 AST 분기 (`rowNumber`, `rank`, `lag`, `sumOver` 등) 를 직접 처리할 때.
+- **`DateUnit`** — `dateDiff`/`dateAdd` 의 단위 union (`"year" | "month" | "day" | "hour" | "minute" | "second"`). 동적으로 단위 선택할 때.
+- **`DataType` (`./types/column`)** — SQL 타입 union (`{type:"int"}` / `{type:"varchar",length}` / `{type:"decimal",precision,scale?}` ...). DDL/cast 의 타입 인자.
+- **`ColumnPrimitive` / `ColumnPrimitiveStr` / `ColumnPrimitiveMap`** — Column 값으로 허용되는 TS 타입 union (`string|number|boolean|DateTime|DateOnly|Time|Uuid|Bytes|undefined`), 그 키 이름 union, 키→타입 매핑. ExprUnit/ResultMeta 가 사용.
+- **`ColumnMeta`** — `ColumnBuilder.meta` 의 형태 (`{type, dataType, autoIncrement?, nullable?, default?, description?}`). 외부에서 column 정의를 읽어 DDL 만들 때.
+- **`dataTypeStrToColumnPrimitiveStr`** — `DataType.type` → `ColumnPrimitiveStr` 상수 매핑. cast 결과 dataType 추론에 사용.
+- **`InferColumnPrimitiveFromDataType<T>`** — `DataType` 타입에서 TS 값 타입 추론 (제네릭 타입 유틸).
+- **`inferColumnPrimitiveStr(value)`** — 런타임 값에서 `ColumnPrimitiveStr` 추론. NULL/unknown 이면 throw.
+- **`Dialect`** — `"mysql" | "mssql" | "postgresql"` union. dialect 분기/`createQueryBuilder` 인자.
+- **`dialects`** — `Dialect[]` 상수 배열. 테스트의 `it.each(dialects)` 또는 모든 dialect 순회용.
+- **`DataRecord`** — query 결과 row 의 재귀 타입 (`{ [key]: ColumnPrimitive | DataRecord | DataRecord[] }`). Queryable/Executable 의 결과 제약.
+- **`DbContextExecutor`** — 외부에서 DbContext 에 주입할 executor 인터페이스 (`connect`/`close`/`beginTransaction`/`commitTransaction`/`rollbackTransaction`/`executeDefs`). 신규 dialect/원격 executor 구현 시.
+- **`ResultMeta`** — `executeDefs` 가 받는 `{columns: Record<string,ColumnPrimitiveStr>, joins: Record<string,{isSingle}>}`. raw row → 타입 변환·JOIN 그룹핑에 필요.
+- **`IsolationLevel`** — `"READ_UNCOMMITTED" | "READ_COMMITTED" | "REPEATABLE_READ" | "SERIALIZABLE"`. `connect`/`transaction` 인자.
+- **`Migration`** — `{name, up(db)}`. DbContext 서브클래스의 `migrations` 프로퍼티 타입. `initialize()` 가 적용.
+- **`QueryBuildResult`** — `QueryBuilder.build()` 반환 (`{sql, resultSetIndex?, resultSetStride?}`). executor 가 `pickResultSets` 로 좁힐 때 필요.
+- **`DbContextBase` (`./types/db-context-def`)** — DbContext 의 코어 인터페이스 (`status`/`database`/`schema`/`executeDefs`/`getNextAlias` 등). Queryable·Executable·ViewBuilder 가 의존하므로 mock/대체 구현 시 사용.
+- **`DbContextStatus`** — `"ready" | "connect" | "transact"`. status 분기 시.
+- **`DbContextDdlMethods`** — `createTable`/`addColumn`/`addForeignKey` 등 DDL 메서드 집합 인터페이스. `Migration.up` 의 db 인자 타입.
+- **`DbTransactionError`** — executor 가 트랜잭션 에러를 표준화해 throw 하는 클래스. 호출측은 `instanceof DbTransactionError` 로 분기.
+- **`DbErrorCode`** — `NO_ACTIVE_TRANSACTION` / `TRANSACTION_ALREADY_STARTED` / `DEADLOCK` / `LOCK_TIMEOUT` enum. `err.code === DbErrorCode.DEADLOCK` 같은 분기에 사용.
+- **`parseQueryResult(rows, meta)` (`./utils/result-parser`)** — flat row 배열 + `ResultMeta` → 타입 변환 + JOIN 그룹핑된 중첩 객체 배열. async. 빈 결과면 undefined. executor 가 SELECT/OUTPUT 결과를 사용자 객체로 가공할 때.
+- **`pickResultSets(rawResults, buildResult)` (`./utils/pick-result-sets`)** — `QueryBuildResult` 의 `resultSetIndex`/`resultSetStride` 따라 여러 결과 셋 중 필요한 셋만 추출/concat. MySQL 배치 INSERT 의 OUTPUT SELECT 만 모을 때.
+- **`_Migration`** — `_migration(code PK varchar(255))` 시스템 테이블의 TableBuilder. DbContext 가 자동 등록, 사용자 직접 import 불필요.
+- **`SD_BUILDER`** — `queryable()`/`executable()` 팩토리 함수에 builder 를 부착하는 심볼. `initialize()` 가 DbContext 의 프로퍼티에서 builder 를 회수할 때 사용. 사용자 코드 직접 사용 X.
 
 ## QueryBuilder (인라인)
 

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

@@ -4,13 +4,23 @@ Node.js 환경에서 `@simplysm/orm-common` 의 `DbContext` 를 실제 DB(MSSQL/
 
 ## 사용 트리거 인덱스
 
-- **`createOrm` / `Orm` / `OrmOptions`** — `DbContext` 서브클래스 + `DbConnConfig` 로 ORM 인스턴스를 만들고, 트랜잭션 유/무 콜백을 실행한다. 일반 ORM 사용의 진입점.
-- **`createDbConn`** — `DbConnConfig` 만으로 저수준 `DbConn` 인스턴스를 직접 만든다. `DbContext` 없이 raw SQL/bulk insert 가 필요할 때.
+- **`createOrm`** — `DbContext` 서브클래스 + `DbConnConfig` 로 ORM 인스턴스 생성. 일반 ORM 사용의 진입점.
+- **`Orm<T>`** — `createOrm` 반환 타입. 함수 시그니처·DI 토큰에서 참조하거나 `connect` / `connectWithoutTransaction` 호출 시.
+- **`OrmOptions`** — `createOrm` 3번째 인자. `DbConnConfig` 의 `database` / `schema` 를 런타임에 덮어쓸 때.
+- **`createDbConn`** — `DbConnConfig` 만으로 저수준 `DbConn` 인스턴스 직접 생성. `DbContext` 없이 raw SQL/bulk insert 가 필요할 때.
 - **`NodeDbContextExecutor`** — `DbContext` 의 executor 직접 주입이 필요할 때. 일반적으로는 `createOrm` 이 내부적으로 사용.
-- **`MysqlDbConn` / `MssqlDbConn` / `PostgresqlDbConn`** — dialect별 `DbConn` 구현. 직접 `new` 하지 말고 `createDbConn` 사용. 타입 참조용으로만 import.
-- **`DbConn` / `DbConnConfig` (+ `MysqlDbConnConfig` / `MssqlDbConnConfig` / `PostgresqlDbConnConfig`)** — 설정/연결 타입. 함수 시그니처·DI 토큰 등에서 참조.
+- **`MysqlDbConn`** — MySQL 용 `DbConn` 구현 클래스. 직접 `new` 하지 말고 `createDbConn` 사용. 타입 참조용 import.
+- **`MssqlDbConn`** — MSSQL/Azure SQL 용 `DbConn` 구현 클래스. 직접 `new` 하지 말고 `createDbConn` 사용. 타입 참조용 import.
+- **`PostgresqlDbConn`** — PostgreSQL 용 `DbConn` 구현 클래스. 직접 `new` 하지 말고 `createDbConn` 사용. 타입 참조용 import.
+- **`DbConn`** — 저수준 연결 인터페이스. 모든 dialect 공통 메서드(`connect`/`close`/트랜잭션/`execute`/`executeParametrized`/`bulkInsert`) 와 `close` 이벤트.
+- **`DbConnConfig`** — dialect 분기 union 타입. `createOrm`/`createDbConn` 입력.
+- **`MysqlDbConnConfig`** — `dialect: "mysql"` 한정 설정 타입.
+- **`MssqlDbConnConfig`** — `dialect: "mssql" | "mssql-azure"` 설정 타입. `schema?` 포함.
+- **`PostgresqlDbConnConfig`** — `dialect: "postgresql"` 설정 타입. `schema?` 포함.
 - **`getDialectFromConfig`** — `DbConnConfig` → `Dialect` 변환(`mssql-azure` → `mssql`). 쿼리 빌더 선택 시.
-- **`DB_CONN_CONNECT_TIMEOUT` (10s) / `DB_CONN_DEFAULT_TIMEOUT` (10m) / `DB_CONN_ERRORS`** — 타임아웃·에러 메시지 상수.
+- **`DB_CONN_CONNECT_TIMEOUT`** — DB 연결 수립 타임아웃 상수 (10초).
+- **`DB_CONN_DEFAULT_TIMEOUT`** — 쿼리/유휴 기본 타임아웃 상수 (10분).
+- **`DB_CONN_ERRORS`** — `NOT_CONNECTED` / `ALREADY_CONNECTED` 에러 메시지 리터럴.
 
 ## createOrm
 

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

@@ -4,6 +4,6 @@ Claude Code 셋업 자산(`.claude/` 의 sd-* 스킬·룰·훅) 배포 및 `sd-c
 
 코드 API 없음 (npm 배포용). 외부에서 import 할 수 있는 라이브러리 심볼은 노출하지 않는다.
 
-- `bin`: `sd-claude` — `auth save` / `auth switch` (저장된 Claude 계정 전환).
-- `postinstall`: 설치 시 사용자 `~/.claude/` 로 자산 동기화.
-- `prepack`: 배포 전 `.claude/` → `packages/sd-claude/claude/` 증분 복사.
+- `bin`: `sd-claude` — `auth save` (현재 Claude 계정 저장) / `auth switch` (저장된 계정 목록에서 선택해 전환).
+- `postinstall`: 패키지 설치 시 `claude/` 의 sd-\* 에셋을 소비 프로젝트 루트의 `.claude/` 로 복사 (기존 sd-\* 항목은 정리 후 재복사, `settings.json`·`simplysm.json` 포함).
+- `prepack`: 배포 전 워크스페이스의 `.claude/` → `packages/sd-claude/claude/` 증분 복사 (mtime+size 비교, `evals/`·`SKILL.eval.md`·`eval_*` 제외).

package/claude/references/sd-simplysm14/apis/sd-cli/README.md

@@ -1,14 +1,44 @@
 # @simplysm/sd-cli
 
-워크스페이스 빌드/배포 오케스트레이터. 라이브러리 export 는 `sd.config.ts` 작성용 타입과 Vitest Angular 플러그인, 그리고 외부 도구가 재사용할 `SdTsCompiler` 다. CLI 서브커맨드는 이 문서 대상 아님 (`pnpm sd-cli --help`).
+워크스페이스 빌드/배포 오케스트레이터. 소비 표면은 두 갈래다 — `pnpm sd-cli <cmd>` 서브커맨드와 `sd.config.ts` 작성용 타입. 라이브러리 export 로는 Vitest Angular 플러그인과 외부 도구가 재사용할 `SdTsCompiler` 도 노출한다.
 
 ## 사용 트리거 인덱스
-- **`SdConfigFn` / `SdConfig` / `SdConfigParams`** — `sd.config.ts` 의 default export 타이핑. 자세히: [sd-config.md](./sd-config.md)
-- **패키지별 설정 타입 (`SdBuildPackageConfig`, `SdClientPackageConfig`, `SdServerPackageConfig`, `SdScriptsPackageConfig`)** — `SdConfig.packages` 값 타이핑. 자세히: [sd-config.md](./sd-config.md)
-- **`SdPublishConfig` / `SdPostPublishScriptConfig`** — `publish`·`postPublish` 항목 타이핑. 자세히: [sd-config.md](./sd-config.md)
-- **`SdCapacitorConfig` / `SdElectronConfig` / `SdPwaConfig` / `SdBrowserSupportConfig`** — 클라이언트 패키지의 모바일/데스크톱/PWA/브라우저 지원 옵션. 자세히: [sd-config.md](./sd-config.md)
-- **`sdAngularPlugin(options)`** — Vitest 의 `vite.config` (또는 `vitest.config`) 에서 Angular 패키지 AOT 컴파일이 필요할 때 plugin 으로 추가.
-- **`SdTsCompiler` (+ `ISdTsCompilerOptions`, `ISdTsCompilerResult`)** — 사용자 코드에서 직접 호출할 일은 거의 없음. Angular/Non-Angular TS 패키지를 증분 컴파일·진단·lint·SCSS 통합 처리하는 엔진. `sd-cli` 내부 엔진(`engines/`, `orchestrators/`) 및 `sdAngularPlugin` 에서 사용. 외부에서 동일한 엔진을 재사용해야 할 때만 직접 import.
+
+### 서브커맨드 (`pnpm sd-cli <cmd>`)
+
+- **`check`** — 타입체크와 lint 를 병렬 실행. 일반 검증 명령으로 가장 자주 호출됨.
+- **`watch`** — 워크스페이스 전체 또는 일부 패키지를 watch 모드로 증분 빌드.
+- **`dev`** — server 패키지를 dev 모드로 실행 (`tsx` 핫리로드 + client 패키지의 dev http 서버 동반 기동).
+- **`device`** — client 패키지를 안드로이드 디바이스 또는 Electron 데스크톱에서 실행. dev 서버가 떠 있어야 함.
+- **`build`** — 프로덕션 빌드. `sd.config.ts` 의 `packages` 전 항목 또는 `-t` 지정 항목.
+- **`publish`** — 빌드 후 `publish` 설정을 따라 배포 (npm / 로컬 디렉토리 / FTP·SFTP). `--no-build` 로 기존 산출물만 배포.
+- **`replace-deps`** — `sd.config.ts.replaceDeps` 에 따라 `node_modules` 패키지를 로컬 소스로 심링크 교체.
+- **`init`** — 인터랙티브 프롬프트로 SI 워크스페이스 골격 생성.
+
+공통 옵션:
+- `-t / --target <pkg>` (반복 가능) — 대상 패키지. `sd.config.ts.packages` 키 (= `@simplysm/` 접두사 **제외**한 짧은 이름). 미지정 시 전체.
+- `-o / --opt <val>` (반복 가능) — `sd.config.ts` 함수의 `params.opt[]` 로 전달. `check` 와 `init` 제외 전 커맨드에서 지원.
+- `--debug` — 디버그 로그 출력 (모든 커맨드).
+- `--help / -h` — 단독 호출 시 모든 서브커맨드 종합 도움말.
+
+커맨드별 고유 옵션:
+- `check`: `--type typecheck|lint` (반복 가능, 기본 둘 다), `--fix` (lint 자동 수정).
+- `device`: `--target <pkg>` (단수, 미지정 시 유일 client 자동 선택), `--url <devServerUrl>` (미지정 시 `sd.config.ts` 의 server 설정에서 자동 도출).
+- `publish`: `--no-build` (빌드 생략), `--dry-run` (실제 배포 없이 시뮬레이션).
+
+진실 근거: `packages/sd-cli/src/sd-cli-entry.ts` (yargs 등록부), `packages/sd-cli/src/commands/<cmd>.ts`.
+
+### 설정 타입 (`sd.config.ts`)
+
+- **`SdConfigFn` / `SdConfig` / `SdConfigParams`** — `sd.config.ts` 의 default export 함수와 그 반환 타입. 자세히: [sd-config.md](./sd-config.md)
+- **`SdBuildPackageConfig` / `SdClientPackageConfig` / `SdServerPackageConfig` / `SdScriptsPackageConfig`** — `SdConfig.packages` 의 값 타입. 각각 라이브러리 / Frontend 앱 / Fastify 서버 / 유틸 패키지에 대응. 자세히: [sd-config.md](./sd-config.md)
+- **`SdPublishConfig` / `SdPostPublishScriptConfig`** — 패키지의 `publish` 와 전역 `postPublish` 항목 타입. 자세히: [sd-config.md](./sd-config.md)
+- **`SdCapacitorConfig` / `SdElectronConfig` / `SdPwaConfig` / `SdBrowserSupportConfig`** — client 패키지의 모바일·데스크톱·PWA·브라우저 지원 옵션. 자세히: [sd-config.md](./sd-config.md)
+
+### 라이브러리 export
+
+- **`sdAngularPlugin(options)`** — Vitest 의 `vite.config` / `vitest.config` 에서 Angular 패키지 AOT 컴파일이 필요할 때 plugin 으로 추가.
+- **`SdTsCompiler` (+ `ISdTsCompilerOptions`, `ISdTsCompilerResult`)** — Angular/Non-Angular TS 패키지를 증분 컴파일·진단·lint·SCSS 통합 처리하는 엔진. `sd-cli` 내부와 `sdAngularPlugin` 이 사용. 외부에서 동일한 엔진을 재사용할 때만 직접 import.
 
 ## sdAngularPlugin
 

package/claude/references/sd-simplysm14/apis/service-client/README.md

@@ -3,28 +3,33 @@
 `@simplysm/service-server` 와 WebSocket 으로 통신하는 클라이언트. RPC 호출·이벤트 구독·파일 업/다운로드·원격 ORM 실행을 단일 `ServiceClient` 에서 제공한다 (Node/브라우저 공용).
 
 ## 사용 트리거 인덱스
-- **createServiceClient / ServiceConnectionOptions** — 클라이언트 인스턴스 생성·서버 접속/종료할 때.
-- **getService / send / ServiceProxy** — 서버 서비스 메서드를 타입 안전 RPC 로 호출할 때.
-- **auth** — 서버 인증 토큰을 등록하고 재연결 시 자동 재인증되게 할 때.
-- **getEvent / addListener / removeListener / emitEvent** — 서버 사이드 이벤트 구독 또는 다른 클라이언트로 이벤트 발행할 때.
-- **uploadFile / downloadFileBuffer** — 서버에 파일을 올리거나 정적 경로에서 바이트로 받을 때.
-- **createOrmClientConnector / OrmConnectOptions** — 서버의 ORM 서비스를 통해 DbContext 트랜잭션을 원격 실행할 때.
-- **ServiceClient 이벤트 (`state`, `request-progress`, `response-progress`, `server-progress`)** — 연결 상태와 전송/응답/서버 진행률을 구독할 때.
+
+- **createServiceClient / ServiceConnectionOptions** — 서버 접속용 `ServiceClient` 를 만들고 `connect()`/`close()` 로 연결을 열고 닫을 때.
+- **getService / send / ServiceProxy** — 서버에 등록된 서비스의 메서드를 타입 안전 RPC 로 호출할 때 (Proxy 기반 메서드 호출 또는 저수준 `send`).
+- **auth** — 서버 인증 토큰을 등록하고 재연결 시 자동 재인증되도록 토큰을 내부에 보관할 때.
+- **getEvent / addListener / removeListener / emitEvent** — 서버 push 이벤트를 구독·해지하거나, 다른 클라이언트에게 이벤트를 발행할 때.
+- **uploadFile / downloadFileBuffer** — 서버에 multipart 파일을 올리거나 정적 경로에서 바이트(`Uint8Array`)로 받을 때.
+- **createOrmClientConnector / OrmConnectOptions** — 서버 측 `"Orm"` 서비스를 통해 `DbContext` 트랜잭션을 원격 실행할 때.
+- **ServiceClient 이벤트 (`state` / `request-progress` / `response-progress` / `server-progress`)** — 연결 상태 변화와 전송/응답/서버 진행률을 인스턴스 레벨에서 구독할 때.
+- **BlobInput / FileCollection / isWorkerSupported 외** — Node/브라우저 양쪽 환경에서 동일한 코드를 쓰기 위해 DOM 의존 타입을 대체하거나 Worker 지원 여부를 미리 확인할 때.
 
 ## 연결/생성
+
 ```ts
 createServiceClient(name: string, options: ServiceConnectionOptions): ServiceClient
 interface ServiceConnectionOptions { port: number; host: string; ssl?: boolean; maxReconnectCount?: number; }
 client.connect(): Promise<void>
-client.close(): Promise<void>
+client.close(): Promise<void>     // protocol wrapper 의 worker 자원도 dispose
 client.connected: boolean
-client.hostUrl: string  // `${ssl?https:http}://host:port`
+client.hostUrl: string            // `${ssl?https:http}://host:port`
 ```
-- WebSocket URL 은 `${ws|wss}://host:port/ws` 로 고정.
+
+- WebSocket URL 은 `${ws|wss}://host:port/ws?ver=2&clientId=<uuid>&clientName=<name>` 으로 접속한다.
 - `maxReconnectCount` 기본 10, `0` 이면 재연결 비활성.
-- 5s ping / 30s 무응답 시 강제 재연결, 재연결 성공 시 인증 토큰과 이벤트 리스너가 자동 복구됨.
+- 5s 마다 ping, 30s 무응답 시 강제 재연결. 재연결 성공 시 인증 토큰(`auth()`)과 이벤트 리스너(`addListener`)가 자동 복구된다.
 
 ## RPC 호출
+
 ```ts
 client.getService<TService>(serviceName): ServiceProxy<TService>
 client.send(serviceName, methodName, params, progress?): Promise<unknown>
@@ -32,18 +37,25 @@ type ServiceProxy<T> = { [K in keyof T]: T[K] extends (...a:infer P)=>infer R ?
 interface ServiceProgress { request?(s); response?(s); server?(s); }
 interface ServiceProgressState { uuid: string; totalSize: number; completedSize: number; }
 ```
-- `getService` 는 Proxy 라 임의 메서드명 호출 가능. 타입은 `TService` 로만 보장됨.
-- 메시지 이름은 `"<serviceName>.<methodName>"` 으로 전송.
-- 30KB 초과 또는 `Uint8Array`/큰 배열 페이로드는 Worker 에서 인코딩/디코딩.
+
+- `getService` 는 Proxy 라 임의 메서드명 호출 가능. 타입은 `TService` 로만 보장된다.
+- 와이어 메시지 이름은 `"<serviceName>.<methodName>"`.
+- 인코딩/디코딩의 Worker 오프로딩 임계값:
+  - **인코드**: body 가 `Uint8Array`, 30KB 초과 문자열, 길이 100 초과 배열, 또는 첫 요소가 `Uint8Array` 인 배열일 때 Worker 사용.
+  - **디코드**: 수신 바이트가 30KB 초과일 때 Worker 사용.
+  - Worker 미지원 환경(또는 초기화 실패)에선 메인 스레드 fallback.
 
 ## 인증
+
 ```ts
 client.auth(token: string): Promise<void>
 ```
+
 - 서버에 `auth` 메시지를 보내고 토큰을 내부 저장. 재연결 시 자동으로 같은 토큰으로 재인증.
-- `uploadFile` 은 인증 토큰이 없으면 에러를 던짐.
+- `uploadFile` 은 인증 토큰이 없으면 에러를 던진다.
 
 ## 이벤트 (서버 push)
+
 ```ts
 client.getEvent<TEventDef>(eventName): ClientEventProxy<TEventDef>
 client.addListener<TEventDef>(eventName, info, cb): Promise<string>   // key 반환
@@ -51,22 +63,26 @@ client.removeListener(key): Promise<void>
 client.emitEvent<TEventDef>(eventName, infoSelector, data): Promise<void>
 interface ClientEventProxy<T> { addListener(info, cb): Promise<string>; removeListener(key): Promise<void>; emit(infoSelector, data): Promise<void>; }
 ```
-- `addListener` 는 연결 상태에서만 가능. 로컬 맵에도 보관해 재연결 시 자동 재구독.
-- `emitEvent` 는 서버에 `evt:gets` 로 후보를 받아 `infoSelector` 통과분에만 `evt:emit` 호출.
-- 핸들러 내부 에러는 로깅만 되고 다른 핸들러 호출은 계속됨.
+
+- `addListener` 는 연결 상태에서만 호출 가능 (`!connected` 시 throw). 로컬 맵에도 보관해 재연결 시 자동 재구독.
+- `emitEvent` 는 서버에 `evt:gets` 로 후보를 받아 `infoSelector` 통과분에만 `evt:emit` 호출. 대상이 0건이면 emit 생략.
+- 핸들러 내부 에러는 로깅만 되고 다른 핸들러 호출은 계속 진행.
 
 ## 파일 업/다운로드
+
 ```ts
 client.uploadFile(files: File[] | FileCollection | { name: string; data: BlobInput }[]): Promise<ServiceUploadResult[]>
 client.downloadFileBuffer(relPath: string): Promise<Uint8Array>
 type BlobInput = Blob | Uint8Array<ArrayBuffer> | ArrayBuffer | string
 interface FileCollection { length; item(i); [i]; [Symbol.iterator]() }  // 브라우저 FileList 호환
 ```
+
 - 업로드: `POST {hostUrl}/upload` (multipart). 헤더 `x-sd-client-name`, `Authorization: Bearer <token>`. 인증 필수.
-- 다운로드: `GET {hostUrl}/{relPath}` 의 응답 본문을 `Uint8Array` 로 반환.
+- 다운로드: `GET {hostUrl}/{relPath}` 의 응답 본문을 `Uint8Array` 로 반환. `relPath` 가 `/` 로 시작하지 않으면 자동으로 붙임.
 - 브라우저 전용 `File`/`FileList` 대신 `BlobInput`/`FileCollection` 으로 Node 환경도 지원.
 
 ## ORM 클라이언트
+
 ```ts
 createOrmClientConnector(client: ServiceClient): OrmClientConnector
 interface OrmConnectOptions<T extends DbContext> {
@@ -77,16 +93,32 @@ interface OrmConnectOptions<T extends DbContext> {
 connector.connect(config, async db => ...)               // 트랜잭션 래핑
 connector.connectWithoutTransaction(config, async db => ...)
 ```
-- 서버의 `"Orm"` 서비스에 RPC 를 걸어 `getInfo` → `connect` → `executeDefs` 등을 실행.
-- `dbContextOpt` 생략 시 서버가 알려준 `database`/`schema` 사용. 둘 다 비면 에러.
-- 외래키 참조 위반 에러(`a parent row: a foreign key constraint` / `conflicted with the REFERENCE`)는 사용자 메시지로 변환되어 throw.
+
+- 서버의 `"Orm"` 서비스에 RPC 를 걸어 `getInfo` → `connect` → `executeDefs`/`executeParametrized`/`bulkInsert` 등을 실행.
+- `dbContextOpt` 생략 시 서버가 알려준 `database`/`schema` 사용. 최종 `database` 가 빈 값이면 에러.
+- 외래키 참조 위반 에러(`a parent row: a foreign key constraint` / `conflicted with the REFERENCE`)는 "경고! 연관된 작업으로 인해 작업이 거부되었습니다..." 사용자 메시지로 변환되어 throw (원본은 `cause`).
 
 ## 상태/진행률 이벤트
+
 ```ts
 client.on("state", (s: "connected" | "closed" | "reconnecting") => ...)
 client.on("request-progress",  (s: ServiceProgressState) => ...)  // 클라이언트 → 서버 전송 청크 진행
 client.on("response-progress", (s: ServiceProgressState) => ...)  // 서버 → 클라이언트 응답 청크 진행
 client.on("server-progress",   (s: ServiceProgressState) => ...)  // 서버가 명시적으로 보내는 진행률
 ```
-- 단일 청크 메시지에는 progress 가 발행되지 않음(분할 메시지에서만).
-- `send` 호출 시 전달한 `progress?: ServiceProgress` 콜백은 인스턴스 이벤트와 별도로 호출됨.
+
+- `request-progress` 는 인코드 결과 chunk 가 2개 이상일 때만 초기 0% 가 발행됨. 단일 청크는 progress 없음.
+- `response-progress` 는 분할 수신 중에는 서버 progress 메시지로, 응답 완료 시 100% 보정값으로 발행됨.
+- `send` 호출 시 전달한 `progress?: ServiceProgress` 콜백은 인스턴스 이벤트와 함께 호출된다.
+
+## 환경 호환 유틸
+
+```ts
+import { BlobInput, FileCollection, BrowserWorker,
+         isBrowserWorkerSupported, isNodeWorkerSupported, isWorkerSupported }
+  from "@simplysm/service-client";
+```
+
+- `BrowserWorker` — DOM `Worker` 의 구조적 호환 인터페이스. Node 환경 typecheck 통과용.
+- `isBrowserWorkerSupported()` / `isNodeWorkerSupported()` / `isWorkerSupported()` — 현재 런타임에서 Worker 오프로딩이 가능한지 사전 확인.
+- 보통 직접 호출할 필요 없음. `ServiceClient` 가 내부에서 분기하므로, 환경별 분기 로직을 사용자 코드에서 직접 짤 때만 사용.

package/claude/references/sd-simplysm14/apis/storage/README.md

@@ -7,7 +7,9 @@ FTP/FTPS/SFTP 원격 스토리지에 동일 인터페이스(`StorageClient`)로
 - **`StorageFactory.connect`** — FTP/FTPS/SFTP 어느 것이든 연결→작업→자동 종료를 한 번에 처리할 때 (권장 진입점).
 - **`StorageClient`** — 콜백 안에서 사용하는 공통 파일 작업 인터페이스(mkdir/list/readFile/put/uploadDir/remove/rename/exists).
 - **`FtpStorageClient` / `SftpStorageClient`** — 연결 생명주기를 직접 관리해야 할 때만 (장기 연결 풀 등). 그 외엔 `StorageFactory.connect` 사용.
-- **`StorageConnConfig`, `StorageProtocol`, `FileInfo`** — 위 API 호출 시 타입.
+- **`StorageConnConfig`** — `connect`/`StorageFactory.connect` 에 넘기는 접속 정보(host/port/user/password) 타입.
+- **`StorageProtocol`** — `StorageFactory.connect` 의 `type` 인자로 쓰는 프로토콜 리터럴(`"ftp" | "ftps" | "sftp"`).
+- **`FileInfo`** — `list` 결과 항목 타입(`{ name, isFile }`).
 
 ## StorageFactory.connect
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simplysm/sd-claude",
-  "version": "14.0.72",
+  "version": "14.0.73",
   "description": "심플리즘 패키지 - Claude Code 셋업",
   "author": "심플리즘",
   "license": "Apache-2.0",