284 lines
21 KiB
Markdown
284 lines
21 KiB
Markdown
# Incido
|
||
|
||
> **Your notes. Your device. Your terms.**
|
||
|
||
Incido is a privacy-first, on-device note-taking application for Android.
|
||
All data stays on your device by default — no accounts, no cloud, no
|
||
trackers.
|
||
|
||
This repository contains the **v0.3.6.0** release: a single-user, offline
|
||
note app with hashtags, favourites, full-text search, colour-coded
|
||
notes, photo and file attachments, share-into from other apps and the
|
||
web, at-rest AES-256-GCM encryption with screenshot blocking, PIN /
|
||
biometric lock, encrypted backup and restore, and an exportable
|
||
encryption key for device migrations. The architecture is multi-module
|
||
Android today and is structured so iOS / Desktop ports can happen later
|
||
without UI rewrites.
|
||
|
||
**Current release:** v0.3.6.0 (see [Changelog](#changelog) below).
|
||
|
||
> **Version scheme (from v0.3.0.0 onwards):** `MAJOR.MINOR.MAINTENANCE.EMERGENCY` —
|
||
> e.g. `0.3.0.0`. `MAJOR.MINOR.MAINTENANCE` are normal release numbers;
|
||
> `EMERGENCY` is non-zero only for hotfixes shipped out-of-band.
|
||
> `versionCode` is a monotonic int and always +1 per release.
|
||
> An empty MAINTENANCE/EMERGENCY slot is written as `0`.
|
||
> The build refuses to compile if `versionName` doesn't match this shape.
|
||
|
||
---
|
||
|
||
## Features
|
||
|
||
### v0.3.0.0 highlights
|
||
|
||
- **Hashtags.** Tag any note with up to 5 hashtags. Tags are always
|
||
visible as chips above the editor text field; tap ✕ to remove. Tap
|
||
`#` (or `+ add`) to open a sheet with autocomplete suggestions from
|
||
your existing tags. Hashtags are searchable from the list (typing
|
||
`work` finds notes containing the word *and* notes tagged `#work`).
|
||
- **Bolder colour accent on list cards.** Each colour-tagged note now
|
||
gets a 14 dp vertical gradient stripe on the left, a subtle 12 %
|
||
tinted card background, and a 10 dp solid colour chip in the
|
||
top-right — so different-coloured notes are visually distinct at a
|
||
glance without you needing to focus on the stripe.
|
||
- **Navigation drawer.** Hamburger top-left opens a drawer with
|
||
**Home**, **Favorites**, **Untagged**, a divider, then a live scrollable
|
||
list of the most-recently-used hashtags. Tap any entry to filter the
|
||
list to just those notes.
|
||
- **Centred app-bar title.** Both the list screen (`Incido`) and the
|
||
editor (`Edit note` / `New note`) now centre their titles via
|
||
Material 3's `CenterAlignedTopAppBar`.
|
||
- **New version scheme.** All version bumps from now on follow the
|
||
`MAJOR.MINOR.MAINTENANCE.EMERGENCY` pattern; the build refuses anything
|
||
that doesn't match.
|
||
|
||
### v0.2.0.0
|
||
|
||
- **Favourites.** Tap the star icon on any card to pin it to the top of
|
||
the list.
|
||
- **Full-text search.** Tap the search icon in the top app bar; the list
|
||
filters live as you type.
|
||
- **Color-coded notes.** Pick from six preset accent colours in the
|
||
editor; each list card gets a 4 dp vertical stripe.
|
||
- **Inline checklists.** Lines beginning with `- [ ]` or `- [x]` show
|
||
open/done counts on the card preview.
|
||
- **Discard-confirm dialog.** Closing the editor with unsaved changes
|
||
prompts `Discard changes?` (works for both Back arrow and hardware
|
||
back gesture).
|
||
- **Release signing** — dev keystore in `keystore/`, `assembleRelease`
|
||
produces a v2-signed APK out of the box.
|
||
|
||
### v0.2.0.1 (hotfix)
|
||
|
||
- **Search icon actually opens the search bar.** v0.2.0.0's
|
||
search-active flag was on a separate `StateFlow` the composable never
|
||
observed; folded into `uiState` so tapping the icon now lights up the
|
||
field.
|
||
|
||
### v0.1.1.0
|
||
|
||
- **Editor respects the soft keyboard.** `Scaffold` unions
|
||
`WindowInsets.systemBars` with `WindowInsets.ime` so the text field
|
||
shrinks above the keyboard. `adjustResize` set as pre-Android-15
|
||
fallback.
|
||
- **List cards now show a title + body preview.** First non-empty line
|
||
= title; remainder = body preview (max 2 lines, ellipsised).
|
||
Empty notes display as "Untitled".
|
||
|
||
### v0.1.0.0
|
||
|
||
- Create, edit, and delete plain-text notes
|
||
- ObjectBox-backed persistence ([objectbox.io](https://objectbox.io/))
|
||
- Material 3 UI with dynamic color (Android 12+), dark/light follows system
|
||
- Fully offline — no `INTERNET` permission
|
||
- Multi-module Android project (Android today, iOS/Desktop-ready later)
|
||
|
||
---
|
||
|
||
## Roadmap
|
||
|
||
See [`Incido Development Plan.txt`](./Incido%20Development%20Plan.txt) at
|
||
the repository root for the canonical backlog, including on-device ML,
|
||
cross-platform ports, end-to-end sync, and security features.
|
||
|
||
---
|
||
|
||
## Changelog
|
||
|
||
| Version | Date | Highlights |
|
||
|-----------|------------|------------|
|
||
| 0.3.6.0 | 2026-08-19 | **Share webpages to Incido.** Sharing a page from your browser (Share → Incido) now creates a note with the page title on the first line and the URL below — fully offline (the title comes from the browser's share data, Incido never touches the network). **Export encryption key.** Settings → Security gains "Export encryption key" — saves the AES-256 key that protects your encrypted notes to a passphrase-protected `.inckey` file for device migrations. **Import encryption key** restores that key on a fresh install, with a clear warning before the current key is replaced. |
|
||
| 0.3.5.1 | 2026-08-17 | **"Encrypted" badge now appears the moment you flip the switch.** A race in `EncryptionVerifier.checkNow()` could silently drop the post-migration verification, leaving cards without the badge until a second toggle; replaced with a serializing Mutex so every check runs in invocation order. **"Encrypted" indicator is now a single lock icon next to the date** — consistent position on every card instead of a centred "lock + label" group at the bottom. |
|
||
| 0.3.5.0 | 2026-08-17 | **Real at-rest encryption.** Note text and attachment bytes are now AES-256-GCM encrypted in place the moment you toggle "Encrypt notes at rest" — no restart required; keyed by the Keystore-wrapped 32-byte key. **Verified "Encrypted" badge.** Every encrypted note is trial-decrypted on app open and after each migration; only verified notes get the lock badge. **Block screenshots (default ON).** New toggle in Settings → Security prevents screenshots, screen recording, and app-switcher previews while Incido is open. |
|
||
| 0.3.4.0 | 2026-08-17 | **Attachment indicator on note cards** — a paperclip icon now appears on the right edge of every card that carries an attachment. **Light-theme readability over image thumbnails** — cards with a dark photo background now force light text/icon colours over the image so notes stay readable in Light mode. **Auto-Lock "Immediately" no longer locks during file pickers** — attaching a file, taking a photo, viewing an attachment, or exporting/importing a backup no longer destroys your in-progress note. |
|
||
| 0.3.3.8 | 2026-08-17 | **Designed Incido artwork is now the app icon.** The glass shield + fountain-pen nib replaces the placeholder glyph on the home screen, app drawer, and adaptive-icon layers. |
|
||
| 0.3.3.7 | 2026-08-17 | **Biometric auto-launch.** When Biometric is your active lock method, the fingerprint / face reader now opens automatically when the lock screen appears — no extra tap on "Authenticate" needed. |
|
||
| 0.3.3.6 | 2026-08-17 | **Card height tuned for real devices.** The fixed card height from v0.3.3.5 proved too tall on real devices; reduced by ~15% (now 143.dp). |
|
||
| 0.3.3.5 | 2026-08-17 | **Fixed card height.** All note cards now have a single fixed height (168.dp), so untagged notes no longer look shorter than tagged ones; timestamp pinned to the bottom via a weighted spacer; hashtag row still hidden when empty; left colour stripe spans the full card height. |
|
||
| 0.3.3.4 | 2026-08-17 | **Favourite star no longer overlaps the overflow button.** Star is now anchored to the card's bottom-right corner (same column as the top-right ⋮), so the two controls no longer collide. |
|
||
| 0.3.3.3 | 2026-08-17 | **Importing an encrypted backup no longer crashes.** The passphrase was being wiped between the preview step and the confirm dialog's Import button; now retained across the confirmation step, with proper try/catch around preview/import so failures surface a snackbar ("Import failed. Check the file and passphrase." / "Could not read backup file.") instead of crashing. |
|
||
| 0.3.3.2 | 2026-08-17 | **White-on-white lock screen in dark mode fixed.** `PinEntryScreen` is now wrapped in a themed Surface so it always paints its own theme-aware background. **Biometric unlock hang fixed.** Authentication is now fully asynchronous (BiometricPrompt callbacks run on the main executor) instead of busy-waiting on the main thread. Device-credential fallback preserved. |
|
||
| 0.3.3.1 | 2026-08-17 | **"Encrypt notes at rest" toggle now correctly greyed out** until Security is on and you've chosen either PIN or Biometric — with a subtitle explaining the requirement. **"Enable Security" no longer requires a PIN first.** The master switch just flips on; PIN / Biometric / Encrypt sub-toggles were already gated. **Importing an encrypted backup now opens a dedicated passphrase dialog** (single field, no policy check) — wrong passphrase surfaces "Incorrect passphrase." via snackbar. |
|
||
| 0.3.3.0 | 2026-08-17 | **Lock mode as a single choice.** Security now exposes two mutually-exclusive toggles (PIN and Biometric) — either alone is enough to lock; Biometric no longer requires PIN first. New "Reset PIN" row appears when PIN is active; lock screen shows only the biometric button when no Incido PIN is set. **Encrypted-import passphrase prompt.** Selecting an encrypted backup opens the passphrase dialog first and surfaces "Incorrect passphrase." on mismatch. **Press-and-hold note card menu.** The inline delete button is gone; long-press a card (or tap the ⋮ button) to open a DropdownMenu with Delete — ready for future actions like Share. |
|
||
| 0.3.2.0 | 2026-08-15 | **New Settings screen** (Untagged → Settings in the nav drawer) with Appearance, Security, Backup & Restore, and About sections. **At-rest encryption.** ObjectBox store is opened with a 32-byte AES-256 key wrapped by the Android Keystore; toggling the switch generates / deletes the key and surfaces a "Re-encrypting notes…" dialog. **PIN lock + biometric.** 4–6 digit PIN (PBKDF2-hashed, 100k iters, constant-time compare) with optional fingerprint / face unlock; cold launch + auto-lock timeout gate. **Backup / Import / Export.** JSON codec with Base64 attachment bytes; encrypted variant uses AES-256-GCM + PBKDF2(passphrase, 200k iters) with a Generate button + Copy to clipboard. Passphrase policy: 12–32 chars, ≥1 digit, ≥1 special. **Release notes dialog** — tap the version number on the About card. Adds `USE_BIOMETRIC` + `USE_FINGERPRINT` permissions (still no INTERNET). |
|
||
| 0.3.1.2 | 2026-08-15 | Hotfix for three issues found in v0.3.1.1 testing: **card thumbnails are actually visible now** — the v0.3.1.1 layout had the thumbnail Image as a sibling of the Card, so the Card's opaque `containerColor` was drawn on top and the image was completely hidden; the architecture is restructured so the Image + dark scrim live INSIDE the Card, and `containerColor = Color.Transparent` when a thumbnail is present (plain notes still get the existing tinted/surface background). **Camera photos honour EXIF orientation** — `NoteRepositoryImpl.normalizeImageOrientation(bytes)` runs at storage time inside `addAttachment` (guarded `if (mimeType.startsWith("image/"))`); reads EXIF `Orientation`, rotates the bitmap, re-encodes as JPEG quality 92, and stores the corrected bytes so every render path (editor thumbnail, card thumbnail, full-screen viewer) sees the photo the right way up. **Non-image attachments open in the system viewer** — `AttachmentThumbnail.onClick` now branches on `isImage`: image taps still go to the in-app full-screen viewer; non-image taps write the bytes to a `cacheDir` temp file, get a `FileProvider` URI, and launch `Intent.ACTION_VIEW` with `FLAG_GRANT_READ_URI_PERMISSION` (the previous unconditional viewer path silently failed for PDFs/MP3s/etc. with a stuck "Loading…"). `file_paths.xml` already exposes `cacheDir` via `<cache-path>`, so no manifest change was needed. Attaching arbitrary file types from the paperclip icon was already shipped in v0.3.1.1 (the `*/*` intent filters) — no code change here, just called out so it's clear what was already in place. |
|
||
| 0.3.1.1 | 2026-08-15 | Hotfix for five issues found in v0.3.1.0 testing: persisted image attachments now render a thumbnail in the editor strip (previously fell through to the file-type placeholder because bytes weren't loaded) — `AttachmentThumbnail` lazy-loads bytes from the DB via `produceState` + `repository.getAttachmentBytes()`. Card thumbnails are more visible — alpha bumped 0.45 → 0.70 and the dark scrim dropped 0.18 → 0.08; also `clipToBounds()` so the image can't bleed past the card's rounded corners. Share-into from webpages now opens a fresh editor — `MainActivity.handleShareIntent()` stashes the share text synchronously before launching the async image-byte I/O, so the Compose tree's `LaunchedEffect(Unit)` always finds a payload on first composition. Share menu now offers Incido for any file type (PDF, MP3, video, archives) — added `<data android:mimeType="*/*" />` to both `ACTION_SEND` and `ACTION_SEND_MULTIPLE` intent filters. Editor top-bar title shortened to "Edit" / "New" so it fits on one line with the new icon row. |
|
||
| 0.3.1.0 | 2026-08-15 | **Context-aware search** — on the Favorites and Untagged pages, the search icon is now visible and a typed query intersects with the active filter (search only favourites on Favorites, only untagged notes on Untagged). On Home, search spans everything. **Photo / File attachments** — the editor now has Camera (camera icon) and Attach File (paperclip icon) buttons. Photos are captured via `MediaStore.ACTION_IMAGE_CAPTURE` (with a transient `FileProvider` outbox; bytes live in the database, the temp file is deleted) and files via `ACTION_OPEN_DOCUMENT`. Attachments are stored as `ByteArray` columns inside ObjectBox — no filesystem paths to manage. Each note's attachments show up as a thumbnail strip in the editor with a in the top-right corner to remove. Tapping a thumbnail opens a full-screen viewer with pinch-to-zoom + pan (`Modifier.transformable`) and a close button. **Card thumbnails** — notes with image attachments show the first image as a (alpha-blended, scrimmed) background on the list card. **Share-into** — the app accepts `ACTION_SEND` (text + image) and `ACTION_SEND_MULTIPLE` (multiple images) from other apps. Inbound bytes are copied into a process-singleton `SharedIntentBuffer` and pre-filled into a new-note editor. Adds the `CAMERA` permission — still no `INTERNET`, still fully offline. |
|
||
| 0.3.0.5 | 2026-08-15 | Hotfix: `NoteEditorViewModel.save()` still did upsert + per-tag `addHashtag` in three separate writes, so the drawer's `hashtagUsageSnapshot()` could read a transient empty `xrefBox` between the `tagBox.put` and the `xrefBox.put` and leave `emptyList()` stuck in the StateFlow (toggling the favourite star worked around it because `setFavorite` re-touches `noteBox`). New `NoteRepository.saveNoteWithHashtags()` wraps upsert + hashtag reconciliation in a single ObjectBox transaction via `boxStore.callInTx { ... }`, so the per-box observers fire **once** at commit time with the final state. New hashtags now appear in the drawer's Recent Tags list the moment a note is saved — no workaround required. |
|
||
| 0.3.0.4 | 2026-08-14 | Hotfix: `observeHashtagsByRecentUse()` now subscribes to **all three** boxes (`noteBox`, `tagBox`, `xrefBox`) — adding a brand-new hashtag only touches `tagBox` + `xrefBox`, so the previous single-`noteBox` subscription missed those updates and the drawer's Recent Tags list only refreshed when something else touched `noteBox` (e.g. toggling the favourite star). Now the new tag is visible immediately after saving the note. |
|
||
| 0.3.0.3 | 2026-08-14 | Hotfix: batched hashtag-usage lookups in `NoteRepositoryImpl.hashtagUsageSnapshot()` (one `Box.get` per distinct noteId and tagId, not per xref) and dropped the manual `trySend(snapshot())` in `observeHashtagsByRecentUse()` — the ObjectBox observer's first fire is now the sole source. The drawer's Recent Tags list fills in well under a second instead of taking minutes. |
|
||
| 0.3.0.2 | 2026-08-14 | Hotfix: dropped the redundant leading `#` from the AddTagSheet placeholder (was `#tag-name`, now `hashtag-name` — the leading `#` icon in the field already signals the format). |
|
||
| 0.3.0.1 | 2026-08-14 | Urgent UI polish: editor hashtag row moved to the bottom (and hidden when empty), `+ add` chip removed (use `#` icon in top bar), colour picker centred horizontally, list-card dog-ear colour accent replaces the small circle chip, list cards show a hashtag row (with `+N` abbreviation when capped). |
|
||
| 0.3.0.0 | 2026-08-14 | Hashtags (visible chips on editor, 5-tag cap, autocomplete) + bolder colour accent + nav drawer (Home / Favorites / Untagged + recent tags) + centred app-bar title + new version scheme |
|
||
| 0.2.0.1 | 2026-08-14 | Hotfix: search icon now actually opens the search bar |
|
||
| 0.2.0.0 | 2026-08-14 | Polish + favourites, search, colours, checklists, discard dialog, release signing |
|
||
| 0.1.1.0 | 2026-08-14 | Editor IME fix + title/body on list cards |
|
||
| 0.1.0.0 | 2026-08-14 | First MVP: list + editor, ObjectBox, Material 3 |
|
||
|
||
---
|
||
|
||
## License
|
||
|
||
Incido is released under the **GNU General Public License v3.0**
|
||
(GPL-3.0). See [`LICENSE`](./LICENSE) for the full text and
|
||
[`NOTICE`](./NOTICE) for attributions.
|
||
|
||
---
|
||
|
||
## Project Layout
|
||
|
||
```
|
||
incido/
|
||
├── app/ # Android entry point (manifest, MainActivity)
|
||
├── composeApp/ # Shared Compose UI module
|
||
├── core/
|
||
│ ├── domain/ # Pure-Kotlin domain models + repository interface
|
||
│ └── data/ # ObjectBox-backed repository implementation
|
||
├── gradle/ # Version catalog (libs.versions.toml) + wrapper
|
||
├── keystore/ # Release signing (gitignored *.jks, README kept)
|
||
├── .gitea/ # Gitea Actions workflow + issue/PR templates
|
||
├── CONTRIBUTING.md
|
||
└── LICENSE
|
||
```
|
||
|
||
---
|
||
|
||
## Build Instructions
|
||
|
||
### Prerequisites
|
||
|
||
| Tool | Version | Notes |
|
||
|------|---------|-------|
|
||
| JDK | 17 (LTS) | `java -version` |
|
||
| Android SDK | API 35 + build-tools 35.0.0 | Install via `sdkmanager` |
|
||
| Gradle | 8.10.2 | Wrapped — `./gradlew` downloads it on first run |
|
||
| Kotlin | 2.0.21 | Bundled with the Gradle build |
|
||
|
||
You do **not** need Android Studio. The CLI build works.
|
||
|
||
### 1. Configure `local.properties`
|
||
|
||
Create `local.properties` at the project root (already gitignored):
|
||
|
||
```
|
||
sdk.dir=/path/to/your/Android/sdk
|
||
```
|
||
|
||
On Linux this is typically `~/Android/sdk`.
|
||
|
||
### 2. Accept SDK licenses (one-time)
|
||
|
||
```bash
|
||
yes | $ANDROID_HOME/cmdline-tools/latest/bin/sdkmanager --licenses
|
||
```
|
||
|
||
### 3. Build the debug APK
|
||
|
||
```bash
|
||
./gradlew assembleDebug
|
||
```
|
||
|
||
The APK is written to `app/build/outputs/apk/debug/app-debug.apk`.
|
||
|
||
### 4. (Optional) Build a signed release APK
|
||
|
||
```bash
|
||
./gradlew assembleRelease
|
||
```
|
||
|
||
Uses the dev keystore at `keystore/release.jks` — see
|
||
[`keystore/README.md`](./keystore/README.md) for regeneration instructions.
|
||
**Replace this keystore with a production key before any external
|
||
distribution.**
|
||
|
||
The build will **fail** if `versionName` doesn't match
|
||
`^\d+\.\d+\.\d+\.\d+$` (the new scheme). Update `app/build.gradle.kts`
|
||
to fix.
|
||
|
||
### 5. Install on a device
|
||
|
||
```bash
|
||
adb install -r app/build/outputs/apk/debug/app-debug.apk
|
||
```
|
||
|
||
Or open the project in Android Studio and click **Run**.
|
||
|
||
---
|
||
|
||
## Remote / Gitea Setup
|
||
|
||
When your self-hosted Gitea instance is online, register the remote and
|
||
push the existing local commits:
|
||
|
||
```bash
|
||
git remote add origin https://your-gitea.example.com/yourname/incido.git
|
||
git push -u origin main
|
||
git push origin --tags # if you have any local tags
|
||
```
|
||
|
||
After the first push:
|
||
|
||
- `.gitea/workflows/build.yml` will automatically build the debug APK
|
||
on every push to `main` and on every pull request. The APK is uploaded
|
||
as a workflow artefact (`.gitea → Actions → build → Artifacts`).
|
||
- `.gitea/ISSUE_TEMPLATE/bug_report.yml` and
|
||
`feature_request.yml` will be picked up by Gitea when users open new
|
||
issues.
|
||
- `.gitea/PULL_REQUEST_TEMPLATE.md` will be auto-loaded on new PRs.
|
||
|
||
---
|
||
|
||
## Manual Smoke Test (Development Plan §7.2 + v0.3.0.0 additions)
|
||
|
||
```
|
||
[ ] Launch app — "Incido" title centred, hamburger top-left
|
||
[ ] Tap hamburger → drawer slides in with Home / Favorites / Untagged + divider + Recent tags
|
||
[ ] Tap "Favorites" → list shows only starred notes
|
||
[ ] Tap "Untagged" → list shows only notes with zero hashtags
|
||
[ ] Tap a recent hashtag → list filters to that tag
|
||
[ ] Tap "Home" → back to all notes
|
||
[ ] Open a note → chip row above text field shows current tags (empty placeholder if none)
|
||
[ ] Tap "#" icon → sheet opens, type "wo" → suggestions filter
|
||
[ ] Add a new tag → chip appears, counter goes from N/5 to (N+1)/5
|
||
[ ] Tap chip ✕ → removed
|
||
[ ] Add 5 tags, attempt 6th → Snackbar "Maximum 5 tags reached"
|
||
[ ] Force-stop + reopen → all notes + hashtags + favourites + colours persist
|
||
```
|
||
|
||
---
|
||
|
||
## Architecture (brief)
|
||
|
||
- **UI**: 100% Jetpack Compose in `composeApp/`. ViewModels expose
|
||
immutable `StateFlow<UiState>` per screen; no third-party state
|
||
management library.
|
||
- **Domain**: Pure Kotlin interfaces in `core/domain/` — the only thing
|
||
the UI sees.
|
||
- **Data**: `core/data/` provides the ObjectBox implementation. ViewModels
|
||
depend on the interface, so the data layer can be swapped (e.g., for
|
||
tests) without touching UI code.
|
||
|
||
## Contributing
|
||
|
||
See [`CONTRIBUTING.md`](./CONTRIBUTING.md). By submitting a
|
||
contribution you affirm you have the right to license it under GPL-3.0.
|