fix(channels): back active-workspace persistence with a jotai atom so the native pager sees switcher picks instead of a stale memoized localStorage read

This reverts commit a1ff5db724.

.eslintignore

@@ -1,2 +1,3 @@
 experiment
-node_modules
+node_modules
+*.css

.eslintrc.cjs

@@ -4,15 +4,15 @@ module.exports = {
     es2021: true,
   },
   extends: [
-    "eslint:recommended",
+    'eslint:recommended',
-    "plugin:react/recommended",
+    'plugin:react/recommended',
-    "plugin:react-hooks/recommended",
+    'plugin:react-hooks/recommended',
-    "plugin:@typescript-eslint/eslint-recommended",
+    'plugin:@typescript-eslint/eslint-recommended',
-    "plugin:@typescript-eslint/recommended",
+    'plugin:@typescript-eslint/recommended',
     'airbnb',
     'prettier',
   ],
-  parser: "@typescript-eslint/parser",
+  parser: '@typescript-eslint/parser',
   parserOptions: {
     ecmaFeatures: {
       jsx: true,
@@ -20,53 +20,80 @@ module.exports = {
     ecmaVersion: 'latest',
     sourceType: 'module',
   },
-  "globals": {
+  globals: {
-    JSX: "readonly"
+    JSX: 'readonly',
+    __APP_VERSION__: 'readonly',
   },
-  plugins: [
+  plugins: ['react', '@typescript-eslint'],
-    'react',
-    '@typescript-eslint'
-  ],
   rules: {
     'linebreak-style': 0,
     'no-underscore-dangle': 0,
-    "no-shadow": "off",
+    'no-shadow': 'off',
 
-    "import/prefer-default-export": "off",
+    'import/prefer-default-export': 'off',
-    "import/extensions": "off",
+    'import/extensions': 'off',
-    "import/no-unresolved": "off",
+    'import/no-unresolved': 'off',
-    "import/no-extraneous-dependencies": [
+    'import/no-extraneous-dependencies': [
-      "error",
+      'error',
       {
         devDependencies: true,
       },
     ],
 
-    'react/no-unstable-nested-components': [
+    'react/no-unstable-nested-components': ['error', { allowAsProps: true }],
+    'react/jsx-filename-extension': [
       'error',
-      { allowAsProps: true },
-    ],
-    "react/jsx-filename-extension": [
-      "error",
       {
-        extensions: [".tsx", ".jsx"],
+        extensions: ['.tsx', '.jsx'],
       },
     ],
 
-    "react/require-default-props": "off",
+    'react/require-default-props': 'off',
-    "react/jsx-props-no-spreading": "off",
+    'react/jsx-props-no-spreading': 'off',
-    "react-hooks/rules-of-hooks": "error",
+    'react-hooks/rules-of-hooks': 'error',
-    "react-hooks/exhaustive-deps": "error",
+    'react-hooks/exhaustive-deps': 'error',
 
-    "@typescript-eslint/no-unused-vars": "error",
+    // Disable base rules in favour of their @typescript-eslint counterparts —
-    "@typescript-eslint/no-shadow": "error"
+    // the base rules can't see TS-specific constructs (interface members, type
+    // imports, etc.) and double-fire alongside the TS versions.
+    'no-unused-vars': 'off',
+    '@typescript-eslint/no-unused-vars': ['error', { argsIgnorePattern: '^_' }],
+    '@typescript-eslint/no-shadow': 'error',
+
+    // Policy: kept as `warn` at the rule level so editors / `eslint --fix` /
+    // ad-hoc runs surface them as warnings, but `npm run check:eslint` and
+    // `lint-staged` BOTH pass `--max-warnings 0`, so new occurrences block
+    // commit. When unavoidable (matrix-js-sdk boundary, generic helpers,
+    // third-party callback shapes), suppress on the line with
+    // `// eslint-disable-next-line` and a one-line justification.
+    '@typescript-eslint/no-explicit-any': 'warn',
+    '@typescript-eslint/no-non-null-assertion': 'warn',
   },
   overrides: [
     {
-      files: ['*.ts'],
+      files: ['*.ts', '*.tsx'],
       rules: {
         'no-undef': 'off',
       },
     },
+    {
+      // Upstream-vendored binary parsing copied verbatim from matrix-react-sdk
+      // (src/util/cryptE2ERoomKeys.js header link). Bitwise ops, post-increment
+      // and string concatenation are correct for the domain — clean-up risks
+      // breaking E2E room-key import/export. Keep the body byte-identical to
+      // upstream and disable only the rules that fire on those idioms.
+      files: ['src/util/cryptE2ERoomKeys.js'],
+      rules: {
+        'no-bitwise': 'off',
+        'no-plusplus': 'off',
+        'prefer-template': 'off',
+        'no-param-reassign': 'off',
+        // `for (;;)` form upstream uses for the iter-loops trips eslint
+        // even though it's intentional — keep upstream control flow.
+        'no-constant-condition': 'off',
+        // Diagnostic `console.log` left as-is in vendor copy.
+        'no-console': 'off',
+      },
+    },
   ],
 };

.github/DISCUSSION_TEMPLATE/issue-triage.yml

@@ -0,0 +1,125 @@
+labels: ["needs-confirmation"]
+body:
+  - type: markdown #add faqs in future
+    attributes:
+      value: |
+        > [!IMPORTANT]
+        > Please check for both existing Discussions and Issues prior to opening a new Discussion.
+  - type: markdown
+    attributes:
+      value: "# Issue Details"
+  - type: textarea
+    attributes:
+      label: Issue Description
+      description: |
+        Provide a detailed description of the issue.  Include relevant information, such as:
+        - The feature or configuration option you encounter the issue with.
+        - Screenshots, screen recordings, or other supporting media (as needed).
+        - If this is a regression of an existing issue that was closed or resolved, please include the previous item reference (Discussion, Issue, PR, commit) in your description.
+      placeholder: |
+        When I try to send a message in a room, the message doesn't appear in the timeline.
+        OR
+        The application crashes when I click on the settings button.
+    validations:
+      required: true
+  - type: textarea
+    attributes:
+      label: Expected Behavior
+      description: |
+        Describe how you expect Vojo to behave in this situation.
+      placeholder: |
+        I expected the message to appear in the room timeline immediately after sending.
+        OR
+        The settings panel should open smoothly without any crashes.
+    validations:
+      required: true
+  - type: textarea
+    attributes:
+      label: Actual Behavior
+      description: |
+        Describe how Vojo actually behaves in this situation.  If it is not immediately obvious how the actual behavior differs from the expected behavior described above, please be sure to mention the deviation specifically.
+      placeholder: |
+        The application freezes for 3 seconds and then shows a white screen.
+    validations:
+      required: true
+  - type: textarea
+    attributes:
+      label: Reproduction Steps
+      description: |
+        Provide a detailed set of step-by-step instructions for reproducing this issue.
+      placeholder: |
+        1. Open Vojo and log in to my account
+        2. Navigate to the #general room
+        3. Type a message in the message box
+        4. Press Enter to send
+        5. Notice that the message doesn't appear in the timeline
+    validations:
+      required: true
+  - type: textarea
+    attributes:
+      label: Environement
+      description: |
+        Please provide information about your environment. Include the following:
+        - OS:
+        - Browser: 
+        - Vojo Web Version: (vojo.chat or self hosted)
+        - Matrix Homeserver: 
+      placeholder: |
+        - OS: Windows 11
+        - Browser: Chrome 120.0.6099.109
+        - Vojo Web Version: (vojo.chat or self hosted)
+        - Matrix Homeserver: matrix.org (Synapse 1.97.0)
+      render: text
+    validations:
+      required: true
+  - type: textarea
+    id: logs
+    attributes:
+      label: Relevant Logs
+      description: |
+        If applicable, add browser console logs to help explain your problem.
+        
+        **To get browser console logs:**
+        - Chrome/Edge: Press F12 → Console tab
+        - Firefox: Press F12 → Console tab  
+        - Safari: Develop → Show Web Inspector → Console
+        
+        Please wrap large log outputs in code blocks with triple backticks (```).
+      placeholder: |
+        ```
+        Error: Failed to send message
+            at MessageComposer.sendMessage (composer.js:245)
+            at HTMLButtonElement.onClick (composer.js:189)
+        TypeError: Cannot read property 'content' of undefined
+            at RoomTimeline.render (timeline.js:567)
+        ```
+      render: shell
+    validations:
+      required: false
+  - type: textarea 
+    attributes:
+      label: Additional context
+      description: |
+        Add any other context about the problem here (e.g., when did this start happening, does it happen on different homeservers, etc.)
+      placeholder: |
+        - This started happening after I updated to version 3.2.0
+        - It only happens in encrypted rooms, not in public rooms
+        - I've tried on both Firefox and Chrome with the same result
+        - It works fine on my phone using the same account
+        - This happens on all homeservers I've tested (matrix.org, mozilla.org)
+    validations:
+      required: false
+  - type: markdown
+    attributes:
+      value: |
+        # User Acknowledgements
+        > [!TIP]
+        > Use the search function to review existing Discussions and Issues.
+  - type: checkboxes #add faqs in future
+    attributes:
+      label: "I acknowledge that:"
+      options:
+        - label: I have searched the Vojo repository (both open and closed Discussions and Issues) and confirm this is not a duplicate of an existing issue or discussion.
+          required: true
+        - label: I have checked the "Preview" tab on all text fields to ensure that everything looks right, and have wrapped all configuration and code in code blocks with a group of three backticks (` ``` `) on separate lines.
+          required: true

.github/FUNDING.yml

@@ -1,3 +1 @@
-github: ajbura
+# Vojo project funding
-liberapay: ajbura
-open_collective: cinny

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -1,57 +0,0 @@
-name: 🐞 Bug Report
-description: Report a bug
-
-body:
-  - type: markdown
-    attributes:
-      value: |
-        ## First of all
-        1. Please search for [existing issues](https://github.com/ajbura/cinny/issues?q=is%3Aissue) about this problem first.
-        2. Make sure Cinny is up to date.
-        3. Make sure it's an issue with Cinny and not something else you are using.
-        4. Remember to be friendly.
-
-  - type: textarea
-    id: description
-    attributes:
-      label: Describe the bug
-      description: A clear description of what the bug is. Include screenshots if applicable.
-      placeholder: Bug description
-    validations:
-      required: true
-
-  - type: textarea
-    id: reproduction
-    attributes:
-      label: Reproduction
-      description: Steps to reproduce the behavior.
-      placeholder: |
-        1. Go to ...
-        2. Click on ...
-        3. See error
-
-  - type: textarea
-    id: expected-behavior
-    attributes:
-      label: Expected behavior
-      description: A clear description of what you expected to happen.
-
-  - type: textarea
-    id: info
-    attributes:
-      label: Platform and versions
-      description: "Provide OS, browser and Cinny version with your Homeserver."
-      placeholder: |
-       1. OS: [e.g. Windows 10, MacOS]
-       2. Browser: [e.g. chrome 99.5, firefox 97.2]
-       3. Cinny version: [e.g. 1.8.1 (app.cinny.in)]
-       4. Matrix homeserver: [e.g. matrix.org]
-      render: shell
-    validations:
-      required: true
-
-  - type: textarea
-    id: context
-    attributes:
-      label: Additional context
-      description: Add any other context about the problem here.

.github/ISSUE_TEMPLATE/config.yml

@@ -1,4 +1,5 @@
+blank_issues_enabled: false
 contact_links:
-  - name: 💬 Matrix Chat
+  - name: Features, Bug Reports, Questions
-    url: https://matrix.to/#/#cinny:matrix.org
+    url: https://github.com/nicejuice-cc/vojo/discussions/new/choose
-    about: Ask questions and talk to other Cinny users and the maintainers
+    about: Our preferred starting point if you have any questions or suggestions about features or behavior.

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -1,33 +0,0 @@
-name: 💡 Feature Request
-description: Suggest an idea
-
-body:
-  - type: textarea
-    id: problem
-    attributes:
-      label: Describe the problem
-      description: A clear description of the problem this feature would solve
-      placeholder: "I'm always frustrated when..."
-    validations:
-      required: true
-
-  - type: textarea
-    id: solution
-    attributes:
-      label: "Describe the solution you'd like"
-      description: A clear description of what change you would like
-      placeholder: "I would like to..."
-    validations:
-      required: true
-
-  - type: textarea
-    id: alternatives
-    attributes:
-      label: Alternatives considered
-      description: "Any alternative solutions you've considered"
-
-  - type: textarea
-    id: context
-    attributes:
-      label: Additional context
-      description: Add any other context about the problem here.

.github/ISSUE_TEMPLATE/preapproved.md

@@ -0,0 +1,9 @@
+---
+name: Pre-Discussed and Approved Topics
+about: |-
+  Only for topics already discussed and approved in the GitHub Discussions section.
+---
+
+**DO NOT OPEN A NEW ISSUE. PLEASE USE THE DISCUSSIONS SECTION.**
+
+**I DIDN'T READ THE ABOVE LINE. PLEASE CLOSE THIS ISSUE.**

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,22 +0,0 @@
-<!-- Please read https://github.com/ajbura/cinny/blob/dev/CONTRIBUTING.md before submitting your pull request -->
-
-### Description
-<!-- Please include a summary of the change. Please also include relevant motivation and context. List any dependencies that are required for this change. -->
-
-
-Fixes #
-
-#### Type of change
-
-- [ ] Bug fix (non-breaking change which fixes an issue)
-- [ ] New feature (non-breaking change which adds functionality)
-- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
-- [ ] This change requires a documentation update
-
-### Checklist:
-
-- [ ] My code follows the style guidelines of this project
-- [ ] I have performed a self-review of my own code
-- [ ] I have commented my code, particularly in hard-to-understand areas
-- [ ] I have made corresponding changes to the documentation
-- [ ] My changes generate no new warnings

.github/SECURITY.md

@@ -1,3 +0,0 @@
-# Reporting a Vulnerability
-
-**If you've found a security vulnerability, please report it to cinnyapp@gmail.com**

.github/renovate.json

@@ -1,10 +1,28 @@
 {
   "$schema": "https://docs.renovatebot.com/renovate-schema.json",
-  "extends": ["config:recommended", ":dependencyDashboardApproval"],
+  "extends": [
+    "config:recommended",
+    ":dependencyDashboardApproval",
+    ":semanticCommits",
+    "group:monorepos"
+  ],
   "labels": ["Dependencies"],
+  "rebaseWhen": "conflicted",
   "packageRules": [
     {
       "matchUpdateTypes": ["lockFileMaintenance"]
+    },
+    {
+      "groupName": "Slatejs",
+      "matchPackageNames": ["slate", "slate-dom", "slate-history", "slate-react"]
+    },
+    {
+      "groupName": "Call",
+      "matchPackageNames": ["@element-hq/element-call-embedded", "matrix-widget-api"]
+    },
+    {
+      "groupName": "Linkify",
+      "matchPackageNames": ["linkifyjs", "linkify-react"]
     }
   ],
   "lockFileMaintenance": {

.github/workflows/build-pull-request.yml

@@ -12,12 +12,12 @@ jobs:
       PR_NUMBER: ${{github.event.number}}
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v6.0.2
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
       - name: Setup node
-        uses: actions/setup-node@v6.2.0
+        uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6.3.0
         with:
-          node-version: 24.13.1
+          node-version-file: ".node-version"
-          cache: 'npm'
+          package-manager-cache: false
       - name: Install dependencies
         run: npm ci
       - name: Build app
@@ -25,7 +25,7 @@ jobs:
           NODE_OPTIONS: '--max_old_space_size=4096'
         run: npm run build
       - name: Upload artifact
-        uses: actions/upload-artifact@v6.0.0
+        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
         with:
           name: preview
           path: dist
@@ -33,7 +33,7 @@ jobs:
       - name: Save pr number
         run: echo ${PR_NUMBER} > ./pr.txt
       - name: Upload pr number
-        uses: actions/upload-artifact@v6.0.0
+        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
         with:
           name: pr
           path: ./pr.txt

.github/workflows/cla.yml

@@ -1,36 +0,0 @@
-name: 'CLA Assistant'
-on:
-  issue_comment:
-    types: [created]
-  pull_request_target:
-    types: [opened, closed, synchronize]
-
-jobs:
-  CLAssistant:
-    runs-on: ubuntu-latest
-    steps:
-      - name: 'CLA Assistant'
-        if: (github.event.comment.body == 'recheck' || github.event.comment.body == 'I have read the CLA Document and I hereby sign the CLA') || github.event_name == 'pull_request_target'
-        # Beta Release
-        uses: cla-assistant/github-action@v2.6.1
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          # the below token should have repo scope and must be manually added by you in the repository's secret
-          PERSONAL_ACCESS_TOKEN: ${{ secrets.CLA_PAT }}
-        with:
-          path-to-signatures: 'signatures.json'
-          path-to-document: 'https://github.com/cinnyapp/cla/blob/main/cla.md' # e.g. a CLA or a DCO document
-          # branch should not be protected
-          branch: 'main'
-          allowlist: ajbura,bot*
-
-          #below are the optional inputs - If the optional inputs are not given, then default values will be taken
-          remote-organization-name: cinnyapp
-          remote-repository-name: cla
-          #create-file-commit-message: 'For example: Creating file for storing CLA Signatures'
-          #signed-commit-message: 'For example: $contributorName has signed the CLA in #$pullRequestNo'
-          #custom-notsigned-prcomment: 'pull request comment with Introductory message to ask new contributors to sign'
-          #custom-pr-sign-comment: 'The signature to be committed in order to sign the CLA'
-          #custom-allsigned-prcomment: 'pull request comment when all contributors has signed, defaults to **CLA Assistant Lite bot** All Contributors have signed the CLA.'
-          #lock-pullrequest-aftermerge: false - if you don't want this bot to automatically lock the pull request after merging (default - true)
-          #use-dco-flag: true - If you are using DCO instead of CLA

.github/workflows/deploy-pull-request.yml

@@ -1,4 +1,5 @@
 name: Deploy PR to Netlify
+run-name: "Deploy PR to Netlify (${{ github.event.workflow_run.head_branch }})"
 
 on:
   workflow_run:
@@ -15,7 +16,7 @@ jobs:
     if: ${{ github.event.workflow_run.conclusion == 'success' }}
     steps:
       - name: Download pr number
-        uses: dawidd6/action-download-artifact@ac66b43f0e6a346234dd65d4d0c8fbb31cb316e5
+        uses: dawidd6/action-download-artifact@2536c51d3d126276eb39f74d6bc9c72ac6ef30d3 # v16
         with:
           workflow: ${{ github.event.workflow.id }}
           run_id: ${{ github.event.workflow_run.id }}
@@ -24,7 +25,7 @@ jobs:
         id: pr
         run: echo "id=$(<pr.txt)" >> $GITHUB_OUTPUT
       - name: Download artifact
-        uses: dawidd6/action-download-artifact@ac66b43f0e6a346234dd65d4d0c8fbb31cb316e5
+        uses: dawidd6/action-download-artifact@2536c51d3d126276eb39f74d6bc9c72ac6ef30d3 # v16
         with:
           workflow: ${{ github.event.workflow.id }}
           run_id: ${{ github.event.workflow_run.id }}
@@ -32,7 +33,7 @@ jobs:
           path: dist
       - name: Deploy to Netlify
         id: netlify
-        uses: nwtgck/actions-netlify@4cbaf4c08f1a7bfa537d6113472ef4424e4eb654
+        uses: nwtgck/actions-netlify@4cbaf4c08f1a7bfa537d6113472ef4424e4eb654 # v3.0.0
         with:
           publish-dir: dist
           deploy-message: "Deploy PR ${{ steps.pr.outputs.id }}"
@@ -42,15 +43,15 @@ jobs:
           enable-commit-comment: false
         env:
           NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }}
-          NETLIFY_SITE_ID: ${{ secrets.NETLIFY_SITE_ID_PR_CINNY }}
+          NETLIFY_SITE_ID: ${{ secrets.NETLIFY_SITE_ID_PR_VOJO }}
         timeout-minutes: 1
       - name: Comment preview on PR
-        uses: thollander/actions-comment-pull-request@fabd468d3a1a0b97feee5f6b9e499eab0dd903f6
+        uses: thollander/actions-comment-pull-request@24bffb9b452ba05a4f3f77933840a6a841d1b32b #v3.0.1
         env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          github-token: ${{ secrets.GITHUB_TOKEN }}
         with:
-          pr_number: ${{ steps.pr.outputs.id }}
+          pr-number: ${{ steps.pr.outputs.id }}
-          comment_tag: ${{ steps.pr.outputs.id }}
+          comment-tag: ${{ steps.pr.outputs.id }}
           message: |
               Preview: ${{ steps.netlify.outputs.deploy-url }}
-              ⚠️ Exercise caution. Use test accounts. ⚠️
+              ⚠️ Exercise caution. Use test accounts. ⚠️

.github/workflows/docker-pr.yml

@@ -10,11 +10,53 @@ on:
 jobs:
   docker-build:
     runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v6.0.2
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
-      - name: Build Docker image
+
-        uses: docker/build-push-action@v6.19.2
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@c7c53464625b32c7a7e944ae62b3e17d2b600130 # v3.7.0
+        
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@8d2750c68a42422c14e847fe6c8ac0403b4cbd6f # v3.12.0
+
+      - name: Login to Docker Hub #Do not update this action from a outside PR
+        if: github.event.pull_request.head.repo.fork == false
+        uses: docker/login-action@c94ce9fb468520275223c153574b00df6fe4bcc9 # v3.7.0
+        with:
+          username: ${{ secrets.DOCKER_USERNAME }}
+          password: ${{ secrets.DOCKER_PASSWORD }}
+        continue-on-error: true
+
+      - name: Login to the Github Container registry #Do not update this action from a outside PR
+        if: github.event.pull_request.head.repo.fork == false
+        uses: docker/login-action@c94ce9fb468520275223c153574b00df6fe4bcc9 # v3.7.0
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+        continue-on-error: true
+
+      - name: Extract metadata (tags, labels) for Docker, GHCR
+        id: meta
+        uses: docker/metadata-action@c299e40c65443455700f0fdfc63efafe5b349051 # v5.10.0
+        with:
+          images: |
+            ghcr.io/${{ github.repository }}
+
+      - name: Build Docker image (no push)
+        uses: docker/build-push-action@10e90e3645eae34f1e60eeb005ba3a3d33f178e8 # v6.19.2
         with:
           context: .
+          platforms: linux/amd64
           push: false
+          load: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+
+      - name: Show Docker images
+        run: docker images

.github/workflows/lockfile.yml

@@ -14,9 +14,9 @@ jobs:
       pull-requests: write
     steps:
       - name: Checkout
-        uses: actions/checkout@v6.0.2
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
       - name: NPM Lockfile Changes
-        uses: codepunkt/npm-lockfile-changes@b40543471c36394409466fdb277a73a0856d7891
+        uses: codepunkt/npm-lockfile-changes@b40543471c36394409466fdb277a73a0856d7891 # v1.0.0
         with:
           token: ${{ secrets.GITHUB_TOKEN }}
           # Optional inputs, can be deleted safely if you are happy with default values.

.github/workflows/netlify-dev.yml

@@ -11,12 +11,12 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v6.0.2
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
       - name: Setup node
-        uses: actions/setup-node@v6.2.0
+        uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6.3.0
         with:
-          node-version: 24.13.1
+          node-version-file: ".node-version"
-          cache: 'npm'
+          package-manager-cache: false
       - name: Install dependencies
         run: npm ci
       - name: Build app
@@ -24,7 +24,7 @@ jobs:
           NODE_OPTIONS: '--max_old_space_size=4096'
         run: npm run build
       - name: Deploy to Netlify
-        uses: nwtgck/actions-netlify@4cbaf4c08f1a7bfa537d6113472ef4424e4eb654
+        uses: nwtgck/actions-netlify@4cbaf4c08f1a7bfa537d6113472ef4424e4eb654 # v3.0.0
         with:
           publish-dir: dist
           deploy-message: 'Dev deploy ${{ github.sha }}'

.github/workflows/pr-title.yml

@@ -0,0 +1,15 @@
+name: Check PR title
+
+on:
+  pull_request_target:
+    types:
+      - opened
+      - edited
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: amannn/action-semantic-pull-request@48f256284bd46cdaab1048c3721360e808335d50 # v6.1.1
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/prod-deploy.yml

@@ -1,32 +1,40 @@
 name: Production deploy
 
 on:
-  release:
+  workflow_dispatch:
-    types: [published]
 
 jobs:
   deploy-and-tarball:
     name: Netlify deploy and tarball
+    outputs:
+      version: ${{ steps.vars.outputs.tag }}
     runs-on: ubuntu-latest
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v6.0.2
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
-      - name: Setup node
-        uses: actions/setup-node@v6.2.0
         with:
-          node-version: 24.13.1
+          fetch-depth: 0
-          cache: 'npm'
+      - name: Setup node
+        uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6.3.0
+        with:
+          node-version-file: ".node-version"
+          package-manager-cache: false
       - name: Install dependencies
         run: npm ci
+      - name: Get version from tag
+        id: vars
+        run: |
+          TAG=$(git describe --tags --abbrev=0) 
+          echo "tag=$TAG" >> $GITHUB_OUTPUT
       - name: Build app
         env:
           NODE_OPTIONS: '--max_old_space_size=4096'
         run: npm run build
       - name: Deploy to Netlify
-        uses: nwtgck/actions-netlify@4cbaf4c08f1a7bfa537d6113472ef4424e4eb654
+        uses: nwtgck/actions-netlify@4cbaf4c08f1a7bfa537d6113472ef4424e4eb654 # v3.0.0
         with:
           publish-dir: dist
-          deploy-message: 'Prod deploy ${{ github.ref_name }}'
+          deploy-message: 'Prod deploy ${{ steps.vars.outputs.tag }}'
           enable-commit-comment: false
           github-token: ${{ secrets.GITHUB_TOKEN }}
           production-deploy: true
@@ -36,11 +44,8 @@ jobs:
           NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }}
           NETLIFY_SITE_ID: ${{ secrets.NETLIFY_SITE_ID_APP }}
         timeout-minutes: 1
-      - name: Get version from tag
-        id: vars
-        run: echo "tag=${GITHUB_REF#refs/*/}" >> $GITHUB_OUTPUT
       - name: Create tar.gz
-        run: tar -czvf cinny-${{ steps.vars.outputs.tag }}.tar.gz dist
+        run: tar -czvf vojo-${{ steps.vars.outputs.tag }}.tar.gz dist
       - name: Sign tar.gz
         run: |
           echo '${{ secrets.GNUPG_KEY }}' | gpg --batch --import
@@ -50,50 +55,59 @@ jobs:
           # non-armored and hex-encode it so that its printable.
           echo "PGP Signing key, in raw PGP format in hex. Import with cat ... | xxd -r -p - | gpg --import"
           gpg --export | xxd -p
-          echo '${{ secrets.GNUPG_PASSPHRASE }}' | gpg --batch --yes --pinentry-mode loopback --passphrase-fd 0 --armor --detach-sign cinny-${{ steps.vars.outputs.tag }}.tar.gz
+          echo '${{ secrets.GNUPG_PASSPHRASE }}' | gpg --batch --yes --pinentry-mode loopback --passphrase-fd 0 --armor --detach-sign vojo-${{ steps.vars.outputs.tag }}.tar.gz
       - name: Upload tagged release
-        uses: softprops/action-gh-release@6cbd405e2c4e67a21c47fa9e383d020e4e28b836
+        uses: softprops/action-gh-release@6cbd405e2c4e67a21c47fa9e383d020e4e28b836 # v2.3.3
         with:
+          tag_name: ${{ steps.vars.outputs.tag }}
           files: |
-            cinny-${{ steps.vars.outputs.tag }}.tar.gz
+            vojo-${{ steps.vars.outputs.tag }}.tar.gz
-            cinny-${{ steps.vars.outputs.tag }}.tar.gz.asc
+            vojo-${{ steps.vars.outputs.tag }}.tar.gz.asc
 
   publish-image:
-    name: Push Docker image to Docker Hub, ghcr
+    name: Push Docker image to Docker Hub, GHCR
+    needs: deploy-and-tarball
+    env:
+      VERSION: ${{ needs.deploy-and-tarball.outputs.version }}
     runs-on: ubuntu-latest
     permissions:
       contents: read
       packages: write
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v6.0.2
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          fetch-depth: 0
       - name: Set up QEMU
-        uses: docker/setup-qemu-action@v3.7.0
+        uses: docker/setup-qemu-action@c7c53464625b32c7a7e944ae62b3e17d2b600130 # v3.7.0
       - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@v3.12.0
+        uses: docker/setup-buildx-action@8d2750c68a42422c14e847fe6c8ac0403b4cbd6f # v3.12.0
-      - name: Login to Docker Hub
+      - name: Login to Docker Hub #Do not update this action from a outside PR
-        uses: docker/login-action@v3.7.0
+        uses: docker/login-action@c94ce9fb468520275223c153574b00df6fe4bcc9 # v3.7.0
         with:
           username: ${{ secrets.DOCKER_USERNAME }}
           password: ${{ secrets.DOCKER_PASSWORD }}
-      - name: Login to the Container registry
+      - name: Login to the Github Container registry #Do not update this action from a outside PR
-        uses: docker/login-action@v3.7.0
+        uses: docker/login-action@c94ce9fb468520275223c153574b00df6fe4bcc9 # v3.7.0
         with:
           registry: ghcr.io
           username: ${{ github.actor }}
           password: ${{ secrets.GITHUB_TOKEN }}
-      - name: Extract metadata (tags, labels) for Docker
+      - name: Extract metadata (tags, labels) for Docker, GHCR
         id: meta
-        uses: docker/metadata-action@v5.10.0
+        uses: docker/metadata-action@c299e40c65443455700f0fdfc63efafe5b349051 # v5.10.0
         with:
           images: |
-            ${{ secrets.DOCKER_USERNAME }}/cinny
+            ${{ secrets.DOCKER_USERNAME }}/vojo
             ghcr.io/${{ github.repository }}
+          tags: |
+            type=raw,value=${{ env.VERSION }}
+            type=raw,value=latest
       - name: Build and push Docker image
-        uses: docker/build-push-action@v6.19.2
+        uses: docker/build-push-action@10e90e3645eae34f1e60eeb005ba3a3d33f178e8 # v6.19.2
         with:
           context: .
           platforms: linux/amd64,linux/arm64
           push: true
           tags: ${{ steps.meta.outputs.tags }}
-          labels: ${{ steps.meta.outputs.labels }}
+          labels: ${{ steps.meta.outputs.labels }}

.gitignore

@@ -2,6 +2,26 @@ experiment
 dist
 node_modules
 devAssets
+config.local.json
+
+electron/dist-electron
+release
 
 .DS_Store
-.idea
+.idea
+.vscode/*
+!.vscode/tasks.json
+.codex
+.claude
+docs/plans
+docs/design
+docs/ai/*
+!docs/ai/README.md
+!docs/ai/android.md
+!docs/ai/architecture.md
+!docs/ai/electron.md
+!docs/ai/i18n.md
+!docs/ai/overview.md
+!docs/ai/server-side.md
+
+vite.config.*.timestamp-*.mjs

.husky/pre-commit

@@ -0,0 +1,2 @@
+npx tsc -p tsconfig.json --noEmit
+npx lint-staged

.node-version

@@ -0,0 +1 @@
+24.13.1

.prettierignore

@@ -3,4 +3,40 @@ node_modules
 package.json
 package-lock.json
 LICENSE
-README.md
+README.md
+
+# Generated by Capacitor / Gradle / AGP — never format these.
+android/app/build/
+android/build/
+android/capacitor-cordova-android-plugins/build/
+android/app/src/main/assets/public/
+android/app/src/main/assets/capacitor.config.json
+android/app/src/main/assets/capacitor.plugins.json
+android/app/google-services.json
+
+# Internal docs — hand-formatted markdown. Prettier reflows tables and
+# fenced code blocks (e.g. YAML inside fences in server-side.md, tables in
+# architecture.md) in ways that change document structure, not whitespace.
+# Most paths under docs/ are gitignored anyway via top-level .gitignore.
+docs/
+
+# Upstream Cinny GitHub Actions / templates — leave as-is, format drift here
+# is unrelated to our work.
+.github/
+
+# Minified third-party assets.
+*.min.js
+
+# Top-level docs / HTML inherited from upstream Cinny — not part of this
+# infra cleanup's scope. They have minor pre-existing format drift; touching
+# them would just add review noise.
+CLAUDE.md
+CODE_OF_CONDUCT.md
+CONTRIBUTING.md
+index.html
+
+# Upstream-vendored files copied verbatim from external projects (links in
+# their headers). Keep byte-identical to upstream to make future re-syncs
+# trivially diffable. Same intent as the per-file ESLint override.
+src/util/cryptE2ERoomKeys.js
+src/util/colorMXID.js

.vscode/tasks.json

@@ -0,0 +1,104 @@
+{
+  "version": "2.0.0",
+  "tasks": [
+    {
+      "label": "Deploy to vojo.chat",
+      "type": "shell",
+      "command": "npm run build && rsync -avz --delete dist/ vojo-superuser@187.127.77.124:~/vojo/cinny/",
+      "group": "none",
+      "presentation": {
+        "reveal": "always",
+        "panel": "shared",
+        "showReuseMessage": false
+      },
+      "problemMatcher": []
+    },
+    {
+      "label": "Deploy widgets",
+      "type": "shell",
+      "command": "(cd apps/widget-telegram && npm run build && rsync -avz --delete dist/ vojo-superuser@187.127.77.124:~/vojo/widgets/telegram/) & PID1=$!; (cd apps/widget-discord && npm run build && rsync -avz --delete dist/ vojo-superuser@187.127.77.124:~/vojo/widgets/discord/) & PID2=$!; (cd apps/widget-whatsapp && npm run build && rsync -avz --delete dist/ vojo-superuser@187.127.77.124:~/vojo/widgets/whatsapp/) & PID3=$!; FAIL=0; wait $PID1 || FAIL=1; wait $PID2 || FAIL=1; wait $PID3 || FAIL=1; exit $FAIL",
+      "group": "none",
+      "presentation": {
+        "reveal": "always",
+        "panel": "shared",
+        "showReuseMessage": false
+      },
+      "problemMatcher": []
+    },
+    {
+      "label": "Build Android APK",
+      "type": "shell",
+      "command": "npm run build:android:debug",
+      "group": "none",
+      "presentation": {
+        "reveal": "always",
+        "panel": "shared",
+        "showReuseMessage": false
+      },
+      "problemMatcher": []
+    },
+    {
+      "label": "Deploy to Android (ADB)",
+      "type": "shell",
+      "command": "npm run build:android:debug && adb install -r android/app/build/outputs/apk/debug/app-debug.apk",
+      "group": "none",
+      "presentation": {
+        "reveal": "always",
+        "panel": "shared",
+        "showReuseMessage": false
+      },
+      "problemMatcher": []
+    },
+    {
+      "label": "Connect to Android device (ADB)",
+      "type": "shell",
+      "command": "adb connect 192.168.1.204:5555",
+      "group": "none",
+      "presentation": {
+        "reveal": "always",
+        "panel": "shared",
+        "showReuseMessage": false
+      },
+      "problemMatcher": []
+    },
+    {
+      "label": "Start Electron (dev)",
+      "type": "shell",
+      "command": "npm run electron:dev",
+      "group": "none",
+      "presentation": {
+        "reveal": "always",
+        "panel": "shared",
+        "showReuseMessage": false
+      },
+      "problemMatcher": []
+    },
+    {
+      "label": "Build Electron Windows",
+      "type": "shell",
+      "command": "npm run build:electron:win",
+      "group": "none",
+      "presentation": {
+        "reveal": "always",
+        "panel": "shared",
+        "showReuseMessage": false
+      },
+      "problemMatcher": []
+    },
+    {
+      "label": "Deploy Discord bridge",
+      "type": "shell",
+      "command": "docker build -t vojo-mautrix-discord:custom . && docker save vojo-mautrix-discord:custom | gzip | ssh vojo-superuser@187.127.77.124 'gunzip | docker load'",
+      "options": {
+        "cwd": "${workspaceFolder}/../vojo-mautrix-discord"
+      },
+      "group": "none",
+      "presentation": {
+        "reveal": "always",
+        "panel": "shared",
+        "showReuseMessage": false
+      },
+      "problemMatcher": []
+    }
+  ]
+}

CLAUDE.md

@@ -0,0 +1,9 @@
+# Directive for AI agents
+
+**All project context for Vojo lives in [`docs/ai/`](docs/ai/README.md). Read it before making any non-trivial change.**
+
+**All plans that you create should be always created in docs/plans
+
+This file exists only as a pointer. Do not add project knowledge here — put it in `docs/ai/`. Same rule for `.cursorrules`, `.windsurfrules`, `AGENTS.md`, `.codex`, home-directory memory, or any other agent-specific context file: if you're tempted to write project knowledge there, write it in `docs/ai/` instead and keep those files as thin pointers.
+
+Start here: [docs/ai/README.md](docs/ai/README.md).

CODE_OF_CONDUCT.md

@@ -60,7 +60,7 @@ representative at an online or offline event.
 
 Instances of abusive, harassing, or otherwise unacceptable behavior may be
 reported to the community leaders responsible for enforcement at
-cinnyapp@gmail.com.
+vojo@vojo.chat.
 All complaints will be reviewed and investigated promptly and fairly.
 
 All community leaders are obligated to respect the privacy and security of the

CONTRIBUTING.md

@@ -1,26 +1,21 @@
-# Contributing to Cinny
+# Contributing to Vojo
 
-First off, thanks for taking the time to contribute! ❤️
+First off, thanks for taking the time to contribute!
 
-All types of contributions are encouraged and valued. Please make sure to read the relevant section before making your contribution. It will make it a lot easier for us maintainers and smooth out the experience for all involved. The community looks forward to your contributions. 🎉
+All types of contributions are encouraged and valued. Please make sure to read the relevant section before making your contribution.
 
-> And if you like the project, but just don't have time to contribute, that's fine. There are other easy ways to support the project and show your appreciation, which we would also be very happy about:
+> And if you like the project, but just don't have time to contribute, that's fine. There are other easy ways to support the project and show your appreciation:
 > - Star the project
-> - Tweet about it (tag @cinnyapp)
 > - Refer this project in your project's readme
 > - Mention the project at local meetups and tell your friends/colleagues
-> - [Donate to us](https://cinny.in/#sponsor)
 
 ## Bug reports
 
-Bug reports and feature suggestions must use descriptive and concise titles and be submitted to [GitHub Issues](https://github.com/ajbura/cinny/issues). Please use the search function to make sure that you are not submitting duplicates, and that a similar report or request has not already been resolved or rejected.
+Bug reports and feature suggestions must use descriptive and concise titles and be submitted to GitHub Issues. Please use the search function to make sure that you are not submitting duplicates, and that a similar report or request has not already been resolved or rejected.
 
 ## Pull requests
 
-> ### Legal Notice
+**NOTE: If you want to add new features, please discuss with maintainers before coding or opening a pull request.** This is to ensure that we are on the same track.
-> When contributing to this project, you must agree that you have authored 100% of the content, that you have the necessary rights to the content and that the content you contribute may be provided under the project license.
-
-**NOTE: If you want to add new features, please discuss with maintainers before coding or opening a pull request.** This is to ensure that we are on same track and following our roadmap.
 
 **Please use clean, concise titles for your pull requests.** We use commit squashing, so the final commit in the dev branch will carry the title of the pull request. For easier sorting in changelog, start your pull request titles using one of the verbs "Add", "Change", "Remove", or "Fix" (present tense).
 
@@ -34,11 +29,7 @@ It is not always possible to phrase every change in such a manner, but it is des
 
 **The smaller the set of changes in the pull request is, the quicker it can be reviewed and merged.** Splitting tasks into multiple smaller pull requests is often preferable.
 
-Also, we use [ESLint](https://eslint.org/) for clean and stylistically consistent code syntax, so make sure your pull request follow it.
+Also, we use [ESLint](https://eslint.org/) for clean and stylistically consistent code syntax, so make sure your pull request follows it.
-
-**For any query or design discussion, join our [Matrix room](https://matrix.to/#/#cinny:matrix.org).**
 
 ## Helpful links
-- [BEM methodology](http://getbem.com/introduction/)
-- [Atomic design](https://bradfrost.com/blog/post/atomic-web-design/)
 - [Matrix JavaScript SDK documentation](https://matrix-org.github.io/matrix-js-sdk/index.html)

README.md

@@ -1,89 +1,29 @@
-# Cinny
+# Vojo
-<p>
-    <a href="https://github.com/ajbura/cinny/releases">
-        <img alt="GitHub release downloads" src="https://img.shields.io/github/downloads/ajbura/cinny/total?logo=github&style=social"></a>
-    <a href="https://hub.docker.com/r/ajbura/cinny">
-        <img alt="DockerHub downloads" src="https://img.shields.io/docker/pulls/ajbura/cinny?logo=docker&style=social"></a>
-    <a href="https://fosstodon.org/@cinnyapp">
-        <img alt="Follow on Mastodon" src="https://img.shields.io/mastodon/follow/106845779685925461?domain=https%3A%2F%2Ffosstodon.org&logo=mastodon&style=social"></a>
-    <a href="https://twitter.com/intent/follow?screen_name=cinnyapp">
-        <img alt="Follow on Twitter" src="https://img.shields.io/twitter/follow/cinnyapp?logo=twitter&style=social"></a>
-    <a href="https://cinny.in/#sponsor">
-        <img alt="Sponsor Cinny" src="https://img.shields.io/opencollective/all/cinny?logo=opencollective&style=social"></a>
-</p>
 
 A Matrix client focusing primarily on simple, elegant and secure interface. The main goal is to have an instant messaging application that is easy on people and has a modern touch.
-- [Roadmap](https://github.com/orgs/cinnyapp/projects/1)
+
+Based on [Cinny](https://github.com/cinnyapp/cinny) (MIT license).
+
 - [Contributing](./CONTRIBUTING.md)
 
-<img align="center" src="https://raw.githubusercontent.com/cinnyapp/cinny-site/main/assets/preview2-light.png" height="380">
-
 ## Getting started
-The web app is available at [app.cinny.in](https://app.cinny.in/) and gets updated on each new release. The `dev` branch is continuously deployed at [dev.cinny.in](https://dev.cinny.in) but keep in mind that it could have things broken.
 
-You can also download our desktop app from the [cinny-desktop repository](https://github.com/cinnyapp/cinny-desktop).
+The web app is available at [vojo.chat](https://vojo.chat).
 
 ## Self-hosting
-To host Cinny on your own, simply download the tarball from [GitHub releases](https://github.com/cinnyapp/cinny/releases/latest), and serve the files from `dist/` using your preferred webserver. Alternatively, you can just pull the docker image from [DockerHub](https://hub.docker.com/r/ajbura/cinny) or [GitHub Container Registry](https://github.com/cinnyapp/cinny/pkgs/container/cinny).
 
-* The default homeservers and explore pages are defined in [`config.json`](config.json).
+To host Vojo on your own, build from source and serve the files from `dist/` using your preferred webserver.
 
-* You need to set up redirects to serve the assests. Example configurations; [netlify](netlify.toml), [nginx](contrib/nginx/cinny.domain.tld.conf), [caddy](contrib/caddy/caddyfile).
+* The default homeserver is defined in [`config.json`](config.json).
-    * If you have trouble configuring redirects you can [enable hash routing](config.json#L35) — the url in the browser will have a `/#/` between the domain and open channel (ie. `app.cinny.in/#/home/` instead of `app.cinny.in/home/`) but you won't have to configure your webserver.
 
-* To deploy on subdirectory, you need to rebuild the app youself after updating the `base` path in [`build.config.ts`](build.config.ts).
+* You need to set up redirects to serve the assets. Example configurations: [nginx](contrib/nginx/vojo.domain.tld.conf), [caddy](contrib/caddy/caddyfile).
-    * For example, if you want to deploy on `https://cinny.in/app`, then set `base: '/app'`.
 
-<details><summary><b>PGP Public Key to verify tarball</b></summary>
+* To deploy on a subdirectory, rebuild the app after updating the `base` path in [`build.config.ts`](build.config.ts).
-
-```
------BEGIN PGP PUBLIC KEY BLOCK-----
-
-mQGNBGJw/g0BDAC8qQeLqDMzYzfPyOmRlHVEoguVTo+eo1aVdQH2X7OELdjjBlyj
-6d6c1adv/uF2g83NNMoQY7GEeHjRnXE4m8kYSaarb840pxrYUagDc0dAbJOGaCBY
-FKTo7U1Kvg0vdiaRuus0pvc1NVdXSxRNQbFXBSwduD+zn66TI3HfcEHNN62FG1cE
-K1jWDwLAU0P3kKmj8+CAc3h9ZklPu0k/+t5bf/LJkvdBJAUzGZpehbPL5f3u3BZ0
-leZLIrR8uV7PiV5jKFahxlKR5KQHld8qQm+qVhYbUzpuMBGmh419I6UvTzxuRcvU
-Frn9ttCEzV55Y+so4X2e4ZnB+5gOnNw+ecifGVdj/+UyWnqvqqDvLrEjjK890nLb
-Pil4siecNMEpiwAN6WSmKpWaCwQAHEGDVeZCc/kT0iYfj5FBcsTVqWiO6eaxkUlm
-jnulqWqRrlB8CJQQvih/g//uSEBdzIibo+ro+3Jpe120U/XVUH62i9HoRQEm6ADG
-4zS5hIq4xyA8fL8AEQEAAbQdQ2lubnlBcHAgPGNpbm55YXBwQGdtYWlsLmNvbT6J
-AdQEEwEIAD4CGwMFCwkIBwIGFQoJCAsCBBYCAwECHgECF4AWIQSRri2MHidaaZv+
-vvuUMwx6UK/M8wUCZqEDwAUJFvwIswAKCRCUMwx6UK/M877qC/4lxXOQIoWnLLkK
-YiRCTkGsH6NdxgeYr6wpXT4xuQ45ZxCytwHpOGQmO/5up5961TxWW8D1frRIJHjj
-AZGoRCL3EKEuY8nt3D99fpf3DvZrs1uoVAhiyn737hRlZAg+QsJheeGCmdSJ0hX5
-Yud8SE+9zxLS1+CEjMrsUd/RGre/phme+wNXfaHfREAC9ewolgVChPIbMxG2f+vs
-K8Xv52BFng7ta9fgsl1XuOjpuaSbQv6g+4ONk/lxKF0SmnhEGM3dmIYPONxW47Yf
-atnIjRra/YhPTNwrNBGMmG4IFKaOsMbjW/eakjWTWOVKKJNBMoDdRcYYWIMCpLy8
-AQUrMtQEsHSnqCwrw818S5A6rrhcfVGk36RGm0nOy6LS5g5jmqaYsvbCcBGY9B2c
-SUAVNm17oo7TtEajk8hcSXoZod1t++pyjcVKEmSn3nFK7v5m3V+cPhNTxZMK459P
-3x1Ucqj/kTqrxKw6s2Uknuk0ajmw0ljV+BQwgL6maguo9BKgCNW5AY0EYnD+DQEM
-ANOu/d6ZMF8bW+Df9RDCUQKytbaZfa+ZbIHBus7whCD/SQMOhPKntv3HX7SmMCs+
-5i27kJMu4YN623JCS7hdCoXVO1R5kXCEcneW/rPBMDutaM472YvIWMIqK9Wwl5+0
-Piu2N+uTkKhe9uS2u7eN+Khef3d7xfjGRxoppM+xI9dZO+jhYiy8LuC0oBohTjJq
-QPqfGDpowBwRkkOsGz/XVcesJ1Pzg4bKivTS9kZjZSyT9RRSY8As0sVUN57AwYul
-s1+eh00n/tVpi2Jj9pCm7S0csSXvXj8v2OTdK1jt4YjpzR0/rwh4+/xlOjDjZEqH
-vMPhpzpbgnwkxZ3X8BFne9dJ3maC5zQ3LAeCP5m1W0hXzagYhfyjo74slJgD1O8c
-LDf2Oxc5MyM8Y/UK497zfqSPfgT3NhQmhHzk83DjXw3I6Z3A3U+Jp61w0eBRI1nx
-H1UIG+gldcAKUTcfwL0lghoT3nmi9JAbvek0Smhz00Bbo8/dx8vwQRxDUxlt7Exx
-NwARAQABiQG8BBgBCAAmAhsMFiEEka4tjB4nWmmb/r77lDMMelCvzPMFAmahA9IF
-CRb8CMUACgkQlDMMelCvzPPQgQv/d5/z+fxgKqgfhQX+V49X4WgTVxZ/CzztDoJ1
-XAq1dzTNEy8AFguXIo6eVXPSpMxec7ZreN3+UPQBnCf3eR5YxWNYOYKmk0G4E8D2
-KGUJept7TSA42/8N2ov6tToXFg4CgzKZj0fYLwgutly7K8eiWmSU6ptaO8aEQBHB
-gTGIOO3h6vJMGVycmoeRnHjv4wV84YWSVFSoJ7cY0he4Z9UznJBbE/KHZjrkXsPo
-N+Gg5lDuOP5xjKzM5SogV9lhxBAhMWAg3URUF15yruZBiA8uV1FOK8sal/9C1G7V
-M6ygA6uOZqXlZtcdA94RoSsW2pZ9eLVPsxz2B3Zko7tu11MpNP/wYmfGTI3KxZBj
-n/eodvwjJSgHpGOFSmbNzvPJo3to5nNlp7wH1KxIMc6Uuu9hgfDfwkFZgV2bnFIa
-Q6gyF548Ub48z7Dz83+WwLgbX19ve4oZx+dqSdczP6ILHRQomtrzrkkP2LU52oI5
-mxFo+ioe/ABCufSmyqFye0psX3Sp
-=WtqZ
------END PGP PUBLIC KEY BLOCK-----
-```
-</details>
 
 ## Local development
+
 > [!TIP]
-> We recommend using a version manager as versions change very quickly. You will likely need to switch between multiple Node.js versions based on the needs of different projects you're working on. [NVM on windows](https://github.com/coreybutler/nvm-windows#installation--upgrades) on Windows and [nvm](https://github.com/nvm-sh/nvm) on Linux/macOS are pretty good choices. Recommended nodejs version is Krypton LTS (v24.13.1).
+> We recommend using a version manager as versions change very quickly. [NVM on Windows](https://github.com/coreybutler/nvm-windows#installation--upgrades) or [nvm](https://github.com/nvm-sh/nvm) on Linux/macOS are good choices.
 
 Execute the following commands to start a development server:
 ```sh
@@ -97,15 +37,15 @@ npm run build # Compiles the app into the dist/ directory
 ```
 
 ### Running with Docker
-This repository includes a Dockerfile, which builds the application from source and serves it with Nginx on port 80. To
+
-use this locally, you can build the container like so:
+This repository includes a Dockerfile, which builds the application from source and serves it with Nginx on port 80. To use this locally, you can build the container like so:
 ```
-docker build -t cinny:latest .
+docker build -t vojo:latest .
 ```
 
 You can then run the container you've built with a command similar to this:
 ```
-docker run -p 8080:80 cinny:latest
+docker run -p 8080:80 vojo:latest
 ```
 
 This will forward your `localhost` port 8080 to the container's port 80. You can visit the app in your browser by navigating to `http://localhost:8080`.

android/.gitignore

@@ -0,0 +1,101 @@
+# Using Android gitignore template: https://github.com/github/gitignore/blob/HEAD/Android.gitignore
+
+# Built application files
+*.apk
+*.aar
+*.ap_
+*.aab
+
+# Files for the ART/Dalvik VM
+*.dex
+
+# Java class files
+*.class
+
+# Generated files
+bin/
+gen/
+out/
+#  Uncomment the following line in case you need and you don't have the release build type files in your app
+# release/
+
+# Gradle files
+.gradle/
+build/
+
+# Local configuration file (sdk path, etc)
+local.properties
+
+# Proguard folder generated by Eclipse
+proguard/
+
+# Log Files
+*.log
+
+# Android Studio Navigation editor temp files
+.navigation/
+
+# Android Studio captures folder
+captures/
+
+# IntelliJ
+*.iml
+.idea/workspace.xml
+.idea/tasks.xml
+.idea/gradle.xml
+.idea/assetWizardSettings.xml
+.idea/dictionaries
+.idea/libraries
+# Android Studio 3 in .gitignore file.
+.idea/caches
+.idea/modules.xml
+# Comment next line if keeping position of elements in Navigation Editor is relevant for you
+.idea/navEditor.xml
+
+# Keystore files
+# Uncomment the following lines if you do not want to check your keystore files in.
+#*.jks
+#*.keystore
+
+# External native build folder generated in Android Studio 2.2 and later
+.externalNativeBuild
+.cxx/
+
+# Google Services (e.g. APIs or Firebase)
+# google-services.json
+
+# Freeline
+freeline.py
+freeline/
+freeline_project_description.json
+
+# fastlane
+fastlane/report.xml
+fastlane/Preview.html
+fastlane/screenshots
+fastlane/test_output
+fastlane/readme.md
+
+# Version control
+vcs.xml
+
+# lint
+lint/intermediates/
+lint/generated/
+lint/outputs/
+lint/tmp/
+# lint/reports/
+
+# Android Profiling
+*.hprof
+
+# Cordova plugins for Capacitor
+capacitor-cordova-android-plugins
+
+# Copied web assets
+app/src/main/assets/public
+
+# Generated Config files
+app/src/main/assets/capacitor.config.json
+app/src/main/assets/capacitor.plugins.json
+app/src/main/res/xml/config.xml

android/app/.gitignore

@@ -0,0 +1,2 @@
+/build/*
+!/build/.npmkeep

android/app/build.gradle

@@ -0,0 +1,148 @@
+apply plugin: 'com.android.application'
+
+// Mirror of resolveAppVersion() in ../../vite.config.js so the APK's
+// versionName matches __APP_VERSION__ rendered in the About screen.
+// `git describe --tags --match 'v*'` against tag v0.2.0 yields
+// `v0.2.0-<commits>-g<hash>`; patch = commit count since the tag.
+// Falls back to package.json only when git is unavailable.
+def gitDescribe = providers.exec {
+    it.commandLine 'git', 'describe', '--tags', '--match', 'v*', '--always'
+    it.workingDir rootDir.parentFile
+    it.ignoreExitValue = true
+}
+def appVersion = {
+    def fromGit = gitDescribe.result.get().exitValue == 0 ? gitDescribe.standardOutput.asText.get().trim() : null
+    def m = fromGit =~ /^v?(\d+)\.(\d+)\.(\d+)(?:-(\d+)-g[0-9a-f]+)?$/
+    if (fromGit && m.matches()) {
+        def major = m[0][1].toInteger()
+        def minor = m[0][2].toInteger()
+        def patch = (m[0][4] ?: m[0][3]).toInteger()
+        return [name: "${major}.${minor}.${patch}", major: major, minor: minor, patch: patch]
+    }
+    def pkg = new groovy.json.JsonSlurper().parseText(file('../../package.json').text)
+    def parts = pkg.version.split('\\.')
+    return [name: pkg.version, major: parts[0].toInteger(), minor: parts[1].toInteger(), patch: parts[2].toInteger()]
+}()
+def computedVersionCode = appVersion.major * 1000000 + appVersion.minor * 1000 + appVersion.patch
+
+android {
+    namespace = "chat.vojo.app"
+    compileSdk = rootProject.ext.compileSdkVersion
+    defaultConfig {
+        applicationId "chat.vojo.app"
+        minSdkVersion rootProject.ext.minSdkVersion
+        targetSdkVersion rootProject.ext.targetSdkVersion
+        versionCode computedVersionCode
+        versionName appVersion.name
+        testInstrumentationRunner "androidx.test.runner.AndroidJUnitRunner"
+        aaptOptions {
+             // Files and dirs to omit from the packaged assets dir, modified to accommodate modern web apps.
+             // Default: https://android.googlesource.com/platform/frameworks/base/+/282e181b58cf72b6ca770dc7ca5f91f135444502/tools/aapt/AaptAssets.cpp#61
+            ignoreAssetsPattern = '!.svn:!.git:!.ds_store:!*.scc:.*:!CVS:!thumbs.db:!picasa.ini:!*~'
+        }
+    }
+    // AGP 8+ requires explicit opt-in for BuildConfig generation. We rely on
+    // BuildConfig.DEBUG to gate Log.d calls that dump privacy-sensitive
+    // identifiers (roomId, eventId) so release builds don't leak them through
+    // logcat / crash-reporter buffers. See dlog() in VojoFirebaseMessagingService.
+    buildFeatures {
+        buildConfig = true
+    }
+
+    signingConfigs {
+        release {
+            if (project.hasProperty('VOJO_RELEASE_STORE_FILE')) {
+                storeFile file(VOJO_RELEASE_STORE_FILE)
+                storePassword VOJO_RELEASE_STORE_PASSWORD
+                keyAlias VOJO_RELEASE_KEY_ALIAS
+                keyPassword VOJO_RELEASE_KEY_PASSWORD
+            }
+        }
+    }
+
+    buildTypes {
+        release {
+            minifyEnabled true
+            shrinkResources true
+            proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'
+            signingConfig signingConfigs.release
+        }
+    }
+}
+
+repositories {
+    flatDir{
+        dirs '../capacitor-cordova-android-plugins/src/main/libs', 'libs'
+    }
+}
+
+dependencies {
+    implementation fileTree(include: ['*.jar'], dir: 'libs')
+    implementation "androidx.activity:activity:$androidxActivityVersion"
+    implementation "androidx.appcompat:appcompat:$androidxAppCompatVersion"
+    implementation "androidx.coordinatorlayout:coordinatorlayout:$androidxCoordinatorLayoutVersion"
+    implementation "androidx.core:core-splashscreen:$coreSplashScreenVersion"
+    implementation project(':capacitor-android')
+    // Needed for VojoFirebaseMessagingService. @capacitor/push-notifications
+    // already depends on firebase-messaging but declares it `implementation`
+    // so classes aren't exposed at app-module compile time.
+    implementation "com.google.firebase:firebase-messaging:25.0.1"
+    // WorkManager hosts VojoPollWorker — periodic /notifications poll that
+    // delivers messages and missed-call surfaces on networks where FCM
+    // (mtalk.google.com:5228) is blocked. Library self-registers its scheduler
+    // in the merged manifest; we declare no permission for it.
+    implementation "androidx.work:work-runtime:2.10.0"
+    testImplementation "junit:junit:$junitVersion"
+    androidTestImplementation "androidx.test.ext:junit:$androidxJunitVersion"
+    androidTestImplementation "androidx.test.espresso:espresso-core:$androidxEspressoCoreVersion"
+    implementation project(':capacitor-cordova-android-plugins')
+}
+
+apply from: 'capacitor.build.gradle'
+
+abstract class GeneratePushStringsTask extends DefaultTask {
+    @InputFiles
+    abstract ConfigurableFileCollection getInputFiles()
+
+    @OutputDirectory
+    abstract DirectoryProperty getOutputDir()
+
+    @TaskAction
+    void generate() {
+        def nodeBin = project.findProperty('NODE_BIN') ?: 'node'
+        project.exec {
+            commandLine nodeBin,
+                new File(project.rootProject.projectDir.parentFile, 'scripts/gen-push-strings.mjs').absolutePath,
+                '--out', outputDir.get().asFile.absolutePath
+        }
+    }
+}
+
+androidComponents {
+    onVariants(selector().all()) { variant ->
+        def repoRoot = rootProject.projectDir.parentFile
+        def taskProvider = tasks.register(
+            "generatePushStrings${variant.name.capitalize()}",
+            GeneratePushStringsTask
+        ) {
+            inputFiles.from(
+                new File(repoRoot, 'public/locales/en.json'),
+                new File(repoRoot, 'public/locales/ru.json'),
+                new File(repoRoot, 'scripts/gen-push-strings.mjs')
+            )
+            outputDir.set(layout.buildDirectory.dir("generated/res/push/${variant.name}"))
+        }
+        variant.sources.res.addGeneratedSourceDirectory(
+            taskProvider, GeneratePushStringsTask::getOutputDir
+        )
+    }
+}
+
+try {
+    def servicesJSON = file('google-services.json')
+    if (servicesJSON.text) {
+        apply plugin: 'com.google.gms.google-services'
+    }
+} catch(Exception e) {
+    logger.info("google-services.json not found, google-services plugin not applied. Push Notifications won't work")
+}

android/app/capacitor.build.gradle

@@ -0,0 +1,23 @@
+// DO NOT EDIT THIS FILE! IT IS GENERATED EACH TIME "capacitor update" IS RUN
+
+android {
+  compileOptions {
+      sourceCompatibility JavaVersion.VERSION_21
+      targetCompatibility JavaVersion.VERSION_21
+  }
+}
+
+apply from: "../capacitor-cordova-android-plugins/cordova.variables.gradle"
+dependencies {
+    implementation project(':capacitor-app')
+    implementation project(':capacitor-browser')
+    implementation project(':capacitor-preferences')
+    implementation project(':capacitor-push-notifications')
+    implementation project(':capacitor-toast')
+
+}
+
+
+if (hasProperty('postBuildExtras')) {
+  postBuildExtras()
+}

android/app/google-services.json

@@ -0,0 +1,29 @@
+{
+  "project_info": {
+    "project_number": "51806967595",
+    "project_id": "chat-vojo-app",
+    "storage_bucket": "chat-vojo-app.firebasestorage.app"
+  },
+  "client": [
+    {
+      "client_info": {
+        "mobilesdk_app_id": "1:51806967595:android:93921bf62aa9713a79576e",
+        "android_client_info": {
+          "package_name": "chat.vojo.app"
+        }
+      },
+      "oauth_client": [],
+      "api_key": [
+        {
+          "current_key": "AIzaSyBroeOOHxg-tEyU-O-zjSWF7mEejedRWsM"
+        }
+      ],
+      "services": {
+        "appinvite_service": {
+          "other_platform_oauth_client": []
+        }
+      }
+    }
+  ],
+  "configuration_version": "1"
+}

android/app/proguard-rules.pro

@@ -0,0 +1,45 @@
+# Add project specific ProGuard rules here.
+# You can control the set of applied configuration files using the
+# proguardFiles setting in build.gradle.
+#
+# For more details, see
+#   http://developer.android.com/guide/developing/tools/proguard.html
+
+# If your project uses WebView with JS, uncomment the following
+# and specify the fully qualified class name to the JavaScript interface
+# class:
+#-keepclassmembers class fqcn.of.javascript.interface.for.webview {
+#   public *;
+#}
+
+# Uncomment this to preserve the line number information for
+# debugging stack traces.
+#-keepattributes SourceFile,LineNumberTable
+
+# If you keep the line number information, uncomment this to
+# hide the original source file name.
+#-renamesourcefileattribute SourceFile
+
+# Keep custom app classes — entry points invoked by Android system (Intents,
+# FCM, AndroidManifest references) or by JS bridge via reflection.
+-keep class chat.vojo.app.MainActivity { *; }
+-keep class chat.vojo.app.VojoFirebaseMessagingService { *; }
+-keep class chat.vojo.app.CallForegroundPlugin { *; }
+-keep class chat.vojo.app.CallForegroundService { *; }
+-keep class chat.vojo.app.CallDeclineReceiver { *; }
+-keep class chat.vojo.app.CallCancelReceiver { *; }
+-keep class chat.vojo.app.FullScreenIntentPlugin { *; }
+-keep class chat.vojo.app.LaunchSplashPlugin { *; }
+
+# Firebase Messaging — receivers/services resolved by Android via manifest.
+-keep public class * extends com.google.firebase.messaging.FirebaseMessagingService
+-keep class com.google.firebase.iid.** { *; }
+-keep class com.google.firebase.messaging.** { *; }
+
+# Capacitor — plugins discovered by annotation/reflection.
+-keep @com.getcapacitor.annotation.CapacitorPlugin class * { *; }
+-keep class com.getcapacitor.** { *; }
+-keep class com.getcapacitor.plugin.** { *; }
+
+# AndroidX splashscreen — reflection paths.
+-keep class androidx.core.splashscreen.** { *; }

android/app/src/androidTest/java/com/getcapacitor/myapp/ExampleInstrumentedTest.java

@@ -0,0 +1,26 @@
+package com.getcapacitor.myapp;
+
+import static org.junit.Assert.*;
+
+import android.content.Context;
+import androidx.test.ext.junit.runners.AndroidJUnit4;
+import androidx.test.platform.app.InstrumentationRegistry;
+import org.junit.Test;
+import org.junit.runner.RunWith;
+
+/**
+ * Instrumented test, which will execute on an Android device.
+ *
+ * @see <a href="http://d.android.com/tools/testing">Testing documentation</a>
+ */
+@RunWith(AndroidJUnit4.class)
+public class ExampleInstrumentedTest {
+
+    @Test
+    public void useAppContext() throws Exception {
+        // Context of the app under test.
+        Context appContext = InstrumentationRegistry.getInstrumentation().getTargetContext();
+
+        assertEquals("com.getcapacitor.app", appContext.getPackageName());
+    }
+}

android/app/src/main/AndroidManifest.xml

@@ -0,0 +1,145 @@
+<?xml version="1.0" encoding="utf-8"?>
+<manifest xmlns:android="http://schemas.android.com/apk/res/android"
+    xmlns:tools="http://schemas.android.com/tools">
+
+    <!-- allowBackup=false: CallDeclineReceiver reads the Matrix access_token
+         from shared_prefs/CapacitorStorage.xml (written by sessionBridge).
+         With allowBackup=true a rooted device or adb-backup-enabled user
+         could exfiltrate the cleartext token. Session data is cheap to
+         recreate via re-login, so excluding ourselves from Auto Backup
+         is the simpler control vs. fine-grained backup_rules.xml exclusions. -->
+    <application
+        android:allowBackup="false"
+        android:icon="@mipmap/ic_launcher"
+        android:label="@string/app_name"
+        android:roundIcon="@mipmap/ic_launcher_round"
+        android:supportsRtl="true"
+        android:theme="@style/AppTheme">
+
+        <activity
+            android:configChanges="orientation|keyboardHidden|keyboard|screenSize|locale|smallestScreenSize|screenLayout|uiMode|navigation|density"
+            android:name=".MainActivity"
+            android:label="@string/title_activity_main"
+            android:theme="@style/AppTheme.NoActionBarLaunch"
+            android:launchMode="singleTask"
+            android:exported="true">
+
+            <intent-filter>
+                <action android:name="android.intent.action.MAIN" />
+                <category android:name="android.intent.category.LAUNCHER" />
+            </intent-filter>
+
+            <!-- App Links for https://vojo.chat/u/<user>. autoVerify=true lets
+                 Chrome/Gmail/SMS hand the tap straight to this activity; the
+                 server must publish a matching /.well-known/assetlinks.json
+                 over HTTPS with the installed APK's signing SHA-256. Telegram
+                 and other in-app browsers ignore verification and load the
+                 URL in their own webview — the intent-URL redirect injected
+                 in index.html covers that case. -->
+            <intent-filter android:autoVerify="true">
+                <action android:name="android.intent.action.VIEW" />
+                <category android:name="android.intent.category.DEFAULT" />
+                <category android:name="android.intent.category.BROWSABLE" />
+                <data
+                    android:scheme="https"
+                    android:host="vojo.chat"
+                    android:pathPrefix="/u/" />
+            </intent-filter>
+
+            <!-- System share-sheet target. Three filters because Android's
+                 sheet UI dedupes by activity but resolves by MIME match:
+                 text/* gets its own filter so the Vojo icon shows up
+                 alongside WhatsApp/Telegram for «share link/selection»; */*
+                 covers single-file (image/video/audio/pdf/…) and
+                 SEND_MULTIPLE picks up gallery multi-select.
+                 Payload extraction lives in ShareTargetPlugin — MainActivity
+                 only routes the Intent to the plugin via onNewIntent. -->
+            <intent-filter>
+                <action android:name="android.intent.action.SEND" />
+                <category android:name="android.intent.category.DEFAULT" />
+                <data android:mimeType="text/*" />
+            </intent-filter>
+            <intent-filter>
+                <action android:name="android.intent.action.SEND" />
+                <category android:name="android.intent.category.DEFAULT" />
+                <data android:mimeType="*/*" />
+            </intent-filter>
+            <intent-filter>
+                <action android:name="android.intent.action.SEND_MULTIPLE" />
+                <category android:name="android.intent.category.DEFAULT" />
+                <data android:mimeType="*/*" />
+            </intent-filter>
+
+        </activity>
+
+        <provider
+            android:name="androidx.core.content.FileProvider"
+            android:authorities="${applicationId}.fileprovider"
+            android:exported="false"
+            android:grantUriPermissions="true">
+            <meta-data
+                android:name="android.support.FILE_PROVIDER_PATHS"
+                android:resource="@xml/file_paths"></meta-data>
+        </provider>
+
+        <!-- Replace Capacitor's default FCM service. VojoFirebaseMessagingService
+             extends MessagingService so super.onMessageReceived() still forwards
+             to the JS bridge; we add cold-start notification display on top. -->
+        <service
+            android:name="com.capacitorjs.plugins.pushnotifications.MessagingService"
+            tools:node="remove" />
+
+        <service
+            android:name=".VojoFirebaseMessagingService"
+            android:exported="false">
+            <intent-filter>
+                <action android:name="com.google.firebase.MESSAGING_EVENT" />
+            </intent-filter>
+        </service>
+
+        <service
+            android:name=".CallForegroundService"
+            android:exported="false"
+            android:foregroundServiceType="microphone" />
+
+        <receiver
+            android:name=".CallCancelReceiver"
+            android:exported="false" />
+
+        <receiver
+            android:name=".CallDeclineReceiver"
+            android:exported="false" />
+
+        <receiver
+            android:name=".MarkAsReadReceiver"
+            android:exported="false" />
+
+        <receiver
+            android:name=".NotificationDismissReceiver"
+            android:exported="false" />
+
+        <receiver
+            android:name=".ReplyReceiver"
+            android:exported="false" />
+    </application>
+
+    <!-- Permissions -->
+
+    <uses-permission android:name="android.permission.INTERNET" />
+    <uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
+    <!-- DM voice calls: mic + audio routing. Capacitor auto-requests at getUserMedia time. -->
+    <uses-permission android:name="android.permission.RECORD_AUDIO" />
+    <uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS" />
+    <!-- Required to unblock NotificationCompat.CallStyle on API 31+: NMS's
+         checkDisqualifyingFeatures rejects CallStyle notifications without
+         FSI/FGS/UIJ, throwing IllegalArgumentException on its own handler
+         thread (silent to the app). Declaring the permission flips
+         FLAG_FSI_REQUESTED_BUT_DENIED so the gate passes, even though we
+         never call setFullScreenIntent(). See ADR 2.5-heads-up. -->
+    <uses-permission android:name="android.permission.USE_FULL_SCREEN_INTENT" />
+    <!-- DM call lock-screen retention: CallForegroundService keeps the call
+         process foregrounded under lock so AppOps doesn't revoke RECORD_AUDIO
+         and netd doesn't block background network. -->
+    <uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
+    <uses-permission android:name="android.permission.FOREGROUND_SERVICE_MICROPHONE" />
+</manifest>

android/app/src/main/java/chat/vojo/app/AvatarBitmapCache.java

@@ -0,0 +1,65 @@
+package chat.vojo.app;
+
+import android.graphics.Bitmap;
+import android.util.LruCache;
+
+/**
+ * In-memory LRU cache of decoded avatar bitmaps keyed by MXC URL string.
+ *
+ * Sized as a process-singleton (~4 MB) so the FCM service, polling Worker
+ * and ReplyReceiver all share one pool. 96×96 ARGB_8888 bitmap is about
+ * 36 KB, so a 4 MB cache holds ~110 avatars — enough for the active
+ * conversation set on a typical user. LruCache evicts the least-recently-
+ * read entry when full; this is the right shape for "rooms the user is
+ * actively talking in stay warm, dormant rooms reload on demand".
+ *
+ * Thread-safety: LruCache itself is synchronized internally on every
+ * get/put/remove. We don't need an outer lock for normal operation. The
+ * AvatarLoader funnels all puts through this class.
+ *
+ * Process death: cache is in-memory only. After a kill, the first push
+ * to any room cold-renders without avatars and re-renders once the
+ * loader populates the cache (see AvatarLoader.loadAllWithTimeout).
+ */
+final class AvatarBitmapCache {
+
+    // Heap budget: bytes. 4 MB is generous against ARGB_8888 96×96 bitmaps
+    // (~36 KB each) and stays comfortably under the 1/8-of-heap Android
+    // recommendation on every device we ship to (minSdk 24 → at least
+    // 96 MB heap on a low-end phone).
+    private static final int MAX_SIZE_BYTES = 4 * 1024 * 1024;
+
+    private static final LruCache<String, Bitmap> CACHE =
+        new LruCache<String, Bitmap>(MAX_SIZE_BYTES) {
+            @Override
+            protected int sizeOf(String key, Bitmap value) {
+                return value.getByteCount();
+            }
+        };
+
+    private AvatarBitmapCache() {}
+
+    /**
+     * Returns the cached bitmap for an MXC URL, or null on miss.
+     *
+     * Bitmap references are NOT defensively copied — the cache hands out
+     * the same reference to every caller. This is safe because no code
+     * path in the app calls Bitmap.recycle() on a cached bitmap (the
+     * intermediate square / source bitmaps inside AvatarLoader.
+     * toCircularBitmap ARE recycled, but the circular output that lands
+     * here is held until LRU evicts it). LRU eviction simply drops the
+     * cache's reference, and the GC reclaims memory only after every
+     * Notification that referenced the bitmap is also released by the
+     * system. Adding a defensive copy here would halve the effective
+     * cache size for no real-world benefit.
+     */
+    static Bitmap get(String mxc) {
+        if (mxc == null || mxc.isEmpty()) return null;
+        return CACHE.get(mxc);
+    }
+
+    static void put(String mxc, Bitmap bitmap) {
+        if (mxc == null || mxc.isEmpty() || bitmap == null) return;
+        CACHE.put(mxc, bitmap);
+    }
+}

android/app/src/main/java/chat/vojo/app/AvatarLoader.java

@@ -0,0 +1,368 @@
+package chat.vojo.app;
+
+import android.content.Context;
+import android.content.SharedPreferences;
+import android.graphics.Bitmap;
+import android.graphics.BitmapFactory;
+import android.graphics.BitmapShader;
+import android.graphics.Canvas;
+import android.graphics.Paint;
+import android.graphics.Shader;
+import android.util.Log;
+
+import java.io.IOException;
+import java.io.InputStream;
+import java.net.HttpURLConnection;
+import java.net.URL;
+import java.util.Collection;
+import java.util.LinkedHashSet;
+import java.util.Set;
+import java.util.concurrent.ConcurrentHashMap;
+import java.util.concurrent.CountDownLatch;
+import java.util.concurrent.ExecutorService;
+import java.util.concurrent.Executors;
+import java.util.concurrent.TimeUnit;
+
+/**
+ * Fetches and decodes avatar bitmaps from MXC URLs, populating
+ * {@link AvatarBitmapCache}.
+ *
+ * URL resolution mirrors matrix-js-sdk's auth-media v1.11+ pattern:
+ *   mxc://server/mediaId
+ *     → <homeserver>/_matrix/client/v1/media/thumbnail/<server>/<mediaId>
+ *       ?width=96&height=96&method=crop
+ *     + Authorization: Bearer <accessToken>
+ *
+ * The legacy unauthenticated `/_matrix/media/v3/thumbnail/...` endpoint is
+ * NOT used — every Synapse the Vojo audience runs against (vanilla, v1.11+
+ * by deployment policy, see docs/ai/server-side.md) speaks auth media.
+ * Removing the legacy fallback keeps the loader off the deprecated path
+ * and avoids leaking the access token to a server route that doesn't
+ * require it.
+ *
+ * Concurrency: each MXC URL is fetched at most once concurrently — the
+ * `inFlight` set short-circuits duplicate requests from rapid
+ * append-rebuild cycles on the same conversation. Loads happen on a
+ * shared 4-thread pool; bigger than 1 so 5 senders in a group chat can
+ * load in parallel, capped to keep socket pressure under the typical
+ * mobile network budget.
+ *
+ * Two entry points:
+ *   - {@link #loadAllWithTimeout}: synchronous wait, used by the render
+ *     path to populate the cache before building the MessagingStyle so the
+ *     first post already has avatars. Timeout-bounded to keep FCM thread
+ *     responsive (Android budgets ~10s; we use 800 ms).
+ *   - {@link #prefetch}: fire-and-forget, used for warm-up scenarios.
+ *     Not currently called but kept for the room-metadata bridge to
+ *     eventually warm the cache on visibility resume.
+ */
+final class AvatarLoader {
+
+    private static final String TAG = "AvatarLoader";
+
+    private static final int AVATAR_SIZE_PX = 96;
+    private static final int CONNECT_TIMEOUT_MS = 5_000;
+    private static final int READ_TIMEOUT_MS = 5_000;
+    private static final int RENDER_BLOCK_TIMEOUT_MS = 800;
+    // Cap decoded bitmap byte count — a malicious / huge avatar shouldn't
+    // OOM the FCM service. 96×96 ARGB_8888 is ~36 KB; we accept up to
+    // 4× that (~140 KB) to allow some downscaling slack on servers that
+    // return slightly oversized thumbnails.
+    private static final int MAX_DECODED_BYTES = 144 * 1024;
+
+    private static final ExecutorService EXECUTOR = Executors.newFixedThreadPool(4);
+
+    // MXC URL → CountDownLatch that fires when the in-flight download
+    // completes (success or failure). A second caller observing an
+    // already-pending mxc waits on the SAME latch instead of either
+    // returning empty-handed or kicking off a duplicate fetch. Latches
+    // are removed by the worker task in its finally block; the same task
+    // that put the entry is the only one allowed to remove it, so a slow
+    // remove() race is harmless.
+    private static final ConcurrentHashMap<String, CountDownLatch> inFlight =
+        new ConcurrentHashMap<>();
+
+    private AvatarLoader() {}
+
+    /**
+     * Block the caller for up to {@link #RENDER_BLOCK_TIMEOUT_MS} while
+     * fetching any of the given MXC URLs that are not yet in
+     * {@link AvatarBitmapCache}. Cache hits are no-ops. Already-in-flight
+     * URLs are awaited via the shared latch — duplicate concurrent
+     * fetches do not happen.
+     *
+     * Designed to be called inline from the render path: after this
+     * returns, {@link AvatarBitmapCache#get} will be non-null for every
+     * MXC that loaded successfully within the budget. Failures are
+     * silent — the render then falls back to a Person without icon
+     * (Android renders initials/blank).
+     *
+     * Returns the count of avatars that landed in the cache during this
+     * call (purely informational — useful for logs).
+     */
+    static int loadAllWithTimeout(Context ctx, Collection<String> mxcs) {
+        if (mxcs == null || mxcs.isEmpty()) {
+            Log.i(TAG, "loadAll: empty input, skip");
+            return 0;
+        }
+        SharedPreferences prefs = ctx.getSharedPreferences(
+            VojoPollWorker.PREFS, Context.MODE_PRIVATE);
+        String token = prefs.getString(VojoPollWorker.KEY_ACCESS_TOKEN, null);
+        String homeserver = prefs.getString(VojoPollWorker.KEY_HOMESERVER_URL, null);
+        if (token == null || token.isEmpty() || homeserver == null || homeserver.isEmpty()) {
+            // No credentials yet (fresh install + first push). We can't
+            // resolve MXC URLs without an access token. Falling back to
+            // no-icon Person renderer is the correct behaviour here.
+            Log.i(TAG, "loadAll: no credentials in prefs, skip"
+                + " hasToken=" + (token != null && !token.isEmpty())
+                + " hasHs=" + (homeserver != null && !homeserver.isEmpty()));
+            return 0;
+        }
+        // De-duplicate and filter to misses only; if the cache already has
+        // an entry, no work is needed.
+        Set<String> toLoad = new LinkedHashSet<>();
+        for (String mxc : mxcs) {
+            if (mxc == null || mxc.isEmpty()) continue;
+            if (!mxc.startsWith("mxc://")) continue;
+            if (AvatarBitmapCache.get(mxc) != null) continue;
+            toLoad.add(mxc);
+        }
+        if (toLoad.isEmpty()) return 0;
+
+        // Per-mxc latches shared across concurrent callers — a second
+        // caller arriving while we're already mid-fetch waits on the
+        // SAME latch instead of forcing a duplicate HTTP or returning
+        // immediately empty-handed (which was the previous bug — see
+        // git blame for the race description).
+        java.util.List<CountDownLatch> waits = new java.util.ArrayList<>(toLoad.size());
+        for (String mxc : toLoad) {
+            CountDownLatch myLatch = new CountDownLatch(1);
+            CountDownLatch existing = inFlight.putIfAbsent(mxc, myLatch);
+            if (existing != null) {
+                // Already in flight — share the original latch.
+                waits.add(existing);
+                continue;
+            }
+            // We own this fetch; kick off the worker that will fire
+            // myLatch when done.
+            waits.add(myLatch);
+            final String capturedMxc = mxc;
+            final String capturedHomeserver = homeserver;
+            final String capturedToken = token;
+            EXECUTOR.execute(() -> {
+                try {
+                    Bitmap bmp = fetchAndDecode(capturedMxc, capturedHomeserver, capturedToken);
+                    if (bmp != null) AvatarBitmapCache.put(capturedMxc, bmp);
+                } catch (Throwable t) {
+                    Log.w(TAG, "fetch threw mxc=" + capturedMxc, t);
+                } finally {
+                    // Remove BEFORE countDown so a freshly-arriving caller
+                    // doesn't observe a stale latch for an already-loaded
+                    // mxc (would block until the next call with no fetch
+                    // actually pending). Cache.get() on the post-await
+                    // side covers the race where remove+put-cache happens
+                    // between two latch waits.
+                    inFlight.remove(capturedMxc);
+                    myLatch.countDown();
+                }
+            });
+        }
+        // Single budget for the whole batch — wait for all latches OR
+        // hit the timeout. Latches that fire early just return await()
+        // immediately; the slowest one consumes the remainder of the
+        // budget.
+        long deadline = System.nanoTime() + TimeUnit.MILLISECONDS.toNanos(RENDER_BLOCK_TIMEOUT_MS);
+        try {
+            for (CountDownLatch latch : waits) {
+                long remaining = deadline - System.nanoTime();
+                if (remaining <= 0) break;
+                latch.await(remaining, TimeUnit.NANOSECONDS);
+            }
+        } catch (InterruptedException ie) {
+            Thread.currentThread().interrupt();
+        }
+        // Count how many actually landed in the cache during this call —
+        // includes both items we fetched and items that finished after our
+        // timeout (which won't be reflected in this count but are still
+        // usable on the next render).
+        int hits = 0;
+        for (String mxc : toLoad) {
+            if (AvatarBitmapCache.get(mxc) != null) hits += 1;
+        }
+        Log.i(TAG, "loadAll: requested=" + mxcs.size()
+            + " toLoad=" + toLoad.size() + " hits=" + hits);
+        return hits;
+    }
+
+    /**
+     * Resolve an `mxc://server/mediaId` URL to a 96×96 thumbnail via the
+     * authenticated v1.11+ media endpoint and decode the response into a
+     * Bitmap. Returns null on any non-2xx, decode failure, or oversized
+     * payload (see {@link #MAX_DECODED_BYTES}).
+     */
+    private static Bitmap fetchAndDecode(String mxc, String homeserver, String token)
+        throws IOException {
+        Parsed parsed = parseMxc(mxc);
+        if (parsed == null) {
+            Log.w(TAG, "fetch: malformed mxc=" + mxc);
+            return null;
+        }
+
+        // Server + mediaId are NOT URL-encoded — matches matrix-js-sdk's
+        // content-repo.ts (it concatenates verbatim via `new URL()`).
+        // URLEncoder would turn `example.com:8448` into `example.com%3A8448`,
+        // which Synapse's media router rejects as an unknown server.
+        // mediaId is base64-ish per spec (URL-safe alphabet) so no
+        // encoding is needed there either.
+        StringBuilder url = new StringBuilder(homeserver);
+        if (!homeserver.endsWith("/")) url.append('/');
+        url.append("_matrix/client/v1/media/thumbnail/")
+            .append(parsed.server)
+            .append('/')
+            .append(parsed.mediaId)
+            .append("?width=").append(AVATAR_SIZE_PX)
+            .append("&height=").append(AVATAR_SIZE_PX)
+            .append("&method=crop");
+
+        HttpURLConnection conn = (HttpURLConnection) new URL(url.toString()).openConnection();
+        try {
+            conn.setRequestMethod("GET");
+            conn.setRequestProperty("Authorization", "Bearer " + token);
+            conn.setRequestProperty("Accept", "image/*");
+            conn.setConnectTimeout(CONNECT_TIMEOUT_MS);
+            conn.setReadTimeout(READ_TIMEOUT_MS);
+            int code = conn.getResponseCode();
+            Log.i(TAG, "fetch: mxc=" + mxc + " status=" + code);
+            if (code < 200 || code >= 300) return null;
+            int contentLength = conn.getContentLength();
+            if (contentLength > MAX_DECODED_BYTES) {
+                Log.w(TAG, "fetch: oversized contentLength=" + contentLength + " mxc=" + mxc);
+                return null;
+            }
+            try (InputStream in = conn.getInputStream()) {
+                BitmapFactory.Options opts = new BitmapFactory.Options();
+                // Stick with ARGB_8888 even on low-mem devices — RGB_565
+                // would lose alpha (group avatars often have a
+                // transparent corner) and the cache cap (4 MB) already
+                // bounds total memory. inJustDecodeBounds + sample-size
+                // dance is overkill at 96×96.
+                opts.inPreferredConfig = Bitmap.Config.ARGB_8888;
+                Bitmap bmp = BitmapFactory.decodeStream(in, null, opts);
+                if (bmp == null) {
+                    Log.w(TAG, "fetch: decodeStream returned null mxc=" + mxc);
+                    return null;
+                }
+                if (bmp.getByteCount() > MAX_DECODED_BYTES) {
+                    Log.w(TAG, "fetch: decoded oversized "
+                        + bmp.getByteCount() + " bytes mxc=" + mxc);
+                    bmp.recycle();
+                    return null;
+                }
+                // Crop into a circle BEFORE caching — IconCompat.createWithBitmap
+                // renders the bitmap verbatim, with no shape mask, so a
+                // square thumbnail from the homeserver lands as a square
+                // tile in the shade (visible on Android 12+ where
+                // conversation Person icons used to be auto-rounded by the
+                // OS — this changed). Pre-cropping guarantees a round
+                // visual on every API level instead of relying on the
+                // SystemUI of the day. The original square bitmap is
+                // recycled once the circular copy is in hand.
+                return toCircularBitmap(bmp);
+            }
+        } finally {
+            conn.disconnect();
+        }
+    }
+
+    /**
+     * Re-encode a circular avatar as an adaptive-icon-shaped bitmap:
+     * embeds the avatar inside a transparent canvas whose total size is
+     * 1.5× the avatar so Android's adaptive-icon safe zone (66% of total)
+     * covers the entire avatar without clipping.
+     *
+     * Required for conversation-shortcut icons per docs at
+     * developer.android.com/develop/ui/views/notifications/conversations:
+     * *"To avoid unintentional clipping of your shortcut avatar, provide
+     * an AdaptiveIconDrawable for the shortcut's icon."*
+     *
+     * Without this padding, IconCompat.createWithAdaptiveBitmap would
+     * crop ~17% off every edge of the avatar to fit the safe zone — a
+     * visible mutilation. With it, the shortcut icon renders pixel-
+     * identical to the circular avatar inside the system shade's
+     * conversation slot.
+     */
+    static Bitmap toAdaptivePaddedBitmap(Bitmap circularAvatar) {
+        int avatarSize = Math.min(circularAvatar.getWidth(), circularAvatar.getHeight());
+        // Pad to 150% so the adaptive safe-zone (66% of canvas = avatarSize)
+        // covers the full avatar. Rounded up to keep the canvas even.
+        int canvasSize = (int) Math.ceil(avatarSize / 0.66f);
+        if (canvasSize % 2 != 0) canvasSize += 1;
+        Bitmap output = Bitmap.createBitmap(canvasSize, canvasSize, Bitmap.Config.ARGB_8888);
+        Canvas canvas = new Canvas(output);
+        int offset = (canvasSize - avatarSize) / 2;
+        canvas.drawBitmap(circularAvatar, offset, offset, null);
+        return output;
+    }
+
+    /**
+     * Return a circular ARGB_8888 bitmap of the source — centre-cropped to
+     * a square if non-square, then masked with a circular path so the
+     * corners are transparent. The source bitmap is recycled.
+     *
+     * Anti-aliased edges via Paint.setAntiAlias on the circle draw — the
+     * BitmapShader copies the source's pixels into the circular region in
+     * a single drawCircle call, which keeps allocation to one output
+     * bitmap (vs the naive "decode → square crop → mask compose" path
+     * that touches three intermediate bitmaps).
+     */
+    private static Bitmap toCircularBitmap(Bitmap source) {
+        int size = Math.min(source.getWidth(), source.getHeight());
+        Bitmap squareSource;
+        if (source.getWidth() == size && source.getHeight() == size) {
+            squareSource = source;
+        } else {
+            int x = (source.getWidth() - size) / 2;
+            int y = (source.getHeight() - size) / 2;
+            squareSource = Bitmap.createBitmap(source, x, y, size, size);
+            source.recycle();
+        }
+        Bitmap output = Bitmap.createBitmap(size, size, Bitmap.Config.ARGB_8888);
+        Canvas canvas = new Canvas(output);
+        Paint paint = new Paint();
+        paint.setAntiAlias(true);
+        paint.setShader(new BitmapShader(
+            squareSource, Shader.TileMode.CLAMP, Shader.TileMode.CLAMP));
+        float radius = size / 2f;
+        canvas.drawCircle(radius, radius, radius, paint);
+        if (squareSource != source) {
+            squareSource.recycle();
+        }
+        return output;
+    }
+
+    private static final class Parsed {
+        final String server;
+        final String mediaId;
+
+        Parsed(String server, String mediaId) {
+            this.server = server;
+            this.mediaId = mediaId;
+        }
+    }
+
+    /**
+     * Split an `mxc://server/mediaId` URL into its two components. Returns
+     * null on any malformed input — caller drops the avatar silently.
+     */
+    private static Parsed parseMxc(String mxc) {
+        if (mxc == null) return null;
+        final String prefix = "mxc://";
+        if (!mxc.startsWith(prefix)) return null;
+        int slash = mxc.indexOf('/', prefix.length());
+        if (slash < 0 || slash == prefix.length()) return null;
+        String server = mxc.substring(prefix.length(), slash);
+        String mediaId = mxc.substring(slash + 1);
+        if (server.isEmpty() || mediaId.isEmpty()) return null;
+        return new Parsed(server, mediaId);
+    }
+}

android/app/src/main/java/chat/vojo/app/CallCancelReceiver.java

@@ -0,0 +1,44 @@
+package chat.vojo.app;
+
+import android.app.NotificationManager;
+import android.content.BroadcastReceiver;
+import android.content.Context;
+import android.content.Intent;
+
+/**
+ * Dismisses the incoming-call notification when its RTC lifetime expires.
+ *
+ * Scheduled by {@link VojoFirebaseMessagingService} via AlarmManager at
+ * sender_ts + lifetime. The extras carry tag/id so we can target the exact
+ * notification even if multiple ring pushes overlap (rare but possible across
+ * rapid re-dials).
+ *
+ * Also invoked directly (same intent shape) when the app receives a decline /
+ * other-device-answer via the live Matrix sync and wants the system notification
+ * cleared — see Capacitor removeDeliveredNotifications in the JS layer.
+ */
+public class CallCancelReceiver extends BroadcastReceiver {
+
+    public static final String ACTION_CANCEL_CALL = "chat.vojo.app.CANCEL_CALL";
+    public static final String EXTRA_NOTIF_TAG = "notif_tag";
+    public static final String EXTRA_NOTIF_ID = "notif_id";
+    // Carried so the receiver can tombstone and drop the matching registry
+    // entry — otherwise a same-eventId re-delivery after expiry would seed the
+    // registry again and render a stale ring on next backgrounding.
+    public static final String EXTRA_NOTIF_EVENT_ID = "notif_event_id";
+
+    @Override
+    public void onReceive(Context context, Intent intent) {
+        if (intent == null || !ACTION_CANCEL_CALL.equals(intent.getAction())) return;
+        String tag = intent.getStringExtra(EXTRA_NOTIF_TAG);
+        int id = intent.getIntExtra(EXTRA_NOTIF_ID, -1);
+        String notifEventId = intent.getStringExtra(EXTRA_NOTIF_EVENT_ID);
+        if (tag == null || id == -1) return;
+        NotificationManager nm =
+            (NotificationManager) context.getSystemService(Context.NOTIFICATION_SERVICE);
+        if (nm != null) nm.cancel(tag, id);
+        if (notifEventId != null) {
+            VojoFirebaseMessagingService.removeIncomingRing(context, notifEventId);
+        }
+    }
+}

android/app/src/main/java/chat/vojo/app/CallDeclineReceiver.java

@@ -0,0 +1,219 @@
+package chat.vojo.app;
+
+import android.content.BroadcastReceiver;
+import android.content.Context;
+import android.content.Intent;
+import android.content.SharedPreferences;
+import android.util.Log;
+
+import androidx.core.app.NotificationManagerCompat;
+
+import org.json.JSONObject;
+
+import java.io.OutputStream;
+import java.net.HttpURLConnection;
+import java.net.URL;
+import java.net.URLEncoder;
+import java.util.UUID;
+import java.util.concurrent.ExecutorService;
+import java.util.concurrent.Executors;
+
+/**
+ * Sends {@code m.call.decline} directly from the notification action tap,
+ * bypassing the WebView boot entirely. Fires via {@code PendingIntent.getBroadcast}
+ * from the CallStyle Decline button — MainActivity never starts, so the
+ * lockscreen-unlock-and-app-flash UX from Phase 2.5.3 is gone.
+ *
+ * Session data ({@code accessToken}, {@code baseUrl}, {@code userId}) is
+ * mirrored from JS into {@code shared_prefs/CapacitorStorage.xml} by
+ * {@code writeSessionBridge()} on client mount.
+ *
+ * Recovery contract:
+ *   - Before HTTP: write {@code vojo.pendingDeclines.{notifEventId}} tombstone
+ *     so {@code usePendingDeclinesFlusher} can retry on app resume if our
+ *     HTTP fails (network drop, token invalidated, process killed mid-PUT).
+ *   - On 2xx: remove the tombstone — receiver path succeeded, no flusher work.
+ *   - On non-2xx or exception: leave tombstone; flusher drains on next resume.
+ *
+ * Null-session edge case (fresh reinstall + first push before first login):
+ * we cannot send the decline at all — there's no access token, and the
+ * JS-path can't cover us either (a logged-out client has no Matrix session
+ * to call sendRtcDecline against). Cancelling the notification is the only
+ * feedback we can give; leaving the ring would trap the user on a call they
+ * can't accept or decline until the A-side times out.
+ *
+ * Note on idempotency: the flusher's retry generates a new txnId, so on a
+ * split-success-fail sequence (receiver HTTP timed out, flusher succeeds)
+ * we may land two {@code m.call.decline} events in the timeline with the
+ * same {@code rel.event_id}. This is cosmetic — the caller's auto-hangup
+ * hook is idempotent and fires on the first decline.
+ */
+public class CallDeclineReceiver extends BroadcastReceiver {
+
+    public static final String ACTION_DECLINE_CALL = "chat.vojo.app.DECLINE_CALL";
+    public static final String EXTRA_ROOM_ID = "room_id";
+    public static final String EXTRA_NOTIF_EVENT_ID = "notif_event_id";
+    public static final String EXTRA_NOTIF_TAG = "notif_tag";
+    public static final String EXTRA_NOTIF_ID = "notif_id";
+
+    private static final String PREFS_FILE = "CapacitorStorage";
+    private static final String SESSION_KEY = "vojo.matrixSession";
+    private static final String PENDING_DECLINES_PREFIX = "vojo.pendingDeclines.";
+
+    private static final int CONNECT_TIMEOUT_MS = 8_000;
+    private static final int READ_TIMEOUT_MS = 8_000;
+
+    private static final String TAG = "CallDeclineReceiver";
+
+    // Single reusable executor keeps us off the main thread without spawning
+    // a fresh one per broadcast — declines come rarely enough that a pool of 1
+    // is fine; a short-lived Thread would also work but is noisier on tracing.
+    private static final ExecutorService EXECUTOR = Executors.newSingleThreadExecutor();
+
+    @Override
+    public void onReceive(Context context, Intent intent) {
+        if (intent == null) return;
+        final String roomId = intent.getStringExtra(EXTRA_ROOM_ID);
+        final String notifEventId = intent.getStringExtra(EXTRA_NOTIF_EVENT_ID);
+        final String notifTag = intent.getStringExtra(EXTRA_NOTIF_TAG);
+        final int notifId = intent.getIntExtra(EXTRA_NOTIF_ID, -1);
+        if (roomId == null || notifEventId == null) {
+            Log.w(TAG, "onReceive: missing extras, abort");
+            return;
+        }
+
+        final Context appContext = context.getApplicationContext();
+        final SharedPreferences prefs =
+            appContext.getSharedPreferences(PREFS_FILE, Context.MODE_PRIVATE);
+
+        final String sessionJson = prefs.getString(SESSION_KEY, null);
+        if (sessionJson == null) {
+            // Fresh reinstall / logged-out: no access token, no Matrix client.
+            // We can't send m.call.decline and neither can the JS-path (no
+            // session to decline from). Cancel the notif so the user isn't
+            // stuck on a ring they can't action. Skip the tombstone — a
+            // retry without a session would be equally impotent.
+            Log.w(TAG, "onReceive: no session in prefs, cancelling notif without HTTP");
+            if (notifTag != null && notifId != -1) {
+                NotificationManagerCompat.from(appContext).cancel(notifTag, notifId);
+            }
+            VojoFirebaseMessagingService.removeIncomingRing(appContext, notifEventId);
+            return;
+        }
+
+        final String accessToken;
+        final String baseUrl;
+        try {
+            JSONObject session = new JSONObject(sessionJson);
+            accessToken = session.optString("accessToken", null);
+            baseUrl = session.optString("baseUrl", null);
+        } catch (Throwable t) {
+            // Do NOT pass the Throwable — JSONException.getMessage() embeds
+            // the malformed input, which here contains the access token.
+            Log.e(TAG, "onReceive: prefs JSON parse failed: " + t.getClass().getSimpleName());
+            // Still drop the native and the registry entry — user tapped Decline,
+            // the ring should not re-surface on next backgrounding just because
+            // we can't send the decline over HTTP.
+            if (notifTag != null && notifId != -1) {
+                NotificationManagerCompat.from(appContext).cancel(notifTag, notifId);
+            }
+            VojoFirebaseMessagingService.removeIncomingRing(appContext, notifEventId);
+            return;
+        }
+        if (accessToken == null || accessToken.isEmpty() || baseUrl == null || baseUrl.isEmpty()) {
+            Log.w(TAG, "onReceive: empty accessToken/baseUrl in session, cancelling ring locally");
+            if (notifTag != null && notifId != -1) {
+                NotificationManagerCompat.from(appContext).cancel(notifTag, notifId);
+            }
+            VojoFirebaseMessagingService.removeIncomingRing(appContext, notifEventId);
+            return;
+        }
+
+        // 1. Cancel first for instant user feedback. Ringtone stops within
+        //    NotificationManagerCompat's Binder latency (~tens of ms) — HTTP
+        //    completion is irrelevant to the perceived UX.
+        if (notifTag != null && notifId != -1) {
+            NotificationManagerCompat.from(appContext).cancel(notifTag, notifId);
+        }
+        // Drop the registry entry and tombstone the eventId so the next
+        // onPause renderRegistry can't resurrect the declined ring.
+        VojoFirebaseMessagingService.removeIncomingRing(appContext, notifEventId);
+
+        // 2. Write tombstone BEFORE HTTP so the flusher sees work to do
+        //    if we fail/die. Remove only on confirmed 2xx.
+        try {
+            JSONObject tombstone = new JSONObject();
+            tombstone.put("roomId", roomId);
+            tombstone.put("ts", System.currentTimeMillis());
+            prefs.edit()
+                .putString(PENDING_DECLINES_PREFIX + notifEventId, tombstone.toString())
+                .apply();
+        } catch (Throwable t) {
+            Log.w(TAG, "onReceive: tombstone write failed (non-fatal)", t);
+        }
+
+        // 3. HTTP PUT off-main on goAsync. Receiver stays alive ~10s for us
+        //    to finish; after that Android reclaims the process and the
+        //    pending request dies — flusher covers recovery on next resume.
+        final PendingResult pendingResult = goAsync();
+        final String txnId = UUID.randomUUID().toString();
+        EXECUTOR.execute(() -> {
+            try {
+                int status = sendDecline(baseUrl, accessToken, roomId, notifEventId, txnId);
+                if (status >= 200 && status < 300) {
+                    prefs.edit().remove(PENDING_DECLINES_PREFIX + notifEventId).apply();
+                    Log.d(TAG, "decline PUT ok status=" + status + " room=" + roomId);
+                } else {
+                    Log.w(TAG, "decline PUT non-2xx status=" + status + " room=" + roomId);
+                }
+            } catch (Throwable t) {
+                Log.e(TAG, "decline PUT threw", t);
+            } finally {
+                pendingResult.finish();
+            }
+        });
+    }
+
+    private int sendDecline(
+        String baseUrl,
+        String accessToken,
+        String roomId,
+        String notifEventId,
+        String txnId
+    ) throws Exception {
+        String url = trimTrailingSlash(baseUrl)
+            + "/_matrix/client/v3/rooms/"
+            + URLEncoder.encode(roomId, "UTF-8")
+            + "/send/org.matrix.msc4310.rtc.decline/"
+            + URLEncoder.encode(txnId, "UTF-8");
+
+        JSONObject relates = new JSONObject();
+        relates.put("rel_type", "m.reference");
+        relates.put("event_id", notifEventId);
+        JSONObject body = new JSONObject();
+        body.put("m.relates_to", relates);
+        byte[] payload = body.toString().getBytes("UTF-8");
+
+        HttpURLConnection conn = null;
+        try {
+            conn = (HttpURLConnection) new URL(url).openConnection();
+            conn.setRequestMethod("PUT");
+            conn.setConnectTimeout(CONNECT_TIMEOUT_MS);
+            conn.setReadTimeout(READ_TIMEOUT_MS);
+            conn.setDoOutput(true);
+            conn.setRequestProperty("Authorization", "Bearer " + accessToken);
+            conn.setRequestProperty("Content-Type", "application/json");
+            conn.setFixedLengthStreamingMode(payload.length);
+            try (OutputStream os = conn.getOutputStream()) {
+                os.write(payload);
+            }
+            return conn.getResponseCode();
+        } finally {
+            if (conn != null) conn.disconnect();
+        }
+    }
+
+    private static String trimTrailingSlash(String s) {
+        return (s != null && s.endsWith("/")) ? s.substring(0, s.length() - 1) : s;
+    }
+}

android/app/src/main/java/chat/vojo/app/CallForegroundPlugin.java

@@ -0,0 +1,148 @@
+package chat.vojo.app;
+
+import android.Manifest;
+import android.content.Context;
+import android.content.Intent;
+import android.content.pm.PackageManager;
+import android.os.Build;
+import android.util.Log;
+
+import androidx.core.content.ContextCompat;
+
+import com.getcapacitor.Plugin;
+import com.getcapacitor.PluginCall;
+import com.getcapacitor.PluginMethod;
+import com.getcapacitor.annotation.CapacitorPlugin;
+
+import java.util.HashMap;
+import java.util.Map;
+
+/**
+ * JS → Android bridge for CallForegroundService lifecycle.
+ *
+ * start / stop map onto startForegroundService / stopService.
+ *
+ * RECORD_AUDIO permission is re-verified here before dispatch: the JS caller
+ * (useAndroidCallForegroundSync) gates on the widget's JoinCall signal, which
+ * implies getUserMedia has run and the grant is in place — but the plugin
+ * checks defensively so the service never attempts startForeground with
+ * TYPE_MICROPHONE without the permission. The manifest declares the service
+ * as foregroundServiceType="microphone" only (no fallback type), so on API
+ * 34+ starting without RECORD_AUDIO would throw ForegroundServiceTypeException.
+ */
+@CapacitorPlugin(name = "CallForegroundService")
+public class CallForegroundPlugin extends Plugin {
+
+    private static final String TAG = "CallFgsPlugin";
+
+    @PluginMethod
+    public void start(PluginCall call) {
+        String title = call.getString("title");
+        String body = call.getString("body");
+        Context ctx = getContext();
+
+        // Defense-in-depth: starting the microphone-typed FGS without
+        // RECORD_AUDIO granted is invalid on API 34+. JS side already gates
+        // on JoinCall (see useAndroidCallForegroundSync) so this should never
+        // fire in practice. If it does, resolve cleanly without starting —
+        // the call will run without retention, which is the same fate as
+        // the first-ever-call window before getUserMedia prompt answered.
+        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.R) {
+            int micPerm = ContextCompat.checkSelfPermission(ctx, Manifest.permission.RECORD_AUDIO);
+            if (micPerm != PackageManager.PERMISSION_GRANTED) {
+                Log.w(TAG, "start: RECORD_AUDIO not granted, skipping FGS (would fail on TYPE_MICROPHONE)");
+                call.resolve();
+                return;
+            }
+        }
+
+        Intent intent = new Intent(ctx, CallForegroundService.class);
+        if (title != null) intent.putExtra(CallForegroundService.EXTRA_TITLE, title);
+        if (body != null) intent.putExtra(CallForegroundService.EXTRA_BODY, body);
+        try {
+            if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
+                ctx.startForegroundService(intent);
+            } else {
+                ctx.startService(intent);
+            }
+            Log.d(TAG, "start: service started");
+            call.resolve();
+        } catch (Throwable t) {
+            Log.e(TAG, "start: failed to start service", t);
+            call.reject("start_failed: " + t.getClass().getSimpleName() + ": " + t.getMessage());
+        }
+    }
+
+    @PluginMethod
+    public void stop(PluginCall call) {
+        Context ctx = getContext();
+        try {
+            ctx.stopService(new Intent(ctx, CallForegroundService.class));
+            Log.d(TAG, "stop: stopService dispatched");
+            call.resolve();
+        } catch (Throwable t) {
+            Log.w(TAG, "stop: stopService threw", t);
+            call.reject("stop_failed: " + t.getClass().getSimpleName() + ": " + t.getMessage());
+        }
+    }
+
+    // JS upserts a live incoming ring into the native registry (atom ADD
+    // happy-path). Idempotent with any prior FCM seed for the same eventId —
+    // Java merges metadata fields append-only. See VojoFirebaseMessagingService
+    // for the registry operations contract.
+    @PluginMethod
+    public void upsertIncomingRing(PluginCall call) {
+        String eventId = call.getString("eventId");
+        String roomId = call.getString("roomId");
+        if (eventId == null || eventId.isEmpty() || roomId == null || roomId.isEmpty()) {
+            call.reject("missing_eventId_or_roomId");
+            return;
+        }
+        Map<String, String> data = new HashMap<>();
+        data.put("event_id", eventId);
+        data.put("room_id", roomId);
+        String callerName = call.getString("callerName");
+        if (callerName != null && !callerName.isEmpty()) {
+            data.put("sender_display_name", callerName);
+        }
+        // Pass through senderTs/lifetime as strings — registry stores the same
+        // Map<String,String> shape that FCM delivers, and downstream consumers
+        // (scheduleCallNotificationExpiry, isExpired) parseLong them.
+        Long senderTs = call.getLong("senderTs");
+        if (senderTs != null && senderTs > 0) {
+            data.put("content_sender_ts", Long.toString(senderTs));
+        }
+        Long lifetime = call.getLong("lifetime");
+        if (lifetime != null && lifetime > 0) {
+            data.put("content_lifetime", Long.toString(lifetime));
+        }
+        String messageId = call.getString("messageId");
+        // messageId is used as google.message_id in the Answer/Launch PendingIntent
+        // extras — Capacitor PushNotificationsPlugin gates pushNotificationActionPerformed
+        // on containsKey. Empty string also satisfies the gate; we pass the
+        // caller's value through verbatim.
+        boolean seeded = VojoFirebaseMessagingService.upsertIncomingRing(data, messageId);
+        // Mark in NotificationDedup so a polling fire 15 minutes later
+        // doesn't post a "Missed call" notification for a ring the user
+        // already saw live via the in-app strip. Mirrors the FCM-arrival
+        // path in VojoFirebaseMessagingService.onMessageReceived.
+        if (seeded) {
+            NotificationDedup.markNotified(getContext(), eventId);
+        }
+        call.resolve();
+    }
+
+    // JS removes a ring from the native registry (atom REMOVE / suppress path /
+    // native action receiver path). Tombstones the eventId to reject late
+    // FCM or /sync re-seeds within the ring lifetime.
+    @PluginMethod
+    public void removeIncomingRing(PluginCall call) {
+        String eventId = call.getString("eventId");
+        if (eventId == null || eventId.isEmpty()) {
+            call.reject("missing_event_id");
+            return;
+        }
+        VojoFirebaseMessagingService.removeIncomingRing(getContext(), eventId);
+        call.resolve();
+    }
+}

android/app/src/main/java/chat/vojo/app/CallForegroundService.java

@@ -0,0 +1,143 @@
+package chat.vojo.app;
+
+import android.app.NotificationChannel;
+import android.app.NotificationManager;
+import android.app.PendingIntent;
+import android.app.Service;
+import android.content.Context;
+import android.content.Intent;
+import android.content.pm.ServiceInfo;
+import android.os.Build;
+import android.os.IBinder;
+import android.util.Log;
+
+import androidx.core.app.NotificationCompat;
+
+/**
+ * Foreground service kept alive for the duration of an active DM call. Its
+ * sole job is to promote the process to PROCESS_STATE_FOREGROUND_SERVICE so
+ * Android doesn't:
+ *   - revoke RECORD_AUDIO via AppOps (API 31+ while-in-use gating);
+ *   - apply background network firewall via netd.
+ *
+ * Both revocations were observed in Phase 0 capture on Samsung OneUI API 36:
+ * mic went Active=false ~5s after screen-off, netd isBlocked=true ~13s after,
+ * causing Element Call inside the hidden WebView to tear down the LiveKit
+ * session and the call to drop.
+ *
+ * Preconditions enforced by callers:
+ *   - RECORD_AUDIO runtime permission granted (plugin-side check in
+ *     CallForegroundPlugin.start). The manifest declares
+ *     foregroundServiceType="microphone" only, so TYPE_NONE is not a valid
+ *     fallback on API 34+ — we never attempt one.
+ *   - JS side gates on useCallJoined so the widget's getUserMedia has already
+ *     prompted for and received the grant by the time we start.
+ */
+public class CallForegroundService extends Service {
+
+    public static final String EXTRA_TITLE = "title";
+    public static final String EXTRA_BODY = "body";
+
+    private static final String CHANNEL_ID = "vojo_calls_ongoing";
+    // Stable id, distinct from VojoFirebaseMessagingService.SUMMARY_NOTIFICATION_ID
+    // (Integer.MIN_VALUE) and from per-room call ids (String.hashCode of "call_<roomId>").
+    private static final int NOTIFICATION_ID = 0x766F6A6F; // "vojo" as ASCII bytes
+
+    private static final String TAG = "CallFgs";
+
+    @Override
+    public int onStartCommand(Intent intent, int flags, int startId) {
+        String title = intent != null ? intent.getStringExtra(EXTRA_TITLE) : null;
+        String body = intent != null ? intent.getStringExtra(EXTRA_BODY) : null;
+        if (title == null || title.isEmpty()) title = "Активный звонок";
+        if (body == null) body = "";
+
+        NotificationManager nm = (NotificationManager) getSystemService(Context.NOTIFICATION_SERVICE);
+        if (nm == null) {
+            Log.w(TAG, "onStartCommand: NotificationManager null, cannot start FGS");
+            stopSelf(startId);
+            return START_NOT_STICKY;
+        }
+
+        ensureOngoingChannel(nm);
+
+        Intent launchIntent = new Intent(this, MainActivity.class)
+            .setAction(Intent.ACTION_MAIN)
+            .addCategory(Intent.CATEGORY_LAUNCHER)
+            .addFlags(Intent.FLAG_ACTIVITY_NEW_TASK | Intent.FLAG_ACTIVITY_SINGLE_TOP);
+        int piFlags = PendingIntent.FLAG_UPDATE_CURRENT
+            | (Build.VERSION.SDK_INT >= Build.VERSION_CODES.M ? PendingIntent.FLAG_IMMUTABLE : 0);
+        PendingIntent launchPI = PendingIntent.getActivity(this, 0, launchIntent, piFlags);
+
+        NotificationCompat.Builder builder = new NotificationCompat.Builder(this, CHANNEL_ID)
+            .setSmallIcon(R.mipmap.ic_launcher)
+            .setContentTitle(title)
+            .setContentText(body)
+            .setCategory(NotificationCompat.CATEGORY_CALL)
+            .setOngoing(true)
+            .setAutoCancel(false)
+            .setOnlyAlertOnce(true)
+            .setPriority(NotificationCompat.PRIORITY_LOW)
+            .setContentIntent(launchPI);
+
+        try {
+            if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.R) {
+                // API 30+: FOREGROUND_SERVICE_TYPE_MICROPHONE constant exists
+                // and 3-arg startForeground is available. API 34+ REQUIRES
+                // the type to match the manifest — we declared `microphone`
+                // and always pass it. RECORD_AUDIO grant is ensured by
+                // CallForegroundPlugin before this code runs.
+                startForeground(NOTIFICATION_ID, builder.build(),
+                    ServiceInfo.FOREGROUND_SERVICE_TYPE_MICROPHONE);
+                Log.d(TAG, "startForeground ok type=microphone");
+            } else {
+                // API 24-29: 2-arg form; manifest foregroundServiceType attribute
+                // is enough for the OS to classify the service correctly.
+                startForeground(NOTIFICATION_ID, builder.build());
+                Log.d(TAG, "startForeground ok (pre-R, manifest-driven type)");
+            }
+        } catch (Throwable t) {
+            // If startForeground with TYPE_MICROPHONE throws despite our
+            // precondition checks (unexpected OEM behavior, race, manifest
+            // drift), we intentionally do NOT retry with TYPE_NONE — that is
+            // invalid on API 34+ when the manifest declares `microphone`.
+            // Better to surface the failure and let the call proceed without
+            // retention than to silently crash with ForegroundServiceTypeException.
+            Log.e(TAG, "startForeground threw, stopping service without retry", t);
+            stopSelf(startId);
+        }
+
+        return START_NOT_STICKY;
+    }
+
+    @Override
+    public IBinder onBind(Intent intent) {
+        return null;
+    }
+
+    @Override
+    public void onDestroy() {
+        Log.d(TAG, "onDestroy");
+        // Belt-and-suspenders: if the service is being stopped via stopService
+        // and the FGS flag is still up, make sure the notification goes away.
+        // Idempotent if stopForeground was already called elsewhere.
+        stopForeground(STOP_FOREGROUND_REMOVE);
+        super.onDestroy();
+    }
+
+    private void ensureOngoingChannel(NotificationManager nm) {
+        if (Build.VERSION.SDK_INT < Build.VERSION_CODES.O) return;
+        if (nm.getNotificationChannel(CHANNEL_ID) != null) return;
+        NotificationChannel channel = new NotificationChannel(
+            CHANNEL_ID,
+            "Активные звонки",
+            NotificationManager.IMPORTANCE_LOW
+        );
+        channel.setDescription("Уведомление во время активного звонка Vojo");
+        channel.setShowBadge(false);
+        channel.enableLights(false);
+        channel.enableVibration(false);
+        channel.setSound(null, null);
+        nm.createNotificationChannel(channel);
+    }
+}

