Joplin HarmonyOS Port

This directory is the HarmonyOS/RNOH host project boundary for the Joplin mobile app.

The React Native JavaScript entrypoint is ../index.harmony.js. For development, Metro must be started with:

yarn workspace @joplin/app-mobile start:harmony

Running on HarmonyOS PC

This is a React Native OpenHarmony host project, so the app has two moving parts during development:

1. Start Metro from the repository root:

   yarn workspace @joplin/app-mobile start:harmony
   

2. Open packages/app-mobile/harmony in DevEco Studio.

3. Select the entry module and a HarmonyOS PC target, then run/debug the app.

4. Keep Metro running while the app starts. entry/src/main/ets/pages/Index.ets tries these bundle sources in order:

   • packaged hermes_bundle.hbc
   • packaged bundle.harmony.js
   • /data/storage/el2/base/files/bundle.harmony.js
   • http://localhost:8081/packages/app-mobile/index.bundle?platform=harmony&dev=true&minify=false

If the target cannot reach the Mac through localhost, replace the Metro URL in Index.ets with the Mac's LAN IP address and make sure port 8081 is reachable. The PC simulator and a real PC device do not always resolve localhost to the development machine.

For an installable build that does not depend on Metro, generate the packaged JavaScript bundle before building the HAP:

yarn workspace @joplin/app-mobile bundle:harmony

This writes entry/src/main/resources/rawfile/bundle.harmony.js and copies React Native assets to entry/src/main/resources/rawfile/assets.

When the app only shows the notebook editor, use the side menu/new notebook flow to create or select a real notebook first. The notebook editor's parent picker only lists other notebooks as possible parents; when there are no other notebooks, it is disabled and the current notebook is kept at the top level.

The JavaScript side expects two native registrations:

• JoplinHarmony: a native module matching ../utils/harmony/HarmonyNative.ts
• JoplinHarmonyWebView: a native component used by ../components/ExtendedWebView/index.harmony.tsx

Current RNOH dependency note: @react-native-oh/react-native-harmony@0.82.29 declares a peer dependency on react-native@0.82.1, while this app currently uses react-native@0.81.6. Do not pin it into package.json until the app is either upgraded to RN 0.82.1 or an RNOH build compatible with RN 0.81.x is selected.

Current Limitations

• Whisper voice typing is disabled until a Harmony native speech-to-text runtime is selected.
• Quick actions are disabled until launcher shortcut support is implemented.
• Share-in is not wired yet: JoplinHarmony.shareData() currently returns an empty object and shareClose() is a no-op. The JavaScript adapter ignores empty share payloads, but until the Harmony Want handoff is implemented, importing content from another app through the system share sheet is expected to be incomplete.
• OneDrive sign-in can be completed by pasting the redirected URL or code parameter back into the Harmony login screen. Native OAuth redirect capture is still pending.
• Large image attachments fall back to attaching the original image until native Harmony image resizing is implemented.
• JoplinHarmonyWebView has placeholder injection/message methods. Note viewing works only to the extent supported by the upstream RNOH WebView package; editor/plugin postMessage parity still needs device validation.

Native Capability Order

1. Storage foundation: app/cache paths, SQLite, file system, tar/zip, md5.
2. Security foundation: random bytes, E2EE crypto, RSA provider.
3. Network foundation: fetch/upload blob, networkInfo, TLS policy.
4. WebView foundation: note viewer, markdown editor, rich text editor, drawing editor, plugin panels.
5. User integrations: document picker, share sheet, share extension, alarms, biometrics, camera, audio recorder.
6. Optional parity: voice typing model runtime and quick actions.

Expected DevEco Layout

The concrete DevEco project should be generated here and wired to RNOH:

harmony/
  AppScope/
  entry/
    src/main/ets/
      entryability/EntryAbility.ets
      rn/JoplinHarmonyModule.ets
      rn/JoplinHarmonyWebView.ets
      rn/JoplinHarmonyPackage.ets

The entryability must initialize RNOH with the Joplin component name and register the package that exposes the module/component above.

Bridge Contract

The source of truth is ../utils/harmony/HarmonyNative.ts.

Native methods should reject with actionable error messages and preserve Joplin-compatible data shapes:

• file content encodings: utf8, ascii, base64
• SQLite query results: plain JS objects with stable column names
• binary crypto inputs/outputs: base64 strings unless otherwise specified
• paths: absolute sandbox paths, not content:// style aliases
• WebView messages: string data in nativeEvent.data

Validation Gates

Before calling the port complete:

• yarn workspace @joplin/app-mobile tsc:harmony
• app starts through index.harmony.js
• create/edit/delete notes and notebooks
• attach files, images, camera photos, drawings, and audio
• sync with Joplin Cloud, WebDAV/Nextcloud, Dropbox, OneDrive, filesystem
• E2EE crypto and RSA integration tests pass on device
• note viewer/editor WebView supports resources, plugin assets, injected JS, and postMessage
• alarms, biometrics, share sheet, and share extension work on device