Migration Plans

Relevant source files

The following files were used as context for generating this wiki page:

• plans/migration.md
• plans/migration.editor.md
• plans/migration.inventory.md
• plans/migration.editor.tiptap.md
• plans/migration.qa.md

The migration plans outline the transition of the Augenblick application from its original Svelte 5 and bits-ui implementation to a React-based architecture. The primary goal is to achieve complete feature parity while upgrading the UI implementation using shadcn/ui v4 and transitioning the editor from Milkdown to Tiptap.

This process ensures that existing user data is preserved by maintaining the Rust backend and app identifier while refactoring the frontend shell, state management, and component library. The migration is divided into distinct phases covering baseline capture, architecture scaffolding, data layer porting, and comprehensive quality assurance.

Sources: plans/migration.md:1-12, plans/migration.md:37-43

Target Architecture

The React-based architecture is designed to mirror the original Svelte module boundaries to ensure rapid parity before further refactoring. It relies on a typed Tauri invoke wrapper for backend communication and centralized state management via stores.

Module Mapping

The migration involves mapping existing Svelte modules to React equivalents:

Svelte Component/Module	React Equivalent	Purpose
notes.ts (Store)	src/stores/notesStore.ts	Handles persistence, autosave timers, and reordering.
+layout.svelte	src/app/AppShell.tsx	Main layout, titlebar, and global hosts (Toast/Dialog).
Editor.svelte	src/features/editor/Editor.tsx	Tiptap-based markdown editing.
pageActions.ts	src/routes/pageActions.ts	Pure functions for dialogs and file operations.
dialog.ts	src/stores/dialogStore.tsx	Promise-based dialog management.

Sources: plans/migration.md:45-66, plans/migration.inventory.md:1-15

State Management Requirements

The notesStore must implement specific behaviors to match the original application:

• App State Persistence: Tracks sidebarWidth, selectedNoteId, and viewMode with a 250ms debounce.
• Draft Autosave: Note-specific timers with a 500ms idle debounce.
• Undo/Redo: Depth-limited (20) stacks for reordering operations per section.
• Caching: Content is cached by ID to prevent redundant note_get calls.

Sources: plans/migration.md:68-75, plans/migration.inventory.md:79-115

Migration Phases

The migration is executed in seven distinct phases to manage risk and ensure data integrity.

Phase 1: Backend & Data Preservation

The Rust backend is preserved to ensure existing SQLite databases (augenblick.db) and markdown files in drafts/ or trash/ remain compatible. Key tasks include copying the src-tauri directory, updating tauri.conf.json for the React build path, and maintaining macOS entitlements for security-scoped bookmarks.

Sources: plans/migration.md:113-128, plans/migration.inventory.md:17-40

Phase 4: UI & Editor Implementation

The UI utilizes Tailwind v4 and shadcn/ui v4. A critical component of this phase is the editor transition.

Editor Migration: Milkdown to Tiptap

The editor is being migrated to an OSS-only Tiptap stack to reduce complexity and remove custom hacks.

Feature	Milkdown (Current)	Tiptap (Target)
Engine	Commonmark/GFM	@tiptap/markdown
UI Layers	Slash Menu, Selection Toolbar	Dropped (Constraint)
Features	Find/Replace, Task Hitbox	Dropped (Constraint)
Extensions	Custom ProseMirror Plugins	Tiptap StarterKit + OSS Exts

Feature Parity Inventory

To meet the "Definition of Done," the following core behaviors must be replicated:

Note Lifecycle & Trash

Notes follow a strict lifecycle from Draft to Saved or Trash. Drafts are stored internally, while Saved notes are linked to external .md files.

• Auto-Expiry: Unpinned notes move to trash after a configurable period (default 7 days).
• Trash Retention: Trashed notes are permanently deleted after a set duration (default 30 days).
• No-Confirm Trash: Trashing active notes is non-destructive and generally does not require a confirmation dialog unless the note is a "Dirty Saved" note.

Sources: plans/migration.inventory.md:129-165, plans/migration.qa.md:1-15

Window & Chrome Parity

The application must maintain specific desktop behaviors:

• Titlebar Inset: 38px inset for macOS-style traffic lights.
• Drag Region: A dedicated data-tauri-drag-region at the top of the window (height: 52px).
• Window State: The window-state plugin must be used to restore position and size, with logic to clamp the window within visible monitor bounds.

Sources: plans/migration.md:180-192, plans/migration.inventory.md:255-275

Quality Assurance

The migration concludes with a manual QA gate based on the parity inventory.

Core Checklist

• Hotkeys: Cmd+N (New), Cmd+S (Save), Cmd+P (Pin), and Cmd+W (Trash) must function exactly as in the Svelte version.
• Pinning Limits: Users are restricted to a maximum of 5 pinned notes; the 6th attempt must trigger an error toast.
• Data Integrity: Opening an existing markdown file via Cmd+O must select the existing note if it already exists in the database rather than creating a duplicate.

Sources: plans/migration.qa.md:7-40, plans/migration.inventory.md:167-175

The migration plans prioritize technical accuracy and behavioral consistency to ensure Augenblick users experience no loss of functionality or data during the transition to the React ecosystem.