android/app/src/main/java/chat/vojo/app/ConversationShortcuts.java

@@ -0,0 +1,163 @@
+package chat.vojo.app;
+
+import android.content.Context;
+import android.content.Intent;
+import android.graphics.Bitmap;
+import android.os.Build;
+import android.util.Log;
+
+import androidx.core.content.LocusIdCompat;
+import androidx.core.content.pm.ShortcutInfoCompat;
+import androidx.core.content.pm.ShortcutManagerCompat;
+import androidx.core.graphics.drawable.IconCompat;
+
+import java.util.Collections;
+import java.util.Set;
+
+/**
+ * Publish a long-lived sharing shortcut for a Matrix room so the system
+ * treats per-room MessagingStyle notifications as conversations on
+ * Android 11+ (API 30+).
+ *
+ * Without a published shortcut whose id matches the notification's
+ * setShortcutId(), Android falls back to the app icon for the collapsed-
+ * preview avatar regardless of Person.setIcon / Builder.setLargeIcon —
+ * Person icons are only consulted by the Conversation styling layer,
+ * which activates exclusively for notifications backed by a real
+ * ShortcutInfoCompat marked Long Lived + the SHORTCUT_CATEGORY_CONVERSATION
+ * sharing category.
+ *
+ * Idempotent: republishing the same shortcut id is the documented "update"
+ * path; ShortcutManagerCompat handles dedup internally. Cheap to call
+ * from the render hot path (~ms on warm system, indistinguishable from a
+ * SharedPreferences write at our scale).
+ */
+final class ConversationShortcuts {
+
+    private static final String TAG = "ConvShortcuts";
+
+    private ConversationShortcuts() {}
+
+    /**
+     * Publish or refresh the shortcut backing a room's conversation
+     * notification. No-op on API < 30 — Conversation styling is an
+     * Android 11+ feature; older OS versions render the notification
+     * fine without the shortcut, and the largeIcon/Person.setIcon
+     * pipeline is the primary avatar source on them.
+     *
+     * @param ctx        Context for the shortcut manager binding.
+     * @param roomId     Matrix room id, used as the shortcut id so it
+     *                   matches NotificationCompat.Builder.setShortcutId.
+     * @param isDirect   Whether the room is a DM; flips the shortcut
+     *                   category so launchers can group DMs separately.
+     * @param label      Short visible label, typically the room name (or
+     *                   the peer's display name for a DM).
+     * @param avatar     Optional cached avatar bitmap. Null falls through
+     *                   to the app launcher icon — still publishes the
+     *                   shortcut so the conversation styling activates.
+     */
+    /**
+     * Returns the published ShortcutInfoCompat so the caller can attach
+     * it directly to the notification via setShortcutInfo() — this is
+     * the documented "atomic publish + bind" path that avoids the race
+     * where the notification posts before the shortcut publish has
+     * settled and Android sees an orphan shortcut id. Null on API < 30,
+     * null on failure (notification still posts cleanly).
+     */
+    static ShortcutInfoCompat publishForRoom(
+        Context ctx,
+        String roomId,
+        boolean isDirect,
+        String label,
+        Bitmap avatar
+    ) {
+        if (Build.VERSION.SDK_INT < Build.VERSION_CODES.R) {
+            return null;
+        }
+        if (roomId == null || roomId.isEmpty()) return null;
+        try {
+            // Conversation shortcut icon MUST be adaptive — official docs:
+            // "To avoid unintentional clipping of your shortcut avatar,
+            // provide an AdaptiveIconDrawable for the shortcut's icon."
+            // Without this, Android silently falls back to the app's
+            // launcher icon for the collapsed-shade conversation avatar
+            // slot, even though shortcut publish + bind succeed.
+            // Resource icons (mipmap.ic_launcher) already ship with
+            // adaptive layers in the manifest; bitmap avatars need padding
+            // so the safe zone doesn't crop them.
+            IconCompat icon;
+            if (avatar != null) {
+                Bitmap padded = AvatarLoader.toAdaptivePaddedBitmap(avatar);
+                icon = IconCompat.createWithAdaptiveBitmap(padded);
+            } else {
+                icon = IconCompat.createWithResource(ctx, R.mipmap.ic_launcher);
+            }
+
+            // Intent the shortcut launches when tapped from the launcher
+            // long-press menu or share sheet — opens MainActivity and
+            // delivers the same `room_id` extra the notification tap
+            // path uses, so the existing pushNotificationActionPerformed
+            // listener navigates correctly.
+            Intent launchIntent = new Intent(ctx, MainActivity.class)
+                .setAction(Intent.ACTION_VIEW)
+                .addFlags(Intent.FLAG_ACTIVITY_SINGLE_TOP | Intent.FLAG_ACTIVITY_CLEAR_TOP)
+                .putExtra("room_id", roomId)
+                // Capacitor PushNotificationsPlugin gates its action
+                // delivery on bundle.containsKey("google.message_id"); we
+                // attach an empty value so a launcher-initiated open
+                // takes the same path as a push-tap.
+                .putExtra("google.message_id", "");
+
+            // Constant value of androidx.core's
+            // ShortcutInfoCompat.SHORTCUT_CATEGORY_CONVERSATION. Hardcoded
+            // verbatim because older androidx.core in our dependency
+            // graph doesn't export the constant; the string itself is
+            // platform-stable per the Android shortcut category contract.
+            Set<String> categories =
+                Collections.singleton("android.shortcut.conversation");
+
+            ShortcutInfoCompat.Builder b = new ShortcutInfoCompat.Builder(ctx, roomId)
+                .setShortLabel(label != null && !label.isEmpty() ? label : "Vojo")
+                .setLongLabel(label != null && !label.isEmpty() ? label : "Vojo")
+                .setIntent(launchIntent)
+                .setIcon(icon)
+                .setLongLived(true)
+                .setCategories(categories)
+                // LocusId mirrors the shortcut id; the OS uses it to
+                // attribute the notification to a specific conversation
+                // for digital-wellbeing dashboards and bubble grouping.
+                .setLocusId(new LocusIdCompat(roomId))
+                // Marks isDirect so launchers / share sheet can present
+                // person-style affordances on DMs.
+                .setIsConversation();
+            // setPerson is only needed for one-on-one conversations to
+            // unlock direct-share suggestions, but for a DM we also want
+            // it to anchor the shortcut on the peer's identity. Skipped
+            // for groups (single Person doesn't represent the room).
+            if (isDirect) {
+                b.setPerson(new androidx.core.app.Person.Builder()
+                    // setKey must match the Person.key used in the
+                    // MessagingStyle so Android's conversation
+                    // attribution matches the shortcut to the
+                    // notification on the same identity.
+                    .setKey(roomId)
+                    .setName(label != null ? label : "")
+                    .setIcon(icon)
+                    .build());
+            }
+
+            ShortcutInfoCompat shortcut = b.build();
+            boolean ok = ShortcutManagerCompat.pushDynamicShortcut(ctx, shortcut);
+            Log.i(TAG, "publish room=" + roomId + " label=" + label
+                + " hasAvatar=" + (avatar != null) + " ok=" + ok);
+            return shortcut;
+        } catch (Throwable t) {
+            // Shortcut publish is best-effort UX — a failure must not
+            // sink the notification. Worst case: collapsed preview
+            // falls back to app icon (same as before the shortcut path
+            // existed at all).
+            Log.w(TAG, "publish failed room=" + roomId, t);
+            return null;
+        }
+    }
+}

