# 03 — Shared Packages Map > Surface: `packages/*` (npm workspaces) > Source of truth for: shared domain logic, design systems, i18n, API client All packages are private, version `1.2.0`, source-only (`main`/`types` point at `src`). --- ## 1. `@d3ro/core` — business logic SSOT (`packages/core`) The canonical place for types and cross-surface logic. Both desktop and web/mobile depend on it. | Area | Exports | Notes | |---|---|---| | Types | `./types` | Domain types shared across surfaces, including the record+meeting `UnifiedSearchSource` / `UnifiedSearchMatchedField` / `UnifiedSearchResult` / `UnifiedSearchParams` / `UnifiedSearchResponse` contract | | Errors | `./errors` | `D3ROError`, `ErrorCode` | | IPC channels | `./ipc-channels` | `IPC_CHANNELS` object + `IPCChannel` union. **SSOT** for every desktop IPC channel (VOICE, AUDIO, STT, TTS, LLM, KEYBINDING, CONFIG, HISTORY, UNIFIED_SEARCH, DICTIONARY, WINDOW, SYSTEM, STATS, MEMO, VOICE_COMMAND, CONTEXT, CHAIN, CAPTION, FILE_TRANSCRIPTION, MEETING_SUMMARY, DICTATION_TEMPLATE, VOICE_CONVERSATION, RAG, VOICE_ACTION, MEETING_MODE, MEETING_DOC_TEMPLATE, MEETING_CHAT, LICENSE, CLOUD_SYNC, INSTRUCTION, SYSTEM_AUDIO, POPUP_RESULT, POPUP_HISTORY, POPUP_COMMAND, POPUP_CAPTION, VOICE_PARTIAL, CLIPBOARD, APP, ONLINE_AUTH, ADS, SUPPORT, INPUT_TELEMETRY, SUGGESTION, POPUP_SUGGESTION) | | Key bindings | `./keybinding` | **SSOT** for every global shortcut in the app: `KeyBinding` (`device`/`code`/`ctrl`/`alt`/`shift`/`meta`), `KEY_CATALOG` (10 selectable groups incl. mouse), `KEYBINDING_ACTIONS` (9 rebindable actions incl. the three suggestion actions), `bindingKey`/`normalizeBinding`/`validateBinding`/`detectBindingConflicts`/`formatBindingSegments`/`searchKeyCatalog`/`parseBindingMap`. Persisted as `AppConfig.keyBindings`. i18n keys are exposed as plain `string` so core stays independent of `@d3ro/i18n`; consumers narrow at the boundary (`asTranslationKey`) and a contract test guards the keys — accepted constraint, `11` §7 CONSTRAINT-I18N-01. Tests: `__tests__/keybinding*.test.ts` via `vitest.config.ts` (`npm run test --workspace=@d3ro/core`), 117 cases as of 2026-09-21 | | Input intelligence | `./input-intelligence` | **SSOT** for the input-telemetry and next-sentence-suggestion domain (added 2026-09-21): key classification (`classifyKeyStroke`), text metrics (`countWords`/`countSentences`/`endsSentence`/`textBeforeCaret`), `computeTypedDelta` (UIA snapshot diff — the IME-safe way to count typed text), `decideSuggestion` + `isAppExcluded` (when to request / skip / clear), `parseSuggestionCandidates`/`sanitizeSuggestionLine` (prompt-leak and prefix-echo defence), `anchorFloatingPanel` (caret-anchored overlay placement), `mergeActivityBucket`/`summarizeActivity`/`pixelsToMeters`, `extractPhrases`/`selectPhraseHints`, `INPUT_TELEMETRY_DEFAULTS`/`SUGGESTION_DEFAULTS` | | Typo correction & Araso layout | `./typo-correction`, `./araso-layout` | **SSOT** for built-in automatic Han/Eng conversion and typo auto-correction (upgraded 2026-10-29): 2-set Korean/English layout conversion (`engToHangul`/`hangulToEng`), shifted/unshifted 2-letter loose-jamo acronyms (`ㅔㅊ`/`ㅖㅊ`→`PC`, `ㅐㄴ`/`ㅒㄴ`→`OS`, `ㅔㄱ`/`ㅖㄱ`→`PR`, `ㅊㅑ`→`CI`, `ㅍㅡ`→`VM`, `ㅔㅡ`→`PM`, `ㅔㅐ`→`PO`, `ㅗㄱ`→`HR`, `ㅑㄱ`→`IR`, `ㅇㅡ`→`DM`, `ㅡㅇ`→`MD`, `ㅔㅇ`→`PD`, `ㅍㅔ`→`VP`, `ㅠㅡ`→`BM`, `ㅆㅍ`→`TV`, `ㅑㅖ`→`IP`) and Korean-prefix + loose-jamo compounds (`내ㅔㅊ`→`내PC`, `회사ㅔㅊ에서`→`회사PC에서`, `한글로ㅔㅊ라고`→`한글로PC라고`), productive English derivational prefixes/suffixes (`matchesInflectedOrDerivedEnglish`, `EXTENDED_ENGLISH_STEMS`), phrase-level lookahead English detection (`TO_FOLLOWING_ENGLISH_WORDS`, `resolveTokenAsEnglishPreview`), lingering Shift normalization (`normalizeLingeringShift`/`lingersAfterKoreanShift`), mixed-word splitting with Korean particle batchim agreement (`splitMixedWord`/`particleAgrees`), reverse Hangul-to-English/mixed restoration, URL/path/email run protection (`isUrlOrPathRun`), deterministic spelling & jamo-noise rules (`detectTypos`/`detectJamoNoise`), delta-rebasing for in-flight typing (`rebaseTypoReplacementPlan`), and LLM typo validation (`validateModelCorrections`). | | Dictation cleaner | `./dictation-cleaner` | **SSOT** for deterministic zero-latency speech disfluency & dictation cleanup (`cleanDictatedText`, added 2026-10-29): strips standalone spoken fillers (`어`, `음`, `그 쓸데없는` while preserving quoted mentions like `어라든가`, `아라든가` and demonstratives), mid-sentence self-corrections (`X 아니 X이 아니라 Y` → `Y`), word stutters (`내가 내가` → `내가`), colloquial suffixes (`예를 들자면은` → `예를 들어`, `보면은` → `보면`), redundant expressions (`쓸데없는 의미없는` → `불필요한`), and clear contextual STT homophones (`스시가 영어로 변경되지` → `PC가 영어로 변경되지`, `그 길을 쓸 이유가` → `그 기능을 쓸 이유가`) while preserving speaker register. | | Personal graph & n-gram | `./personal-graph`, `./personal-ngram` | **SSOT** for relational personalization and n-gram continuation (upgraded 2026-10-28): exact & particle-invariant stemmed continuations (`continuationsFrom`/`stemContinuationsFrom`), IDF-weighted related node scoring (`scoreRelatedNodes`), 2-hop graph path ranking (`rankTwoHopGraphTargets` across `shares_terms→follows` and `follows→follows`), personalized candidate reranking (`scoreCandidatePersonalization`), and frequency-weighted n-gram indexing with Korean stemmed-word bigram fallback (`PersonalNgramModel`). | | Constants | `./constants` | Shared constants | | Guards, CSV & formatters | `./guards`, `./csv`, `./format` | Cross-surface predicate & codec SSOT (2026-11-13, Wave 5 `W5-05`): `isRecord`, `isNonEmptyString`, `isUuid`, `escapeLikePattern`; RFC 4180 `csvCell` / `parseCsvRows`; `formatDurationSec` / `formatDurationMs` / `formatClockTimestampMs` | | Unified search helpers | `./unified-search` | Cross-surface unified search normalization, snippet extraction (`buildSearchSnippet`), and newest-first ranker (`sortUnifiedSearchResults`) shared by desktop `UnifiedSearchService` and mobile `unified-search-service` (2026-11-13, `W5-06`) | | Admin role hierarchy | `./admin-roles` | `ADMIN_ROLE_RANK`, `hasMinimumAdminRole`, `canManageTargetRole` shared across `apps/admin` and Supabase `_shared/admin-auth.ts` via `core-contract.generated.ts` (2026-11-13, `W5-07`) | | Meeting transcript & speakers | `./meeting-transcript` | Timestamped/speaker segment parser & serializer (`toTranscriptSegments`, `parseSegmentText`), `formatPyannoteSpeakerLabel` (`SPEAKER_00` → `화자 1`), `resolveSpeakerColorIndex`, and `extractDistinctSpeakers` (2026-11-13, `GAP-MTG-02`) | | Determinism ports | `./ports` | Injectable `Clock`, `FakeClock` (`createFakeClock`), `Random`, `systemClock`, `systemRandom`, and `createSeededRandom` (Mulberry32) for deterministic tests (2026-11-13, TDD v2.0 Phase 4) | | Crypto license | `./utils/crypto-license` | Ed25519 license sign/verify (used by admin issuer + desktop verifier) | | PII & ZDR | `pii-redactor`, `secure-memory` | `redactPII`/`redactPIIMessages`/`rehydrateText` (wired into `OnlineLLMService` and `support-handlers`) + `secureZeroBuffer`/`secureWipeAudioChunks` (wired into `VoiceModeService` and `AudioCaptureService`, 2026-11-13 `W5-01`) | | Supabase config | `supabase-config` | Shared Supabase config shape | | Entitlement | `./entitlement` | `EntitlementTier`, `AdminRole`, `EntitlementSnapshot`, `resolveEntitlement`, `normalizeEntitlementTier`/`normalizeAdminRole` — canonical tier/role contract across Supabase, desktop license, and .NET | | Plan catalog | `./plan-catalog` | Tier/price/quota SSOT. `knowledge_embedding` is explicit per tier (Free 5,000/week; Pro 50,000/day; Pro+ 150,000/day; Team 300,000/day; Enterprise unlimited), generated into `server/supabase/functions/_shared/core-contract.generated.ts`, and guarded by `contract:check` | | Doc utils | `./utils/meeting-markdown`, `./utils/markdown-to-docx` | Meeting Markdown export + DOCX generation (dep: `docx`) | **When to change:** new cross-surface type, new error code, new IPC channel, license format. Add here first, then consume. --- ## 2. `@d3ro/ui` — web/desktop design system (`packages/ui`) | Export | Contents | |---|---| | `.` | Barrel | | `./theme` | `theme.ts` — `d3roPalette`, `d3roTypo` (13 steps), `d3roShadow` (10), `d3roRadius` (7); 6 themes (dark/Midnight, light, nord, solarized, catppuccin, dracula) + build helpers | | `./theme-vars` | CSS variable map for popups/vanilla surfaces | | `./components/ds` | MUI/Emotion DS components: CrtDisplay, InstrumentPanel, Led, PhysicalButton, MetalCard, PhosphorText (13 variants), MetalDial, ScreenPanel, SegmentControl (ARIA `tablist`/`tab` + roving `tabIndex` + keyboard `Enter`/`Space`), ButtonGroup, TiltCard, GradientWave, StatRing. Verified by `packages/ui/__tests__/ds-contract.test.tsx` and `npm run check:ds-contract` | Peers: React 19, MUI 7, Emotion 11. Depends on `@d3ro/core`. **Theme SSOT rule:** never hardcode hex outside `theme.ts`; use `d3roPalette`/`d3roShadow` tokens. `accent.amber` was removed in Wave 2; use `accent.main`. --- ## 3. `@d3ro/ui-native` — React Native design system (`packages/ui-native`) | Provides | |---| | `NativeThemeProvider` / `useNativePalette`; dark/light/get-palette, raw/status, typo/radius/fonts/space/control/weight/motion/numeral tokens. The v4 semantic colors mirror `packages/ui/src/theme-raw.ts`; `d3roNativeControl.h` is the 48dp control floor | | Components: `MetalCard`, `PhosphorText`, `Led`, `PhysicalButton`, `ScreenPanel`, `WaveBars`, `FilterChip` | | Responsive layout (`./responsive`, 2026-11-13 `GAP-UX-08`): `resolveResponsiveLayout` (`>=600dp` tablet/unfolded foldable vs `<600dp` phone, `contentMaxWidth: 880`, `formMaxWidth: 520`, `gridColumns: 2`, `adaptiveBannerHeight: 90`), `useResponsiveLayout`, `useContentWidth`, `` | Peers: `react`, `react-native`. Consumed by `apps/mobile-rn` via file: workspace dependencies. App-specific `ScreenHeader`, `RecordFab`, and `UnifiedSearchResultRow` stay under `apps/mobile-rn/src/components`; they are not shared package exports. --- ## 4. `@d3ro/i18n` — internationalization (`packages/i18n`) | Provides | Notes | |---|---| | 12 locales | `ko` (master), `en`, `ja`, `zh`, `zh-TW`, `es`, `fr`, `de`, `pt`, `ru`, `vi`, `th` in `src/locales/`; 2,500 parity-checked keys (253 unreferenced keys pruned on 2026-11-13), guarded by `npm run check:i18n` and `__tests__/locale-contract.test.ts` (15/15 PASS) | | Multi-entry architecture (2026-11-13) | `src/shared.ts` (zero-React/zero-JSON types & `Intl` formatters), `src/index.tsx` (`@d3ro/i18n` — web/desktop renderer entry: `ko`+`en` eager, 10 secondary locales loaded on demand via literal dynamic `import('./locales/.json')`), `src/main.ts` (`@d3ro/i18n/main` — zero-React Node/Electron main entry reading only the active `locales/.json` synchronously from disk with per-locale cache), and `src/index.native.tsx` (React Native Metro `.native.tsx` entry supporting all 12 locales with Metro `inlineRequires: true` lazy evaluation on `switch` branch entry) | | Type-safe keys | `TranslationKey` derived from `ko.json` | | React context | `I18nProvider`, `useI18n`, `TFunction` | | Fallback chain | locale → `en` → `ko` → key | | Formatters | `formatDate`, `formatNumber`, `formatRelativeDate`, `formatTime` via `Intl` | | Storage injection | `I18nStorage` adapter (localStorage on web, AsyncStorage on mobile) | Electron-independent. Rule: no hardcoded Korean/English strings in UI; use `t()`. --- ## 5. `@d3ro/api-client` — Supabase wrapper (`packages/api-client`) | Export | Purpose | |---|---| | `client` | Base Supabase client factory | | `auth` | Auth helpers | | `meetings` | Meeting queries | | `history` | History queries | | `usage` | Usage queries | | `transcribe` | STT calls | | `supabase-browser` | Browser client (`getSupabaseBrowserClient`, `isSupabaseConfigured`) | | `supabase-server` | Server client (`createSupabaseServerClient`) | | `types` | Shared DB/domain types — **canonical; do not redefine table types per app**. Includes `PushProvider`, device-bound `PushToken`, `push_tokens` row/insert/update shapes, `register_push_registration`/`unregister_push_registration`, period-aware `consume_quota` RPC contracts, and immutable `meeting_memos.revision` CAS shape (`20261113000001`) | Deps: `@supabase/supabase-js`; optional peer `@supabase/ssr`. The unused `@d3ro/core` dependency was removed in Wave 4. Tests: `__tests__/` (client, transcribe, types) via vitest. Consumed by `apps/web`, `apps/admin` (via re-exports), `apps/mobile-rn`, and desktop cloud paths. --- ## 6. Dependency direction ``` @d3ro/i18n (standalone) @d3ro/ui → @d3ro/core @d3ro/ui-native(standalone, peers react-native) @d3ro/api-client(standalone; depends on Supabase SDK) @d3ro/core (standalone) ``` Apps depend on packages, never the reverse. Shared package changes ripple to all consumers (see `docs/REFACTOR_POLICY.md`). --- ## 7. Package-level gaps - `apps/mobile-rn` is not an npm workspace member, so root `typecheck`/`test` skip it; use `typecheck:mobile`/`lint:mobile`/`test:mobile` from the repo root. - No versioned publishing of packages (private, source-only); all consumers are in-repo. --- ## 8. Wave 6 hardening (2026-11-14) - **`@d3ro/core` (Vitest 39 files / 626 tests PASS):** `utils/pii-redactor.ts` hardens placeholder collision avoidance, stateful regex index resets, and length-sorted single-pass `rehydrateText`; `csv.ts` adds UTF-8 BOM and `\r` line-ending escaping; `unified-search.ts`, `utils/meeting-markdown.ts`, and `meeting-transcript.ts` (reusing `formatDurationClockFromMs` and finite date guards) harden boundary inputs (`pii-redactor.test.ts` 5, `shared-utilities.test.ts` 10). Deno-synced contracts (`plan-catalog`, `web-urls`, `guards`, `admin-roles`) untouched (`contract:check` GREEN). - **`@d3ro/i18n` (Vitest 2 files / 25 tests PASS):** extracted `src/shared.ts` (`I18nStorage`, `noopI18nStorage`, `safeLoadStoredLocale`, `safeSaveStoredLocale`, non-finite date guard) shared by `index.tsx` and `index.native.tsx`, with `cancelled`, `userChangedLocaleRef`, and `localeRevisionRef` guards blocking stale async storage loads from overwriting explicit `setLocale()` changes (`__tests__/i18n-provider.test.tsx` 10). - **`@d3ro/ui` & `@d3ro/ui-native` & `@d3ro/api-client`:** `@d3ro/ui` extracted `src/components/ds/wave-math.ts` and cached canvas `LinearGradient` instances in `AudioVisualizerBar.tsx` and `GradientWave.tsx` (`__tests__/wave-visualizer.test.tsx` 3, Vitest 2 files / 7 tests PASS); `@d3ro/ui-native` extracted `resolveContentMaxWidth` (`responsive.tsx`) and guarded non-finite bars (`WaveBars.tsx`); `@d3ro/api-client/src/transcribe.ts` clamped negative latencies (Vitest 4 files / 31 tests PASS). --- ## 9. Wave 7 hardening (2026-11-14, `2a009e4`, post-`v1.17.1`) - **`@d3ro/core` (Vitest 39 files / 629 tests PASS):** `araso-layout.ts` and `typo-correction.ts` refine `isUrlOrPathRun()` so `domain.tld?` / `file.ext?` URLs remain untouched while Hangul ellipsis tokens (`[가-힣ㄱ-ㆎ][!?~]*\.{2,}$`) convert without affecting `...props` (`WORD_BOUNDARY_AFTER_RE` aligned, `__tests__/typo-correction.test.ts` +3); `personal-ngram.ts` removes a redundant intermediate `Map` allocation in `PersonalNgramModel.next()`. Other shared packages hold green on integrated `main` (`@d3ro/i18n` 2/25, `@d3ro/ui` 2/7, `@d3ro/api-client` 4/31 PASS).