aljaz/boris
1
1
Fork 0
mirror of https://github.com/dergigi/boris.git synced 2026-02-23 07:54:59 +01:00
Code Issues Packages Projects Releases Wiki Activity

docs: rewrite README to be user-focused and non-technical

Browse Source
This commit is contained in:
Gigi
2025-10-05 21:56:35 +01:00
parent f2422e9601
commit 7735508c77
1 changed files with 38 additions and 168 deletions
Download Patch File Download Diff File Expand all files Collapse all files

206
README.md
View File

@@ -1,187 +1,57 @@
# Boris
A minimal nostr client for bookmark management, built with [applesauce](https://github.com/hzrd149/applesauce).
Your reading list for the Nostr world.
## Features
Boris turns your Nostr bookmarks into a calm, fast, and focused reading experience. Connect your Nostr account and you’ll get a clean three‑pane reader: bookmarks on the left, the article in the middle, and highlights on the right.
- **Nostr Authentication**: Connect using your nostr account via browser extension
- **Bookmark Display**: View your nostr bookmarks as per [NIP-51](https://github.com/nostr-protocol/nips/blob/master/51.md)
- **Content Classification**: Automatically detect and classify URLs (articles, videos, YouTube, images)
- **Reader Mode**: View article content inline with readable formatting
- **Collapsible Sidebar**: Expand/collapse bookmark list for focused reading
- **Profile Integration**: Display user profile images using applesauce ProfileModel
- **Relative Timestamps**: Human-friendly time display (e.g., "2 hours ago")
- **Event Links**: Quick access to view bookmarks on search.dergigi.com
- **Private Bookmarks**: Support for Amethyst-style hidden/encrypted bookmarks
- **Highlights Panel**: View and manage your NIP-84 highlights in a dedicated collapsible panel
- **Three-Pane Layout**: Bookmarks sidebar, content viewer, and highlights panel working together
- **Minimal UI**: Clean, modern interface focused on bookmark management
## What Boris does
## Getting Started
- Collects your saved links from Nostr and shows them as a tidy reading list
- Opens articles in a distraction‑free reader with clear typography
- Shows community highlights layered on the article (yours, friends, everyone)
- Lets you collapse sidebars anytime for full‑focus reading
- Remembers simple preferences like view mode, fonts, and highlight style
### Prerequisites
## How it works
- Node.js 18+
- npm, pnpm, or yarn
1. Connect your Nostr account.
- Click “Connect” and approve with your usual Nostr signer.
2. Browse your bookmarks.
- Your lists and items appear on the left. Pick anything to read.
3. Read in comfort.
- The center panel renders a readable article view with images and headings.
4. See what people highlighted.
- The right panel shows highlights by level:
- Mine (your highlights)
- Friends (people you follow)
- Nostrverse (everyone else)
- Each level has its own color. Click any highlight to jump to that spot.
5. Focus when you want.
- Collapse one or both side panels. The layout adapts without wasting space.
### Installation
## Why people like Boris
1. Clone the repository:
```bash
git clone <your-repo-url>
cd boris
```
- No noise: Just your saved links and the best excerpts others found
- Fast by default: Opens instantly in your browser
- Portable: Works with any Nostr account; your data travels with you
- Designed for reading: Smooth navigation and instant scroll‑to‑highlight
2. Install dependencies:
```bash
npm install
# or
pnpm install
# or
yarn install
```
## Tips
3. Start the development server:
```bash
npm run dev
# or
pnpm dev
# or
yarn dev
```
- Hover icons and counters to see what they do — most controls are discoverable.
- Lots of highlights? Scan the right panel and click to jump between them.
- Open Settings to switch fonts, tweak highlight styles, and change the list view.
4. Open your browser and navigate to `http://localhost:3000`
## Privacy and data
## Usage
- Boris doesn’t ask for an email or create a new account — it connects to your existing Nostr identity.
- Your bookmarks and highlights live on Nostr. Boris reads from the network and renders everything locally in your browser.
1. **Connect**: Click "Connect with Nostr" to authenticate using your nostr account
2. **View Bookmarks**: Once connected, you'll see all your nostr bookmarks in the left sidebar
3. **View Highlights**: Your NIP-84 highlights appear in the right panel
4. **Navigate**: Click on bookmark URLs to view content in the center panel
5. **Collapse Panels**: Use the collapse buttons to hide/show sidebars for focused viewing
## Troubleshooting
## Technical Details
- Built with React and TypeScript
- Uses [applesauce-core](https://github.com/hzrd149/applesauce) for nostr functionality
- Implements [NIP-51](https://github.com/nostr-protocol/nips/blob/master/51.md) for bookmark management
- Supports both individual bookmarks and bookmark lists
## Development
### Project Structure
```
src/
├── components/
│ ├── Login.tsx # Authentication component
│ ├── Bookmarks.tsx # Main bookmarks view with layout
│ ├── BookmarkList.tsx # Bookmark list sidebar
│ ├── BookmarkItem.tsx # Individual bookmark card
│ ├── SidebarHeader.tsx # Header bar with collapse, profile, logout
│ ├── ContentPanel.tsx # Content viewer panel
│ ├── HighlightsPanel.tsx # Highlights sidebar panel (NIP-84)
│ ├── HighlightItem.tsx # Individual highlight display
│ ├── IconButton.tsx # Reusable icon button component
│ ├── ContentWithResolvedProfiles.tsx # Profile mention resolver
│ ├── ResolvedMention.tsx # Nostr mention component
│ └── kindIcon.ts # Kind-specific icon mapping
├── services/
│ ├── bookmarkService.ts # Main bookmark fetching orchestration
│ ├── bookmarkProcessing.ts # Decryption and processing pipeline
│ ├── bookmarkHelpers.ts # Shared types, guards, and utilities
│ ├── bookmarkEvents.ts # Event type handling and deduplication
│ ├── highlightService.ts # Highlight fetching (NIP-84)
│ └── readerService.ts # Content extraction via reader API
├── types/
│ ├── bookmarks.ts # Bookmark type definitions
│ ├── highlights.ts # Highlight type definitions (NIP-84)
│ ├── nostr.d.ts # Nostr type augmentations
│ └── relative-time.d.ts # relative-time package types
├── utils/
│ ├── bookmarkUtils.tsx # Bookmark rendering utilities
│ └── helpers.ts # General helper functions
├── App.tsx # Main application component
├── main.tsx # Application entry point
└── index.css # Global styles
```
### Private (hidden) bookmarks (Amethyst-style)
We support Amethyst-style private (hidden) bookmark lists alongside public ones (NIP‑51):
- **Detection and unlock**
- Use `Helpers.hasHiddenTags(evt)` and `Helpers.isHiddenTagsLocked(evt)` to detect hidden tags.
- First try `Helpers.unlockHiddenTags(evt, signer)`; if that fails, try with `'nip44'`.
- For events with encrypted `content` that aren’t recognized as supporting hidden tags (e.g. kind 30001), manually decrypt:
- Prefer `signer.nip44.decrypt(evt.pubkey, evt.content)`, fallback to `signer.nip04.decrypt(evt.pubkey, evt.content)`.
- **Parsing and rendering**
- Decrypted `content` is JSON `string[][]` (tags). Convert with `Helpers.parseBookmarkTags(hiddenTags)`.
- Map to `IndividualBookmark[]` via our `processApplesauceBookmarks(..., isPrivate=true)` and append to the private list so they render immediately alongside public items.
- **Caching for downstream helpers**
- Cache manual results on the event with `BookmarkHiddenSymbol` and also store the decrypted blob under `EncryptedContentSymbol` to aid debugging and hydration.
- **Structure**
- `src/services/bookmarkService.ts`: orchestrates fetching, hydration, and assembling the final bookmark payload.
- `src/services/bookmarkProcessing.ts`: decryption/collection pipeline (unlock, manual decrypt, parse, merge).
- `src/services/bookmarkHelpers.ts`: shared types, guards, mapping, hydration, and symbols.
- `src/services/bookmarkEvents.ts`: event type and de‑duplication for NIP‑51 lists/sets.
- **Notes**
- We avoid `any` via narrow type guards for `nip44`/`nip04` decrypt functions.
- Files are kept small and DRY per project rules.
- Built on applesauce helpers (`Helpers.getPublicBookmarks`, `Helpers.getHiddenBookmarks`, etc.). See applesauce docs: https://hzrd149.github.io/applesauce/typedoc/modules.html
### Building for Production
```bash
npm run build
# or
pnpm build
# or
yarn build
```
## TODO
### High Priority
- [ ] **Mobile Responsive Design**: Optimize sidebar and content panel for mobile devices
- [ ] **Keyboard Shortcuts**: Add keyboard navigation (collapse sidebar, navigate bookmarks)
- [ ] **Search & Filter**: Add ability to search bookmarks by title, URL, or content
- [ ] **Error Handling**: Improve error states and retry logic for failed fetches
- [ ] **Loading States**: Better skeleton screens and loading indicators
### Medium Priority
- [ ] **Bookmark Creation**: Add ability to create new bookmarks
- [ ] **Bookmark Editing**: Edit existing bookmark metadata and tags
- [ ] **Bookmark Deletion**: Remove bookmarks from lists
- [ ] **Sorting Options**: Sort by date, title, kind, or custom order
- [ ] **Bulk Actions**: Select and perform actions on multiple bookmarks
- [ ] **Video Embeds**: Inline YouTube and video playback for video bookmarks
### Nice to Have
- [ ] **Dark/Light Mode Toggle**: User preference for color scheme
- [ ] **Export Functionality**: Export bookmarks as JSON, CSV, or HTML
- [ ] **Import Bookmarks**: Import from browser bookmarks or other formats
- [ ] **Tags & Categories**: Better organization with custom tags
- [ ] **Bookmark Collections**: Create and manage custom bookmark collections
- [ ] **Offline Support**: Cache bookmarks for offline viewing
- [ ] **Share Bookmarks**: Generate shareable links to bookmark lists
- [ ] **Performance Optimization**: Virtual scrolling for large bookmark lists
- [ ] **Browser Extension**: Quick bookmark saving from any page
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request. Make sure to:
- Follow the existing code style
- Keep files under 210 lines
- Use conventional commits
- Run linter and type checks before submitting
- If something looks empty, try opening another article and coming back — network data can arrive in bursts.
- Not every article has highlights yet; they grow as the community reads.
## License
MIT