android/app/src/main/java/chat/vojo/app/FullScreenIntentPlugin.java

@@ -0,0 +1,75 @@
+package chat.vojo.app;
+
+import android.app.NotificationManager;
+import android.content.Context;
+import android.content.Intent;
+import android.net.Uri;
+import android.os.Build;
+import android.provider.Settings;
+
+import com.getcapacitor.JSObject;
+import com.getcapacitor.Plugin;
+import com.getcapacitor.PluginCall;
+import com.getcapacitor.PluginMethod;
+import com.getcapacitor.annotation.CapacitorPlugin;
+
+/**
+ * Bridges Android 14+ (API 34) full-screen-intent opt-in into JS.
+ *
+ * On API 34 `USE_FULL_SCREEN_INTENT` was reclassified from "normal" to
+ * "special appop" — declaring it in the manifest is no longer enough to
+ * actually display a full-screen notification over the lockscreen. The user
+ * must opt in via Settings → Apps → Vojo → Full-screen notifications. There's
+ * no runtime grant API, only a deep-link.
+ *
+ * Without the opt-in, `setFullScreenIntent(launchPI, true)` still satisfies
+ * the AOSP NotificationManagerService gate (so CallStyle doesn't get silently
+ * dropped), but the notification renders as a regular heads-up and the screen
+ * doesn't wake over the lockscreen — which was the "why is this just a banner
+ * on the lockscreen?" symptom we saw on the Samsung OneUI test device.
+ *
+ * See docs/plans/dm_calls.md ADR 2.5-fsi for the full history.
+ */
+@CapacitorPlugin(name = "FullScreenIntent")
+public class FullScreenIntentPlugin extends Plugin {
+
+    @PluginMethod
+    public void canUseFullScreenIntent(PluginCall call) {
+        JSObject ret = new JSObject();
+        ret.put("value", canUseFullScreenIntentInternal());
+        call.resolve(ret);
+    }
+
+    @PluginMethod
+    public void openSettings(PluginCall call) {
+        Context ctx = getContext();
+        Intent intent;
+        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.UPSIDE_DOWN_CAKE) {
+            // API 34+ has a dedicated Settings screen for the full-screen notification opt-in.
+            intent = new Intent(Settings.ACTION_MANAGE_APP_USE_FULL_SCREEN_INTENT);
+            intent.setData(Uri.parse("package:" + ctx.getPackageName()));
+        } else {
+            // Fallback for API ≤33: the per-app notification Settings page is the closest
+            // equivalent and also covers channel-level toggles (mute, DND bypass, etc).
+            intent = new Intent(Settings.ACTION_APP_NOTIFICATION_SETTINGS);
+            intent.putExtra(Settings.EXTRA_APP_PACKAGE, ctx.getPackageName());
+        }
+        intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK);
+        try {
+            ctx.startActivity(intent);
+            call.resolve();
+        } catch (Throwable t) {
+            call.reject("Failed to open FSI settings: " + t.getMessage());
+        }
+    }
+
+    private boolean canUseFullScreenIntentInternal() {
+        // On API ≤33 `USE_FULL_SCREEN_INTENT` is a normal permission — if it's
+        // declared in the manifest, the app already has it. Skip the runtime check.
+        if (Build.VERSION.SDK_INT < Build.VERSION_CODES.UPSIDE_DOWN_CAKE) return true;
+        NotificationManager nm = (NotificationManager)
+            getContext().getSystemService(Context.NOTIFICATION_SERVICE);
+        if (nm == null) return false;
+        return nm.canUseFullScreenIntent();
+    }
+}

