From 5a5cd14df58ad11c64559d5404261b706618cd6f Mon Sep 17 00:00:00 2001
From: Gigi <dergigi@pm.me>
Date: Fri, 17 Oct 2025 21:41:25 +0200
Subject: [PATCH] docs: add Amethyst-style bookmarks section to Amber.md

Documented kind:30001 bookmark format used by Amethyst:
- Public bookmarks in event tags
- Private bookmarks in encrypted content (NIP-04 or NIP-44)

Explained why explicit NIP-04 detection (?iv= check) is required:
- Helpers.hasHiddenContent() only detects NIP-44
- Without NIP-04 detection, private bookmarks never get decrypted

Added example event structure and implementation notes for both
display logic and decryption logic.
---
 Amber.md | 35 ++++++++++++++++++++++++++++++++++-
 1 file changed, 34 insertions(+), 1 deletion(-)

diff --git a/Amber.md b/Amber.md
index 57ac68e1..9154bf38 100644
--- a/Amber.md
+++ b/Amber.md
@@ -94,14 +94,47 @@ If DECRYPT entries still don’t appear:
   - Process sequentially (removed concurrent `mapWithConcurrency` hack).
 - **Result**: Bookmark decryption is near-instant, limited only by bunker response time and user approval speed.
 
+## Amethyst-style bookmarks (kind:30001)
+
+**Important**: Bookmark events (kind:30001) that have public `tags` and private `content` are **Amethyst-style bookmarks**.
+
+### Format:
+- **Public bookmarks**: Stored in event `tags` (e.g., `["e", "..."]`, `["a", "..."]`)
+- **Private bookmarks**: Stored in encrypted `content` field (NIP-04 or NIP-44)
+
+### Implementation details:
+- The encrypted `content` field contains a JSON array of private bookmark tags
+- `Helpers.hasHiddenContent()` from `applesauce-core` only detects **NIP-44** encrypted content
+- **NIP-04** encrypted content must be detected explicitly by checking for `?iv=` in the content string
+- Both detection methods are needed in:
+  1. **Display logic** (`Debug.tsx` - `hasEncryptedContent()`) - to show padlock emoji and decrypt button
+  2. **Decryption logic** (`bookmarkProcessing.ts`) - to schedule decrypt jobs
+
+### Example event structure:
+```json
+{
+  "kind": 30001,
+  "tags": [
+    ["d", "bookmark"],
+    ["e", "102a2fe..."],  // Public bookmark
+    ["e", "84ce035..."]   // Public bookmark
+  ],
+  "content": "lvOfl7Qb...?iv=5KzDXv09..."  // NIP-04 encrypted private bookmarks
+}
+```
+
+### Why this matters:
+This dual-storage format (public + private) is why we need explicit NIP-04 detection. Without it, `Helpers.hasHiddenContent()` returns `false` and the encrypted content is never decrypted, resulting in 0 private bookmarks despite having encrypted data.
+
 ## Current conclusion
 
 - Client is configured and publishing requests correctly; encryption proves end‑to‑end path is alive.
 - Non-blocking publish keeps operations fast (~1-2s for encrypt/decrypt).
 - **Account queue is GLOBALLY DISABLED** - this was the primary cause of hangs/timeouts.
-- Smart encryption detection and no artificial timeouts make operations instant.
+- Smart encryption detection (both NIP-04 and NIP-44) and no artificial timeouts make operations instant.
 - Sequential processing is cleaner and more predictable than concurrent hacks.
 - Relay queries now trust EOSE signals instead of arbitrary timeouts, completing in 1-2s instead of 6s.
 - The missing DECRYPT activity in Amber was partially due to requests never being sent (stuck in queue). With queue disabled globally, Amber receives all decrypt requests immediately.
+- **Amethyst-style bookmarks** require explicit NIP-04 detection (`?iv=` check) since `Helpers.hasHiddenContent()` only detects NIP-44.