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

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