android/app/src/main/java/chat/vojo/app/LaunchSplashPlugin.java

@@ -0,0 +1,16 @@
+package chat.vojo.app;
+
+import com.getcapacitor.Plugin;
+import com.getcapacitor.PluginCall;
+import com.getcapacitor.PluginMethod;
+import com.getcapacitor.annotation.CapacitorPlugin;
+
+@CapacitorPlugin(name = "LaunchSplash")
+public class LaunchSplashPlugin extends Plugin {
+
+    @PluginMethod
+    public void ready(PluginCall call) {
+        MainActivity.releaseLaunchSplash();
+        call.resolve();
+    }
+}

android/app/src/main/java/chat/vojo/app/MainActivity.java

@@ -0,0 +1,128 @@
+package chat.vojo.app;
+
+import android.os.Bundle;
+import android.os.Handler;
+import android.os.Looper;
+import androidx.activity.EdgeToEdge;
+import androidx.core.splashscreen.SplashScreen;
+import androidx.core.view.WindowCompat;
+import androidx.core.view.WindowInsetsControllerCompat;
+import com.getcapacitor.BridgeActivity;
+
+public class MainActivity extends BridgeActivity {
+    public static volatile boolean isInForeground = false;
+    private static volatile boolean launchSplashReady = false;
+
+    // Safety net for setKeepOnScreenCondition: if JS never calls
+    // launchSplash.ready() (boot crash, exception during config load before
+    // AuthMascot mounts, network hang in useClientConfig, deep-link straight
+    // into AuthLayout where the centered AuthMascot variant doesn't render,
+    // …) the splash would otherwise hang indefinitely and the user can't
+    // interact with anything. 5s covers normal cold boots on mid-range
+    // Android (config + bundle parse + first paint typically lands inside
+    // 1-2s) with comfortable headroom; past it we drop the splash and let
+    // whatever the web side has rendered take over — including blank
+    // AuthLayout, which is at least recoverable.
+    private static final long SPLASH_SAFETY_TIMEOUT_MS = 5000L;
+
+    // Short debounce on the onPause→renderRegistry edge so an in-flight JS
+    // removeIncomingRing bridge call (e.g. user accepted/declined, then
+    // immediately pressed Home) has a chance to land before we post native
+    // CallStyle for a ring that's about to be removed. 150ms covers the
+    // strip-accept chain (Capacitor roundtrip + switchOrStartDmCall
+    // resolve + sync-effect → bridge) on mid-range Android; imperceptible
+    // as a silent-ring delay.
+    private static final long RENDER_DEBOUNCE_MS = 150L;
+    // Modest debounce on the onResume→cancelRenderedIncomingRings edge so JS
+    // has a moment to hydrate incomingCallsAtom before the native surface
+    // goes away. Covers warm resume (hook alive, /sync delivers an ADD
+    // within ~100-200ms) cleanly. Cold resume (killed process, Matrix
+    // client rehydration takes 1-3s) still has a "no surface" window —
+    // acceptable tradeoff since tap-native flows carry call_action and
+    // are handled by pendingCallActionConsumer regardless of atom state.
+    private static final long CANCEL_DEBOUNCE_MS = 300L;
+    private final Handler lifecycleHandler = new Handler(Looper.getMainLooper());
+    private final Runnable renderRunnable = () ->
+        VojoFirebaseMessagingService.renderRegistry(this);
+    private final Runnable cancelRunnable = () ->
+        VojoFirebaseMessagingService.cancelRenderedIncomingRings(this);
+
+    public static void releaseLaunchSplash() {
+        launchSplashReady = true;
+    }
+
+    @Override
+    protected void onCreate(Bundle savedInstanceState) {
+        if (savedInstanceState == null) {
+            launchSplashReady = false;
+        }
+
+        // Custom plugins must be registered before super.onCreate so BridgeActivity
+        // can wire them into the WebView bridge on load. Registering after
+        // super.onCreate would make the plugin invisible to JS until the next relaunch.
+        registerPlugin(FullScreenIntentPlugin.class);
+        registerPlugin(CallForegroundPlugin.class);
+        registerPlugin(LaunchSplashPlugin.class);
+        registerPlugin(ShareTargetPlugin.class);
+        registerPlugin(PollingPlugin.class);
+
+        // AndroidX SplashScreen must be installed before super.onCreate().
+        // Keep it until the web splash confirms its first visible frame is
+        // ready, OR the safety timeout elapses (see SPLASH_SAFETY_TIMEOUT_MS).
+        final long splashStartMs = System.currentTimeMillis();
+        SplashScreen splashScreen = SplashScreen.installSplashScreen(this);
+        splashScreen.setKeepOnScreenCondition(() -> {
+            if (launchSplashReady) return false;
+            return System.currentTimeMillis() - splashStartMs < SPLASH_SAFETY_TIMEOUT_MS;
+        });
+
+        EdgeToEdge.enable(this);
+        super.onCreate(savedInstanceState);
+        // Force light icons on both system bars: our CSS is permanently dark
+        // (Dawn redesign), but EdgeToEdge.enable auto-detects icon tint from
+        // the device uiMode — on a light-mode device that gives dark icons
+        // over our dark bars and they vanish.
+        WindowInsetsControllerCompat controller =
+            WindowCompat.getInsetsController(getWindow(), getWindow().getDecorView());
+        controller.setAppearanceLightStatusBars(false);
+        controller.setAppearanceLightNavigationBars(false);
+    }
+
+    @Override
+    public void onResume() {
+        super.onResume();
+        isInForeground = true;
+        // Cancel any pending render: user came back before the debounce fired,
+        // JS strip will own UX, no need to surface native.
+        lifecycleHandler.removeCallbacks(renderRunnable);
+        // Defer the native cancel so JS strip has a moment to hydrate from
+        // incomingCallsAtom. Registry entries persist — they still represent
+        // live rings, just the native surfaces go.
+        lifecycleHandler.removeCallbacks(cancelRunnable);
+        lifecycleHandler.postDelayed(cancelRunnable, CANCEL_DEBOUNCE_MS);
+    }
+
+    @Override
+    public void onPause() {
+        super.onPause();
+        isInForeground = false;
+        // Re-backgrounding: don't cancel a native the user will still need
+        // visible. The render runnable below will re-render if needed.
+        lifecycleHandler.removeCallbacks(cancelRunnable);
+        // Schedule render — user is backgrounding, JS audio gate is about to
+        // close, native CallStyle must surface or the ring goes silent. Debounce
+        // absorbs the bridge-call race: if onResume fires within RENDER_DEBOUNCE_MS
+        // (user bounce), the render is cancelled.
+        lifecycleHandler.removeCallbacks(renderRunnable);
+        lifecycleHandler.postDelayed(renderRunnable, RENDER_DEBOUNCE_MS);
+    }
+
+    @Override
+    public void onDestroy() {
+        // Drop any pending render/cancel so runnables — which capture `this` —
+        // can't fire post-destroy and land an nm.notify / nm.cancel against a
+        // dead Activity context on config change (rotation) or process teardown.
+        lifecycleHandler.removeCallbacksAndMessages(null);
+        super.onDestroy();
+    }
+}

android/app/src/main/java/chat/vojo/app/MarkAsReadReceiver.java

