d3ro-voice/docs/map/03-shared-packages.md
Yun Chan 876e72ea2f
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
docs(wave7): record peer-swarm bug fixes, metrics, and map sync
2026-11-14 15:41:48 +09:00

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-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).