zennotesandroid

KO | EN

gitlite — search

#ios #python #agents #javascript #web #claude-code #cross-platform #graphql #hacktoberfest #android

zennotesandroid

(★ 9)

No description available.

File Explorer

ZIP Download

- - ci.yml
  - cloud-e2e.yml
- dependabot.yml
- - .gitignore
  - build.gradle
  - capacitor.build.gradle
  - proguard-rules.pro
- .gitignore
- build.gradle
- capacitor.settings.gradle
- gradle.properties
- gradlew
- gradlew.bat
- settings.gradle
- variables.gradle
- feature-graphic.png
- icon-512.png
- icon-only.png
- logo.png
- android-issue-validation-2026-09-11.md
- - fonts.css
  - ubuntu-sans-italic-cyrillic-ext.woff2
  - ubuntu-sans-italic-cyrillic.woff2
  - ubuntu-sans-italic-greek-ext.woff2
  - ubuntu-sans-italic-greek.woff2
  - ubuntu-sans-italic-latin-ext.woff2
  - ubuntu-sans-italic-latin.woff2
  - ubuntu-sans-mono-italic-cyrillic-ext.woff2
  - ubuntu-sans-mono-italic-cyrillic.woff2
  - ubuntu-sans-mono-italic-greek-ext.woff2
  - ubuntu-sans-mono-italic-greek.woff2
  - ubuntu-sans-mono-italic-latin-ext.woff2
  - ubuntu-sans-mono-italic-latin.woff2
  - ubuntu-sans-mono-normal-cyrillic-ext.woff2
  - ubuntu-sans-mono-normal-cyrillic.woff2
  - ubuntu-sans-mono-normal-greek-ext.woff2
  - ubuntu-sans-mono-normal-greek.woff2
  - ubuntu-sans-mono-normal-latin-ext.woff2
  - ubuntu-sans-mono-normal-latin.woff2
  - ubuntu-sans-normal-cyrillic-ext.woff2
  - ubuntu-sans-normal-cyrillic.woff2
  - ubuntu-sans-normal-greek-ext.woff2
  - ubuntu-sans-normal-greek.woff2
  - ubuntu-sans-normal-latin-ext.woff2
  - ubuntu-sans-normal-latin.woff2
  - UFL.txt
- - fonts.css
  - README.md
  - tikzjax.js
- - enso.png
- - cloud-layout.ts
  - cloud-sync-client.ts
  - cloud-sync-refresh.test.ts
  - cloud-sync-refresh.ts
  - cloud-sync-repository.test.ts
  - cloud-sync-repository.ts
  - cloud-sync-rescan.test.ts
  - cloud-sync-work.test.ts
  - cloud-sync-work.ts
  - events.ts
  - folder-picker.ts
  - fs-errors.test.ts
  - fs-errors.ts
  - icloud.ts
  - imported-assets.test.ts
  - imported-assets.ts
  - link-metadata.ts
  - mobile-bridge.ts
  - mobile-cloud-auth.ts
  - mobile-cloud-sync.integration.test.ts
  - mobile-cloud-sync.ts
  - mobile-direct-upload.test.ts
  - mobile-direct-upload.ts
  - native-fs.ts
  - remote-client.ts
  - remote-vault-paste.test.ts
  - remote-vault.ts
  - remote-workspace.ts
  - tikz.ts
  - vault-core.ts
  - vault-fs.ts
  - welcome-note.ts
  - widget-snapshot.test.ts
  - widget-snapshot.ts
  - widgets.ts
- - atlas-touch-shim.ts
  - attach.ts
  - deep-links.ts
  - drawer-state.ts
  - editor-keyboard-scroll.ts
  - editor-native-typing.ts
  - EditorToolbar.tsx
  - fullscreen.ts
  - gestures.test.ts
  - gestures.ts
  - image-paste-session.test.ts
  - image-paste-session.ts
  - image-paste.ts
  - mobile-layout.test.ts
  - mobile.css
  - MobileDrawer.tsx
  - MobileShell.tsx
  - nav.ts
  - note-actions.tsx
  - note-order.ts
  - note-row-gestures.ts
  - Onboarding.tsx
  - pins.ts
  - refresh.ts
  - selection-toolbar-space.test.ts
  - selection-toolbar-space.ts
  - sheet-drag.test.ts
  - sheet-drag.ts
  - sheet-handle.test.ts
  - sheet-state.ts
  - SheetHandle.tsx
  - splash-config.test.ts
  - start-screen.test.ts
  - start-screen.ts
  - SwipeRow.tsx
  - system-bars-mode.test.ts
  - system-bars-mode.ts
  - tags-empty-state.test.ts
  - tags-empty-state.ts
  - vault-settings-access.test.ts
  - vault-settings-access.ts
  - widget-links.test.ts
  - widget-links.ts
  - wikilink-touch.test.ts
  - wikilink-touch.ts
  - youtube-embed-shim.ts