@@ -0,0 +1,147 @@
+package chat.vojo.app;
+
+import android.content.BroadcastReceiver;
+import android.content.Context;
+import android.content.Intent;
+import android.content.SharedPreferences;
+import android.util.Log;
+
+import java.io.IOException;
+import java.net.HttpURLConnection;
+import java.net.URL;
+import java.net.URLEncoder;
+import java.util.concurrent.ExecutorService;
+import java.util.concurrent.Executors;
+
+/**
+ * Handles the per-notification "Mark as read" action.
+ *
+ * Posts {@code POST /_matrix/client/v3/rooms/{roomId}/receipt/m.read/{eventId}}
+ * using the access token saved by the polling lifecycle in
+ * {@code vojo_poll_state} SharedPreferences (same storage VojoPollWorker uses;
+ * keeps the credential lifecycle single-sourced). After a successful 2xx the
+ * per-room MessagingStyle notification is dismissed and the
+ * {@link RoomMessageCache} is cleared so the next push to that room starts a
+ * fresh conversation rather than re-appending to the prior history.
+ *
+ * Dismiss policy: OPTIMISTIC. The per-room notification is dismissed
+ * synchronously in onReceive — before the HTTP receipt PUT is even
+ * attempted — so the user sees instant feedback. The async receipt POST
+ * happens on a worker thread afterwards. This mirrors element-android's
+ * NotificationBroadcastReceiver pattern and matches the user's mental
+ * model ("I tapped, it should disappear immediately").
+ *
+ * Failure mode: on any non-2xx or thrown exception we accept that the
+ * server-side read receipt did not land. We do NOT re-post the
+ * notification or implement a flusher because:
+ *   - the next room open from the JS app issues a fresh read-receipt
+ *     for the latest visible event, catching up the server state
+ *   - the in-app read-marker logic is the authoritative path; this
+ *     receiver is a convenience for the shade-tap shortcut
+ *   - accumulating tombstones in prefs (the CallDeclineReceiver pattern)
+ *     would risk leaking historical eventIds the JS side would re-issue
+ *     on app resume anyway
+ *
+ * Null-credential edge case (fresh install + first push before any
+ * saveSession bridge): no token to use, we still dismiss the notification
+ * locally so the user isn't stuck looking at a "stuck" Mark-as-read
+ * button. The next room open from JS covers the server view.
+ */
+public class MarkAsReadReceiver extends BroadcastReceiver {
+
+    public static final String ACTION_MARK_AS_READ = "chat.vojo.app.MARK_AS_READ";
+    public static final String EXTRA_ROOM_ID = "room_id";
+    public static final String EXTRA_EVENT_ID = "event_id";
+
+    private static final int CONNECT_TIMEOUT_MS = 8_000;
+    private static final int READ_TIMEOUT_MS = 8_000;
+    private static final String TAG = "MarkAsReadRcvr";
+
+    private static final ExecutorService EXECUTOR = Executors.newSingleThreadExecutor();
+
+    @Override
+    public void onReceive(Context context, Intent intent) {
+        if (intent == null) return;
+        final String roomId = intent.getStringExtra(EXTRA_ROOM_ID);
+        final String eventId = intent.getStringExtra(EXTRA_EVENT_ID);
+        if (roomId == null || roomId.isEmpty()) {
+            Log.w(TAG, "onReceive: missing room_id, abort");
+            return;
+        }
+
+        final Context appContext = context.getApplicationContext();
+        // Dismiss first for instant UX feedback — HTTP latency is irrelevant
+        // to the perceived "marked as read" action.
+        VojoFirebaseMessagingService.dismissRoomNotification(appContext, roomId);
+
+        final SharedPreferences prefs = appContext.getSharedPreferences(
+            VojoPollWorker.PREFS, Context.MODE_PRIVATE);
+        final String token = prefs.getString(VojoPollWorker.KEY_ACCESS_TOKEN, null);
+        final String homeserver = prefs.getString(VojoPollWorker.KEY_HOMESERVER_URL, null);
+        if (token == null || token.isEmpty() || homeserver == null || homeserver.isEmpty()) {
+            Log.w(TAG, "onReceive: no credentials in prefs, local dismiss only");
+            return;
+        }
+        if (eventId == null || eventId.isEmpty()) {
+            // Without an eventId we cannot issue a receipt PUT — the JS-side
+            // read-marker handler will catch this up on the next room open.
+            Log.w(TAG, "onReceive: no event_id, local dismiss only");
+            return;
+        }
+
+        final PendingResult pendingResult = goAsync();
+        EXECUTOR.execute(() -> {
+            try {
+                int status = sendReceipt(homeserver, token, roomId, eventId);
+                if (status >= 200 && status < 300) {
+                    if (BuildConfig.DEBUG) {
+                        Log.d(TAG, "receipt ok status=" + status + " room=" + roomId);
+                    }
+                } else {
+                    Log.w(TAG, "receipt non-2xx status=" + status + " room=" + roomId);
+                }
+            } catch (Throwable t) {
+                Log.w(TAG, "receipt threw room=" + roomId, t);
+            } finally {
+                pendingResult.finish();
+            }
+        });
+    }
+
+    private int sendReceipt(
+        String baseUrl,
+        String accessToken,
+        String roomId,
+        String eventId
+    ) throws IOException {
+        String url = trimTrailingSlash(baseUrl)
+            + "/_matrix/client/v3/rooms/"
+            + URLEncoder.encode(roomId, "UTF-8")
+            + "/receipt/m.read/"
+            + URLEncoder.encode(eventId, "UTF-8");
+
+        HttpURLConnection conn = (HttpURLConnection) new URL(url).openConnection();
+        try {
+            conn.setRequestMethod("POST");
+            conn.setRequestProperty("Authorization", "Bearer " + accessToken);
+            conn.setRequestProperty("Content-Type", "application/json");
+            conn.setConnectTimeout(CONNECT_TIMEOUT_MS);
+            conn.setReadTimeout(READ_TIMEOUT_MS);
+            conn.setDoOutput(true);
+            // Empty JSON body per spec; setFixedLengthStreamingMode keeps the
+            // connection on the cached path instead of chunked-transfer fallback.
+            byte[] payload = "{}".getBytes("UTF-8");
+            conn.setFixedLengthStreamingMode(payload.length);
+            try (java.io.OutputStream os = conn.getOutputStream()) {
+                os.write(payload);
+            }
+            return conn.getResponseCode();
+        } finally {
+            conn.disconnect();
+        }
+    }
+
+    private static String trimTrailingSlash(String s) {
+        return (s != null && s.endsWith("/")) ? s.substring(0, s.length() - 1) : s;
+    }
+}

android/app/src/main/java/chat/vojo/app/NotificationDedup.java

@@ -0,0 +1,104 @@
+package chat.vojo.app;
+
+import android.content.Context;
+import android.content.SharedPreferences;
+
+import java.util.Iterator;
+import java.util.LinkedHashSet;
+import java.util.Set;
+
+/**
+ * Cross-source LRU dedup for rendered push event_ids.
+ *
+ * Both the FCM service (after a successful nm.notify) and the polling Worker
+ * write into the same bounded SharedPreferences-backed set. The Worker reads
+ * it to skip events FCM already delivered — which fixes the regression where
+ * a user who dismissed an FCM notification before polling fired would see
+ * the same event resurface up to 15 minutes later via the polling fallback.
+ *
+ * The native `eventId.hashCode()` notification-id slot is still the primary
+ * dedup for *concurrent* render (Android NotificationManager replace), but
+ * that only collapses surfaces while both notifications are still visible;
+ * once the user dismisses, the slot is empty and the second render would
+ * post fresh. This shared set covers that gap.
+ *
+ * Synchronisation: SharedPreferences read-modify-write is not atomic across
+ * threads/processes, and FCM service runs on a Firebase-managed background
+ * thread while the Worker runs on WorkManager's executor. We serialise all
+ * mutations through a static lock. Critical sections are short (string split
+ * + LinkedHashSet trim + putString) — no Binder calls.
+ */
+final class NotificationDedup {
+
+    // Capacity is intentionally larger than VojoPollWorker's worst-case per-run
+    // event count (MAX_PAGES_PER_RUN × PAGE_LIMIT = 250). If a single fire
+    // marks 250 events and the cap were 200, the 50 oldest of those would
+    // already be evicted by the time we finish writing — so a sibling poll
+    // resuming the same window would re-render them. 500 gives 2× headroom
+    // while staying ~12 KB in SharedPreferences (negligible).
+    private static final int MAX_TRACKED = 500;
+    private static final Object lock = new Object();
+
+    private NotificationDedup() {}
+
+    /** Returns true iff the given event_id has been notified in a recent cycle. */
+    static boolean wasNotified(Context ctx, String eventId) {
+        if (eventId == null || eventId.isEmpty()) return false;
+        synchronized (lock) {
+            return readSet(ctx).contains(eventId);
+        }
+    }
+
+    /** Append the event_id to the LRU set, trimming the oldest when full. */
+    static void markNotified(Context ctx, String eventId) {
+        if (eventId == null || eventId.isEmpty()) return;
+        synchronized (lock) {
+            Set<String> set = readSet(ctx);
+            // LinkedHashSet preserves insertion order — re-adding moves to tail
+            // only if we remove-then-add. The Set#add no-op on a present entry
+            // does NOT refresh position, but the simple "drop oldest" trim
+            // below is adequate for our scale and matches the Worker's
+            // existing semantics. Skip the disk write entirely when add()
+            // returned false — the event was already in the set, persistence
+            // would just churn SharedPreferences for no state change.
+            if (!set.add(eventId)) return;
+            if (set.size() > MAX_TRACKED) {
+                Iterator<String> it = set.iterator();
+                int drop = set.size() - MAX_TRACKED;
+                while (it.hasNext() && drop > 0) {
+                    it.next();
+                    it.remove();
+                    drop -= 1;
+                }
+            }
+            writeSet(ctx, set);
+        }
+    }
+
+    /** Caller must hold {@link #lock}. */
+    private static Set<String> readSet(Context ctx) {
+        SharedPreferences prefs = ctx.getSharedPreferences(
+            VojoPollWorker.PREFS, Context.MODE_PRIVATE);
+        String raw = prefs.getString(VojoPollWorker.KEY_NOTIFIED_IDS, "");
+        Set<String> out = new LinkedHashSet<>();
+        if (raw.isEmpty()) return out;
+        for (String id : raw.split(",")) {
+            if (!id.isEmpty()) out.add(id);
+        }
+        return out;
+    }
+
+    /** Caller must hold {@link #lock}. */
+    private static void writeSet(Context ctx, Set<String> set) {
+        SharedPreferences prefs = ctx.getSharedPreferences(
+            VojoPollWorker.PREFS, Context.MODE_PRIVATE);
+        StringBuilder sb = new StringBuilder(set.size() * 25);
+        boolean first = true;
+        for (String id : set) {
+            if (!first) sb.append(',');
+            sb.append(id);
+            first = false;
+        }
+        prefs.edit().putString(VojoPollWorker.KEY_NOTIFIED_IDS, sb.toString()).apply();
+    }
+}

android/app/src/main/java/chat/vojo/app/NotificationDismissReceiver.java

@@ -0,0 +1,37 @@
+package chat.vojo.app;
+
+import android.content.BroadcastReceiver;
+import android.content.Context;
+import android.content.Intent;
+import android.util.Log;
+
+/**
+ * Fires when the user swipes a per-room MessagingStyle notification away.
+ *
+ * Without this hook, RoomMessageCache would still hold the prior messages
+ * for that room — and the next push would append onto that history and
+ * re-surface the messages the user just dismissed. With it, swipe clears
+ * the cache so the next push starts a fresh conversation for the room.
+ *
+ * NOTE: this only fires for user-driven dismissals — programmatic
+ * nm.cancel calls (mark-as-read, receipt-driven dismiss, channel migration)
+ * already call RoomMessageCache.clear themselves and do NOT fire the
+ * delete intent. There's no double-clear risk.
+ */
+public class NotificationDismissReceiver extends BroadcastReceiver {
+
+    public static final String ACTION_NOTIFICATION_DISMISSED =
+        "chat.vojo.app.NOTIFICATION_DISMISSED";
+    public static final String EXTRA_ROOM_ID = "room_id";
+
+    private static final String TAG = "DismissRcvr";
+
+    @Override
+    public void onReceive(Context context, Intent intent) {
+        if (intent == null) return;
+        String roomId = intent.getStringExtra(EXTRA_ROOM_ID);
+        if (roomId == null || roomId.isEmpty()) return;
+        if (BuildConfig.DEBUG) Log.d(TAG, "swipe clear cache room=" + roomId);
+        RoomMessageCache.clear(roomId);
+    }
+}

android/app/src/main/java/chat/vojo/app/PollingPlugin.java

@@ -0,0 +1,236 @@
+package chat.vojo.app;
+
+import android.content.Context;
+import android.content.SharedPreferences;
+import android.util.Log;
+
+import androidx.work.Constraints;
+import androidx.work.ExistingPeriodicWorkPolicy;
+import androidx.work.NetworkType;
+import androidx.work.PeriodicWorkRequest;
+import androidx.work.WorkManager;
+
+import com.getcapacitor.JSObject;
+import com.getcapacitor.Plugin;
+import com.getcapacitor.PluginCall;
+import com.getcapacitor.PluginMethod;
+import com.getcapacitor.annotation.CapacitorPlugin;
+
+import java.util.concurrent.TimeUnit;
+
+/**
+ * JS ↔ Android bridge for the WorkManager-based polling fallback.
+ *
+ * Lifecycle:
+ *   - JS calls saveSession({accessToken, homeserverUrl, userId}) on login,
+ *     on push (re)enable, and on visibilitychange → visible (to recover a
+ *     401-cleared credentials slot without a full remount).
+ *   - JS calls schedule({intervalMinutes}) once push is enabled. Idempotent:
+ *     KEEP policy means a second schedule() call against an already-enqueued
+ *     worker is a no-op (the running period continues unchanged).
+ *   - JS calls saveRoomNames({names}) on mount + visibilitychange → visible
+ *     so VojoPollWorker has a local cache to resolve room_id → display name
+ *     without making N extra GET /rooms/{id}/state/m.room.name requests.
+ *     Brand-new rooms created between visibility events fall back to
+ *     sender_display_name in the renderer.
+ *   - JS calls cancel() + clearSession() on logout / push disable.
+ *
+ * Worker tag: a single unique periodic worker named UNIQUE_WORK_NAME — KEEP
+ * policy prevents schedule churn from re-creating it. Cancel() removes it
+ * by the same name.
+ */
+@CapacitorPlugin(name = "Polling")
+public class PollingPlugin extends Plugin {
+
+    private static final String TAG = "PollingPlugin";
+    private static final String UNIQUE_WORK_NAME = "vojo_push_poll";
+
+    // Android's hard floor for PeriodicWorkRequest. Requests with shorter
+    // intervals are silently clamped to 15 minutes. We accept the requested
+    // value from JS but enforce the floor here so misuse from JS doesn't
+    // produce a silently-different behavior.
+    private static final long MIN_INTERVAL_MINUTES = 15;
+
+    @PluginMethod
+    public void saveSession(PluginCall call) {
+        String accessToken = call.getString("accessToken");
+        String homeserverUrl = call.getString("homeserverUrl");
+        if (accessToken == null || accessToken.isEmpty()
+            || homeserverUrl == null || homeserverUrl.isEmpty()) {
+            call.reject("missing_accessToken_or_homeserverUrl");
+            return;
+        }
+        String userId = call.getString("userId");
+        SharedPreferences prefs = getContext()
+            .getSharedPreferences(VojoPollWorker.PREFS, Context.MODE_PRIVATE);
+        SharedPreferences.Editor editor = prefs.edit()
+            .putString(VojoPollWorker.KEY_ACCESS_TOKEN, accessToken)
+            .putString(VojoPollWorker.KEY_HOMESERVER_URL, homeserverUrl);
+        if (userId != null && !userId.isEmpty()) {
+            editor.putString(VojoPollWorker.KEY_USER_ID, userId);
+        }
+        // Seed the watermark to "now minus a small clock-skew buffer" on the
+        // first saveSession after install / logout. Without seeding the
+        // Worker's first fire sees watermark=0 and renders every historical
+        // unread /notifications entry as a fresh push. The buffer covers the
+        // case where the device clock runs ahead of the homeserver's clock —
+        // event ts is server-side, so a too-fresh local seed would silently
+        // skip recently-arrived events as "older than watermark" forever.
+        // 60s tolerates typical NTP drift while still suppressing days-old
+        // backlog on first enable. We seed only when the key is absent so
+        // subsequent saveSession calls (token rotation, visibilitychange
+        // re-bridge) don't reset live state.
+        if (!prefs.contains(VojoPollWorker.KEY_LAST_SEEN_TS)) {
+            editor.putLong(
+                VojoPollWorker.KEY_LAST_SEEN_TS,
+                System.currentTimeMillis() - SEED_CLOCK_SKEW_BUFFER_MS
+            );
+        }
+        editor.apply();
+        call.resolve();
+    }
+
+    private static final long SEED_CLOCK_SKEW_BUFFER_MS = 60_000L;
+
+    @PluginMethod
+    public void clearSession(PluginCall call) {
+        getContext()
+            .getSharedPreferences(VojoPollWorker.PREFS, Context.MODE_PRIVATE)
+            .edit()
+            .remove(VojoPollWorker.KEY_ACCESS_TOKEN)
+            .remove(VojoPollWorker.KEY_HOMESERVER_URL)
+            .remove(VojoPollWorker.KEY_USER_ID)
+            .remove(VojoPollWorker.KEY_LAST_SEEN_TS)
+            .remove(VojoPollWorker.KEY_DRAIN_CURSOR)
+            .remove(VojoPollWorker.KEY_DRAIN_TARGET_TS)
+            .remove(VojoPollWorker.KEY_NOTIFIED_IDS)
+            .remove(VojoPollWorker.KEY_ROOM_NAMES)
+            .remove(VojoPollWorker.KEY_USER_AVATARS)
+            .apply();
+        call.resolve();
+    }
+
+    /**
+     * user_id → MXC avatar URL snapshot. Mirrors {@link #saveRoomNames} —
+     * stored as a JSON blob in vojo_poll_state for the FCM service /
+     * polling Worker / ReplyReceiver to consult via
+     * VojoFirebaseMessagingService.lookupUserAvatarMxc. JS dumps on the
+     * same lifecycle triggers as room names (mount, visibility resume,
+     * m.direct change, m.room.encryption flip).
+     */
+    @PluginMethod
+    public void saveUserAvatars(PluginCall call) {
+        JSObject avatars = call.getObject("avatars");
+        if (avatars == null) {
+            call.reject("missing_avatars");
+            return;
+        }
+        String serialized = avatars.toString();
+        getContext()
+            .getSharedPreferences(VojoPollWorker.PREFS, Context.MODE_PRIVATE)
+            .edit()
+            .putString(VojoPollWorker.KEY_USER_AVATARS, serialized)
+            .apply();
+        Log.i(TAG, "saveUserAvatars: " + avatars.length() + " entries, "
+            + serialized.length() + " bytes");
+        call.resolve();
+    }
+
+    @PluginMethod
+    public void saveRoomNames(PluginCall call) {
+        JSObject names = call.getObject("names");
+        if (names == null) {
+            // Empty map is also valid (user cleared all rooms) — JS passes
+            // {} explicitly in that case; missing key is a contract bug.
+            call.reject("missing_names");
+            return;
+        }
+        // `JSObject extends JSONObject`, so names.toString() is already a
+        // valid JSON serialisation of validated values — no need to re-parse
+        // it through `new JSONObject(...)` just to re-serialise. Persist
+        // verbatim.
+        String serialized = names.toString();
+        getContext()
+            .getSharedPreferences(VojoPollWorker.PREFS, Context.MODE_PRIVATE)
+            .edit()
+            .putString(VojoPollWorker.KEY_ROOM_NAMES, serialized)
+            .apply();
+        Log.i(TAG, "saveRoomNames: " + names.length() + " entries, "
+            + serialized.length() + " bytes");
+        call.resolve();
+    }
+
+    @PluginMethod
+    public void schedule(PluginCall call) {
+        Integer intervalMinutes = call.getInt("intervalMinutes", 15);
+        long interval = Math.max(MIN_INTERVAL_MINUTES, intervalMinutes != null ? intervalMinutes : 15);
+
+        Constraints constraints = new Constraints.Builder()
+            .setRequiredNetworkType(NetworkType.CONNECTED)
+            .build();
+
+        PeriodicWorkRequest req = new PeriodicWorkRequest.Builder(
+            VojoPollWorker.class, interval, TimeUnit.MINUTES
+        )
+            .setConstraints(constraints)
+            .addTag("vojo_push_poll")
+            .build();
+
+        try {
+            WorkManager.getInstance(getContext())
+                .enqueueUniquePeriodicWork(
+                    UNIQUE_WORK_NAME,
+                    ExistingPeriodicWorkPolicy.KEEP,
+                    req
+                );
+            Log.d(TAG, "scheduled periodic poll every " + interval + " minutes");
+            call.resolve();
+        } catch (Throwable t) {
+            Log.w(TAG, "schedule failed", t);
+            call.reject("schedule_failed: " + t.getMessage());
+        }
+    }
+
+    /**
+     * Dismiss the per-room MessagingStyle notification + clear the in-memory
+     * RoomMessageCache for the room. Called from the JS receipt listener when
+     * a server-side read receipt zeroes the unread count (the user read on
+     * another device / tab). No-op if the notification was never posted or
+     * has already been swiped away.
+     */
+    @PluginMethod
+    public void dismissRoom(PluginCall call) {
+        String roomId = call.getString("roomId");
+        if (roomId == null || roomId.isEmpty()) {
+            call.reject("missing_roomId");
+            return;
+        }
+        VojoFirebaseMessagingService.dismissRoomNotification(getContext(), roomId);
+        call.resolve();
+    }
+
+    @PluginMethod
+    public void cancel(PluginCall call) {
+        try {
+            // Block on the Operation so callers awaiting cancel() see the
+            // cancel committed to WorkManager's database before we resolve.
+            // (NOTE: this does NOT interrupt a Worker that's already mid
+            // doWork(); cooperative cancellation via isStopped() is owned
+            // by VojoPollWorker itself.) Without this wait a fast
+            // disable→reenable sequence races with ExistingPeriodicWorkPolicy.KEEP
+            // — the second enqueueUniquePeriodicWork can land before the
+            // cancel is committed and become a no-op. We're already off
+            // the main thread (Capacitor dispatches plugin calls on its
+            // own executor), so the blocking get() is safe here.
+            WorkManager.getInstance(getContext())
+                .cancelUniqueWork(UNIQUE_WORK_NAME)
+                .getResult()
+                .get();
+            Log.d(TAG, "cancelled periodic poll");
+            call.resolve();
+        } catch (Throwable t) {
+            Log.w(TAG, "cancel failed", t);
+            call.reject("cancel_failed: " + t.getMessage());
+        }
+    }
+}

android/app/src/main/java/chat/vojo/app/PushStrings.java

@@ -0,0 +1,170 @@
+package chat.vojo.app;
+
+import android.content.Context;
+import android.content.SharedPreferences;
+import android.content.res.Configuration;
+
+import java.util.Locale;
+
+/**
+ * Locale-aware push-notification strings. Resources (values{,-ru}/
+ * push_strings.xml) are auto-generated at build time by
+ * scripts/gen-push-strings.mjs from public/locales/{en,ru}.json so
+ * the Push namespace has a single source of truth shared with the
+ * web Service Worker. Do not edit push_strings.xml by hand — it will
+ * be overwritten on the next `npm run android:sync`.
+ *
+ * Locale selection: Vojo ships an explicit in-app language picker that
+ * does NOT have to match the device locale. pushLanguageBridge.ts
+ * mirrors i18next's current language into Capacitor Preferences
+ * (shared_prefs/CapacitorStorage.xml, key "vojo.appLanguage") on every
+ * `languageChanged` event; we read it here and force it onto a
+ * Configuration-scoped Context before the getString call.
+ *
+ * Killed-process pushes may arrive before JS has ever booted — no pref
+ * to read. In that case we fall back to the device locale, normalised
+ * to {en, ru}; anything else maps to en, matching i18n.ts
+ * fallbackLng: 'en' on the main thread.
+ */
+final class PushStrings {
+
+    private static final String PREFS_GROUP = "CapacitorStorage";
+    private static final String LANG_KEY = "vojo.appLanguage";
+
+    private PushStrings() {}
+
+    static String messageFallback(Context ctx) {
+        return forAppLocale(ctx).getString(R.string.push_new_message);
+    }
+
+    static String messagesFallback(Context ctx) {
+        return forAppLocale(ctx).getString(R.string.push_new_messages);
+    }
+
+    static String inviteTitle(Context ctx) {
+        return forAppLocale(ctx).getString(R.string.push_invitation);
+    }
+
+    static String missedCallTitle(Context ctx) {
+        return forAppLocale(ctx).getString(R.string.push_missed_call);
+    }
+
+    static String missedCallBody(Context ctx, String caller) {
+        String safeCaller = caller == null ? "" : caller;
+        return forAppLocale(ctx).getString(R.string.push_missed_call_body, safeCaller);
+    }
+
+    static String channelGroup(Context ctx) {
+        return forAppLocale(ctx).getString(R.string.push_channel_group);
+    }
+
+    static String channelDm(Context ctx) {
+        return forAppLocale(ctx).getString(R.string.push_channel_dm);
+    }
+
+    static String channelDmDescription(Context ctx) {
+        return forAppLocale(ctx).getString(R.string.push_channel_dm_description);
+    }
+
+    static String channelGroupRoom(Context ctx) {
+        return forAppLocale(ctx).getString(R.string.push_channel_group_room);
+    }
+
+    static String channelGroupRoomDescription(Context ctx) {
+        return forAppLocale(ctx).getString(R.string.push_channel_group_room_description);
+    }
+
+    static String selfName(Context ctx) {
+        return forAppLocale(ctx).getString(R.string.push_self_name);
+    }
+
+    static String markAsReadAction(Context ctx) {
+        return forAppLocale(ctx).getString(R.string.push_action_mark_as_read);
+    }
+
+    static String replyAction(Context ctx) {
+        return forAppLocale(ctx).getString(R.string.push_action_reply);
+    }
+
+    static String replyHint(Context ctx) {
+        return forAppLocale(ctx).getString(R.string.push_reply_hint);
+    }
+
+    static String replyFailed(Context ctx) {
+        return forAppLocale(ctx).getString(R.string.push_reply_failed);
+    }
+
+    /**
+     * Build the invite-notification body from inviter + room name, falling
+     * back through four variants when one or both are absent. The res IDs
+     * all declare positional formatters (%1$s = inviter, %2$s = roomName)
+     * to keep the order stable across locales; we always pass both args
+     * even when only one is used, because Android's formatter requires
+     * every referenced position to be supplied.
+     */
+    static String inviteBody(Context ctx, String inviter, String roomName) {
+        boolean hasInviter = inviter != null && !inviter.isEmpty();
+        boolean hasRoom = roomName != null && !roomName.isEmpty();
+        int resId;
+        if (hasInviter && hasRoom) {
+            resId = R.string.push_invite_body;
+        } else if (hasInviter) {
+            resId = R.string.push_invite_body_no_room;
+        } else if (hasRoom) {
+            resId = R.string.push_invite_body_no_inviter;
+        } else {
+            resId = R.string.push_invite_body_generic;
+        }
+        String safeInviter = hasInviter ? inviter : "";
+        String safeRoom = hasRoom ? roomName : "";
+        return forAppLocale(ctx).getString(resId, safeInviter, safeRoom);
+    }
+
+    private static Context forAppLocale(Context ctx) {
+        String lang = chooseLang(ctx);
+        try {
+            Configuration cfg = new Configuration(ctx.getResources().getConfiguration());
+            cfg.setLocale(Locale.forLanguageTag(lang));
+            return ctx.createConfigurationContext(cfg);
+        } catch (Throwable t) {
+            return ctx;
+        }
+    }
+
+    private static String chooseLang(Context ctx) {
+        String fromPref = readAppLanguage(ctx);
+        if (fromPref != null) return fromPref;
+        try {
+            Locale loc = Locale.getDefault();
+            if (loc != null) return normalize(loc.getLanguage());
+        } catch (Throwable ignored) {
+            // Locale.getDefault is unusually robust but defensively fall through.
+        }
+        return "en";
+    }
+
+    private static String readAppLanguage(Context ctx) {
+        try {
+            SharedPreferences prefs =
+                ctx.getSharedPreferences(PREFS_GROUP, Context.MODE_PRIVATE);
+            return normalize(prefs.getString(LANG_KEY, null));
+        } catch (Throwable t) {
+            return null;
+        }
+    }
+
+    // Match i18next config: `fallbackLng: 'en'`, `load: 'languageOnly'`.
+    // Vojo only ships en.json + ru.json; any other Configuration locale
+    // (e.g. "fr") would bypass both values-ru/ and our bundled resources
+    // and land on values/ anyway — we collapse to "en" explicitly so the
+    // web and native surfaces render the same lingua-franca default and
+    // readers of this method don't have to reason about fall-through.
+    // Clamp on both write (pushLanguageBridge.ts) and read (here) so a
+    // stale or tampered pref value can't leak through.
+    private static String normalize(String raw) {
+        if (raw == null) return null;
+        String lower = raw.toLowerCase(Locale.ROOT);
+        if (lower.startsWith("ru")) return "ru";
+        return "en";
+    }
+}

android/app/src/main/java/chat/vojo/app/ReplyReceiver.java

