$ show tw93/MiaoYan
MiaoYan is a local-first macOS Markdown note-taking application (Swift 6, AppKit, macOS 12+) that treats notes as plain .md/.markdown/.txt files in a user-selected folder. In production it is a desktop editor: an FSEvents watcher detects external file changes, cmark-GFM renders Markdown through a single pipeline, and a WebKit preview surface (vendored KaTeX, Mermaid, PlantUML, Markmap, Reveal.js) handles rendering. The app ships wikilinks/backlinks, version history, CJK-aware typography normalization, PDF/HTML/PNG/PPT export, and URL routing (miaoyan://, nv://, nvalt://). There is no server component — cloud sync is deliberately delegated to iCloud Drive/Nutstore/Dropbox. Distribution includes Sparkle auto-update, Homebrew, App Store, a bash CLI (miao), and an agent-facing SKILL.md. The architecture is a monolith with two UI shells: the primary AppKit storyboard window (ViewController, EditTextView, SidebarProjectView) and an in-progress SwiftUI shell launched via -MiaoYanShell YES. Both shells share the Business/ layer, with dedicated parity tests keeping them aligned. A Foundation-only MiaoYanCore package holds platform-agnostic text logic (frontmatter parsing, multi-encoding detection, search matching, preview extraction) shared with an iOS build — the cleanest architectural boundary in the repo. Core domain services include Storage/Note/Project models, NoteVersionManager, WikilinkIndex, CloudSyncManager (NSMetadataQuery-based), and debounced atomic saves using renamex_np RENAME_SWAP. Engineering strengths: an extensive regression-driven test suite (26+ files) covering real incident history (editor buffer ownership #543, storage relocation, save debounce, shell parity), strict CI where SwiftLint and swift-format warnings block merges, tiered highlighting for very large files, xattr-based note metadata, legacy encoding support (UTF-8/UTF-16/GB18030/Big5/CP1252), and localization in five languages. Notable weaknesses: ViewController is a god-class accumulating layout/keyboard/storage/preview/PPT logic; the dual-UI shell carries ongoing parity risk; saveCloudPins/restoreCloudPins are empty stubs (cloud pin sync is unimplemented); large hand-maintained regex sets in NotesTextProcessor; UserDefaults key sprawl; two Package.resolved manifests with a Sparkle version mismatch (2.8.0 vs 2.9.0); and a large vendored DownView.bundle JS payload that is an update/maintenance burden.
The LLM identified 6 files worth highlighting for reuse:
The data-format boundary of the app: decodes note files across five encodings (UTF-8, UTF-16, GB18030, Big5, CP1252) with structured fallback so legacy CJK notes never corrupt on read. Foundation-only, zero UI coupling, covered by the package's swift test target. Extractable into any tool that must ingest legacy CJK text files safely.
Pure string pipeline that inserts pangu spacing between CJK and Latin/digit runs, normalizes punctuation width, converts ASCII ellipsis to the CJK ellipsis glyph, and protects code/math/link spans from transformation. No AppKit imports and covered by dedicated unit tests (TypographyCleanerTests). Any product handling mixed CJK/Latin text (editors, CMS, chat, export pipelines) can lift it as-is.
Dependency-free HTML→Markdown converter used for pasteboard and import flows. Performs block-structure detection (headings, lists, code blocks, links) without any third-party library and without importing internal app modules. A drop-in utility for any Markdown tooling that must accept rich-text paste.
Classifies installed fonts by script coverage (CJK vs Latin vs monospace), caches the classification per font, provides localized display names, and synthesizes CSS font stacks for the WebKit preview renderer. Environment-tolerant (tests skip missing font families). Reusable in any macOS font picker or HTML/CSS generation pipeline needing CJK-aware font stacks.
FSEvents-based directory watcher that converts raw kernel events into classified app events, with conflict-backup path filtering and coordination with the app's save-debounce logic. Encapsulates a recurring macOS problem — detecting external file changes without polling — in a small self-contained helper that could be repurposed for any document-syncing or folder-monitoring tool.
Hand-built AppKit control kit for the preferences window: capsule dropdowns, pill buttons, switches, a tab bar, and a keyboard-shortcut recorder — all custom-drawn without storyboards. Self-contained enough to be lifted into any macOS settings panel, and demonstrates non-trivial custom drawing, hit-testing, and focus handling.