- bootstrap.ts
- env.d.ts
- main.tsx
- viewport.ts
- android-ui-check.html
- android-ui-check.tsx
- ci-wait-for-emulator.sh
- cloud-direct-upload-e2e.mjs
- load-mobile-module.ts
- prepare-zennotes.sh
- upstream-check.sh
.gitignore
.zennotes-commit
capacitor.config.ts
index.html
package-lock.json
package.json
postcss.config.js
README.md
tailwind.config.js
tsconfig.json
vite.config.ts

# Use via CDN

jsDelivr

jsDelivr serves any public GitHub repository as a CDN with zero setup. Pick a version and a file to get a ready-to-paste link and snippet.

Version

File

Link

Example

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

A Capacitor shell that runs the ZenNotes product core (`packages/app-core` from
the [zennotes monorepo](https://github.com/ZenNotes/zennotes)) inside the Android System
WebView, backed by a local-first vault on the device filesystem. Implements the
architecture in `docs/specs/mobile/` (the Phase 2 "Android fast-follow"),
derived from the iPhone shell at `../zennotesiphone` — the two shells share the
same structure and bridge modules; platform-specific divergences are noted
below.

The zennotes repo is consumed **read-only at the exact commit in
`.zennotes-commit`**. `npm run source:prepare` checks that commit out under the
ignored `.zennotes-source/` directory and installs its locked dependencies.
Every typecheck and release build verifies the pin; no ambient sibling checkout
can silently change a mobile binary.

## Architecture

```
src/
  main.tsx                install bridge → open vault → renderZenNotesApp()
  bridge/
    mobile-bridge.ts      the mobile ZenBridge (window.zen) implementation
    vault-fs.ts           desktop vault.ts semantics over Capacitor Filesystem
    vault-core.ts         pure helpers ported 1:1 (folder map, meta extraction,
                          naming, search scoring) — keep in sync with desktop
    native-fs.ts          Capacitor Filesystem wrapper (vault root = app-scoped
                          external storage via Directory.External)
    events.ts             VaultChangeEvent emitter (in-app writes + rescan)
    widget-snapshot.ts    the Home Screen widget snapshot: the contract + pure selectors
    widgets.ts            publishes it through the ZenWidgets plugin on every change
  ui-mobile/
    MobileShell.tsx       bottom nav (capture ⊕ / search / sidebar / palette),
                          phone drawer behavior via the shared Zustand store
    mobile.css            safe areas, overlay drawers, keyboard handling
    widget-links.ts       the zennotes:// links the widgets fire; deep-links.ts runs them
android/                  Capacitor-generated Gradle project (appId md.zennotes)
  app/src/main/java/md/zennotes/
    MainActivity.java     registers native plugins, stashes ACTION_SEND shares
    DirectUploadPlugin.java streams signed object PUTs on Android 7+
    ShareInboxPlugin.java Android ShareInbox (same jsName/contract as iOS)
    WidgetBridgePlugin.java ZenWidgets (same jsName/contract as iOS): writes the snapshot
    widgets/              New Note, Recent Notes, Today's Tasks: AppWidgetProviders +
                          RemoteViewsServices rendering that snapshot
```

Key decisions (all forced by "don't modify the zennotes repo"):

- **`runtime: 'web'`** — the bridge contract has no `'mobile'` runtime yet.
  Every desktop-only affordance in app-core gates on `runtime === 'desktop'`,
  so `'web'` + the capability flags produces correct mobile behavior. When the
  contract gains `'mobile'` + the new capability flags (spec 02), flip it here.
- **`platform: 'linux'`** (iOS shell reports `'darwin'`) — gives app-core
  Ctrl-based keymaps and hides Mac-only chrome; right for Android hardware
  keyboards.
- **Vault location** — app-scoped external storage:
  `/Android/data/md.zennotes/files/ZenNotes/<vault>` (`Directory.External`),
  the spec-03 Android default tier: no permission prompt, works under scoped
  storage. **Do not switch to `Directory.Documents`** — on Android that is the
  public Documents collection, which the Filesystem plugin permission-gates
  and Android 11+ scoped storage effectively breaks.
- **Home Screen widgets** — the iPhone's three (New Note, Recent Notes,
  Today's Tasks) on the same `src/bridge/widgets.ts` publisher and the same
  snapshot contract, rendered here as classic RemoteViews in Java
  (`md.zennotes.widgets`): no Glance, no Kotlin, the build stays Java-only.
  The snapshot lives in the app's private files
  (`files/widgets/snapshot.json`; iOS uses the App Group), the two list
  widgets are `RemoteViewsService`-backed and scroll, colors come from the
  app's live theme in the snapshot, and every tap is an ACTION_VIEW
  `zennotes://` intent into the single-task MainActivity. Warm, it arrives
  as `onNewIntent` → `appUrlOpen`; at boot the shell asks the plugin for
  the newest link it saw (`ZenWidgets.consumeLaunchLink`, stashed from
  `onCreate` and `onNewIntent`) because Capacitor's `getLaunchUrl` captures
  the activity's intent once and an activity recreated into its old task
  reports the task's *original* intent there — the tap that woke it only
  shows up as a retained `appUrlOpen` the Cloud auth listener consumes.
  Pins are keyed by `vault.root` here, where the iPhone shell has
  `activeVaultStateKey`.
- **Durable app preferences.** WebView localStorage is evictable on some
  devices, which silently reset theme and editor settings. `src/bootstrap.ts`
  mirrors `zen:prefs:v2` into native Capacitor Preferences on every write,
  restores it before app-core loads (the dynamic `import('./main')` preserves
  the module-eval ordering the inline index.html seed script relies on), and
  re-applies the theme attributes pre-paint.
- **Two storage tiers.** Default: app-scoped storage (above) — with a
  one-time boot probe (`initVaultsRoot`) that falls back to internal app
  storage (`Directory.Data`) on devices where `getExternalFilesDir` is
  unusable (custom ROMs / restricted profiles crashed at first launch with
  "Missing parent directory", issue #2); the chosen root is persisted so it
  never flips between launches. Advanced: the
  **SAF external-folder tier** (spec 03) — "Choose Folder…" in the New Vault
  sheet opens `ACTION_OPEN_DOCUMENT_TREE` (`FolderPickerPlugin.java`; the
  persisted tree-URI permission is the "bookmark", surviving reboots), and
  every file op on a `content://` root routes through `SafFsPlugin.java`
  (`DocumentsContract` child queries with a documentId cache — one IPC per
  directory listing, NOT per-file DocumentFile resolution) because Capacitor
  Filesystem cannot address tree URIs. This is the tier that enables
  Syncthing/FolderSync cross-device workflows. iCloud stays iOS-only;
  `icloud.ts` is kept (inert) to minimize drift against the iPhone shell.
  Unlike the iPhone shell's single-bookmark slot, `folder-picker.ts` keeps a
  **registry of every picked folder** (`zn-mobile:external-vaults`, with the
  legacy single-ref key as the "current" pointer and migration seed) so any
  number of SAF folder vaults stay switchable (zennotes#584) — external-tier
  root tokens carry the bookmark URI (`zn://external-vaults/<encoded-uri>`).
  Porting this back to iOS is a known follow-up; multiple security-scoped
  bookmarks are equally legal there.
- **SAF performance (measured, Pixel 7 AVD, 500-note vault):** ~2 ms/op on
  app storage vs ~35 ms/op over SAF (~17×). Cold open+index: ~3.3 s local vs
  ~20 s SAF; warm relaunch: ~2.6 s vs ~23 s — dominated by a per-launch
  full-body read pass (workspace/tasks restore) that every tier performs but
  only SAF makes expensive. The note-meta cache itself hits correctly on both
  tiers. Verdict: fine for small/medium vaults; for large vaults the next
  lever is batching (`readTextMany`-style plugin call or a native scan op),
  not `MANAGE_EXTERNAL_STORAGE` — revisit per spec 09 if users hit it.
- **On-disk contract is byte-compatible with desktop**: same folder layout
  (`inbox|quick|archive|trash`, `assets/`, legacy `attachements/` recognized —
  the misspelling is intentional and load-bearing), same `.zennotes/`
  metadata (vault.json, workspace.json, comments/), same naming/collision
  rules, same NoteMeta extraction regexes, `systemFolderPaths` remaps honored
  via `@shared/system-folder-paths`.
- **Share sheet → quick capture**: Android needs no app extension — a
  `text/plain` `ACTION_SEND` intent-filter on MainActivity stashes captures in
  SharedPreferences; the app-local `ShareInbox` plugin (same `jsName` and
  `drain()` contract as the Swift one) hands them to the unchanged JS side on
  launch/foreground.
- **Long-press context menus**: unlike WKWebView, the Android WebView fires a
  real `contextmenu` event on long-press, so the iOS 450ms synthesizer is
  replaced by a passive listener that only adds the haptic and swallows the
  post-lift synthetic mouse burst (without which menus close instantly).
  Inside the editor the listener instead STOPS the event (issue #8): both
  shells keep text selection native there, but on Android the real
  contextmenu would otherwise reach app-core's editor menu, which
  preventDefaults Chromium's selection action bar and opens at the finger —
  directly over the selection. Stopping propagation (never preventDefault)
  restores the native handles + action bar, including the events Chromium
  refires on selection-handle lifts and text-handle menu taps (those report
  `pointerType: 'mouse'`, so there is deliberately no mouse carve-out).
- **Editing-toolbar keyboard anchor** (issue #7): the iPhone shell anchors
  the formatting toolbar to a keyboard-top Y computed from
  `keyboardWillShow` (`--zn-kb-top`) to dodge a WKWebView stale-paint quirk.
  On Android that geometry is wrong twice over — the plugin's
  `keyboardHeight` includes the gesture-nav inset the edge-to-edge WebView
  margin already excludes, and the plugin event races the JS `resize` event
  (toolbar stuck mid-screen). Here the toolbar is viewport-bottom anchored
  (`bottom: 0` on the natively-resized viewport; lifted by `--zn-kb-height`
  under the `zn-kb-noresize` tablet mode instead of a media query, so
  landscape phones keep the docked anchor). The toolbar's dismiss button
  also blurs the editor before `Keyboard.hide()` — Android's hide is
  `hideSoftInputFromWindow` only (no `endEditing`-style focus resign like
  iOS), and a still-focused editor re-summons the keyboard.
- **Folders/tags discoverability pass** (Discord feedback, 2026-08-14):
  inline "New folder" row at every drawer level (also the only way to create
  NESTED folders on a phone), note long-press → Move to…/Delete action sheet
  in the drawer, a teaching Tags empty state (DOM patch — app-core is
  read-only), and an "Organize with tags and folders" welcome-note section
  whose inline #ideas seeds the Tags view. This pass is kept in parity with
  the iPhone shell.
- **TikZ** capability-gated off; workflows not offered; custom TextMate
  languages gated off; vim mode defaults off on first run — all as on iOS.
- **Desktop 2.21/2.22 features** arrive via shared source, same as the iOS
  1.4 build (both stamp upstream 2.22.0): in-progress task state (`- [/]`,
  set via long-press → Mark in progress — the long-press allowlist covers
  task rows, kanban cards, and calendar day cells), subtask rollups, archived
  notes retiring their tasks, inline mermaid while writing, text
  replacements, configurable tab size, manual kanban card order, and
  absence-aware remote reads (`@shared/remote-absence`).

## Build & run

```sh
npm install
npm run sync              # prepare pinned source + vite build + cap sync android
npx cap open android      # open in Android Studio, or:
cd android && JAVA_HOME=/opt/homebrew/opt/openjdk@21 \
  ANDROID_HOME=/opt/homebrew/share/android-commandlinetools \
  ./gradlew assembleDebug
adb install -r app/build/outputs/apk/debug/app-debug.apk
```

Toolchain: JDK 21 + Android SDK 36 (Capacitor 8; targetSdk 36 required by
Play from Aug 2026, minSdk 24 — Android 7.0+). `android/local.properties`
points at the SDK. Dev loop against a browser (no emulator): `npm run dev` —
Capacitor plugins are absent in a plain browser, so vault I/O won't work; use
the emulator for real testing.

`npm run upstream` verifies the generated checkout matches `.zennotes-commit`
and typechecks the bridge against that exact source. To adopt a newer core,
update the pin to a reviewed full commit SHA and commit it with the dependent
mobile changes.

## Boot-order gotcha (load-bearing)

Prefs seeding + theme attributes live in an **inline classic `<script>` in
index.html**, not a module: the app-core store reads
`localStorage['zen:prefs:v2']` at module-evaluation time, and Rollup chunk
hoisting (manualChunks) runs the store chunk before any entry-chunk module —
an imported "bootstrap.ts" silently ran too late on fresh installs.

## Boot-path chunking (load-bearing)

There is deliberately **no manualChunks rule for mermaid/cytoscape/dagre**
(upstream 2.20 finding): naming that chunk hoisted it into the entry's static
graph, so every cold start fetched and evaluated ~2.5MB of diagram code (plus
vendor-markdown, which it imports) before a note was even open. Left to
Rollup, mermaid splits into async per-diagram chunks fetched the first time a
diagram renders. Same idea: `/@xyflow/` is excluded from the `vendor-react`
substring match so React Flow stays inside the never-loaded WorkflowsView
chunk. Check `dist/index.html`'s modulepreloads after touching the config —
the entry must not statically import mermaid, markdown, or highlight chunks.

## ZenNotes Cloud

On-device and SAF vaults can connect to the optional ZenNotes Cloud service
from Settings → Cloud. The mobile bridge stores the account token in Android
secure storage, links or creates a cloud vault, runs the shared offline-first
sync engine, and exposes backups, note-level restore, publishing, and
automatic sync on app foreground and local changes. Local vaults, SAF folders,
and self-hosted workspaces continue to work without an account or subscription.
Files larger than the 5 MiB inline limit use Cloud's signed object-storage
upload flow. `DirectUploadPlugin` streams decoded bytes without loading a
second binary copy, works back to minSdk 24, rejects redirects and unsafe URLs,
and never receives the Cloud account token.

## Release verification

Pull requests and `main` run bridge tests, strict filesystem tests, a
pinned-source typecheck, production dependency audits for both repositories,
a Capacitor sync, native unit tests, Android lint, debug assembly, and an
emulator launch smoke test. Dependabot opens weekly npm, Gradle, and GitHub
Actions updates.

The scheduled `Cloud direct-upload E2E` workflow verifies the deployed API,
signed object upload, completion, manifest, and cleanup with a deterministic
6 MiB file. Configure these repository secrets before enabling it:

- `ZENNOTES_CLOUD_E2E_BASE_URL` — the HTTPS production or staging origin.
- `ZENNOTES_CLOUD_E2E_TOKEN` — a dedicated active-device token with
  `sync:read` and `sync:write`, Cloud Sync access, and room for one temporary
  vault. Rotate it independently from human accounts.

## Not yet built

- **SAF read batching** — a `readTextMany`/native-scan plugin op to make
  large external vaults fast (see the performance note above)
- Quick-capture home-screen widget / app shortcuts
- Store distribution work (signing config, Play listing — spec 08)
- **iPhone-shell parity for the 2026-08-20 feedback pass** — the Atlas touch
  shim, the About GitHub links island, the single-Done settings treatment,
  and the editor toolbar's Find-in-note + Strikethrough buttons are
  Android-first and still need porting to `../zennotesiphone`
  (`useSystemBackClose` is Android-only: iOS has no system back gesture).
  Underline stayed out on purpose: ZenNotes markdown has no underline
  construct on any platform — an upstream schema decision, not a shell one.

zennotesandroid

Owner Repos

File Explorer

# Use via CDN

Was this content helpful?

Recent Feedback

zennotesandroid

Owner Repos

File Explorer

# Use via CDN

Was this content helpful?

Recent Feedback

Download README