git:20260924.123a73e to git:20260929.61b38e7

# AGENTS.md

Guidance for AI agents and contributors working on this repository.

## Project

gupt is a self-hosted, end-to-end encrypted messenger built with Vue 3 + Vite.

There is no backend — encryption, caching, and publishing all happen in the

browser, and messages are stored on user-chosen Nostr relays as encrypted

events. It ships as a PWA with a service worker, plus Flatpak packaging.

Core concepts:

- **Not a Nostr app** — Nostr relays are used as dumb transport only. We are

not bound to follow NIP specs; if our own implementation achieves something

better, prefer it (e.g. self-addressed encrypted stream tags, NIP-40-style

expirations tuned to our own lifetimes).

- **Identity** — a secp256k1 keypair derived from memory anchors (password,

PIN, dates, and other remembered values) via SHA-256 + Argon2id, or restored

from a pasted hex key / Gupt backup / secret. The private key never leaves

the browser (`src/lib/secureKey.js`).

- **Messaging** — encrypted DMs, group chats, and peer-to-peer WebRTC

calls (`src/lib/webrtc/`), with NIP-40 expirations and read receipts.

- **Streams** — self-addressed encrypted Kind-1 items (bookmarks,

passwords, notes) stored under a `gupt_*` tag; ciphertext sits in a tag

so relay metadata stays public while content stays private.

- **Cache** — an IndexedDB database (`src/lib/idb.js`) with TTL rows, read

cache-first and refreshed from relays, backed by a background replication

worker.

## Repository layout

```

src/

lib/ domain logic (crypto, idb, relay, sendQueue, stream libs, webrtc)

views/ route-level pages

config/ static config (servers, retention)

router/ vue-router routes

sw.js PWA service worker entry

bin/ static server for dist/

flatpak/ Flatpak manifests

```

Module imports use the `@/` alias → `./src/` (see `jsconfig.json`).

## Commands

```sh

npm run dev # format src/ with oxfmt, then start Vite dev server

npm run build # vite build (+ PWA service worker)

npm run build:flatpak

npm start # node bin/gupt.js (static server for dist/)

```

Formatting is enforced via `oxfmt` — run `npx oxfmt <file>` (or the whole

`src/`) before committing. There is no separate linter. Note: `npm run dev`

reformats `src/` automatically on startup. `dist/` is gitignored; build

artifacts are never committed.

## Code style

- JavaScript, ES modules (`type: "module"`), no semicolons.

- No comments unless they carry real context (JSDoc for exported helpers is OK).

- Follow the pattern of neighboring files: domain logic in `src/lib`, state in

`src/stores` (Pinia), UI in `src/views` + `src/components`, relay code under

`src/lib/relay/`.

- UI is Tailwind CSS v4 utility classes driven by CSS variables like

`--app-text`, `--app-primary`, `--app-border` (defined in `src/index.css`);

icons come from `@lucide/vue`.

## UI and layout guidelines

To keep the application uniform across all pages and viewports:

- **Large screens (>= 1024px / desktop)**:

- All route-level views (`src/views/`) and primary navigation (`AppNavbar`)

must be constrained to `max-w-6xl` (`72rem` / `1152px`) and horizontally

centered with `mx-auto`.

- Stream/item list views (Bookmarks, Notes, Passwords) use a single-column card list layout

inside `mx-auto w-full max-w-6xl px-4 py-6 sm:px-6 lg:px-8`, with dedicated

subroutes for creating or editing items (`/bookmarks/new`, `/bookmarks/:id`,

`/notes/new`, `/notes/:id`, `/passwords/new`, `/passwords/:id`).

- Chat uses a uniform single-column route flow inside `mx-auto max-w-6xl w-full h-full`:

`/chat` shows the conversation inbox, and `/chat/:conversationId` shows the active conversation (with navigation back to the inbox via the navbar).

