d3ro-voice/docs/map/03-shared-packages.md
Yun Chan 7fe49c437e chore: land in-progress workspace changes before 1.16.2
The tree carried uncommitted work from several areas (web push, mobile
screens, admin charts, test-hygiene cleanup, CI and map docs). It is landed
as one commit so the release pipeline can start from a clean tree; the
desktop transcript-correction behaviour shipped in the previous commit and
is unchanged here.
2026-11-05 21:58:44 +09:00

115 lines
10 KiB
Markdown

# 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 |
| Crypto license | `./utils/crypto-license` | Ed25519 license sign/verify (used by admin issuer + desktop verifier) |
| PII | `pii-redactor`, `secure-memory` | Redaction + secure memory helpers |
| 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, ButtonGroup, TiltCard, GradientWave, StatRing |
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` |
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,742 parity-checked keys, including the 16 native `update.dialog.*` keys |
| 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`, and period-aware `consume_quota` RPC contracts |
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.