15 KiB
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-rnis not an npm workspace member, so roottypecheck/testskip it; usetypecheck:mobile/lint:mobile/test:mobilefrom 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.tshardens placeholder collision avoidance, stateful regex index resets, and length-sorted single-passrehydrateText;csv.tsadds UTF-8 BOM and\rline-ending escaping;unified-search.ts,utils/meeting-markdown.ts, andmeeting-transcript.ts(reusingformatDurationClockFromMsand finite date guards) harden boundary inputs (pii-redactor.test.ts5,shared-utilities.test.ts10). Deno-synced contracts (plan-catalog,web-urls,guards,admin-roles) untouched (contract:checkGREEN).@d3ro/i18n(Vitest 2 files / 25 tests PASS): extractedsrc/shared.ts(I18nStorage,noopI18nStorage,safeLoadStoredLocale,safeSaveStoredLocale, non-finite date guard) shared byindex.tsxandindex.native.tsx, withcancelled,userChangedLocaleRef, andlocaleRevisionRefguards blocking stale async storage loads from overwriting explicitsetLocale()changes (__tests__/i18n-provider.test.tsx10).@d3ro/ui&@d3ro/ui-native&@d3ro/api-client:@d3ro/uiextractedsrc/components/ds/wave-math.tsand cached canvasLinearGradientinstances inAudioVisualizerBar.tsxandGradientWave.tsx(__tests__/wave-visualizer.test.tsx3, Vitest 2 files / 7 tests PASS);@d3ro/ui-nativeextractedresolveContentMaxWidth(responsive.tsx) and guarded non-finite bars (WaveBars.tsx);@d3ro/api-client/src/transcribe.tsclamped negative latencies (Vitest 4 files / 31 tests PASS).