- Standalone/form/dashboard views use `mx-auto w-full max-w-6xl px-4 py-6 sm:px-6 lg:px-8`

as their outer page container. Form/card columns within the page should center

appropriately (e.g. `mx-auto max-w-2xl space-y-5`).

- **Mobile screens (< 1024px / < 640px)**:

- Layouts must be mobile-optimized: full-width (`w-full`), single-column or

single active panel views (switching between list and conversation/editor)

instead of cramped side-by-side panes.

- Safe mobile viewport sizing: use `min-h-dvh` or `h-dvh`, prevent horizontal

overflow (`overflow-x-hidden`), and avoid double vertical scrollbars.

- Touch-friendly targets: buttons and interactive controls should have

comfortable tap areas (minimum `h-10 w-10` / `h-11 w-11` for icon buttons,

`rounded-xl` or `rounded-2xl`).

- Mobile padding: standard header padding `px-4 py-3 sm:px-6` and body padding

`px-4 py-6 sm:px-6 lg:px-8`.

- **Design tokens**:

- Use semantic CSS variables (`--app-bg`, `--app-surface`, `--app-surface-soft`,

`--app-surface-hover`, `--app-border`, `--app-text`, `--app-text-soft`,

`--app-muted`, `--app-primary`, `--nav-bg`) and `@lucide/vue` icons.

## Dexie cache (IndexedDB)

All local persistence goes through one Dexie database, `src/lib/idb.js`:

- Tables: `mediaCache`, `roomMeta`, `groups`, `profiles`, `syncCursors`,

`messageSearch`, `sendTimings`, `relayStats`, `peerRelayHints`, `rawEvents`.

- Streams read cache-first, then refresh from relays: the views load with

`getBookmarksCached`/`fetchBookmarks`, `getNotesCached`/`fetchNotes`, and

`getPasswordsCached`/`fetchPasswords` (see the stream libs under `src/lib/`).

## Send queue

All relay writes go through the in-memory send queue (`src/lib/sendQueue.js`)

so a transient relay failure retries instead of dropping the write:

- `enqueueSend({ id, fn, onFailed, onSuccess, meta })` appends a task to a

lane (keyed by `meta.conversationId`, so writes to one conversation are

serialized), dedupes by `id`, bumps `pendingCount`, and drains. Returns

`true` when accepted.

- Retry policy: exponential backoff from 1s up to 3min, `MAX_ATTEMPTS = 8`,

with a 1200ms global throttle between sends. On permanent failure the task

is dropped and `onFailed` fires.

- `pendingCount` drives the navbar badge (`/queue` links when > 1 pending).

- A `window.online` listener flushes queued lanes when connectivity returns.

- Stream items (bookmarks, passwords, notes) publish via

`enqueuePublish({ id, kind, result, fn })` — it accepts the task, returns

`result` optimistically, and the write retries in the background. Chat

messages/receipts use `enqueueSend` directly.

- Tasks live in memory only — they are not persisted across page reloads.

## Working in this repo

1. Read the neighboring files first — new code should mirror the existing

patterns (helpers, naming, error handling).

2. After each edit, bump the npm version with a patch release:

`npm version patch` (the build stamps `__APP_VERSION__`/`__APP_BUILD_TIME__`).

3. After changes, run `npm run build` to confirm nothing broke.

4. Run `npx oxfmt <changed files>` so formatting matches.

5. Commit with a Conventional Commit message (see below); scope prefixes are

used but short (e.g. `fix:`, `feat:`, `refactor:`, `style:`, `chore:`,

`docs:`).

## Commits

Conventional Commits, lowercase subject, short scope:

```

feat: add encrypted Markdown notes stream

fix: route stream publishes through send queue

refactor: share hybrid stream renewal across streams

style: keep bookmark row actions always visible

chore: bump version to 3.0.0

```

## Testing

There is no test suite in this repo (`test/` was removed as bloat).

Verify changes with `npm run build` and manual exercise in `npm run dev`.