How vld-b/bismuth works
1. What this repo is
- Bismuth is a Windows 11 note-taking and PDF annotation app built as a packaged desktop app.
- The UI is XAML-based and optimized for keyboard, pen, and touch/finger input.
2. Top-level project split
- WID/ is the main application: windows/pages, editing surface, notebook UI, persistence, and app logic.
- Shared/ contains reusable XAML controls and color-picking helpers used across the app.
- AppSettings/ holds strongly-typed app configuration and config migration logic.
- The solution is built from a single Visual Studio solution, with a GitHub Actions workflow for .NET builds.
3. Application shell and navigation
- App.xaml / App.xaml.cs are the app entry point.
- ExtendedSplashScreen is the startup experience, backed by a Lottie animation asset.
- MainPage is the central host that likely routes the user into notebooks, canvas editing, and settings.
4. Notebook-centric domain model
- The app is organized around notebooks and pages, not around a generic document editor.
- NotebookList, NotebookPage, NotebookSearchResult, PageThumbnail, and CreateNewNotebookOptions define the notebook lifecycle:
- browsing notebooks
- opening a notebook
- creating a new notebook
- showing search results
- rendering page previews/thumbnails
5. Canvas and annotation subsystem
- CanvasPage is the core editing surface for ink and page content.
- CustomInkToolbarTool, ManipulateInkRect, and OnPageImage / OnPageText support mixed annotation workflows:
- freehand ink
- selecting/manipulating ink regions
- placing images on a page
- placing/editing text on a page
- IOnPageItem indicates a common abstraction for objects that can exist on a page.
6. Input and visual tools
- Shared/ColorPickerButton.xaml(.cs) and Shared/SimpleColorPicker.cs provide reusable color selection for ink or page elements.
- This is important because the app supports stylus-driven editing, where color and tool selection are part of the main workflow.
- MenuElement and related UI pieces likely represent editor commands/tools in the in-app UI.
7. State management and editing history
- UndoObject and UndoRedoSystem form the editing history layer.
- The data flow is likely: user interaction on the canvas → mutation of page content → push undo record → allow reversal/restoration.
- This is a key architectural boundary between transient UI events and durable document state.
8. Persistence and file operations
- FileConfig, PendingFileOperationsSystem, and SavingFileDialog show that file handling is explicit rather than hidden behind a framework.
- The app appears to manage notebook/document files directly, with deferred or queued file actions when necessary.
- NotebookUpgrader and SettingsConfigUpgrader indicate schema/version migration for stored notebooks and config files.
9. Settings and configuration
- SettingsPage is the user-facing settings UI.
- AppSettings/Settings.cs defines the app’s configuration model.
- Configuration is separated from the main app code, which helps keep user preferences and persisted app state distinct from notebook content.
10. Assets and packaging
- Package.appxmanifest shows this is packaged for the Microsoft Store / Windows app model.
- The app includes startup animation assets (anim_startup.json and .lottie), which suggests polished launch UX.
- PRIVACYPOLICY.md reinforces that this is a consumer app with a store-style distribution model.
11. Architectural boundaries to draw
- UI layer: XAML pages and controls in WID/ plus shared controls in Shared/.
- Editing layer: canvas, ink tools, page item manipulation, undo/redo.
- Document layer: notebook/page/search/thumbnail structures and migrations.
- Configuration layer: settings objects and settings migration.
- File system layer: config, pending operations, save dialogs, and upgrader logic.
12. Primary runtime flow
- Launch app → splash screen → main page → notebook selection/opening → canvas editing.
- While editing, user actions update page items and are captured by undo/redo.
- Changes eventually pass through the file/persistence layer and may be upgraded when older notebook/settings formats are encountered.
13. Tooling and delivery
- The presence of .github/workflows/dotnet.yml indicates automated build validation in CI.
- Overall, this is a Windows-native, XAML-based note and annotation application with a strong separation between editor UI, document state, and persistence.
Main entry points: CanvasPage.xaml Canvas · NotebookList.xaml Notebook List · App.xaml App · ExtendedSplashScreen.xaml Splash
Components 23
App Shell
Startup and top-level navigation.
Notebook Domain
Notebook browsing, page previews, and page abstractions.
- Notebook List · Notebook browsing and opening surface.
WID/NotebookList.xaml - Notebook Page · Notebook page container and page-level UI.
WID/NotebookPage.xaml - Search Result · Notebook search result presentation.
WID/NotebookSearchResult.xaml - New Notebook · Options for creating a notebook.
WID/CreateNewNotebookOptions.xaml - Page Thumbnail · Page thumbnail and preview rendering.
WID/PageThumbnail.xaml - Page Model · Common page-item interface and page template pattern.
WID/IOnPageItem.cs
Editing Surface
Canvas, ink tools, page objects, and undo history.
- Canvas · Core ink and page-content editing surface.
WID/CanvasPage.xaml - Ink Tool · Custom ink toolbar tool selection and behavior.
WID/CustomInkToolbarTool.xaml - Ink Manipulator · Rectangle-based manipulation of ink regions.
WID/ManipulateInkRect.xaml - Page Image · Image object placed on a page.
WID/OnPageImage.xaml - Page Text · Text object placed on a page.
WID/OnPageText.xaml - Undo System · Undo/redo state and edit history records.
WID/UndoRedoSystem.cs
Persistence
File operations and upgrade/migration logic.
Settings
User configuration model and settings UI.
- Settings Model · Strongly-typed application settings state.
AppSettings/Settings.cs - Settings Page · User-facing settings screen.
WID/SettingsPage.xaml
Shared Controls
Reusable XAML controls and color helpers.
- Color Picker · Reusable color selection controls and helpers.
Shared/ColorPickerButton.xaml
Delivery
Packaged app manifest, startup assets, and CI.
- Package · Packaged Windows app manifest.
WID/Package.appxmanifest - Startup Assets · Launch animation assets for splash experience.
WID/Assets/anim_startup.json - CI Build · GitHub Actions build validation for .NET.
.github/workflows/dotnet.yml
Connections 25
- App → Splash: launches · App startup opens the splash experience first.
- Splash → Main Page: navigates · Startup transitions into the main shell.
- Main Page → Notebook List: opens · Main shell routes into notebook browsing and opening.
- Main Page → Settings Page: opens · Main shell exposes application settings.
- Notebook List → New Notebook: creates · Notebook browsing includes notebook creation flow.
- Notebook List → Search Result: searches · Notebook UI surfaces search results.
- Notebook List → Page Thumbnail: shows · Notebook/page UI uses page previews.
- Notebook List → Notebook Page: opens · Opening a notebook leads into notebook page views.
- Notebook Page → Canvas: hosts · Notebook pages embed the editing surface.
- Canvas → Ink Tool: selects · Canvas uses ink toolbar tools for editing modes.
- Canvas → Ink Manipulator: manipulates · Canvas uses selection handles for ink regions.
- Canvas → Page Image: hosts · Canvas can place images on a page.
- Canvas → Page Text: hosts · Canvas can place and edit page text.
- Canvas → Undo System: records · Canvas mutations are captured in undo/redo history.
- Page Image → Page Model: implements · Page items share a common page-item abstraction.
- Page Text → Page Model: implements · Page items share a common page-item abstraction.
- Undo System → File Ops: persists · History and document changes eventually flow to file operations.
- File Ops → Upgraders: upgrades · File handling invokes migration for older content or config.
- Settings Page → Settings Model: edits · Settings UI is backed by the typed settings model.
- Settings Model → Upgraders: migrates · Configuration changes are versioned and upgraded.
- Color Picker → Ink Tool: supports · Shared color selection feeds ink/tool workflows.
- Color Picker → Settings Page: supports · Shared color controls can be reused in settings UI.
- Splash → Startup Assets: uses · Splash screen is backed by startup animation assets.
- App → Package: packages · Application is delivered as a packaged Windows app.
- App → CI Build: validated by · Repository includes automated .NET build validation.