@@ -0,0 +1,248 @@
+package chat.vojo.app;
+
+import android.app.NotificationManager;
+import android.content.BroadcastReceiver;
+import android.content.Context;
+import android.content.Intent;
+import android.content.SharedPreferences;
+import android.os.Bundle;
+import android.util.Log;
+
+import androidx.core.app.NotificationCompat;
+import androidx.core.app.RemoteInput;
+
+import org.json.JSONObject;
+import org.json.JSONException;
+
+import java.io.IOException;
+import java.io.OutputStream;
+import java.net.HttpURLConnection;
+import java.net.URL;
+import java.net.URLEncoder;
+import java.util.UUID;
+import java.util.concurrent.ExecutorService;
+import java.util.concurrent.Executors;
+
+/**
+ * Handles the inline-reply RemoteInput action on a per-room MessagingStyle
+ * notification.
+ *
+ * Flow:
+ *   1. User taps reply, types text, presses send → broadcast fires here.
+ *   2. We immediately append the outgoing message to RoomMessageCache and
+ *      re-post the notification (instant UX feedback — the message appears
+ *      as a self-Person bubble in the conversation while the HTTP is in
+ *      flight).
+ *   3. PUT /_matrix/client/v3/rooms/{roomId}/send/m.room.message/{txnId}
+ *      with {msgtype: "m.text", body}. Uses the vojo_poll_state token (same
+ *      storage as Worker / MarkAsReadReceiver — single credential lifecycle).
+ *   4. On 2xx: nothing further; the JS sync echo will eventually replace
+ *      the local-echo bubble in-app.
+ *   5. On non-2xx or thrown: post a small error notification "Could not
+ *      send your reply" so the user knows to retry from in-app — better
+ *      than silently swallowing the message.
+ *
+ * E2EE rooms are guarded UP-STREAM in VojoFirebaseMessagingService.
+ * renderMessageNotification: we don't even attach the reply action when
+ * RoomMetadata.isEncrypted is true. So this receiver never has to encrypt.
+ * Defense in depth: if a stale notification with the action ever survives
+ * an encryption flip we still detect the failure as a non-2xx HTTP and
+ * surface the error notification rather than sending cleartext (which
+ * Synapse would in any case reject for an encrypted room).
+ *
+ * Null-credential edge case: post the error notification so the user
+ * notices and retries in-app. Same logic as a network failure.
+ */
+public class ReplyReceiver extends BroadcastReceiver {
+
+    public static final String ACTION_REPLY = "chat.vojo.app.REPLY";
+    public static final String EXTRA_ROOM_ID = "room_id";
+    public static final String KEY_TEXT_REPLY = "vojo.text_reply";
+
+    private static final int CONNECT_TIMEOUT_MS = 8_000;
+    private static final int READ_TIMEOUT_MS = 8_000;
+    private static final String TAG = "ReplyRcvr";
+
+    private static final ExecutorService EXECUTOR = Executors.newSingleThreadExecutor();
+
+    @Override
+    public void onReceive(Context context, Intent intent) {
+        if (intent == null) return;
+        final String roomId = intent.getStringExtra(EXTRA_ROOM_ID);
+        if (roomId == null || roomId.isEmpty()) {
+            Log.w(TAG, "onReceive: missing room_id, abort");
+            return;
+        }
+
+        Bundle remote = RemoteInput.getResultsFromIntent(intent);
+        if (remote == null) {
+            Log.w(TAG, "onReceive: no RemoteInput results");
+            return;
+        }
+        CharSequence reply = remote.getCharSequence(KEY_TEXT_REPLY);
+        if (reply == null) {
+            Log.w(TAG, "onReceive: RemoteInput missing text");
+            return;
+        }
+        final String text = reply.toString().trim();
+        if (text.isEmpty()) return;
+
+        final Context appContext = context.getApplicationContext();
+
+        // Pre-flight validation BEFORE the optimistic echo. Posting a self
+        // bubble first and then immediately stacking an error notif on top
+        // is jarring UX; for predictable failures (logged out, freshly
+        // encrypted room) we'd rather skip the echo and only surface the
+        // error.
+        final SharedPreferences prefs = appContext.getSharedPreferences(
+            VojoPollWorker.PREFS, Context.MODE_PRIVATE);
+        final String token = prefs.getString(VojoPollWorker.KEY_ACCESS_TOKEN, null);
+        final String homeserver = prefs.getString(VojoPollWorker.KEY_HOMESERVER_URL, null);
+        if (token == null || token.isEmpty() || homeserver == null || homeserver.isEmpty()) {
+            Log.w(TAG, "onReceive: no credentials in prefs, surfacing error notif");
+            postReplyError(appContext, roomId);
+            return;
+        }
+
+        // Race guard for E2EE flip: the per-room metadata snapshot is
+        // refreshed by JS on m.room.encryption Timeline events, but a push
+        // delivered in the narrow window between the encryption state
+        // landing and the dump completing could still expose the reply
+        // action on a freshly-encrypted room. Re-read the snapshot
+        // synchronously here — Synapse does NOT enforce "no cleartext in
+        // encrypted rooms" at the spec level, so without this guard we'd
+        // leak the user's reply into an E2EE timeline as plaintext.
+        if (isRoomEncryptedAtSendTime(prefs, roomId)) {
+            Log.w(TAG, "onReceive: room flipped to encrypted between render and send, abort");
+            postReplyError(appContext, roomId);
+            return;
+        }
+
+        // Optimistic local echo — appends a self-Person message to the
+        // conversation and re-posts, so the user sees their reply in the
+        // shade before the HTTP completes. Only happens after pre-flight
+        // checks pass so the user doesn't see an echo for a reply we know
+        // will fail.
+        long now = System.currentTimeMillis();
+        VojoFirebaseMessagingService.appendOutgoingMessage(appContext, roomId, text, now);
+
+        final PendingResult pendingResult = goAsync();
+        final String txnId = "vojo-reply-" + UUID.randomUUID();
+        EXECUTOR.execute(() -> {
+            try {
+                int status = sendReply(homeserver, token, roomId, txnId, text);
+                if (status >= 200 && status < 300) {
+                    if (BuildConfig.DEBUG) {
+                        Log.d(TAG, "reply ok status=" + status + " room=" + roomId);
+                    }
+                } else {
+                    Log.w(TAG, "reply non-2xx status=" + status + " room=" + roomId);
+                    postReplyError(appContext, roomId);
+                }
+            } catch (Throwable t) {
+                Log.w(TAG, "reply threw room=" + roomId, t);
+                postReplyError(appContext, roomId);
+            } finally {
+                pendingResult.finish();
+            }
+        });
+    }
+
+    private int sendReply(
+        String baseUrl,
+        String accessToken,
+        String roomId,
+        String txnId,
+        String text
+    ) throws IOException {
+        String url = trimTrailingSlash(baseUrl)
+            + "/_matrix/client/v3/rooms/"
+            + URLEncoder.encode(roomId, "UTF-8")
+            + "/send/m.room.message/"
+            + URLEncoder.encode(txnId, "UTF-8");
+
+        JSONObject body;
+        try {
+            body = new JSONObject();
+            body.put("msgtype", "m.text");
+            body.put("body", text);
+        } catch (org.json.JSONException je) {
+            // JSONObject.put only throws on NaN/Inf doubles, neither of
+            // which we use — but keep the type contract honest.
+            throw new IOException("payload encode failed", je);
+        }
+        byte[] payload = body.toString().getBytes("UTF-8");
+
+        HttpURLConnection conn = (HttpURLConnection) new URL(url).openConnection();
+        try {
+            conn.setRequestMethod("PUT");
+            conn.setRequestProperty("Authorization", "Bearer " + accessToken);
+            conn.setRequestProperty("Content-Type", "application/json");
+            conn.setConnectTimeout(CONNECT_TIMEOUT_MS);
+            conn.setReadTimeout(READ_TIMEOUT_MS);
+            conn.setDoOutput(true);
+            conn.setFixedLengthStreamingMode(payload.length);
+            try (OutputStream os = conn.getOutputStream()) {
+                os.write(payload);
+            }
+            return conn.getResponseCode();
+        } finally {
+            conn.disconnect();
+        }
+    }
+
+    /**
+     * Surface a short error notification when the reply HTTP fails so the
+     * user knows the message did NOT land server-side and can retry from
+     * within the app. Posted on the DM channel as a one-shot. Unique notif
+     * id per room so it can't clobber the room's conversation slot.
+     */
+    private static void postReplyError(Context ctx, String roomId) {
+        NotificationManager nm = (NotificationManager)
+            ctx.getSystemService(Context.NOTIFICATION_SERVICE);
+        if (nm == null) return;
+        try {
+            String channel = VojoFirebaseMessagingService.CHANNEL_ID_DM;
+            NotificationCompat.Builder b = new NotificationCompat.Builder(ctx, channel)
+                .setSmallIcon(R.mipmap.ic_launcher)
+                .setContentTitle(PushStrings.replyFailed(ctx))
+                .setContentText(PushStrings.replyFailed(ctx))
+                .setAutoCancel(true)
+                .setPriority(NotificationCompat.PRIORITY_DEFAULT);
+            int errId = ("replyErr_" + roomId).hashCode();
+            nm.notify(errId, b.build());
+        } catch (Throwable t) {
+            Log.w(TAG, "reply error notif failed", t);
+        }
+    }
+
+    private static String trimTrailingSlash(String s) {
+        return (s != null && s.endsWith("/")) ? s.substring(0, s.length() - 1) : s;
+    }
+
+    /**
+     * Synchronous re-check of the room's encryption flag at send time.
+     * Mirrors VojoFirebaseMessagingService.loadRoomMetadata's tolerant
+     * parse: legacy string-shape entries and missing flags both default
+     * to encrypted=true (privacy-first — refusing a reply on a falsely-
+     * flagged room is harmless; sending cleartext into a truly encrypted
+     * room is a privacy leak).
+     */
+    private static boolean isRoomEncryptedAtSendTime(SharedPreferences prefs, String roomId) {
+        String raw = prefs.getString(VojoPollWorker.KEY_ROOM_NAMES, null);
+        if (raw == null || raw.isEmpty()) return true;
+        try {
+            JSONObject map = new JSONObject(raw);
+            if (!map.has(roomId) || map.isNull(roomId)) return true;
+            JSONObject obj = map.optJSONObject(roomId);
+            if (obj == null) {
+                // Legacy string-shape predates the encryption flag —
+                // assume encrypted to err on the side of privacy.
+                return true;
+            }
+            return obj.optBoolean("isEncrypted", true);
+        } catch (JSONException je) {
+            return true;
+        }
+    }
+}

android/app/src/main/java/chat/vojo/app/RoomMessageCache.java

@@ -0,0 +1,176 @@
+package chat.vojo.app;
+
+import androidx.core.app.NotificationCompat;
+import androidx.core.app.Person;
+
+import java.util.ArrayDeque;
+import java.util.ArrayList;
+import java.util.Deque;
+import java.util.List;
+import java.util.concurrent.ConcurrentHashMap;
+
+/**
+ * Per-room MessagingStyle history cache.
+ *
+ * Stores the last N messages observed for each room so renderMessageNotification
+ * can rebuild a NotificationCompat.MessagingStyle with conversation context on
+ * every new event instead of posting a fresh single-message notification per
+ * event. Without this every 5-message DM produced 5 distinct entries in the
+ * shade; with it the user sees one expandable conversation per room — the
+ * WhatsApp/Telegram convention.
+ *
+ * Thread-safety: ConcurrentHashMap + per-key synchronized mutation via the
+ * compute() / get() pattern. Both VojoFirebaseMessagingService.onMessageReceived
+ * (Firebase-managed thread) and VojoPollWorker.doWork (WorkManager executor)
+ * mutate the cache; without serialization a same-room FCM + polling race could
+ * lose a message. Mutations are short — only deque append + bounded trim.
+ *
+ * Persistence: in-memory only. After process kill the cache is empty, and
+ * renderMessageNotification falls back to extractMessagingStyleFromNotification
+ * to recover history from the live system shade. If the user dismissed the
+ * notification too, the conversation legitimately starts fresh — no signal we
+ * could recover from there anyway.
+ *
+ * Eviction: bounded at MAX_MESSAGES_PER_ROOM per room, with FIFO eviction
+ * (oldest message at the head of the deque is dropped via pollFirst when the
+ * append would exceed the cap). Map itself is unbounded; in practice the
+ * dump from dismissRoom (when a server-side read receipt clears unread) keeps
+ * the room count proportional to active conversations. For safety against
+ * runaway growth from rooms the user never reads, we cap the map at MAX_ROOMS.
+ */
+final class RoomMessageCache {
+
+    // Element-android keeps a similar in-memory queue (NotificationEventQueue);
+    // 20 messages per room is generous enough for an active group chat while
+    // staying well under Android's MessagingStyle render budget — Android only
+    // shows the last ~7 messages in the shade anyway.
+    private static final int MAX_MESSAGES_PER_ROOM = 20;
+
+    // Hard cap on the map size so a long-running session that touches many
+    // rooms without ever clearing receipts can't slowly leak memory.
+    // Eviction is approximate (oldest-touched first via insertion order from
+    // ConcurrentHashMap is NOT guaranteed, so we just clear the oldest by
+    // arbitrary entry on overflow — acceptable for an LRU at this scale).
+    private static final int MAX_ROOMS = 200;
+
+    private static final ConcurrentHashMap<String, Deque<Entry>> store =
+        new ConcurrentHashMap<>();
+
+    private RoomMessageCache() {}
+
+    /**
+     * Snapshot of a single rendered message. We can't store
+     * NotificationCompat.MessagingStyle.Message directly because Person's
+     * Icon field is not safely shareable across threads / not cheap to
+     * rebuild on every poll. Building the Message at render time from this
+     * record matches element-android's RoomGroupMessageCreator pattern.
+     */
+    static final class Entry {
+        // Matrix event_id when known (incoming pushes always carry one;
+        // outgoing optimistic-echo entries pass null). Used by append() to
+        // suppress duplicate appends when FCM retries / cross-source
+        // delivery hands the same event in twice — without this the
+        // MessagingStyle conversation would render the same message N
+        // times in the shade.
+        final String eventId;
+        final String body;
+        final long timestamp;
+        final String senderKey;
+        final String senderName;
+        final boolean fromSelf;
+
+        Entry(
+            String eventId,
+            String body,
+            long timestamp,
+            String senderKey,
+            String senderName,
+            boolean fromSelf
+        ) {
+            this.eventId = eventId;
+            this.body = body;
+            this.timestamp = timestamp;
+            this.senderKey = senderKey;
+            this.senderName = senderName;
+            this.fromSelf = fromSelf;
+        }
+    }
+
+    /**
+     * Append a message to the room's history and return an ordered snapshot
+     * including the newly-added entry. Snapshot is taken INSIDE the atomic
+     * compute() so a concurrent append for the same room can't mutate the
+     * deque between our addLast and our copy. Returning the deque reference
+     * and copying outside is unsafe — ConcurrentHashMap.compute serialises
+     * only the lambda body per key, not subsequent reads of the value.
+     */
+    static List<Entry> append(String roomId, Entry entry) {
+        if (roomId == null || roomId.isEmpty() || entry == null) {
+            return java.util.Collections.emptyList();
+        }
+        final List<Entry> snapshot = new ArrayList<>();
+        store.compute(roomId, (key, existing) -> {
+            Deque<Entry> d = (existing != null) ? existing : new ArrayDeque<>();
+            // Dedup by eventId — protects against FCM retry / cross-source
+            // (FCM + polling Worker) double-delivery that would otherwise
+            // append the same event twice. Only applies when both the new
+            // entry and a prior one carry a non-empty eventId; outgoing
+            // self-echo entries have null eventId by design and never
+            // collide.
+            boolean isDup = false;
+            if (entry.eventId != null && !entry.eventId.isEmpty()) {
+                for (Entry prior : d) {
+                    if (entry.eventId.equals(prior.eventId)) {
+                        isDup = true;
+                        break;
+                    }
+                }
+            }
+            if (!isDup) {
+                d.addLast(entry);
+                while (d.size() > MAX_MESSAGES_PER_ROOM) {
+                    d.pollFirst();
+                }
+            }
+            snapshot.addAll(d);
+            return d;
+        });
+        // Bound the map. Iteration order of ConcurrentHashMap is unspecified
+        // and the size() check is racy with concurrent puts; we accept ±1
+        // eviction precision at the 200-room cap as an acceptable approximation
+        // of LRU (the alternative is a global lock on every append which is
+        // far more expensive than letting the cache drift by one).
+        if (store.size() > MAX_ROOMS) {
+            java.util.Iterator<String> it = store.keySet().iterator();
+            while (it.hasNext() && store.size() > MAX_ROOMS) {
+                String key = it.next();
+                if (!key.equals(roomId)) it.remove();
+            }
+        }
+        return snapshot;
+    }
+
+    /**
+     * Seed the room's history from an already-posted MessagingStyle (recovered
+     * via NotificationCompat.MessagingStyle.extractMessagingStyleFromNotification
+     * after process kill). Idempotent: if the room already has cached entries
+     * we leave them alone — they are by construction at least as recent.
+     */
+    static void seedIfAbsent(String roomId, List<Entry> entries) {
+        if (roomId == null || roomId.isEmpty() || entries == null || entries.isEmpty()) return;
+        store.computeIfAbsent(roomId, key -> {
+            Deque<Entry> d = new ArrayDeque<>();
+            for (Entry e : entries) {
+                d.addLast(e);
+                while (d.size() > MAX_MESSAGES_PER_ROOM) d.pollFirst();
+            }
+            return d;
+        });
+    }
+
+    /** Drop all cached messages for a room (e.g. on receipt-driven dismiss). */
+    static void clear(String roomId) {
+        if (roomId == null || roomId.isEmpty()) return;
+        store.remove(roomId);
+    }
+}

android/app/src/main/java/chat/vojo/app/ShareTargetPlugin.java

@@ -0,0 +1,273 @@
+package chat.vojo.app;
+
+import android.content.ContentResolver;
+import android.content.Intent;
+import android.database.Cursor;
+import android.net.Uri;
+import android.os.Build;
+import android.provider.OpenableColumns;
+import android.util.Log;
+import android.webkit.MimeTypeMap;
+
+import com.getcapacitor.JSArray;
+import com.getcapacitor.JSObject;
+import com.getcapacitor.Plugin;
+import com.getcapacitor.PluginCall;
+import com.getcapacitor.PluginMethod;
+import com.getcapacitor.annotation.CapacitorPlugin;
+
+import java.io.File;
+import java.io.FileOutputStream;
+import java.io.IOException;
+import java.io.InputStream;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.UUID;
+
+/**
+ * Receives ACTION_SEND / ACTION_SEND_MULTIPLE intents from the system share-
+ * sheet and surfaces them to the WebView as a pending share that JS consumes
+ * via {@code pickPendingShare()} (or reacts to via the {@code shareReceived}
+ * event when the app was already in the foreground).
+ *
+ * Cold-start flow:
+ *   1. Share-sheet → Vojo → MainActivity.onCreate → super.onCreate runs
+ *      BridgeActivity.load(), which itself calls bridge.onNewIntent(getIntent())
+ *      and fans the intent out to every plugin's handleOnNewIntent. So
+ *      cold-start and warm-start share the SAME entry point — we don't
+ *      double-process via handleOnStart.
+ *   2. captureFromIntent copies payload bytes into the app cache and stashes
+ *      the result in {@link #pendingShare}.
+ *   3. JS booting up (Matrix client ready, user logged in) calls
+ *      pickPendingShare(); receives the JSON; opens the room-picker UI. The
+ *      shareReceived event fired here is dropped silently because no JS
+ *      listener is attached yet — that's fine, pickPendingShare drains the
+ *      slot regardless.
+ *
+ * Warm flow (app already running):
+ *   1. Share-sheet → MainActivity.onNewIntent → BridgeActivity forwards to
+ *      plugin.handleOnNewIntent(intent).
+ *   2. We re-capture the payload AND emit {@code shareReceived} so JS can
+ *      open the picker without polling.
+ *
+ * Why we copy to cache instead of handing JS a content:// URI:
+ *   - WebView fetch() rejects content:// schemes outright, and
+ *     `Capacitor.convertFileSrc()` only works on file paths.
+ *   - The originating app holds the read-grant only for the lifetime of the
+ *     launching task; routing the URI through JS+picker+RoomInput would race
+ *     that grant on Android 14+.
+ *   - Copying into our own cache means the share is self-contained: even if
+ *     the user backgrounds Vojo for hours before picking a chat, the bytes
+ *     are still there. We schedule no cleanup of our own — Android's cache
+ *     eviction handles long-tail garbage.
+ */
+@CapacitorPlugin(name = "ShareTarget")
+public class ShareTargetPlugin extends Plugin {
+
+    private static final String TAG = "ShareTargetPlugin";
+    private static final String SHARE_CACHE_SUBDIR = "shared";
+
+    // Single-slot pending share. Multiple share-sheet invocations before JS
+    // drains the slot collapse — the latest wins. JS contract is "consume
+    // once, then it's gone" via pickPendingShare(consume=true). This matches
+    // user intent: tapping share twice on different photos clearly means
+    // "share THIS one now".
+    private volatile JSObject pendingShare = null;
+
+    @Override
+    public void handleOnNewIntent(Intent intent) {
+        super.handleOnNewIntent(intent);
+        captureFromIntent(intent, /* notifyJs */ true);
+    }
+
+    @PluginMethod
+    public void pickPendingShare(PluginCall call) {
+        JSObject ret = new JSObject();
+        JSObject snapshot = pendingShare;
+        if (snapshot == null) {
+            ret.put("empty", true);
+        } else {
+            // Default: consume on read. Lets us treat the slot like a one-shot
+            // mailbox without an extra round-trip. Caller can pass consume=false
+            // to peek (not used today, but cheap to keep).
+            Boolean consume = call.getBoolean("consume", Boolean.TRUE);
+            ret = snapshot;
+            if (Boolean.TRUE.equals(consume)) {
+                pendingShare = null;
+            }
+        }
+        call.resolve(ret);
+    }
+
+    private void captureFromIntent(Intent intent, boolean notifyJs) {
+        if (intent == null) return;
+        String action = intent.getAction();
+        if (action == null) return;
+
+        // Capacitor's JSObject.put() silently swallows JSONException internally
+        // (it wraps org.json.JSONObject and returns `this` on failure) so no
+        // checked exception is thrown here — unlike the raw org.json API.
+        JSObject share = new JSObject();
+        share.put("empty", false);
+
+        String text = intent.getStringExtra(Intent.EXTRA_TEXT);
+        String subject = intent.getStringExtra(Intent.EXTRA_SUBJECT);
+        if (text != null && !text.isEmpty()) share.put("text", text);
+        if (subject != null && !subject.isEmpty()) share.put("subject", subject);
+
+        JSArray items = new JSArray();
+        List<Uri> uris = new ArrayList<>();
+        if (Intent.ACTION_SEND.equals(action)) {
+            Uri uri;
+            if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) {
+                uri = intent.getParcelableExtra(Intent.EXTRA_STREAM, Uri.class);
+            } else {
+                // Deprecated overload — required to read EXTRA_STREAM on
+                // API ≤32, where the typed variant doesn't exist.
+                //noinspection deprecation
+                uri = intent.getParcelableExtra(Intent.EXTRA_STREAM);
+            }
+            if (uri != null) uris.add(uri);
+        } else if (Intent.ACTION_SEND_MULTIPLE.equals(action)) {
+            List<Uri> multi;
+            if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) {
+                multi = intent.getParcelableArrayListExtra(Intent.EXTRA_STREAM, Uri.class);
+            } else {
+                //noinspection deprecation
+                multi = intent.getParcelableArrayListExtra(Intent.EXTRA_STREAM);
+            }
+            if (multi != null) uris.addAll(multi);
+        }
+
+        String intentMime = intent.getType();
+        for (Uri uri : uris) {
+            JSObject item = copyUriToCache(uri, intentMime);
+            if (item != null) items.put(item);
+        }
+        share.put("items", items);
+
+        // Drop pure-noise intents — neither text nor a successfully
+        // copied file. Possible if a sender app handed us only a content://
+        // URI we can't read (permission revoked) or an EXTRA_STREAM with a
+        // null Uri. Keeps JS from showing an empty picker.
+        if (text == null && subject == null && items.length() == 0) {
+            Log.w(TAG, "Dropping share intent with no usable payload");
+            return;
+        }
+
+        pendingShare = share;
+        if (notifyJs) {
+            notifyListeners("shareReceived", new JSObject());
+        }
+    }
+
+    /**
+     * Stream the content of {@code uri} into a fresh file under
+     * cacheDir/shared/, then return {name, mimeType, size, path}. The path is
+     * an absolute filesystem path — JS wraps it with
+     * {@code Capacitor.convertFileSrc} before fetch().
+     */
+    private JSObject copyUriToCache(Uri uri, String fallbackMime) {
+        if (uri == null) return null;
+        ContentResolver resolver = getContext().getContentResolver();
+
+        String name = queryDisplayName(resolver, uri);
+        String mimeType = resolver.getType(uri);
+        if (mimeType == null) mimeType = fallbackMime;
+        if (mimeType == null) mimeType = "application/octet-stream";
+
+        if (name == null || name.isEmpty()) {
+            String ext = MimeTypeMap.getSingleton().getExtensionFromMimeType(mimeType);
+            name = "share-" + UUID.randomUUID() + (ext != null ? "." + ext : "");
+        }
+
+        File dir = new File(getContext().getCacheDir(), SHARE_CACHE_SUBDIR);
+        // mkdirs returns false if the directory already exists — not an error.
+        // The real failure mode is the I/O exception below on FileOutputStream
+        // construction, which we surface.
+        if (!dir.exists() && !dir.mkdirs()) {
+            Log.e(TAG, "Could not create share cache dir: " + dir);
+            return null;
+        }
+        // Prefix with UUID so a repeated share of "IMG_1234.jpg" doesn't
+        // overwrite the previous payload while the user is still picking a
+        // chat for the older one (e.g. Gallery → Vojo, see room-picker open,
+        // background → Gallery → re-share same file → foreground Vojo). Both
+        // payloads stay independently addressable.
+        File out = new File(dir, UUID.randomUUID() + "_" + safeFileName(name));
+
+        // Open the input first; if the sender's provider hands us back
+        // null (revoked grant, gone-away ContentProvider, …) bail before
+        // creating any on-disk file — otherwise the FileOutputStream
+        // initializer below would create a zero-byte orphan we'd never
+        // clean up (catch arm doesn't fire when we early-return).
+        long size;
+        try (InputStream in = resolver.openInputStream(uri)) {
+            if (in == null) {
+                Log.w(TAG, "openInputStream returned null for " + uri);
+                return null;
+            }
+            try (FileOutputStream fos = new FileOutputStream(out)) {
+                byte[] buf = new byte[64 * 1024];
+                int n;
+                long total = 0;
+                while ((n = in.read(buf)) > 0) {
+                    fos.write(buf, 0, n);
+                    total += n;
+                }
+                size = total;
+            }
+        } catch (IOException e) {
+            Log.e(TAG, "Failed to copy " + uri, e);
+            // Drop the partial file so we don't surface a truncated
+            // payload to JS as if it were valid.
+            //noinspection ResultOfMethodCallIgnored
+            out.delete();
+            return null;
+        }
+
+        JSObject item = new JSObject();
+        item.put("name", name);
+        item.put("mimeType", mimeType);
+        item.put("size", size);
+        item.put("path", out.getAbsolutePath());
+        return item;
+    }
+
+    private String queryDisplayName(ContentResolver resolver, Uri uri) {
+        // ContentResolver.query throws if the provider rejects the URI scheme
+        // (e.g. some senders pass a file:// directly — no provider involved).
+        // Wrap in try/catch and fall back to the URI's last path segment.
+        try (Cursor c = resolver.query(uri, new String[]{ OpenableColumns.DISPLAY_NAME }, null, null, null)) {
+            if (c != null && c.moveToFirst()) {
+                int idx = c.getColumnIndex(OpenableColumns.DISPLAY_NAME);
+                if (idx >= 0) {
+                    String name = c.getString(idx);
+                    if (name != null && !name.isEmpty()) return name;
+                }
+            }
+        } catch (Throwable t) {
+            Log.d(TAG, "queryDisplayName failed for " + uri + ": " + t.getMessage());
+        }
+        String last = uri.getLastPathSegment();
+        if (last != null && !last.isEmpty()) {
+            // Strip any directory traversal a malicious sender might encode.
+            int slash = last.lastIndexOf('/');
+            return slash >= 0 ? last.substring(slash + 1) : last;
+        }
+        return null;
+    }
+
+    private static String safeFileName(String name) {
+        // Strip path separators and trim length — the on-disk name is just an
+        // identifier; the display name we return to JS preserves the user's
+        // original filename verbatim. Trim from the tail so the recognisable
+        // head ("IMG_2025_05_16…") survives and the extension is the part
+        // that gets clipped on absurdly long names; the on-disk extension
+        // doesn't matter because nothing inside Vojo dispatches on it (the
+        // display name carries the real extension into JS).
+        String stripped = name.replaceAll("[/\\\\]", "_");
+        if (stripped.length() > 120) stripped = stripped.substring(0, 120);
+        return stripped;
+    }
+}

android/app/src/main/java/chat/vojo/app/VojoPollWorker.java

