Some checks failed
ci / 정본·보안·린트·타입·테스트 (push) Failing after 18s
ci / 워크스페이스 빌드 검증 (push) Has been skipped
ci / 모바일 린트·타입·Jest (push) Successful in 45s
ci / Supabase Edge Functions + Cloudflare Worker (push) Successful in 22s
ci / .NET API 서버 테스트 (push) Successful in 11s
deploy-site / deploy (push) Successful in 44s
136 lines
15 KiB
Markdown
136 lines
15 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 |
|
|
| 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`, `<ContentColumn>` |
|
|
|
|
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/<lang>.json')`), `src/main.ts` (`@d3ro/i18n/main` — zero-React Node/Electron main entry reading only the active `locales/<lang>.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).
|