@@ -0,0 +1,675 @@
+package chat.vojo.app;
+
+import android.content.Context;
+import android.content.SharedPreferences;
+import android.util.Log;
+
+import androidx.annotation.NonNull;
+import androidx.core.app.NotificationManagerCompat;
+import androidx.work.Worker;
+import androidx.work.WorkerParameters;
+
+import org.json.JSONArray;
+import org.json.JSONObject;
+
+import java.io.IOException;
+import java.io.InputStream;
+import java.net.HttpURLConnection;
+import java.net.URL;
+import java.util.HashMap;
+import java.util.Iterator;
+import java.util.Map;
+
+/**
+ * Periodic poll of `/_matrix/client/v3/notifications` as a fallback delivery
+ * channel for users whose network blocks FCM (mtalk.google.com:5228) — the
+ * ~5% slice on whitelist intranets (corporate / school / government) that
+ * otherwise receive zero pushes.
+ *
+ * Scheduling: enqueued from PollingPlugin.schedule() with a 15-minute period
+ * (Android's minimum for PeriodicWorkRequest) and CONNECTED network constraint.
+ * Cancelled via PollingPlugin.cancel() on logout / push disable.
+ *
+ * Credentials: read from SharedPreferences (saved by the JS side through
+ * PollingPlugin.saveSession). Vanilla Synapse (no MAS/OIDC) issues
+ * non-expiring access tokens; we do not implement refresh-token flow here.
+ * If a 401 ever occurs, doWork returns Result.success() — the next foreground
+ * launch re-saves the credentials and polling resumes. Retrying with a stale
+ * token would just waste battery and amplify rate limits.
+ *
+ * Output: messages and invites route through VojoFirebaseMessagingService
+ * .renderMessageNotification (shared with FCM, same notif-id slots →
+ * Android dedupes by replace). RTC ring events route through
+ * .renderMissedCallNotification (always stale by the time we poll — 15-min
+ * cadence vs 30-second ring lifetime), so the user sees "Missed call" instead
+ * of a phantom incoming-call CallStyle for a long-dead ring.
+ *
+ * E2EE caveat: Synapse cannot decrypt event content, so for end-to-end
+ * encrypted rooms the response carries `content.algorithm`+`ciphertext`
+ * with no `body`. The renderer falls through to PushStrings.messageFallback
+ * (i18n "New message") with the room name as title — same UX as the web
+ * Service Worker on encrypted pushes. By design — no key access from the
+ * Worker.
+ *
+ * Dedup is two complementary mechanisms:
+ *   1) A per-poll high-watermark on the latest event ts we've notified.
+ *      Stored as KEY_LAST_SEEN_TS; advances only after a successful render
+ *      (or a foreground-skipped event the user already saw in-app). Worker
+ *      stops walking within a run as soon as it hits ts strictly less than
+ *      watermark — newest-first ordering guarantees the rest are also
+ *      older. Same-ts events fall through to the secondary filters because
+ *      multiple events can share a millisecond.
+ *   2) NotificationDedup — a shared cross-source bounded LRU written by
+ *      every renderer (FCM service after successful nm.notify, this Worker
+ *      after successful render, and the ring-upsert paths at seed time).
+ *      Lets the Worker skip events FCM already delivered even after the
+ *      user dismissed the FCM notification.
+ *
+ * Each fire starts from the HEAD of /notifications (no persistent
+ * pagination cursor — the spec's `next_token` walks BACKWARDS into
+ * history, so a persisted cursor silently drifts off the new events the
+ * next poll should see; see matrix-js-sdk client.ts:5040 for the
+ * reference traversal pattern). When a single fire's backlog exceeds
+ * MAX_PAGES_PER_RUN pages the leftover next_token is saved as
+ * KEY_DRAIN_CURSOR (with the head ts snapshotted in KEY_DRAIN_TARGET_TS)
+ * and resumed on the next run, so big backlogs (>250 events) drain over
+ * consecutive polls without being clipped.
+ */
+public class VojoPollWorker extends Worker {
+
+    private static final String TAG = "VojoPoll";
+
+    static final String PREFS = "vojo_poll_state";
+    static final String KEY_ACCESS_TOKEN = "access_token";
+    static final String KEY_HOMESERVER_URL = "homeserver_url";
+    static final String KEY_USER_ID = "user_id";
+    // High-watermark on the latest event ts we've already notified about.
+    // Stored as a long-millis string. Replaces an earlier `last_from` cursor
+    // experiment that misunderstood /notifications pagination direction.
+    static final String KEY_LAST_SEEN_TS = "last_seen_ts";
+    // Continuation cursor used when a single run hits MAX_PAGES_PER_RUN before
+    // reaching the watermark. Persists the next_token across runs so a >250
+    // event backlog drains over consecutive polls instead of being clipped
+    // forever by the page cap. Cleared once we either reach the watermark or
+    // exhaust pagination on a single run.
+    static final String KEY_DRAIN_CURSOR = "drain_cursor";
+    // The "head ts" we recorded when entering drain mode. After drain
+    // completes the watermark is jumped to THIS value rather than the
+    // (older) max ts seen during drain — otherwise the bounded LRU could
+    // evict events from the original head and let the next normal run
+    // re-render them. Set once on entering drain mode, untouched while
+    // draining, cleared when drain completes.
+    static final String KEY_DRAIN_TARGET_TS = "drain_target_ts";
+    static final String KEY_NOTIFIED_IDS = "notified_ids";
+    static final String KEY_ROOM_NAMES = "room_names";
+    // user_id → MXC avatar URL, JSON-encoded, bridged from JS via
+    // PollingPlugin.saveUserAvatars. Consumed by
+    // VojoFirebaseMessagingService.lookupUserAvatarMxc for per-sender
+    // Person.setIcon in MessagingStyle conversations. Bounded at 500
+    // entries on the JS side; read tolerantly here.
+    static final String KEY_USER_AVATARS = "user_avatars";
+
+    private static final int HTTP_TIMEOUT_MS = 30_000;
+    // Cap pages-per-fire so an unexpectedly large backlog (server-side bug,
+    // first run after a long offline window) cannot loop until Android's
+    // 10-minute Worker kill timer fires. 5 pages × 50 events = up to 250
+    // events per cycle — well above realistic 15-minute backlog for a single
+    // user. We also break as soon as we hit ts ≤ watermark, so most polls
+    // touch only a single page.
+    private static final int MAX_PAGES_PER_RUN = 5;
+    private static final int PAGE_LIMIT = 50;
+
+    private static final String RTC_NOTIFICATION_TYPE = "org.matrix.msc4075.rtc.notification";
+    private static final String RTC_NOTIFICATION_TYPE_STABLE = "m.rtc.notification";
+
+    public VojoPollWorker(@NonNull Context context, @NonNull WorkerParameters params) {
+        super(context, params);
+    }
+
+    @NonNull
+    @Override
+    public Result doWork() {
+        Context ctx = getApplicationContext();
+        SharedPreferences prefs = ctx.getSharedPreferences(PREFS, Context.MODE_PRIVATE);
+
+        String token = prefs.getString(KEY_ACCESS_TOKEN, null);
+        String homeserver = prefs.getString(KEY_HOMESERVER_URL, null);
+        if (token == null || homeserver == null) {
+            // Not logged in (or JS hasn't bridged credentials yet). Return
+            // success so WorkManager keeps the periodic schedule alive —
+            // we'll pick up the credentials on the next fire.
+            Log.i(TAG, "poll: no credentials, bail");
+            return Result.success();
+        }
+
+        // If POST_NOTIFICATIONS was revoked we'd fetch + parse + try to
+        // render and then watch every nm.notify fail with SecurityException
+        // — which leaves the LRU/watermark unadvanced (correctly so for a
+        // transient failure) and re-runs the same loop every 15 minutes
+        // forever. Bail early to avoid burning battery on a permanent
+        // user choice. The next visibility re-bridge inside the JS app
+        // will pick up a re-granted permission.
+        if (!NotificationManagerCompat.from(ctx).areNotificationsEnabled()) {
+            Log.i(TAG, "poll: notifications disabled, bail");
+            return Result.success();
+        }
+
+        long watermark = prefs.getLong(KEY_LAST_SEEN_TS, 0L);
+        String drainCursor = prefs.getString(KEY_DRAIN_CURSOR, null);
+        long drainTargetTs = prefs.getLong(KEY_DRAIN_TARGET_TS, 0L);
+        boolean wasDraining = drainCursor != null;
+        Map<String, String> roomNames = loadRoomNamesMap(prefs);
+        // Mirror the FCM service's foreground gate: if the user is actively in
+        // the app, the live timeline owns the UX and a system notification for
+        // a backlog event would be both stale and visually noisy. We still
+        // consume state (LRU, watermark) so the same event doesn't surface
+        // when the user later backgrounds the app.
+        boolean inForeground = MainActivity.isInForeground;
+
+        Log.i(TAG, "poll: start fg=" + inForeground
+            + " watermark=" + watermark
+            + " draining=" + wasDraining);
+
+        int pagesFetched = 0;
+        int renderedCount = 0;
+        int skippedDedupCount = 0;
+        long highestTsSeen = watermark;
+        boolean reachedWatermark = false;
+        // The continuation cursor we'd save if this run is capped. Starts as
+        // the resumed drain cursor; advances with each successful page fetch
+        // so a transient mid-pagination error still preserves drain progress.
+        String pendingCursor = drainCursor;
+        boolean paginationExhausted = false;
+
+        try {
+            // Cursor strategy: drain cursor resumes from where a previous capped
+            // run stopped; otherwise we start from the HEAD. next_token from
+            // /notifications paginates BACKWARDS into history, so a stored
+            // cursor must be used as a drain-only continuation, NOT as an
+            // ongoing "since" mark (the latter would silently drift off new
+            // events). Within a single fire we stop as soon as ts < watermark
+            // (newest-first ordering means everything past that is covered).
+            String nextFrom = drainCursor;
+            for (int page = 0; page < MAX_PAGES_PER_RUN && !reachedWatermark; page += 1) {
+                // Cooperative cancellation. WorkManager.cancelUniqueWork (called
+                // from PollingPlugin.cancel during logout / push disable) only
+                // marks future scheduling — it does NOT interrupt this thread.
+                // Without these checks the Worker keeps fetching pages, posting
+                // notifications, and (worst of all) running the final
+                // editor.apply() with stale state written AFTER clearSession
+                // wiped prefs — leaking watermark / drain cursor from the
+                // logged-out account into the next login.
+                if (isStopped()) return Result.success();
+
+                JSONObject body = fetchNotifications(homeserver, token, nextFrom);
+                // fetchNotifications throws on every failure path; a null
+                // return is unreachable in current code. The early-break here
+                // is a defensive belt-and-suspenders — keep paginationExhausted
+                // consistent so the drain-bookkeeping below clears the cursor
+                // instead of replaying the same empty page forever.
+                if (body == null) {
+                    paginationExhausted = true;
+                    pendingCursor = null;
+                    break;
+                }
+
+                JSONArray notifications = body.optJSONArray("notifications");
+                if (notifications == null || notifications.length() == 0) {
+                    // Server returned no entries for this page. Treat as
+                    // end-of-pagination so a drain in progress can complete
+                    // (otherwise pendingCursor would keep its old value and
+                    // we'd re-fetch the same empty page next cycle forever).
+                    paginationExhausted = true;
+                    pendingCursor = null;
+                    break;
+                }
+
+                for (int i = 0; i < notifications.length(); i += 1) {
+                    if (isStopped()) return Result.success();
+                    JSONObject entry = notifications.optJSONObject(i);
+                    if (entry == null) continue;
+                    String eventId = extractEventId(entry);
+                    if (eventId == null) continue;
+
+                    // ts gate: server returns newest-first, so once we hit
+                    // ts STRICTLY less than the watermark we know the rest of
+                    // the page (and every subsequent page) is already covered.
+                    // Same-ts events fall through to the LRU/read filters
+                    // below — multiple events can share a millisecond, and
+                    // collapsing them at the ts boundary would silently drop
+                    // a fresh sibling of a previously-rendered one.
+                    long ts = entry.optLong("ts", 0L);
+                    if (ts > 0 && ts < watermark) {
+                        reachedWatermark = true;
+                        break;
+                    }
+
+                    // Skip notifications the user already read on another
+                    // client (web tab, Element, second device). Spec marks
+                    // `read` as a required boolean on each entry.
+                    if (entry.optBoolean("read", false)) {
+                        if (ts > highestTsSeen) highestTsSeen = ts;
+                        continue;
+                    }
+
+                    // Skip events the push rules said don't notify (muted
+                    // rooms, dont_notify overrides). Without this gate
+                    // polling would re-surface events Sygnal already
+                    // suppressed for the FCM path — the mute toggle
+                    // wouldn't actually mute on whitelist networks.
+                    if (!notifyAllowed(entry)) {
+                        if (ts > highestTsSeen) highestTsSeen = ts;
+                        continue;
+                    }
+
+                    // Cross-source dedup via NotificationDedup: FCM writes
+                    // into this set after every successful render, so the
+                    // Worker correctly skips events the FCM service already
+                    // delivered — even if the user dismissed the FCM
+                    // notification before this cycle fired.
+                    if (NotificationDedup.wasNotified(ctx, eventId)) {
+                        skippedDedupCount += 1;
+                        if (ts > highestTsSeen) highestTsSeen = ts;
+                        continue;
+                    }
+
+                    // Three outcomes for marking + watermark advance:
+                    //   foreground            → mark + advance (skip render
+                    //                           but consume state, otherwise
+                    //                           next bg poll would replay)
+                    //   background + posted   → mark + advance
+                    //   background + !posted  → DON'T mark, DON'T advance
+                    //                           (transient render failure
+                    //                           should be retried next poll)
+                    boolean posted = false;
+                    boolean treatAsNotRenderable = false;
+                    if (!inForeground) {
+                        Map<String, String> flattened = flattenNotification(entry, roomNames);
+                        String type = flattened.get("type");
+                        boolean isRtcType = RTC_NOTIFICATION_TYPE.equals(type)
+                            || RTC_NOTIFICATION_TYPE_STABLE.equals(type);
+                        boolean isRing = "ring".equals(flattened.get("content_notification_type"));
+
+                        if (isRtcType && isRing) {
+                            // Composite session dedup: if FCM already alerted
+                            // for this call session (different ring event,
+                            // same parent), skip posting a duplicate
+                            // missed-call. Without this, a session with one
+                            // FCM live-alert ring + one re-ring through
+                            // polling would surface as both a CallStyle and
+                            // a missed-call card. Helpers live in
+                            // VojoFirebaseMessagingService so the key shape
+                            // stays in lock-step across FCM and polling.
+                            String roomIdField = flattened.get("room_id");
+                            String sessionId = VojoFirebaseMessagingService
+                                .extractCallSessionId(flattened);
+                            String composite = null;
+                            if (roomIdField != null && sessionId != null) {
+                                composite = VojoFirebaseMessagingService
+                                    .compositeCallDedupKey(roomIdField, sessionId);
+                                if (NotificationDedup.wasNotified(ctx, composite)) {
+                                    if (ts > highestTsSeen) highestTsSeen = ts;
+                                    treatAsNotRenderable = true;
+                                }
+                            }
+                            if (!treatAsNotRenderable) {
+                                // Stale ring (call lifetime is 30 seconds; we
+                                // poll every 15 minutes). Show "Missed call"
+                                // so the user knows somebody tried, without
+                                // phantom-ringing a long-dead call via
+                                // CallStyle.
+                                posted = VojoFirebaseMessagingService
+                                    .renderMissedCallNotification(ctx, flattened);
+                                if (posted && composite != null) {
+                                    // Mark the composite so the next polling
+                                    // cycle observing a re-ring for the same
+                                    // session doesn't double-post.
+                                    NotificationDedup.markNotified(ctx, composite);
+                                }
+                            }
+                        } else if (isRtcType) {
+                            // Non-ring RTC sub-type. MSC4075 defines at least
+                            // "ring" and "notification" — the latter is the
+                            // chat-style alert variant which doesn't make
+                            // sense to surface as a stale "missed" entry from
+                            // a 15-minute poll. Falling through to
+                            // renderMessageNotification would post a generic
+                            // "New message" with no body (no content.body on
+                            // RTC events). Skip rendering but still mark seen
+                            // so we don't re-walk it next poll.
+                            treatAsNotRenderable = true;
+                        } else {
+                            posted = VojoFirebaseMessagingService
+                                .renderMessageNotification(ctx, flattened, null);
+                        }
+                    }
+                    // Mark + advance ts whenever we've consumed the event
+                    // (foreground-skipped, non-ring-RTC skipped, or
+                    // successfully rendered). Render-failure (bg branch where
+                    // posted==false) is intentionally excluded so the next
+                    // poll retries it.
+                    if (inForeground || posted || treatAsNotRenderable) {
+                        NotificationDedup.markNotified(ctx, eventId);
+                        if (ts > highestTsSeen) highestTsSeen = ts;
+                        if (posted) renderedCount += 1;
+                    }
+                }
+
+                pagesFetched += 1;
+                // optString returns the fallback only when the key is absent;
+                // a literal JSON `null` becomes the string "null" — guard
+                // against the rare server quirk so we don't loop on it.
+                String rawNext = body.optString("next_token", null);
+                if (rawNext == null || rawNext.isEmpty() || "null".equals(rawNext)) {
+                    nextFrom = null;
+                } else {
+                    nextFrom = rawNext;
+                }
+                pendingCursor = nextFrom;
+                if (nextFrom == null) {
+                    paginationExhausted = true;
+                    break;
+                }
+            }
+        } catch (UnauthorizedException e) {
+            Log.w(TAG, "poll: 401 — clearing credentials, awaiting next foreground re-bridge");
+            prefs.edit()
+                .remove(KEY_ACCESS_TOKEN)
+                .apply();
+            return Result.success();
+        } catch (ForbiddenException e) {
+            // 403 from Synapse is usually rate-limit or a transient server
+            // policy reject, not a dead token. Don't clear credentials —
+            // just let the next periodic fire retry. Avoid Result.retry()
+            // because we don't want an immediate accelerated retry that
+            // amplifies the rate-limit cause.
+            Log.w(TAG, "poll: 403/429 — skipping this cycle, will retry on next scheduled fire");
+            return Result.success();
+        } catch (Throwable t) {
+            Log.w(TAG, "poll: failed at page " + pagesFetched, t);
+            return Result.retry();
+        }
+
+        // Final stopped-check before persisting state. If cancellation landed
+        // between the last in-loop check and here, do NOT apply: the
+        // accumulated editor writes would otherwise overwrite KEY_LAST_SEEN_TS
+        // and KEY_DRAIN_CURSOR AFTER JS clearSession wiped them, leaking
+        // stale state from the just-logged-out account into the next login.
+        if (isStopped()) return Result.success();
+
+        SharedPreferences.Editor editor = prefs.edit();
+        // Drain-mode bookkeeping. Three transitions:
+        //  - normal → normal (cap not hit): advance watermark to highestTsSeen.
+        //  - normal → drain (cap hit, no prior drain): save continuation
+        //    cursor AND snapshot drainTargetTs = highestTsSeen. The current
+        //    run's highest ts becomes the "fast-forward" target for when
+        //    drain eventually completes — without this, the bounded LRU
+        //    could evict the original head events and let the post-drain
+        //    normal run re-render them.
+        //  - drain → drain (still capped): keep cursor + target unchanged.
+        //    Don't overwrite drainTargetTs with this run's highestTsSeen,
+        //    because drain pages are always OLDER than the original head.
+        //  - drain → normal (drain complete): clear cursor + target. Advance
+        //    watermark to drainTargetTs — drain pages always walk backwards
+        //    (older than the snapshotted head), so highestTsSeen accumulated
+        //    during drain is by construction ≤ drainTargetTs.
+        boolean cappedWithMore = !reachedWatermark && !paginationExhausted && pendingCursor != null;
+        long newWatermark = watermark;
+        String drainState;
+        if (cappedWithMore) {
+            editor.putString(KEY_DRAIN_CURSOR, pendingCursor);
+            if (!wasDraining) {
+                // First run entering drain mode — snapshot the head ts.
+                editor.putLong(KEY_DRAIN_TARGET_TS, highestTsSeen);
+                drainState = "drain-entered";
+            } else {
+                drainState = "drain-continued";
+            }
+        } else {
+            editor.remove(KEY_DRAIN_CURSOR);
+            editor.remove(KEY_DRAIN_TARGET_TS);
+            long advanceTo = wasDraining ? drainTargetTs : highestTsSeen;
+            if (advanceTo > watermark) {
+                editor.putLong(KEY_LAST_SEEN_TS, advanceTo);
+                newWatermark = advanceTo;
+            }
+            drainState = wasDraining ? "drain-exited" : "normal";
+        }
+        editor.apply();
+
+        Log.i(TAG, "poll: done pages=" + pagesFetched
+            + " rendered=" + renderedCount
+            + " dedupSkipped=" + skippedDedupCount
+            + " watermark=" + newWatermark
+            + " state=" + drainState);
+        return Result.success();
+    }
+
+    // Returns true iff at least one element of entry.actions is the literal
+    // string "notify". Per Matrix spec §13.13.1, tweak objects
+    // (`{set_tweak: ...}`) only MODIFY a notification produced by a separate
+    // `"notify"` action — they do not by themselves imply notify. "dont_notify"
+    // or an empty actions array means the push rule explicitly suppressed
+    // this event (most commonly: a muted room).
+    private static boolean notifyAllowed(JSONObject entry) {
+        JSONArray actions = entry.optJSONArray("actions");
+        if (actions == null || actions.length() == 0) return false;
+        for (int i = 0; i < actions.length(); i += 1) {
+            Object a = actions.opt(i);
+            if ((a instanceof String) && "notify".equals(a)) return true;
+        }
+        return false;
+    }
+
+    // ────────────────────────────────────────────────────────────────────
+    // HTTP
+    // ────────────────────────────────────────────────────────────────────
+
+    private static final class UnauthorizedException extends IOException {
+        UnauthorizedException() {
+            super("401 Unauthorized");
+        }
+    }
+
+    // 403 from Synapse is most commonly a rate-limit or a transient policy
+    // reject (M_LIMIT_EXCEEDED, M_FORBIDDEN). It is NOT "token died" — we
+    // surface it as a distinct exception so doWork can skip this cycle
+    // without clearing credentials and without an accelerated Result.retry()
+    // that would amplify the rate-limit cause.
+    private static final class ForbiddenException extends IOException {
+        ForbiddenException() {
+            super("403 Forbidden");
+        }
+    }
+
+    private JSONObject fetchNotifications(String homeserverUrl, String token, String fromCursor)
+        throws IOException {
+        StringBuilder url = new StringBuilder(homeserverUrl);
+        if (!homeserverUrl.endsWith("/")) url.append('/');
+        url.append("_matrix/client/v3/notifications?limit=").append(PAGE_LIMIT);
+        if (fromCursor != null && !fromCursor.isEmpty()) {
+            url.append("&from=").append(java.net.URLEncoder.encode(fromCursor, "UTF-8"));
+        }
+
+        HttpURLConnection conn = (HttpURLConnection) new URL(url.toString()).openConnection();
+        try {
+            conn.setRequestMethod("GET");
+            conn.setRequestProperty("Authorization", "Bearer " + token);
+            conn.setRequestProperty("Accept", "application/json");
+            // Identifiable UA so server logs can attribute polling traffic
+            // (some WAFs also flag bare "Java/<version>" as suspicious).
+            conn.setRequestProperty("User-Agent", "Vojo-Android-Poll/" + BuildConfig.VERSION_NAME);
+            conn.setConnectTimeout(HTTP_TIMEOUT_MS);
+            conn.setReadTimeout(HTTP_TIMEOUT_MS);
+            int code = conn.getResponseCode();
+            if (code == 401) throw new UnauthorizedException();
+            // Treat 429 (rate limited) and 403 (Synapse policy reject) the
+            // same: skip this cycle, don't retry-storm. Result.retry()'s 30s
+            // backoff would amplify the rate-limit cause; the next periodic
+            // fire in 15 minutes is well past any realistic Retry-After
+            // window from a Matrix homeserver.
+            if (code == 403 || code == 429) throw new ForbiddenException();
+            if (code < 200 || code >= 300) {
+                throw new IOException("HTTP " + code);
+            }
+            try (InputStream in = conn.getInputStream()) {
+                return new JSONObject(readAll(in));
+            } catch (org.json.JSONException je) {
+                throw new IOException("malformed JSON", je);
+            }
+        } finally {
+            conn.disconnect();
+        }
+    }
+
+    private static String readAll(InputStream in) throws IOException {
+        // Accumulate raw bytes, then decode the whole buffer as a single UTF-8
+        // string. Decoding each 8 KB chunk separately would corrupt multi-byte
+        // sequences that straddle a chunk boundary — for a Russian-content
+        // notification body that crosses ~8 KB, the result is U+FFFD in place
+        // of a Cyrillic character. Also use != -1 rather than > 0 for the
+        // read loop: InputStream.read(byte[]) is contractually allowed to
+        // return 0 without indicating EOF.
+        java.io.ByteArrayOutputStream out = new java.io.ByteArrayOutputStream();
+        byte[] buf = new byte[8 * 1024];
+        int n;
+        while ((n = in.read(buf)) != -1) {
+            if (n > 0) out.write(buf, 0, n);
+        }
+        return out.toString("UTF-8");
+    }
+
+    // ────────────────────────────────────────────────────────────────────
+    // Payload shaping
+    //
+    // The /notifications response shape is structured (event{type,sender,
+    // content{}}, room_id, ts, read, actions) — different from Sygnal's
+    // flattened FCM payload. We flatten into the Sygnal-shape Map<String,
+    // String> so the shared renderer in VojoFirebaseMessagingService can
+    // stay source-agnostic. Keys we set: event_id, room_id, sender, type,
+    // content_membership, content_body, content_notification_type,
+    // content_sender_ts, content_lifetime, room_name (from local cache).
+    //
+    // NOTE: sender_display_name is NOT set here — /notifications returns the
+    // raw event without the Sygnal-side profile resolution that gives FCM
+    // its `sender_display_name`. The renderer's title-fallback chain
+    // (room_name → sender_display_name → sender → "Vojo") therefore lands
+    // on `sender` (a raw MXID) when the room name isn't cached. The renderer
+    // strips the MXID to its local-part as a final cosmetic guard so users
+    // see "alice" instead of "@alice:hs.tld".
+    // ────────────────────────────────────────────────────────────────────
+
+    private static Map<String, String> flattenNotification(
+        JSONObject entry, Map<String, String> roomNames
+    ) {
+        Map<String, String> out = new HashMap<>();
+        String roomId = entry.optString("room_id", null);
+        if (roomId != null) out.put("room_id", roomId);
+
+        JSONObject event = entry.optJSONObject("event");
+        if (event != null) {
+            putIfPresent(out, event, "event_id", "event_id");
+            putIfPresent(out, event, "sender", "sender");
+            putIfPresent(out, event, "type", "type");
+            JSONObject content = event.optJSONObject("content");
+            if (content != null) {
+                putIfPresent(out, content, "membership", "content_membership");
+                putIfPresent(out, content, "body", "content_body");
+                putIfPresent(out, content, "notification_type", "content_notification_type");
+                if (content.has("sender_ts")) {
+                    out.put("content_sender_ts", String.valueOf(content.optLong("sender_ts")));
+                }
+                if (content.has("lifetime")) {
+                    out.put("content_lifetime", String.valueOf(content.optLong("lifetime")));
+                }
+                // Parent call event_id for session-level dedup. The shared
+                // FCM renderer reads this from the flattened key
+                // `content_m.relates_to_event_id` (mirroring one of Sygnal's
+                // flatten shapes); writing the literal-dot variant here keeps
+                // FCM and polling on the same key.
+                JSONObject relates = content.optJSONObject("m.relates_to");
+                if (relates != null) {
+                    String parentEventId = relates.optString("event_id", null);
+                    if (parentEventId != null && !parentEventId.isEmpty()) {
+                        out.put("content_m.relates_to_event_id", parentEventId);
+                    }
+                }
+                // Legacy MSC2746 call_id fallback. Modern MSC4075 sessions
+                // surface via m.relates_to above; this branch is a no-op for
+                // them but keeps the shape symmetric for older deployments.
+                if (content.has("call_id")) {
+                    String callId = content.optString("call_id", null);
+                    if (callId != null && !callId.isEmpty()) {
+                        out.put("content_call_id", callId);
+                    }
+                }
+            }
+        }
+
+        // Room name from the snapshot the JS side pushes through
+        // PollingPlugin.saveRoomNames, parsed once at the start of doWork().
+        // Brand-new rooms (not yet observed by JS at last bridge time) miss
+        // the cache — the renderer falls back to sender / "Vojo".
+        if (roomId != null) {
+            String roomName = roomNames.get(roomId);
+            if (roomName != null && !roomName.isEmpty()) out.put("room_name", roomName);
+        }
+
+        return out;
+    }
+
+    // Parse the SharedPreferences-stored room-name JSON snapshot once per
+    // doWork() so we don't redo the parse for every event in the page (up to
+    // PAGE_LIMIT × MAX_PAGES_PER_RUN = 250 events).
+    //
+    // The snapshot shape evolved: legacy was {roomId: "Display name"}, current
+    // is {roomId: {name, isDirect, isEncrypted, avatarMxc?}}. We parse both
+    // tolerantly — for the structured shape we extract `name`, for the legacy
+    // shape we use the string verbatim. A naive optString on the structured
+    // entry serialises the whole object as JSON ("{name:Alice,...}") and that
+    // string leaked into the missed-call / message title on the polling
+    // path — visible bug.
+    private static Map<String, String> loadRoomNamesMap(SharedPreferences prefs) {
+        Map<String, String> out = new HashMap<>();
+        String raw = prefs.getString(KEY_ROOM_NAMES, null);
+        if (raw == null || raw.isEmpty()) return out;
+        try {
+            JSONObject map = new JSONObject(raw);
+            for (Iterator<String> it = map.keys(); it.hasNext(); ) {
+                String roomId = it.next();
+                if (map.isNull(roomId)) continue;
+                JSONObject obj = map.optJSONObject(roomId);
+                String name = obj != null
+                    ? obj.optString("name", null)
+                    : map.optString(roomId, null);
+                if (name != null && !name.isEmpty()) out.put(roomId, name);
+            }
+        } catch (org.json.JSONException je) {
+            // Corrupt blob — return empty map. Renderer falls back to sender.
+        }
+        return out;
+    }
+
+    private static void putIfPresent(
+        Map<String, String> out, JSONObject src, String srcKey, String dstKey
+    ) {
+        // Guard against a literal JSON null at the key: JSONObject.optString
+        // returns the *fallback* only when the key is absent, but on a
+        // present-but-null key it coerces JSONObject.NULL to the four-char
+        // string "null", which would leak as "null" into a notification body.
+        if (!src.has(srcKey) || src.isNull(srcKey)) return;
+        String v = src.optString(srcKey, null);
+        if (v != null && !v.isEmpty()) out.put(dstKey, v);
+    }
+
+    private static String extractEventId(JSONObject entry) {
+        JSONObject event = entry.optJSONObject("event");
+        if (event == null) return null;
+        if (!event.has("event_id") || event.isNull("event_id")) return null;
+        String eventId = event.optString("event_id", null);
+        if (eventId == null || eventId.isEmpty()) return null;
+        return eventId;
+    }
+
+
+}

android/app/src/main/res/drawable-v24/ic_launcher_foreground.xml

@@ -0,0 +1,34 @@
+<vector xmlns:android="http://schemas.android.com/apk/res/android"
+    xmlns:aapt="http://schemas.android.com/aapt"
+    android:width="108dp"
+    android:height="108dp"
+    android:viewportHeight="108"
+    android:viewportWidth="108">
+    <path
+        android:fillType="evenOdd"
+        android:pathData="M32,64C32,64 38.39,52.99 44.13,50.95C51.37,48.37 70.14,49.57 70.14,49.57L108.26,87.69L108,109.01L75.97,107.97L32,64Z"
+        android:strokeColor="#00000000"
+        android:strokeWidth="1">
+        <aapt:attr name="android:fillColor">
+            <gradient
+                android:endX="78.5885"
+                android:endY="90.9159"
+                android:startX="48.7653"
+                android:startY="61.0927"
+                android:type="linear">
+                <item
+                    android:color="#44000000"
+                    android:offset="0.0" />
+                <item
+                    android:color="#00000000"
+                    android:offset="1.0" />
+            </gradient>
+        </aapt:attr>
+    </path>
+    <path
+        android:fillColor="#FFFFFF"
+        android:fillType="nonZero"
+        android:pathData="M66.94,46.02L66.94,46.02C72.44,50.07 76,56.61 76,64L32,64C32,56.61 35.56,50.11 40.98,46.06L36.18,41.19C35.45,40.45 35.45,39.3 36.18,38.56C36.91,37.81 38.05,37.81 38.78,38.56L44.25,44.05C47.18,42.57 50.48,41.71 54,41.71C57.48,41.71 60.78,42.57 63.68,44.05L69.11,38.56C69.84,37.81 70.98,37.81 71.71,38.56C72.44,39.3 72.44,40.45 71.71,41.19L66.94,46.02ZM62.94,56.92C64.08,56.92 65,56.01 65,54.88C65,53.76 64.08,52.85 62.94,52.85C61.8,52.85 60.88,53.76 60.88,54.88C60.88,56.01 61.8,56.92 62.94,56.92ZM45.06,56.92C46.2,56.92 47.13,56.01 47.13,54.88C47.13,53.76 46.2,52.85 45.06,52.85C43.92,52.85 43,53.76 43,54.88C43,56.01 43.92,56.92 45.06,56.92Z"
+        android:strokeColor="#00000000"
+        android:strokeWidth="1" />
+</vector>

android/app/src/main/res/drawable/ic_launcher_background.xml

@@ -0,0 +1,170 @@
+<?xml version="1.0" encoding="utf-8"?>
+<vector xmlns:android="http://schemas.android.com/apk/res/android"
+    android:width="108dp"
+    android:height="108dp"
+    android:viewportHeight="108"
+    android:viewportWidth="108">
+    <path
+        android:fillColor="#26A69A"
+        android:pathData="M0,0h108v108h-108z" />
+    <path
+        android:fillColor="#00000000"
+        android:pathData="M9,0L9,108"
+        android:strokeColor="#33FFFFFF"
+        android:strokeWidth="0.8" />
+    <path
+        android:fillColor="#00000000"
+        android:pathData="M19,0L19,108"
+        android:strokeColor="#33FFFFFF"
+        android:strokeWidth="0.8" />
+    <path
+        android:fillColor="#00000000"
+        android:pathData="M29,0L29,108"
+        android:strokeColor="#33FFFFFF"
+        android:strokeWidth="0.8" />
+    <path
+        android:fillColor="#00000000"
+        android:pathData="M39,0L39,108"
+        android:strokeColor="#33FFFFFF"
+        android:strokeWidth="0.8" />
+    <path
+        android:fillColor="#00000000"
+        android:pathData="M49,0L49,108"
+        android:strokeColor="#33FFFFFF"
+        android:strokeWidth="0.8" />
+    <path
+        android:fillColor="#00000000"
+        android:pathData="M59,0L59,108"
+        android:strokeColor="#33FFFFFF"
+        android:strokeWidth="0.8" />
+    <path
+        android:fillColor="#00000000"
+        android:pathData="M69,0L69,108"
+        android:strokeColor="#33FFFFFF"
+        android:strokeWidth="0.8" />
+    <path
+        android:fillColor="#00000000"
+        android:pathData="M79,0L79,108"
+        android:strokeColor="#33FFFFFF"
+        android:strokeWidth="0.8" />
+    <path
+        android:fillColor="#00000000"
+        android:pathData="M89,0L89,108"
+        android:strokeColor="#33FFFFFF"
+        android:strokeWidth="0.8" />
+    <path
+        android:fillColor="#00000000"
+        android:pathData="M99,0L99,108"
+        android:strokeColor="#33FFFFFF"
+        android:strokeWidth="0.8" />
+    <path
+        android:fillColor="#00000000"
+        android:pathData="M0,9L108,9"
+        android:strokeColor="#33FFFFFF"
+        android:strokeWidth="0.8" />
+    <path
+        android:fillColor="#00000000"
+        android:pathData="M0,19L108,19"
+        android:strokeColor="#33FFFFFF"
+        android:strokeWidth="0.8" />
+    <path
+        android:fillColor="#00000000"
+        android:pathData="M0,29L108,29"
+        android:strokeColor="#33FFFFFF"
+        android:strokeWidth="0.8" />
+    <path
+        android:fillColor="#00000000"
+        android:pathData="M0,39L108,39"
+        android:strokeColor="#33FFFFFF"
+        android:strokeWidth="0.8" />
+    <path
+        android:fillColor="#00000000"
+        android:pathData="M0,49L108,49"
+        android:strokeColor="#33FFFFFF"
+        android:strokeWidth="0.8" />
+    <path
+        android:fillColor="#00000000"
+        android:pathData="M0,59L108,59"
+        android:strokeColor="#33FFFFFF"
+        android:strokeWidth="0.8" />
+    <path
+        android:fillColor="#00000000"
+        android:pathData="M0,69L108,69"
+        android:strokeColor="#33FFFFFF"
+        android:strokeWidth="0.8" />
+    <path
+        android:fillColor="#00000000"
+        android:pathData="M0,79L108,79"
+        android:strokeColor="#33FFFFFF"
+        android:strokeWidth="0.8" />
+    <path
+        android:fillColor="#00000000"
+        android:pathData="M0,89L108,89"
+        android:strokeColor="#33FFFFFF"
+        android:strokeWidth="0.8" />
+    <path
+        android:fillColor="#00000000"
+        android:pathData="M0,99L108,99"
+        android:strokeColor="#33FFFFFF"
+        android:strokeWidth="0.8" />
+    <path
+        android:fillColor="#00000000"
+        android:pathData="M19,29L89,29"
+        android:strokeColor="#33FFFFFF"
+        android:strokeWidth="0.8" />
+    <path
+        android:fillColor="#00000000"
+        android:pathData="M19,39L89,39"
+        android:strokeColor="#33FFFFFF"
+        android:strokeWidth="0.8" />
+    <path
+        android:fillColor="#00000000"
+        android:pathData="M19,49L89,49"
+        android:strokeColor="#33FFFFFF"
+        android:strokeWidth="0.8" />
+    <path
+        android:fillColor="#00000000"
+        android:pathData="M19,59L89,59"
+        android:strokeColor="#33FFFFFF"
+        android:strokeWidth="0.8" />
+    <path
+        android:fillColor="#00000000"
+        android:pathData="M19,69L89,69"
+        android:strokeColor="#33FFFFFF"
+        android:strokeWidth="0.8" />
+    <path
+        android:fillColor="#00000000"
+        android:pathData="M19,79L89,79"
+        android:strokeColor="#33FFFFFF"
+        android:strokeWidth="0.8" />
+    <path
+        android:fillColor="#00000000"
+        android:pathData="M29,19L29,89"
+        android:strokeColor="#33FFFFFF"
+        android:strokeWidth="0.8" />
+    <path
+        android:fillColor="#00000000"
+        android:pathData="M39,19L39,89"
+        android:strokeColor="#33FFFFFF"
+        android:strokeWidth="0.8" />
+    <path
+        android:fillColor="#00000000"
+        android:pathData="M49,19L49,89"
+        android:strokeColor="#33FFFFFF"
+        android:strokeWidth="0.8" />
+    <path
+        android:fillColor="#00000000"
+        android:pathData="M59,19L59,89"
+        android:strokeColor="#33FFFFFF"
+        android:strokeWidth="0.8" />
+    <path
+        android:fillColor="#00000000"
+        android:pathData="M69,19L69,89"
+        android:strokeColor="#33FFFFFF"
+        android:strokeWidth="0.8" />
+    <path
+        android:fillColor="#00000000"
+        android:pathData="M79,19L79,89"
+        android:strokeColor="#33FFFFFF"
+        android:strokeWidth="0.8" />
+</vector>

android/app/src/main/res/layout/activity_main.xml

@@ -0,0 +1,12 @@
+<?xml version="1.0" encoding="utf-8"?>
+<androidx.coordinatorlayout.widget.CoordinatorLayout xmlns:android="http://schemas.android.com/apk/res/android"
+    xmlns:app="http://schemas.android.com/apk/res-auto"
+    xmlns:tools="http://schemas.android.com/tools"
+    android:layout_width="match_parent"
+    android:layout_height="match_parent"
+    tools:context=".MainActivity">
+
+    <WebView
+        android:layout_width="match_parent"
+        android:layout_height="match_parent" />
+</androidx.coordinatorlayout.widget.CoordinatorLayout>

android/app/src/main/res/mipmap-anydpi-v26/ic_launcher.xml

@@ -0,0 +1,5 @@
+<?xml version="1.0" encoding="utf-8"?>
+<adaptive-icon xmlns:android="http://schemas.android.com/apk/res/android">
+    <background android:drawable="@color/ic_launcher_background"/>
+    <foreground android:drawable="@mipmap/ic_launcher_foreground"/>
+</adaptive-icon>

android/app/src/main/res/mipmap-anydpi-v26/ic_launcher_round.xml

@@ -0,0 +1,5 @@
+<?xml version="1.0" encoding="utf-8"?>
+<adaptive-icon xmlns:android="http://schemas.android.com/apk/res/android">
+    <background android:drawable="@color/ic_launcher_background"/>
+    <foreground android:drawable="@mipmap/ic_launcher_foreground"/>
+</adaptive-icon>

android/app/src/main/res/values/colors.xml

@@ -0,0 +1,7 @@
+<?xml version="1.0" encoding="utf-8"?>
+<resources>
+    <!-- Matches web safe-area / DM 1:1 chat background (DAWN.bg2) so the
+         native splash, the WebView body, and the in-app AuthSplashScreen all
+         share a single backdrop and read as one continuous splash. -->
+    <color name="splash_bg">#0d0e11</color>
+</resources>

android/app/src/main/res/values/ic_launcher_background.xml

@@ -0,0 +1,4 @@
+<?xml version="1.0" encoding="utf-8"?>
+<resources>
+    <color name="ic_launcher_background">#121314</color>
+</resources>

android/app/src/main/res/values/strings.xml

@@ -0,0 +1,7 @@
+<?xml version='1.0' encoding='utf-8'?>
+<resources>
+    <string name="app_name">Vojo</string>
+    <string name="title_activity_main">Vojo</string>
+    <string name="package_name">chat.vojo.app</string>
+    <string name="custom_url_scheme">chat.vojo.app</string>
+</resources>

android/app/src/main/res/values/styles.xml

@@ -0,0 +1,53 @@
+<?xml version="1.0" encoding="utf-8"?>
+<resources>
+
+    <!-- Base application theme. -->
+    <style name="AppTheme" parent="Theme.AppCompat.DayNight.NoActionBar">
+        <item name="colorPrimary">@color/colorPrimary</item>
+        <item name="colorPrimaryDark">@color/colorPrimaryDark</item>
+        <item name="colorAccent">@color/colorAccent</item>
+        <item name="windowActionBar">false</item>
+        <item name="windowNoTitle">true</item>
+    </style>
+
+    <style name="AppTheme.NoActionBar" parent="Theme.AppCompat.DayNight.NoActionBar">
+        <item name="windowActionBar">false</item>
+        <item name="windowNoTitle">true</item>
+        <item name="android:background">@null</item>
+        <item name="android:windowLayoutInDisplayCutoutMode">shortEdges</item>
+        <!-- Bridges the gap between native splash exit and the WebView's first
+             body paint: without this the window paints transparent/black for
+             ~200ms while the bundle hydrates, producing a visible black flash
+             between the native and the in-app splash. Matches splash_bg so
+             cold start reads as one continuous backdrop. -->
+        <item name="android:windowBackground">@color/splash_bg</item>
+    </style>
+
+    <!-- Launch theme: Android 12+ system splash (Theme.SplashScreen via
+         androidx.core.splashscreen). Renders the mascot centered on the same
+         #0d0e11 backdrop the web AuthSplashScreen uses, so cold start reads
+         as one continuous splash (native → WebView mount → web splash) instead
+         of three visual jumps. MainActivity installs AndroidX SplashScreen
+         before super.onCreate() and keeps it visible until Capacitor's local
+         WebView has loaded the app shell. -->
+    <style name="AppTheme.NoActionBarLaunch" parent="Theme.SplashScreen">
+        <!-- Theme.SplashScreen only sets the native android:windowActionBar /
+             android:windowNoTitle attrs. Capacitor's BridgeActivity extends
+             AppCompatActivity, whose ActionBar delegate reads the un-prefixed
+             AppCompat attrs — without these two overrides, AppCompat keeps
+             its ActionBar enabled, paints the activity label ("Vojo" from
+             strings.xml/title_activity_main) at the top of the WebView, and
+             persists past the splash exit. -->
+        <item name="windowActionBar">false</item>
+        <item name="windowNoTitle">true</item>
+        <item name="windowSplashScreenBackground">@color/splash_bg</item>
+        <item name="windowSplashScreenAnimatedIcon">@drawable/vojo_mascot_splash</item>
+        <!-- Intentionally NO windowSplashScreenIconBackgroundColor: setting it
+             switches the system to the "with-background" canvas, which is
+             actually 240dp (vs 288dp without) — the colored ring would just
+             shrink the visible icon zone. Background already matches via
+             windowSplashScreenBackground above. -->
+        <item name="postSplashScreenTheme">@style/AppTheme.NoActionBar</item>
+        <item name="android:windowLayoutInDisplayCutoutMode">shortEdges</item>
+    </style>
+</resources>

android/app/src/main/res/xml/file_paths.xml

@@ -0,0 +1,5 @@
+<?xml version="1.0" encoding="utf-8"?>
+<paths xmlns:android="http://schemas.android.com/apk/res/android">
+    <external-path name="my_images" path="." />
+    <cache-path name="my_cache_images" path="." />
+</paths>

android/app/src/test/java/com/getcapacitor/myapp/ExampleUnitTest.java

@@ -0,0 +1,18 @@
+package com.getcapacitor.myapp;
+
+import static org.junit.Assert.*;
+
+import org.junit.Test;
+
+/**
+ * Example local unit test, which will execute on the development machine (host).
+ *
+ * @see <a href="http://d.android.com/tools/testing">Testing documentation</a>
+ */
+public class ExampleUnitTest {
+
+    @Test
+    public void addition_isCorrect() throws Exception {
+        assertEquals(4, 2 + 2);
+    }
+}

android/build.gradle

@@ -0,0 +1,29 @@
+// Top-level build file where you can add configuration options common to all sub-projects/modules.
+
+buildscript {
+    
+    repositories {
+        google()
+        mavenCentral()
+    }
+    dependencies {
+        classpath 'com.android.tools.build:gradle:8.13.0'
+        classpath 'com.google.gms:google-services:4.4.4'
+
+        // NOTE: Do not place your application dependencies here; they belong
+        // in the individual module build.gradle files
+    }
+}
+
+apply from: "variables.gradle"
+
+allprojects {
+    repositories {
+        google()
+        mavenCentral()
+    }
+}
+
+task clean(type: Delete) {
+    delete rootProject.buildDir
+}

android/capacitor.settings.gradle

@@ -0,0 +1,18 @@
+// DO NOT EDIT THIS FILE! IT IS GENERATED EACH TIME "capacitor update" IS RUN
+include ':capacitor-android'
+project(':capacitor-android').projectDir = new File('../node_modules/@capacitor/android/capacitor')
+
+include ':capacitor-app'
+project(':capacitor-app').projectDir = new File('../node_modules/@capacitor/app/android')
+
+include ':capacitor-browser'
+project(':capacitor-browser').projectDir = new File('../node_modules/@capacitor/browser/android')
+
+include ':capacitor-preferences'
+project(':capacitor-preferences').projectDir = new File('../node_modules/@capacitor/preferences/android')
+
+include ':capacitor-push-notifications'
+project(':capacitor-push-notifications').projectDir = new File('../node_modules/@capacitor/push-notifications/android')
+
+include ':capacitor-toast'
+project(':capacitor-toast').projectDir = new File('../node_modules/@capacitor/toast/android')

android/gradle.properties

@@ -0,0 +1,22 @@
+# Project-wide Gradle settings.
+
+# IDE (e.g. Android Studio) users:
+# Gradle settings configured through the IDE *will override*
+# any settings specified in this file.
+
+# For more details on how to configure your build environment visit
+# http://www.gradle.org/docs/current/userguide/build_environment.html
+
+# Specifies the JVM arguments used for the daemon process.
+# The setting is particularly useful for tweaking memory settings.
+org.gradle.jvmargs=-Xmx1536m
+
+# When configured, Gradle will run in incubating parallel mode.
+# This option should only be used with decoupled projects. More details, visit
+# http://www.gradle.org/docs/current/userguide/multi_project_builds.html#sec:decoupled_projects
+# org.gradle.parallel=true
+
+# AndroidX package structure to make it clearer which packages are bundled with the
+# Android operating system, and which are packaged with your app's APK
+# https://developer.android.com/topic/libraries/support-library/androidx-rn
+android.useAndroidX=true

android/gradle/wrapper/gradle-wrapper.properties

@@ -0,0 +1,7 @@
+distributionBase=GRADLE_USER_HOME
+distributionPath=wrapper/dists
+distributionUrl=https\://services.gradle.org/distributions/gradle-8.14.3-all.zip
+networkTimeout=10000
+validateDistributionUrl=true
+zipStoreBase=GRADLE_USER_HOME
+zipStorePath=wrapper/dists

android/gradlew

@@ -0,0 +1,251 @@
+#!/bin/sh
+
+#
+# Copyright © 2015-2021 the original authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# SPDX-License-Identifier: Apache-2.0
+#
+
+##############################################################################
+#
+#   Gradle start up script for POSIX generated by Gradle.
+#
+#   Important for running:
+#
+#   (1) You need a POSIX-compliant shell to run this script. If your /bin/sh is
+#       noncompliant, but you have some other compliant shell such as ksh or
+#       bash, then to run this script, type that shell name before the whole
+#       command line, like:
+#
+#           ksh Gradle
+#
+#       Busybox and similar reduced shells will NOT work, because this script
+#       requires all of these POSIX shell features:
+#         * functions;
+#         * expansions «$var», «${var}», «${var:-default}», «${var+SET}»,
+#           «${var#prefix}», «${var%suffix}», and «$( cmd )»;
+#         * compound commands having a testable exit status, especially «case»;
+#         * various built-in commands including «command», «set», and «ulimit».
+#
+#   Important for patching:
+#
+#   (2) This script targets any POSIX shell, so it avoids extensions provided
+#       by Bash, Ksh, etc; in particular arrays are avoided.
+#
+#       The "traditional" practice of packing multiple parameters into a
+#       space-separated string is a well documented source of bugs and security
+#       problems, so this is (mostly) avoided, by progressively accumulating
+#       options in "$@", and eventually passing that to Java.
+#
+#       Where the inherited environment variables (DEFAULT_JVM_OPTS, JAVA_OPTS,
+#       and GRADLE_OPTS) rely on word-splitting, this is performed explicitly;
+#       see the in-line comments for details.
+#
+#       There are tweaks for specific operating systems such as AIX, CygWin,
+#       Darwin, MinGW, and NonStop.
+#
+#   (3) This script is generated from the Groovy template
+#       https://github.com/gradle/gradle/blob/HEAD/platforms/jvm/plugins-application/src/main/resources/org/gradle/api/internal/plugins/unixStartScript.txt
+#       within the Gradle project.
+#
+#       You can find Gradle at https://github.com/gradle/gradle/.
+#
+##############################################################################
+
+# Attempt to set APP_HOME
+
+# Resolve links: $0 may be a link
+app_path=$0
+
+# Need this for daisy-chained symlinks.
+while
+    APP_HOME=${app_path%"${app_path##*/}"}  # leaves a trailing /; empty if no leading path
+    [ -h "$app_path" ]
+do
+    ls=$( ls -ld "$app_path" )
+    link=${ls#*' -> '}
+    case $link in             #(
+      /*)   app_path=$link ;; #(
+      *)    app_path=$APP_HOME$link ;;
+    esac
+done
+
+# This is normally unused
+# shellcheck disable=SC2034
+APP_BASE_NAME=${0##*/}
+# Discard cd standard output in case $CDPATH is set (https://github.com/gradle/gradle/issues/25036)
+APP_HOME=$( cd -P "${APP_HOME:-./}" > /dev/null && printf '%s\n' "$PWD" ) || exit
+
+# Use the maximum available, or set MAX_FD != -1 to use that value.
+MAX_FD=maximum
+
+warn () {
+    echo "$*"
+} >&2
+
+die () {
+    echo
+    echo "$*"
+    echo
+    exit 1
+} >&2
+
+# OS specific support (must be 'true' or 'false').
+cygwin=false
+msys=false
+darwin=false
+nonstop=false
+case "$( uname )" in                #(
+  CYGWIN* )         cygwin=true  ;; #(
+  Darwin* )         darwin=true  ;; #(
+  MSYS* | MINGW* )  msys=true    ;; #(
+  NONSTOP* )        nonstop=true ;;
+esac
+
+CLASSPATH="\\\"\\\""
+
+
+# Determine the Java command to use to start the JVM.
+if [ -n "$JAVA_HOME" ] ; then
+    if [ -x "$JAVA_HOME/jre/sh/java" ] ; then
+        # IBM's JDK on AIX uses strange locations for the executables
+        JAVACMD=$JAVA_HOME/jre/sh/java
+    else
+        JAVACMD=$JAVA_HOME/bin/java
+    fi
+    if [ ! -x "$JAVACMD" ] ; then
+        die "ERROR: JAVA_HOME is set to an invalid directory: $JAVA_HOME
+
+Please set the JAVA_HOME variable in your environment to match the
+location of your Java installation."
+    fi
+else
+    JAVACMD=java
+    if ! command -v java >/dev/null 2>&1
+    then
+        die "ERROR: JAVA_HOME is not set and no 'java' command could be found in your PATH.
+
+Please set the JAVA_HOME variable in your environment to match the
+location of your Java installation."
+    fi
+fi
+
+# Increase the maximum file descriptors if we can.
+if ! "$cygwin" && ! "$darwin" && ! "$nonstop" ; then
+    case $MAX_FD in #(
+      max*)
+        # In POSIX sh, ulimit -H is undefined. That's why the result is checked to see if it worked.
+        # shellcheck disable=SC2039,SC3045
+        MAX_FD=$( ulimit -H -n ) ||
+            warn "Could not query maximum file descriptor limit"
+    esac
+    case $MAX_FD in  #(
+      '' | soft) :;; #(
+      *)
+        # In POSIX sh, ulimit -n is undefined. That's why the result is checked to see if it worked.
+        # shellcheck disable=SC2039,SC3045
+        ulimit -n "$MAX_FD" ||
+            warn "Could not set maximum file descriptor limit to $MAX_FD"
+    esac
+fi
+
+# Collect all arguments for the java command, stacking in reverse order:
+#   * args from the command line
+#   * the main class name
+#   * -classpath
+#   * -D...appname settings
+#   * --module-path (only if needed)
+#   * DEFAULT_JVM_OPTS, JAVA_OPTS, and GRADLE_OPTS environment variables.
+
+# For Cygwin or MSYS, switch paths to Windows format before running java
+if "$cygwin" || "$msys" ; then
+    APP_HOME=$( cygpath --path --mixed "$APP_HOME" )
+    CLASSPATH=$( cygpath --path --mixed "$CLASSPATH" )
+
+    JAVACMD=$( cygpath --unix "$JAVACMD" )
+
+    # Now convert the arguments - kludge to limit ourselves to /bin/sh
+    for arg do
+        if
+            case $arg in                                #(
+              -*)   false ;;                            # don't mess with options #(
+              /?*)  t=${arg#/} t=/${t%%/*}              # looks like a POSIX filepath
+                    [ -e "$t" ] ;;                      #(
+              *)    false ;;
+            esac
+        then
+            arg=$( cygpath --path --ignore --mixed "$arg" )
+        fi
+        # Roll the args list around exactly as many times as the number of
+        # args, so each arg winds up back in the position where it started, but
+        # possibly modified.
+        #
+        # NB: a `for` loop captures its iteration list before it begins, so
+        # changing the positional parameters here affects neither the number of
+        # iterations, nor the values presented in `arg`.
+        shift                   # remove old arg
+        set -- "$@" "$arg"      # push replacement arg
+    done
+fi
+
+
+# Add default JVM options here. You can also use JAVA_OPTS and GRADLE_OPTS to pass JVM options to this script.
+DEFAULT_JVM_OPTS='"-Xmx64m" "-Xms64m"'
+
+# Collect all arguments for the java command:
+#   * DEFAULT_JVM_OPTS, JAVA_OPTS, and optsEnvironmentVar are not allowed to contain shell fragments,
+#     and any embedded shellness will be escaped.
+#   * For example: A user cannot expect ${Hostname} to be expanded, as it is an environment variable and will be
+#     treated as '${Hostname}' itself on the command line.
+
+set -- \
+        "-Dorg.gradle.appname=$APP_BASE_NAME" \
+        -classpath "$CLASSPATH" \
+        -jar "$APP_HOME/gradle/wrapper/gradle-wrapper.jar" \
+        "$@"
+
+# Stop when "xargs" is not available.
+if ! command -v xargs >/dev/null 2>&1
+then
+    die "xargs is not available"
+fi
+
+# Use "xargs" to parse quoted args.
+#
+# With -n1 it outputs one arg per line, with the quotes and backslashes removed.
+#
+# In Bash we could simply go:
+#
+#   readarray ARGS < <( xargs -n1 <<<"$var" ) &&
+#   set -- "${ARGS[@]}" "$@"
+#
+# but POSIX shell has neither arrays nor command substitution, so instead we
+# post-process each arg (as a line of input to sed) to backslash-escape any
+# character that might be a shell metacharacter, then use eval to reverse
+# that process (while maintaining the separation between arguments), and wrap
+# the whole thing up as a single "set" statement.
+#
+# This will of course break if any of these variables contains a newline or
+# an unmatched quote.
+#
+
+eval "set -- $(
+        printf '%s\n' "$DEFAULT_JVM_OPTS $JAVA_OPTS $GRADLE_OPTS" |
+        xargs -n1 |
+        sed ' s~[^-[:alnum:]+,./:=@_]~\\&~g; ' |
+        tr '\n' ' '
+    )" '"$@"'
+
+exec "$JAVACMD" "$@"

android/gradlew.bat

@@ -0,0 +1,94 @@
+@rem
+@rem Copyright 2015 the original author or authors.
+@rem
+@rem Licensed under the Apache License, Version 2.0 (the "License");
+@rem you may not use this file except in compliance with the License.
+@rem You may obtain a copy of the License at
+@rem
+@rem      https://www.apache.org/licenses/LICENSE-2.0
+@rem
+@rem Unless required by applicable law or agreed to in writing, software
+@rem distributed under the License is distributed on an "AS IS" BASIS,
+@rem WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+@rem See the License for the specific language governing permissions and
+@rem limitations under the License.
+@rem
+@rem SPDX-License-Identifier: Apache-2.0
+@rem
+
+@if "%DEBUG%"=="" @echo off
+@rem ##########################################################################
+@rem
+@rem  Gradle startup script for Windows
+@rem
+@rem ##########################################################################
+
+@rem Set local scope for the variables with windows NT shell
+if "%OS%"=="Windows_NT" setlocal
+
+set DIRNAME=%~dp0
+if "%DIRNAME%"=="" set DIRNAME=.
+@rem This is normally unused
+set APP_BASE_NAME=%~n0
+set APP_HOME=%DIRNAME%
+
+@rem Resolve any "." and ".." in APP_HOME to make it shorter.
+for %%i in ("%APP_HOME%") do set APP_HOME=%%~fi
+
+@rem Add default JVM options here. You can also use JAVA_OPTS and GRADLE_OPTS to pass JVM options to this script.
+set DEFAULT_JVM_OPTS="-Xmx64m" "-Xms64m"
+
+@rem Find java.exe
+if defined JAVA_HOME goto findJavaFromJavaHome
+
+set JAVA_EXE=java.exe
+%JAVA_EXE% -version >NUL 2>&1
+if %ERRORLEVEL% equ 0 goto execute
+
+echo. 1>&2
+echo ERROR: JAVA_HOME is not set and no 'java' command could be found in your PATH. 1>&2
+echo. 1>&2
+echo Please set the JAVA_HOME variable in your environment to match the 1>&2
+echo location of your Java installation. 1>&2
+
+goto fail
+
+:findJavaFromJavaHome
+set JAVA_HOME=%JAVA_HOME:"=%
+set JAVA_EXE=%JAVA_HOME%/bin/java.exe
+
+if exist "%JAVA_EXE%" goto execute
+
+echo. 1>&2
+echo ERROR: JAVA_HOME is set to an invalid directory: %JAVA_HOME% 1>&2
+echo. 1>&2
+echo Please set the JAVA_HOME variable in your environment to match the 1>&2
+echo location of your Java installation. 1>&2
+
+goto fail
+
+:execute
+@rem Setup the command line
+
+set CLASSPATH=
+
+
+@rem Execute Gradle
+"%JAVA_EXE%" %DEFAULT_JVM_OPTS% %JAVA_OPTS% %GRADLE_OPTS% "-Dorg.gradle.appname=%APP_BASE_NAME%" -classpath "%CLASSPATH%" -jar "%APP_HOME%\gradle\wrapper\gradle-wrapper.jar" %*
+
+:end
+@rem End local scope for the variables with windows NT shell
+if %ERRORLEVEL% equ 0 goto mainEnd
+
+:fail
+rem Set variable GRADLE_EXIT_CONSOLE if you need the _script_ return code instead of
+rem the _cmd.exe /c_ return code!
+set EXIT_CODE=%ERRORLEVEL%
+if %EXIT_CODE% equ 0 set EXIT_CODE=1
+if not ""=="%GRADLE_EXIT_CONSOLE%" exit %EXIT_CODE%
+exit /b %EXIT_CODE%
+
+:mainEnd
+if "%OS%"=="Windows_NT" endlocal
+
+:omega

android/settings.gradle

@@ -0,0 +1,5 @@
+include ':app'
+include ':capacitor-cordova-android-plugins'
+project(':capacitor-cordova-android-plugins').projectDir = new File('./capacitor-cordova-android-plugins/')
+
+apply from: 'capacitor.settings.gradle'

android/variables.gradle

@@ -0,0 +1,16 @@
+ext {
+    minSdkVersion = 24
+    compileSdkVersion = 36
+    targetSdkVersion = 36
+    androidxActivityVersion = '1.11.0'
+    androidxAppCompatVersion = '1.7.1'
+    androidxCoordinatorLayoutVersion = '1.3.0'
+    androidxCoreVersion = '1.17.0'
+    androidxFragmentVersion = '1.8.9'
+    coreSplashScreenVersion = '1.2.0'
+    androidxWebkitVersion = '1.14.0'
+    junitVersion = '4.13.2'
+    androidxJunitVersion = '1.3.0'
+    androidxEspressoCoreVersion = '3.7.0'
+    cordovaAndroidVersion = '14.0.1'
+}

apps/.eslintrc.cjs

@@ -0,0 +1,60 @@
+// Per-package ESLint config for the Preact widget apps under `apps/`.
+//
+// `root: true` stops ESLint from walking up to the host's
+// `cinny/.eslintrc.cjs`, which extends airbnb + the React plugin. Those
+// rule sets are tuned for the React host and flag legitimate Preact /
+// small-widget patterns as errors (`class=` attributes, arrow-fn
+// components, inline icon sub-components, for-of loops, etc.). Keeping
+// the hierarchy open would force every widget file to fight host style
+// for no real win.
+//
+// Widgets keep a minimal but real lint pass via the rule sets below:
+//
+//   * `eslint:recommended` — catches genuine bugs (no-undef, no-dupe-*,
+//     no-redeclare, no-unused-vars, …) without enforcing style.
+//   * `@typescript-eslint/recommended` — TS-aware variants of the above
+//     plus type-level checks the recommended set ships.
+//
+// We deliberately DON'T extend `plugin:react/recommended` —
+// `react/react-in-jsx-scope` and `react/no-unknown-property` both flag
+// Preact-correct code as errors, and disabling them one by one creates
+// a long suppression list. Widget JSX is type-checked by each app's
+// `tsc --noEmit` (run by `vite build`), which is the better signal for
+// JSX correctness anyway.
+module.exports = {
+  root: true,
+  // `node` covers `module.exports` in this very file (CommonJS config);
+  // `browser` is the runtime widget code itself sees.
+  env: { browser: true, es2021: true, node: true },
+  extends: [
+    'eslint:recommended',
+    'plugin:@typescript-eslint/recommended',
+    // preact/hooks has the same dep-array semantics as react/hooks, and
+    // the widget code already carries `// eslint-disable-next-line
+    // react-hooks/exhaustive-deps` directives at the relevant sites;
+    // loading the plugin (a) keeps those directives meaningful (without
+    // it ESLint errors on the «unknown rule» referenced by the comment)
+    // and (b) catches the real exhaustive-deps mistakes in widget hooks
+    // for free.
+    'plugin:react-hooks/recommended',
+  ],
+  parser: '@typescript-eslint/parser',
+  parserOptions: {
+    ecmaVersion: 'latest',
+    sourceType: 'module',
+    ecmaFeatures: { jsx: true },
+  },
+  plugins: ['@typescript-eslint', 'react-hooks'],
+  rules: {
+    // Underscore-prefixed args are intentionally unused (Preact event
+    // handlers receive args the body doesn't need); match the host's
+    // convention so lint reads consistently across both trees.
+    '@typescript-eslint/no-unused-vars': ['error', { argsIgnorePattern: '^_' }],
+    // Widget bridge-protocol regexes occasionally escape `-` inside
+    // character classes for visual clarity (e.g. `[0-9\-]`). The escape
+    // is harmless and pre-existing across all three widgets — keeping
+    // the rule on would force a churn-y diff in code that's been stable
+    // since the v0.7.6 bridge dialect work.
+    'no-useless-escape': 'off',
+  },
+};

apps/widget-discord/.gitignore

@@ -0,0 +1,3 @@
+node_modules
+dist
+*.log

apps/widget-discord/README.md

@@ -0,0 +1,193 @@
+# @vojo/widget-discord
+
+Vojo Discord bridge management widget — mounts inside `/bots/discord`
+in the Vojo client. Mirrors the Telegram widget contract; protocol
+specifics differ because mautrix-discord runs on the **legacy** mautrix
+command framework, not bridgev2 (the Discord bridge had not yet been
+ported to v2 as of January 2026 — see
+https://mau.fi/blog/2026-01-mautrix-release/).
+
+This is **not** a Discord client. It's a small panel that drives the
+mautrix-discord bridge bot (`@discordbot:vojo.chat`) by sending text
+commands in the control DM and rendering the bot's text replies. It
+ships QR-only login (the Discord token-login flow stays accessible via
+chat-fallback for power users).
+
+## Layout
+
+```
+src/
+├── bootstrap.ts                  Parse URL params (matches BotWidgetEmbed.ts)
+├── widget-api.ts                 Inline matrix-widget-api postMessage transport
+├── App.tsx                       UI: status pill, QR panel, logout / reconnect cards, transcript
+├── main.tsx                      Entry: bootstrap + render
+├── state.ts                      LoginState reducer + hydrate-from-timeline
+├── styles.css                    Theme-aware CSS variables (Dawn palette)
+├── i18n/                         Tiny RU/EN dictionary harness
+└── bridge-protocol/
+    ├── types.ts                  LoginEvent + ParsableEvent types
+    ├── parser.ts                 Dialect dispatch shim
+    └── dialects/
+        └── legacy_v076.ts        mautrix-discord v0.7.6 wording
+```
+
+## Login flow (QR only)
+
+1. Widget sends `!discord login-qr`.
+2. Bridge replies with an `m.image` event whose `body` is a Discord
+   remoteauth URL (`https://discord.com/ra/<token>`). The host driver
+   strips `url`/`file`/`info` so the widget never touches the uploaded
+   PNG bytes — it re-encodes the URL into an SVG QR matrix client-side
+   via `qrcode-generator`.
+3. The user scans the QR with the **Discord mobile app** (Settings →
+   Devices → Scan QR Code). Discord's remoteauth gateway requires the
+   mobile app — desktop Discord and the browser cannot scan.
+4. Bridge redacts the `m.image` event after a successful scan and sends
+   `Successfully logged in as @<username>`.
+5. Widget fires `!discord ping` to pick up the discord snowflake for
+   the connected pill.
+
+If Discord asks for a CAPTCHA, the bridge replies with the standard
+error line plus a hint about token-login. The widget surfaces an amber
+warning suggesting the user retry later or use chat-fallback.
+
+## Status probe
+
+Discord's legacy command system has no `list-logins` API; status is
+queried via `!discord ping`. The four reply variants map to four UI
+states:
+
+- `You're not logged in` → disconnected
+- `You're logged in as @x (\`<id>\`)` → connected
+- `You have a Discord token stored, but are not connected for some reason 🤔` → connected_dead (token_stored)
+- `You're logged in, but the Discord connection seems to be dead 💥` → connected_dead (connection_dead)
+
+`connected_dead` exposes a «Переподключиться» card that sends
+`!discord reconnect`. `disconnect` is recognised for chat-fallback
+typists but never sent by the widget.
+
+## Local development
+
+Same overlay mechanism as the Telegram widget — create
+`config.local.json` at the project root (gitignored) with a `bots[]`
+entry overriding the discord widget's `experience.url` to your local
+dev server:
+
+```bash
+# one-time: install widget deps
+cd apps/widget-discord && npm install
+
+# config.local.json (gitignored) at the project root
+cat > /home/ubuntu/projects/vojo/cinny/config.local.json <<'JSON'
+{
+  "bots": [
+    {
+      "id": "discord",
+      "experience": {
+        "type": "matrix-widget",
+        "url": "http://localhost:8082/",
+        "commandPrefix": "!discord"
+      }
+    }
+  ]
+}
+JSON
+```
+
+`http://localhost:*` URLs pass the host's URL validator only in dev
+builds — see `src/app/features/bots/catalog.ts` `import.meta.env.DEV`
+branch. Production builds drop the branch via Vite's dead-code
+elimination AND enforce an origin allowlist (`PROD_WIDGET_ORIGINS`).
+
+Run both servers:
+
+```bash
+# terminal 1 — widget on :8082 with HMR
+cd apps/widget-discord && npm run dev
+
+# terminal 2 — host SPA on :8080
+cd /home/ubuntu/projects/vojo/cinny && npm start
+```
+
+Open `http://localhost:8080/bots/discord`. The Telegram widget on :8081
+can run in parallel with no port conflict.
+
+## Build
+
+```bash
+npm run build
+```
+
+Outputs to `apps/widget-discord/dist/`. Deploy by rsyncing `dist/*` into
+`~/vojo/widgets/discord/` on the production host (Caddy serves this via
+the `widgets.vojo.chat` block).
+
+## Hosting (server-side, runbook)
+
+Pre-requisite: `widgets.vojo.chat` already exists for the Telegram
+widget — only the Caddy `widgets.vojo.chat` block needs a new
+`handle_path` and the docker host needs a new directory.
+
+1. `~/vojo/caddy/Caddyfile` — append to the existing
+   `widgets.vojo.chat { … }` block, beside the Telegram `handle_path`:
+   ```
+   handle_path /discord/* {
+       root * /var/www/widgets/discord
+       try_files {path} /index.html
+       file_server
+   }
+   ```
+2. `mkdir -p ~/vojo/widgets/discord` (placeholder so the bind-mount has
+   something to serve), then `docker compose up -d caddy` (or `reload`).
+3. Verify directly:
+   `curl -I https://widgets.vojo.chat/discord/index.html` should
+   return 200 and the `Content-Security-Policy` header.
+
+## Adding the discord bridge to docker-compose
+
+```yaml
+discord-bridge:
+  image: dock.mau.dev/mautrix/discord:v0.7.6
+  restart: unless-stopped
+  volumes:
+    - ./mautrix-discord:/data
+```
+
+Then `~/vojo/synapse/homeserver.yaml` needs the discord registration
+file added to `app_service_config_files`:
+
+```yaml
+app_service_config_files:
+  - /data/telegram-registration.yaml
+  - /data/discord-registration.yaml
+```
+
+The bridge's `command_prefix` defaults to `!discord` — keep it that
+way so it matches the widget's `experience.commandPrefix`. If you
+override it in `mautrix-discord/config.yaml`, mirror the override in
+`/config.json`.
+
+## Capacitor (Android)
+
+`capacitor.config.ts` already allow-navigates `widgets.vojo.chat` for
+the Telegram widget; no further change needed.
+
+## Capability contract
+
+The widget requests EXACTLY this set (matches the host's
+`BotWidgetDriver.getBotWidgetCapabilities`):
+
+```
+org.matrix.msc2762.timeline:<roomId>
+org.matrix.msc2762.send.event:m.room.message#m.text
+org.matrix.msc2762.receive.event:m.room.message#m.text
+org.matrix.msc2762.receive.event:m.room.message#m.notice
+org.matrix.msc2762.receive.event:m.room.message#m.image
+org.matrix.msc2762.receive.event:m.room.redaction
+org.matrix.msc2762.receive.state_event:m.room.member
+```
+
+`m.image` is the QR carrier; `m.room.redaction` signals the bridge
+consumed the QR after a successful scan. The host sanitizer strips
+`url`/`file`/`info` from `m.image` content, so only the QR URL string
+inside `body` survives the boundary.

apps/widget-discord/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="ru">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />
+    <title>Discord bridge — Vojo</title>
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

apps/widget-discord/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@vojo/widget-discord",
+  "version": "0.0.1",
+  "private": true,
+  "description": "Vojo Discord bridge management widget — mounts inside /bots/discord",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc --noEmit && vite build",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "preact": "10.22.1",
+    "qrcode-generator": "1.4.4"
+  },
+  "devDependencies": {
+    "@preact/preset-vite": "2.9.0",
+    "typescript": "5.4.5",
+    "vite": "5.4.19"
+  }
+}

apps/widget-discord/src/bootstrap.ts

@@ -0,0 +1,69 @@
+// Parse the URL params the Phase 2 bot widget host appends when loading
+// experience.url. Source of truth on the host side:
+//   src/app/features/bots/BotWidgetEmbed.ts (getBotWidgetUrl).
+// Keep this in sync if the host adds params.
+//
+// Identical shape to apps/widget-telegram/src/bootstrap.ts on purpose —
+// the host emits the same param set for every bot. Differences between
+// telegram and discord live in the bridge protocol, not in bootstrap.
+
+export type WidgetBootstrap = {
+  widgetId: string;
+  parentUrl: string;
+  parentOrigin: string;
+  roomId: string;
+  userId: string;
+  botId: string;
+  botMxid: string;
+  /** Bridge command prefix (e.g. `!discord`). Always non-empty — the host
+   * validator (catalog.ts) defaults missing values to `!tg` and rejects
+   * malformed overrides, so the discord bot's /config.json entry MUST set
+   * `experience.commandPrefix: "!discord"` to override the default. The
+   * widget prepends `<commandPrefix> ` to every outbound command. */
+  commandPrefix: string;
+  theme: 'light' | 'dark';
+  clientLanguage: string;
+};
+
+export type BootstrapResult =
+  | { ok: true; bootstrap: WidgetBootstrap }
+  | { ok: false; missing: string[] };
+
+const REQUIRED = ['widgetId', 'parentUrl', 'roomId', 'userId', 'botMxid', 'commandPrefix'] as const;
+
+export const readBootstrap = (search: string): BootstrapResult => {
+  const params = new URLSearchParams(search);
+  const get = (k: string) => params.get(k) ?? '';
+
+  const missing = REQUIRED.filter((k) => !params.get(k));
+  if (missing.length > 0) return { ok: false, missing: [...missing] };
+
+  // Origin is what the widget validates against on incoming postMessage —
+  // see widget-api.ts. Falling back to '*' would defeat the security
+  // boundary, so a malformed parentUrl bails out as a missing-param error.
+  let parentOrigin: string;
+  try {
+    parentOrigin = new URL(get('parentUrl')).origin;
+  } catch {
+    return { ok: false, missing: ['parentUrl'] };
+  }
+
+  const themeRaw = get('theme');
+  const theme: 'light' | 'dark' = themeRaw === 'dark' ? 'dark' : 'light';
+
+  return {
+    ok: true,
+    bootstrap: {
+      widgetId: get('widgetId'),
+      parentUrl: get('parentUrl'),
+      parentOrigin,
+      roomId: get('roomId'),
+      userId: get('userId'),
+      botId: get('botId'),
+      botMxid: get('botMxid'),
+      commandPrefix: get('commandPrefix'),
+      theme,
+      clientLanguage: get('clientLanguage'),
+    },
+  };
+};