-1733

ARCHITECTURE.md

reviewed

··· 1 1 - # Synthesis Architecture Documentation 2 2 - 3 3 - ## Table of Contents 4 4 - 1. [Overview](#overview) 5 5 - 2. [System Architecture](#system-architecture) 6 6 - 3. [Component Deep Dive](#component-deep-dive) 7 7 - 4. [Data Flow](#data-flow) 8 8 - 5. [Message Passing Protocol](#message-passing-protocol) 9 9 - 6. [Authentication System](#authentication-system) 10 10 - 7. [Annotation Lifecycle](#annotation-lifecycle) 11 11 - 8. [Highlight System](#highlight-system) 12 12 - 9. [Selector System](#selector-system) 13 13 - 10. [Comment/Reply System](#comment-reply-system) 14 14 - 11. [Landing Page](#landing-page) 15 15 - 12. [Storage Architecture](#storage-architecture) 16 16 - 13. [Known Issues](#known-issues) 17 17 - 18 18 - --- 19 19 - 20 20 - ## Overview 21 21 - 22 22 - **Synthesis** is a browser extension for creating web annotations using the AT Protocol (ATProto/Bluesky infrastructure). It's a Hypothesis clone that stores annotations as ATProto records on personal data servers (PDS). 23 23 - 24 24 - ### Tech Stack 25 25 - - **Framework**: WXT (Web Extension Framework) 26 26 - - **Language**: TypeScript 27 27 - - **Authentication**: AT Protocol OAuth (`@atcute/oauth-browser-client`) 28 28 - - **API Client**: `@atproto/api` 29 29 - - **Selector Libraries**: `dom-anchor-text-quote`, `dom-anchor-text-position` 30 30 - - **Build Tool**: Vite (via WXT) 31 31 - 32 32 - ### Project Structure 33 33 - ``` 34 34 - seams.so/ 35 35 - ├── entrypoints/ # Extension entry points 36 36 - │ ├── background.ts # Service worker (context menus, auth events) 37 37 - │ ├── content.ts # Content script (page interaction) 38 38 - │ └── sidepanel/ 39 39 - │ └── main.ts # Sidepanel UI (annotation management) 40 40 - ├── lib/ # Core libraries 41 41 - │ ├── oauth.ts # AT Protocol OAuth flow 42 42 - │ ├── pds.ts # PDS API integration (CRUD operations) 43 43 - │ ├── types/ # TypeScript type definitions 44 44 - │ │ ├── annotation.ts # Annotation data model 45 45 - │ │ └── comment.ts # Comment data model 46 46 - │ ├── selectors/ # Selector generation/matching 47 47 - │ │ ├── generate.ts # Create selectors from selections 48 48 - │ │ └── match.ts # Find DOM ranges from selectors 49 49 - │ └── highlights/ # Visual highlight rendering 50 50 - │ ├── apply.ts # Apply highlights to page 51 51 - │ └── popover.ts # Annotation edit popover 52 52 - ├── public/ # Landing page (static site) 53 53 - │ ├── landing.js # Feed viewer (slices.network integration) 54 54 - │ └── landing.css # Landing page styles 55 55 - └── lexicon/ # AT Protocol lexicon definitions 56 56 - ``` 57 57 - 58 58 - --- 59 59 - 60 60 - ## System Architecture 61 61 - 62 62 - ### High-Level Components 63 63 - 64 64 - ``` 65 65 - ┌─────────────────────────────────────────────────────────────┐ 66 66 - │ Web Page │ 67 67 - │ ┌────────────────────────────────────────────────────┐ │ 68 68 - │ │ Content Script (content.ts) │ │ 69 69 - │ │ - Track text selections │ │ 70 70 - │ │ - Generate selectors │ │ 71 71 - │ │ - Apply highlights to DOM │ │ 72 72 - │ │ - Show annotation popovers │ │ 73 73 - │ └─────┬────────────────────────────────────────▲─────┘ │ 74 74 - │ │ messages messages │ │ 75 75 - └────────┼────────────────────────────────────────┼──────────┘ 76 76 - │ │ 77 77 - ▼ │ 78 78 - ┌─────────────────────────────────────────────────┼──────────┐ 79 79 - │ Background Script (background.ts) │ │ 80 80 - │ - Context menu registration │ │ 81 81 - │ - Extension icon click handler │ │ 82 82 - │ - Auth state change broadcast │ │ 83 83 - │ - (Currently minimal state management) │ │ 84 84 - └────────┬────────────────────────────────────────┘ │ 85 85 - │ │ 86 86 - ▼ │ 87 87 - ┌───────────────────────────────────────────────────┐ │ 88 88 - │ Sidepanel (sidepanel/main.ts) │ │ 89 89 - │ - Login UI (AT Protocol OAuth) │────────┘ 90 90 - │ - Annotation form (create/edit) │ 91 91 - │ - Annotation list (with comments/replies) │ 92 92 - │ - Profile menu │ 93 93 - └────────┬──────────────────────────────────────────┘ 94 94 - │ XRPC calls 95 95 - ▼ 96 96 - ┌────────────────────────────────────────────────────────────┐ 97 97 - │ AT Protocol / Bluesky Infrastructure │ 98 98 - │ - Personal Data Server (PDS) │ 99 99 - │ - OAuth authorization │ 100 100 - │ - Record storage (annotations, comments) │ 101 101 - └────────────────────────────────────────────────────────────┘ 102 102 - │ 103 103 - ▼ 104 104 - ┌────────────────────────────────────────────────────────────┐ 105 105 - │ slices.network (GraphQL API) │ 106 106 - │ - Public annotation feed aggregation │ 107 107 - │ - Used by landing page (landing.js) │ 108 108 - └────────────────────────────────────────────────────────────┘ 109 109 - ``` 110 110 - 111 111 - ### Component Relationships 112 112 - 113 113 - ```mermaid 114 114 - graph TB 115 115 - User[User] 116 116 - WebPage[Web Page] 117 117 - Content[Content Script] 118 118 - Background[Background Script] 119 119 - Sidepanel[Sidepanel UI] 120 120 - OAuth[OAuth Module] 121 121 - PDS[PDS Module] 122 122 - Selectors[Selector System] 123 123 - Highlights[Highlight System] 124 124 - ATProto[AT Protocol PDS] 125 125 - SlicesNet[slices.network] 126 126 - Landing[Landing Page] 127 127 - 128 128 - User -->|selects text| WebPage 129 129 - WebPage -->|mouseup event| Content 130 130 - Content -->|generates| Selectors 131 131 - Content -->|sends SELECTION_CHANGED| Sidepanel 132 132 - Content -->|renders| Highlights 133 133 - 134 134 - User -->|clicks icon| Background 135 135 - Background -->|opens| Sidepanel 136 136 - Background -->|registers| ContextMenu[Context Menu] 137 137 - 138 138 - Sidepanel -->|requests GET_SELECTION| Content 139 139 - Sidepanel -->|uses| OAuth 140 140 - Sidepanel -->|uses| PDS 141 141 - 142 142 - OAuth -->|XRPC calls| ATProto 143 143 - PDS -->|XRPC calls| ATProto 144 144 - 145 145 - ATProto -->|indexed by| SlicesNet 146 146 - SlicesNet -->|GraphQL| Landing 147 147 - 148 148 - User -->|visits seams.so| Landing 149 149 - ``` 150 150 - 151 151 - --- 152 152 - 153 153 - ## Component Deep Dive 154 154 - 155 155 - ### 1. Background Script (`entrypoints/background.ts`) 156 156 - 157 157 - **Purpose**: Service Worker that handles extension-wide events and initialization. 158 158 - 159 159 - **Responsibilities**: 160 160 - - **Context Menu**: Registers "Annotate" option on text selection 161 161 - - **Icon Click**: Opens sidepanel when extension icon is clicked (Chrome only) 162 162 - - **Auth Broadcast**: Relays authentication state changes between components 163 163 - - **Logout Handler**: Clears OAuth session on logout 164 164 - 165 165 - **Key Functions**: 166 166 - ```typescript 167 167 - // Context menu creation (on install) 168 168 - browser.contextMenus.create({ 169 169 - id: 'annotate-selection', 170 170 - title: 'Annotate', 171 171 - contexts: ['selection'], 172 172 - }); 173 173 - 174 174 - // Context menu click → save annotation 175 175 - browser.contextMenus.onClicked.addListener((info, tab) => { 176 176 - if (info.menuItemId === 'annotate-selection') { 177 177 - browser.tabs.sendMessage(tab.id, { type: 'SAVE_ANNOTATION' }); 178 178 - } 179 179 - }); 180 180 - 181 181 - // Extension icon click → open sidepanel 182 182 - browser.action.onClicked.addListener((tab) => { 183 183 - if (browser.sidePanel) { 184 184 - browser.sidePanel.open({ tabId: tab.id }); 185 185 - } 186 186 - }); 187 187 - ``` 188 188 - 189 189 - **Current Limitations**: 190 190 - - No centralized state management (planned in refactor) 191 191 - - No URL change tracking 192 192 - - No per-tab state storage 193 193 - 194 194 - --- 195 195 - 196 196 - ### 2. Content Script (`entrypoints/content.ts`) 197 197 - 198 198 - **Purpose**: Runs on every web page to track selections and render highlights. 199 199 - 200 200 - **Lifecycle**: Injected at `document_idle` (after DOM loads) 201 201 - 202 202 - **State**: 203 203 - ```typescript 204 204 - let currentSelection: { 205 205 - text: string; 206 206 - selectors: Selector[]; 207 207 - } | null = null; 208 208 - 209 209 - let currentAnnotations: Annotation[] = []; 210 210 - ``` 211 211 - 212 212 - **Event Handlers**: 213 213 - 214 214 - #### Text Selection Tracking 215 215 - ```typescript 216 216 - document.addEventListener('mouseup', () => { 217 217 - const selection = window.getSelection(); 218 218 - if (selection && selection.toString().trim().length > 0) { 219 219 - const text = selection.toString().trim(); 220 220 - const root = document.querySelector('main') || 221 221 - document.querySelector('article') || 222 222 - document.body; 223 223 - const selectors = generateSelectors(selection, root); 224 224 - 225 225 - currentSelection = { text, selectors }; 226 226 - 227 227 - // Notify sidepanel 228 228 - browser.runtime.sendMessage({ 229 229 - type: 'SELECTION_CHANGED', 230 230 - data: { text, selectors } 231 231 - }); 232 232 - } else { 233 233 - currentSelection = null; 234 234 - } 235 235 - }); 236 236 - ``` 237 237 - 238 238 - **Why `mouseup`?** 239 239 - - `selectionchange` fires too frequently (on every character) 240 240 - - `mouseup` captures the final selection after user releases mouse 241 241 - - Combined with `keyup` for keyboard selections (not currently implemented) 242 242 - 243 243 - #### Message Handlers 244 244 - 245 245 - **GET_SELECTION** (from sidepanel): 246 246 - ```typescript 247 247 - // Sidepanel requests current state on load 248 248 - if (message.type === 'GET_SELECTION') { 249 249 - sendResponse({ 250 250 - selection: currentSelection, 251 251 - url: window.location.href, 252 252 - title: document.title 253 253 - }); 254 254 - return true; 255 255 - } 256 256 - ``` 257 257 - 258 258 - **UPDATE_HIGHLIGHTS** (from sidepanel): 259 259 - ```typescript 260 260 - // Sidepanel sends annotations after creating/loading 261 261 - if (message.type === 'UPDATE_HIGHLIGHTS') { 262 262 - currentAnnotations = message.annotations || []; 263 263 - applyHighlights(currentAnnotations); // Render yellow highlights 264 264 - sendResponse({ success: true }); 265 265 - return true; 266 266 - } 267 267 - ``` 268 268 - 269 269 - **CLEAR_HIGHLIGHTS**: 270 270 - ```typescript 271 271 - if (message.type === 'CLEAR_HIGHLIGHTS') { 272 272 - clearHighlights(); 273 273 - currentAnnotations = []; 274 274 - sendResponse({ success: true }); 275 275 - return true; 276 276 - } 277 277 - ``` 278 278 - 279 279 - **Known Issues**: 280 280 - - No debouncing on selection events (can spam messages) 281 281 - - Selection inside `<input>`, `<textarea>`, or `contenteditable` not filtered 282 282 - - No handling of SPA navigation (URL changes without page reload) 283 283 - - Race condition: sidepanel may request state before content script is ready 284 284 - 285 285 - --- 286 286 - 287 287 - ### 3. Sidepanel UI (`entrypoints/sidepanel/main.ts`) 288 288 - 289 289 - **Purpose**: Main user interface for authentication, creating annotations, and viewing annotations. 290 290 - 291 291 - **UI Sections**: 292 292 - 1. **Auth Section** (login form) 293 293 - 2. **Content Section** (annotation form + list) 294 294 - 3. **Profile Menu** (avatar dropdown with logout) 295 295 - 296 296 - #### State Management 297 297 - 298 298 - ```typescript 299 299 - let currentUrl = ''; // Current page URL 300 300 - let currentSelection: { text: string; selectors: any[] } | null = null; 301 301 - let allComments: Comment[] = []; // All comments for current page 302 302 - const collapsedThreads = new Set<string>(); // Collapsed comment threads 303 303 - const activeReplyForms = new Set<string>(); // Active reply forms 304 304 - ``` 305 305 - 306 306 - #### Initialization Flow 307 307 - 308 308 - ```typescript 309 309 - // 1. Check for existing OAuth session 310 310 - loadSession().then(async session => { 311 311 - if (session) { 312 312 - // Fetch profile and show logged-in UI 313 313 - const profile = await getProfile(session); 314 314 - profileAvatar.src = profile.avatar; 315 315 - authSection.style.display = 'none'; 316 316 - contentSection.style.display = 'block'; 317 317 - } 318 318 - }); 319 319 - 320 320 - // 2. Get current page state from content script 321 321 - browser.tabs.query({ active: true, currentWindow: true }).then(tabs => { 322 322 - if (tabs[0]?.id) { 323 323 - browser.tabs.sendMessage(tabs[0].id, { type: 'GET_SELECTION' }) 324 324 - .then(response => { 325 325 - currentUrl = response.url; 326 326 - currentSelection = response.selection; 327 327 - 328 328 - if (currentSelection) { 329 329 - // Show annotation form with selected text 330 330 - annotationForm.style.display = 'block'; 331 331 - } 332 332 - 333 333 - loadAnnotations(currentUrl); // Fetch annotations for this page 334 334 - }); 335 335 - } 336 336 - }); 337 337 - ``` 338 338 - 339 339 - **Race Condition**: `GET_SELECTION` may fail if content script hasn't loaded yet. 340 340 - 341 341 - #### Login Flow 342 342 - 343 343 - ```typescript 344 344 - loginBtn.addEventListener('click', async () => { 345 345 - let handle = handleInput.value.trim(); 346 346 - 347 347 - // Strip @ prefix if present 348 348 - if (handle.startsWith('@')) { 349 349 - handle = handle.slice(1); 350 350 - } 351 351 - 352 352 - // Start OAuth flow 353 353 - await startLoginProcess(handle); 354 354 - 355 355 - // Reload session and show logged-in UI 356 356 - const session = await loadSession(); 357 357 - if (session) { 358 358 - const profile = await getProfile(session); 359 359 - profileAvatar.src = profile.avatar; 360 360 - authSection.style.display = 'none'; 361 361 - contentSection.style.display = 'block'; 362 362 - } 363 363 - }); 364 364 - ``` 365 365 - 366 366 - #### Creating Annotations 367 367 - 368 368 - ```typescript 369 369 - saveBtn.addEventListener('click', async () => { 370 370 - if (!currentSelection) { 371 371 - alert('Please select text on the page first'); 372 372 - return; 373 373 - } 374 374 - 375 375 - const body = annotationTextarea.value.trim(); 376 376 - 377 377 - const annotation: Annotation = { 378 378 - $type: 'community.lexicon.annotation.annotation', 379 379 - target: [{ 380 380 - source: currentUrl, // BUG: Can be empty if race condition occurs 381 381 - selector: currentSelection.selectors 382 382 - }], 383 383 - body: body || undefined, 384 384 - createdAt: new Date().toISOString() 385 385 - }; 386 386 - 387 387 - // Save locally (legacy - for backward compatibility) 388 388 - await saveAnnotationLocal(annotation); 389 389 - 390 390 - // Save to PDS (AT Protocol) 391 391 - try { 392 392 - const savedAnnotation = await createAnnotation(annotation); 393 393 - console.log('Annotation saved to PDS:', savedAnnotation); 394 394 - } catch (error) { 395 395 - console.error('Failed to save to PDS:', error); 396 396 - } 397 397 - 398 398 - // Reload annotations and update highlights 399 399 - await loadAnnotations(currentUrl); 400 400 - }); 401 401 - ``` 402 402 - 403 403 - **Bug**: `currentUrl` can be empty string if `GET_SELECTION` fails, resulting in annotations with empty `source` field. 404 404 - 405 405 - #### Loading Annotations 406 406 - 407 407 - ```typescript 408 408 - async function loadAnnotations(url: string) { 409 409 - try { 410 410 - // Fetch from PDS 411 411 - const allAnnotations = await listAnnotations(); 412 412 - allComments = await listComments(); 413 413 - 414 414 - // Filter by current URL 415 415 - pageAnnotations = allAnnotations.filter(ann => 416 416 - ann.target[0]?.source === url 417 417 - ); 418 418 - 419 419 - renderAnnotations(); // Update UI 420 420 - 421 421 - // Send highlights to content script 422 422 - await updateHighlights(pageAnnotations); 423 423 - } catch (error) { 424 424 - console.error('Failed to load annotations from PDS:', error); 425 425 - } 426 426 - } 427 427 - ``` 428 428 - 429 429 - #### Comment System 430 430 - 431 431 - **Comment Structure**: 432 432 - ```typescript 433 433 - interface Comment { 434 434 - $type: 'pub.leaflet.comment'; 435 435 - subject: string; // URI of annotation being commented on 436 436 - plaintext: string; // Comment text 437 437 - createdAt: string; 438 438 - reply?: { 439 439 - parent: string; // URI of parent comment (for threaded replies) 440 440 - }; 441 441 - uri?: string; // AT Protocol record URI 442 442 - cid?: string; // Content ID 443 443 - } 444 444 - ``` 445 445 - 446 446 - **Comment Threading**: 447 447 - - Top-level comments: `subject` points to annotation URI, no `reply` field 448 448 - - Replies: `subject` still points to annotation URI, `reply.parent` points to parent comment URI 449 449 - 450 450 - **Rendering Logic**: 451 451 - ```typescript 452 452 - // Build threaded comment tree 453 453 - function buildCommentThread(parentUri: string, parentHasReplies: boolean): string { 454 454 - const replies = allComments.filter(c => c.reply?.parent === parentUri); 455 455 - 456 456 - if (collapsedThreads.has(parentUri)) { 457 457 - return `<button>▸ ${replies.length} hidden</button>`; 458 458 - } 459 459 - 460 460 - return ` 461 461 - <div class="comment-thread"> 462 462 - ${replies.map(comment => ` 463 463 - <div class="comment"> 464 464 - <div class="comment-text">${comment.plaintext}</div> 465 465 - <button class="reply-btn">Reply</button> 466 466 - ${hasReplies ? buildCommentThread(comment.uri!, true) : ''} 467 467 - </div> 468 468 - `).join('')} 469 469 - </div> 470 470 - `; 471 471 - } 472 472 - ``` 473 473 - 474 474 - **Reply Creation**: 475 475 - ```typescript 476 476 - // Save reply button handler 477 477 - document.querySelectorAll('.save-reply-btn').forEach(btn => { 478 478 - btn.addEventListener('click', async (e) => { 479 479 - const form = e.target.closest('.reply-form'); 480 480 - const textarea = form.querySelector('.reply-input'); 481 481 - const parent = form.getAttribute('data-parent'); // Parent comment URI 482 482 - const plaintext = textarea.value.trim(); 483 483 - 484 484 - // Find parent comment to get subject (annotation URI) 485 485 - const parentComment = allComments.find(c => c.uri === parent); 486 486 - 487 487 - await createComment({ 488 488 - $type: 'pub.leaflet.comment', 489 489 - subject: parentComment.subject, // Still points to annotation 490 490 - plaintext, 491 491 - createdAt: new Date().toISOString(), 492 492 - reply: { parent }, // Link to parent comment 493 493 - }); 494 494 - 495 495 - await loadAnnotations(currentUrl); // Refresh 496 496 - }); 497 497 - }); 498 498 - ``` 499 499 - 500 500 - --- 501 501 - 502 502 - ## Data Flow 503 503 - 504 504 - ### Annotation Creation Flow 505 505 - 506 506 - ``` 507 507 - 1. User selects text on page 508 508 - │ 509 509 - ▼ 510 510 - 2. Content Script (mouseup handler) 511 511 - - Extracts selection text 512 512 - - Generates selectors (TextQuote + TextPosition) 513 513 - - Stores in currentSelection 514 514 - │ 515 515 - ▼ 516 516 - 3. Content Script → Sidepanel 517 517 - - Sends: { type: 'SELECTION_CHANGED', data: { text, selectors } } 518 518 - │ 519 519 - ▼ 520 520 - 4. Sidepanel receives message 521 521 - - Updates currentSelection 522 522 - - Shows annotation form with quoted text 523 523 - │ 524 524 - ▼ 525 525 - 5. User writes note and clicks "Save" 526 526 - │ 527 527 - ▼ 528 528 - 6. Sidepanel (saveBtn handler) 529 529 - - Creates Annotation object with: 530 530 - * target[0].source = currentUrl 531 531 - * target[0].selector = currentSelection.selectors 532 532 - * body = note text 533 533 - │ 534 534 - ▼ 535 535 - 7. Sidepanel → PDS Module 536 536 - - Calls: createAnnotation(annotation) 537 537 - │ 538 538 - ▼ 539 539 - 8. PDS Module → AT Protocol 540 540 - - XRPC call: com.atproto.repo.createRecord 541 541 - - Collection: community.lexicon.annotation.annotation 542 542 - - Returns: { uri, cid } 543 543 - │ 544 544 - ▼ 545 545 - 9. Sidepanel reloads annotations 546 546 - - Calls: listAnnotations() from PDS 547 547 - - Filters by currentUrl 548 548 - │ 549 549 - ▼ 550 550 - 10. Sidepanel → Content Script 551 551 - - Sends: { type: 'UPDATE_HIGHLIGHTS', annotations } 552 552 - │ 553 553 - ▼ 554 554 - 11. Content Script applies highlights 555 555 - - For each annotation: 556 556 - * Find DOM range using selectors (match.ts) 557 557 - * Wrap in <span class="synthesis-highlight"> 558 558 - * Add click handler to show popover 559 559 - ``` 560 560 - 561 561 - ### Page Load Flow 562 562 - 563 563 - ``` 564 564 - 1. Extension loads on page 565 565 - │ 566 566 - ▼ 567 567 - 2. Content Script initializes 568 568 - - Sets up mouseup listener 569 569 - - Waits for selection events 570 570 - │ 571 571 - ▼ 572 572 - 3. User clicks extension icon 573 573 - │ 574 574 - ▼ 575 575 - 4. Background Script (action.onClicked) 576 576 - - Opens sidepanel: browser.sidePanel.open() 577 577 - │ 578 578 - ▼ 579 579 - 5. Sidepanel loads (main.ts IIFE) 580 580 - - Checks for OAuth session 581 581 - - If logged in: show content section 582 582 - - If not: show login form 583 583 - │ 584 584 - ▼ 585 585 - 6. Sidepanel → Content Script 586 586 - - Sends: { type: 'GET_SELECTION' } 587 587 - - Receives: { url, title, selection } 588 588 - │ 589 589 - ▼ 590 590 - 7. Sidepanel stores state 591 591 - - currentUrl = response.url 592 592 - - currentSelection = response.selection 593 593 - - If selection exists: show annotation form 594 594 - │ 595 595 - ▼ 596 596 - 8. Sidepanel loads annotations 597 597 - - Calls: listAnnotations() + listComments() 598 598 - - Filters by currentUrl 599 599 - - Renders annotation cards with comments 600 600 - │ 601 601 - ▼ 602 602 - 9. Sidepanel → Content Script 603 603 - - Sends: { type: 'UPDATE_HIGHLIGHTS', annotations } 604 604 - │ 605 605 - ▼ 606 606 - 10. Content Script renders highlights 607 607 - - Yellow highlighted text appears on page 608 608 - - Click highlight → show popover 609 609 - ``` 610 610 - 611 611 - --- 612 612 - 613 613 - ## Message Passing Protocol 614 614 - 615 615 - ### Current Messages (Fragile Architecture) 616 616 - 617 617 - #### Content Script → Sidepanel 618 618 - | Message Type | Direction | Payload | Purpose | 619 619 - |--------------|-----------|---------|---------| 620 620 - | `SELECTION_CHANGED` | Content → Sidepanel | `{ text, selectors }` | Notify sidepanel of new selection | 621 621 - 622 622 - **How it works**: `browser.runtime.sendMessage()` broadcasts to all extension contexts. Sidepanel has a listener that updates its state. 623 623 - 624 624 - #### Sidepanel → Content Script 625 625 - | Message Type | Direction | Payload | Purpose | 626 626 - |--------------|-----------|---------|---------| 627 627 - | `GET_SELECTION` | Sidepanel → Content | - | Request current page state | 628 628 - | `UPDATE_HIGHLIGHTS` | Sidepanel → Content | `{ annotations }` | Render highlights on page | 629 629 - | `CLEAR_HIGHLIGHTS` | Sidepanel → Content | - | Remove all highlights | 630 630 - 631 631 - **How it works**: `browser.tabs.sendMessage(tabId, message)` sends to specific tab's content script. 632 632 - 633 633 - **Response format for GET_SELECTION**: 634 634 - ```typescript 635 635 - { 636 636 - selection: { text: string; selectors: Selector[] } | null, 637 637 - url: string, 638 638 - title: string 639 639 - } 640 640 - ``` 641 641 - 642 642 - #### Background Script Messages 643 643 - | Message Type | Direction | Payload | Purpose | 644 644 - |--------------|-----------|---------|---------| 645 645 - | `AUTH_STATE_CHANGED` | Background → All | `{ isAuthenticated: boolean }` | Broadcast auth state | 646 646 - | `LOGOUT` | Any → Background | - | Request logout | 647 647 - 648 648 - --- 649 649 - 650 650 - ## Authentication System 651 651 - 652 652 - ### AT Protocol OAuth Flow 653 653 - 654 654 - **Library**: `@atcute/oauth-browser-client` 655 655 - 656 656 - **OAuth Configuration**: 657 657 - ```typescript 658 658 - // lib/oauth.ts 659 659 - configureOAuth({ 660 660 - metadata: { 661 661 - client_id: import.meta.env.VITE_OAUTH_CLIENT_ID, 662 662 - redirect_uri: import.meta.env.VITE_OAUTH_REDIRECT_URI, 663 663 - }, 664 664 - }); 665 665 - ``` 666 666 - 667 667 - **Redirect Strategy**: 668 668 - - AT Protocol OAuth expects a web redirect URL 669 669 - - Extension uses `https://synthes-is.netlify.app/oauth-callback.html` 670 670 - - Callback page relays to `chromiumapp://` URL for extension capture 671 671 - 672 672 - ### Login Process 673 673 - 674 674 - ``` 675 675 - 1. User enters handle (e.g., "user.bsky.social") 676 676 - │ 677 677 - ▼ 678 678 - 2. Sidepanel → OAuth Module 679 679 - - Calls: startLoginProcess(handle) 680 680 - │ 681 681 - ▼ 682 682 - 3. OAuth Module 683 683 - - Calls: resolveFromIdentity(handle) 684 684 - - Returns: PDS metadata (authorization server URL, etc.) 685 685 - │ 686 686 - ▼ 687 687 - 4. OAuth Module 688 688 - - Calls: createAuthorizationUrl({ metadata, scope }) 689 689 - - Returns: Authorization URL (e.g., https://bsky.social/oauth/authorize?...) 690 690 - │ 691 691 - ▼ 692 692 - 5. OAuth Module → Browser 693 693 - - Calls: browser.identity.launchWebAuthFlow({ url, interactive: true }) 694 694 - - Opens popup with authorization page 695 695 - │ 696 696 - ▼ 697 697 - 6. User authorizes in popup 698 698 - │ 699 699 - ▼ 700 700 - 7. PDS redirects to: https://synthes-is.netlify.app/oauth-callback.html?code=...&state=... 701 701 - │ 702 702 - ▼ 703 703 - 8. Callback page redirects to: chromiumapp://[extension-id]/extension-callback.html?code=... 704 704 - │ 705 705 - ▼ 706 706 - 9. browser.identity.launchWebAuthFlow captures redirect 707 707 - - Returns: capturedUrl 708 708 - │ 709 709 - ▼ 710 710 - 10. OAuth Module 711 711 - - Parses OAuth params from URL (code, state, etc.) 712 712 - - Calls: finalizeAuthorization(params) 713 713 - - Exchanges code for tokens 714 714 - - Returns: OAuthSession { info: { sub: "did:plc:..." }, ... } 715 715 - │ 716 716 - ▼ 717 717 - 11. OAuth Module 718 718 - - Saves session to: browser.storage.local['synthesis-oauth:session'] 719 719 - │ 720 720 - ▼ 721 721 - 12. Sidepanel 722 722 - - Fetches profile: getProfile(session) 723 723 - - Shows logged-in UI 724 724 - ``` 725 725 - 726 726 - ### Session Management 727 727 - 728 728 - **Storage Key**: `synthesis-oauth:session` 729 729 - 730 730 - **Session Structure**: 731 731 - ```typescript 732 732 - interface OAuthSession { 733 733 - info: { 734 734 - sub: string; // DID (e.g., "did:plc:abc123...") 735 735 - // ... other fields 736 736 - }; 737 737 - // ... tokens and metadata 738 738 - } 739 739 - ``` 740 740 - 741 741 - **Session Functions**: 742 742 - ```typescript 743 743 - // Save session after login 744 744 - async function saveSession(session: OAuthSession) { 745 745 - await browser.storage.local.set({ 746 746 - 'synthesis-oauth:session': session 747 747 - }); 748 748 - } 749 749 - 750 750 - // Load session on startup 751 751 - async function loadSession(): Promise<OAuthSession | null> { 752 752 - const result = await browser.storage.local.get('synthesis-oauth:session'); 753 753 - return result['synthesis-oauth:session'] || null; 754 754 - } 755 755 - 756 756 - // Clear session on logout 757 757 - async function clearSession() { 758 758 - await browser.storage.local.remove('synthesis-oauth:session'); 759 759 - } 760 760 - 761 761 - // Get user profile 762 762 - async function getProfile(session: OAuthSession) { 763 763 - const agent = new OAuthUserAgent(session); 764 764 - const response = await agent.handle( 765 765 - '/xrpc/app.bsky.actor.getProfile?actor=' + session.info.sub 766 766 - ); 767 767 - return await response.json(); 768 768 - } 769 769 - ``` 770 770 - 771 771 - --- 772 772 - 773 773 - ## Annotation Lifecycle 774 774 - 775 775 - ### Data Model 776 776 - 777 777 - **AT Protocol Record Type**: `community.lexicon.annotation.annotation` 778 778 - 779 779 - **TypeScript Interface**: 780 780 - ```typescript 781 781 - interface Annotation { 782 782 - $type: 'community.lexicon.annotation.annotation'; 783 783 - target: Target[]; // What is being annotated 784 784 - body?: string; // Annotation note/comment 785 785 - tags?: string[]; // Tags for categorization 786 786 - document?: { 787 787 - title?: string; 788 788 - canonicalUri?: string; 789 789 - }; 790 790 - createdAt: string; // ISO 8601 timestamp 791 791 - 792 792 - // ATProto metadata (added after creation) 793 793 - uri?: string; // at://did:plc:abc123/collection/rkey 794 794 - cid?: string; // Content ID (hash) 795 795 - author?: { 796 796 - did: string; 797 797 - handle: string; 798 798 - displayName?: string; 799 799 - avatar?: string; 800 800 - }; 801 801 - } 802 802 - 803 803 - interface Target { 804 804 - source: string; // Page URL 805 805 - selector?: Selector[]; // How to find the text 806 806 - } 807 807 - ``` 808 808 - 809 809 - ### Selector Types 810 810 - 811 811 - **TextQuoteSelector** (Most robust - survives content changes): 812 812 - ```typescript 813 813 - { 814 814 - $type: 'community.lexicon.annotation.annotation#textQuoteSelector', 815 815 - exact: "the selected text", 816 816 - prefix: "text before ", // Context before selection 817 817 - suffix: " text after" // Context after selection 818 818 - } 819 819 - ``` 820 820 - 821 821 - **TextPositionSelector** (Precise but fragile): 822 822 - ```typescript 823 823 - { 824 824 - $type: 'community.lexicon.annotation.annotation#textPositionSelector', 825 825 - start: 1234, // Character offset in document 826 826 - end: 1298 // Character offset in document 827 827 - } 828 828 - ``` 829 829 - 830 830 - **Strategy**: Generate both types. Try TextPositionSelector first (fast), fall back to TextQuoteSelector (slower but more robust). 831 831 - 832 832 - ### CRUD Operations 833 833 - 834 834 - All operations go through `lib/pds.ts` using `@atcute/oauth-browser-client`. 835 835 - 836 836 - #### Create Annotation 837 837 - ```typescript 838 838 - // lib/pds.ts 839 839 - async function createAnnotation(annotation: Annotation): Promise<Annotation> { 840 840 - const session = await loadSession(); 841 841 - const agent = new OAuthUserAgent(session); 842 842 - 843 843 - const response = await agent.handle('/xrpc/com.atproto.repo.createRecord', { 844 844 - method: 'POST', 845 845 - headers: { 'Content-Type': 'application/json' }, 846 846 - body: JSON.stringify({ 847 847 - repo: session.info.sub, // User's DID 848 848 - collection: 'community.lexicon.annotation.annotation', 849 849 - record: { 850 850 - $type: annotation.$type, 851 851 - target: annotation.target, 852 852 - body: annotation.body, 853 853 - tags: annotation.tags, 854 854 - document: annotation.document, 855 855 - createdAt: annotation.createdAt, 856 856 - }, 857 857 - }), 858 858 - }); 859 859 - 860 860 - const result = await response.json(); 861 861 - 862 862 - return { 863 863 - ...annotation, 864 864 - uri: result.uri, // at://did:plc:abc123/collection/rkey 865 865 - cid: result.cid, 866 866 - }; 867 867 - } 868 868 - ``` 869 869 - 870 870 - #### List Annotations 871 871 - ```typescript 872 872 - async function listAnnotations(): Promise<Annotation[]> { 873 873 - const session = await loadSession(); 874 874 - const agent = new OAuthUserAgent(session); 875 875 - 876 876 - const response = await agent.handle( 877 877 - `/xrpc/com.atproto.repo.listRecords?` + 878 878 - `repo=${session.info.sub}&` + 879 879 - `collection=community.lexicon.annotation.annotation`, 880 880 - { method: 'GET' } 881 881 - ); 882 882 - 883 883 - const result = await response.json(); 884 884 - 885 885 - return result.records.map((record: any) => ({ 886 886 - ...record.value, 887 887 - uri: record.uri, 888 888 - cid: record.cid, 889 889 - })); 890 890 - } 891 891 - ``` 892 892 - 893 893 - #### Delete Annotation 894 894 - ```typescript 895 895 - async function deleteAnnotation(uri: string): Promise<void> { 896 896 - const session = await loadSession(); 897 897 - const agent = new OAuthUserAgent(session); 898 898 - 899 899 - // Parse rkey from URI: at://did:plc:xxx/collection/rkey 900 900 - const rkey = uri.split("/").pop(); 901 901 - 902 902 - await agent.handle('/xrpc/com.atproto.repo.deleteRecord', { 903 903 - method: 'POST', 904 904 - headers: { 'Content-Type': 'application/json' }, 905 905 - body: JSON.stringify({ 906 906 - repo: session.info.sub, 907 907 - collection: 'community.lexicon.annotation.annotation', 908 908 - rkey, 909 909 - }), 910 910 - }); 911 911 - } 912 912 - ``` 913 913 - 914 914 - --- 915 915 - 916 916 - ## Highlight System 917 917 - 918 918 - ### Rendering Pipeline 919 919 - 920 920 - ``` 921 921 - Annotation → Selector Matching → DOM Range → Highlight Span 922 922 - ``` 923 923 - 924 924 - ### Step 1: Find DOM Range 925 925 - 926 926 - **File**: `lib/selectors/match.ts` 927 927 - 928 928 - ```typescript 929 929 - function findAnnotationRange( 930 930 - annotation: Annotation, 931 931 - container: HTMLElement = document.body 932 932 - ): Range | null { 933 933 - const selectors = annotation.target?.[0]?.selector; 934 934 - 935 935 - // Try each selector in order 936 936 - for (const selector of selectors) { 937 937 - let range: Range | null = null; 938 938 - 939 939 - switch (selector.$type) { 940 940 - case 'community.lexicon.annotation.annotation#textPositionSelector': 941 941 - range = matchTextPositionSelector(selector, container); 942 942 - break; 943 943 - case 'community.lexicon.annotation.annotation#textQuoteSelector': 944 944 - range = matchTextQuoteSelector(selector, container); 945 945 - break; 946 946 - } 947 947 - 948 948 - if (range) return range; 949 949 - } 950 950 - 951 951 - return null; 952 952 - } 953 953 - ``` 954 954 - 955 955 - **TextPositionSelector Matching**: 956 956 - ```typescript 957 957 - function matchTextPositionSelector( 958 958 - selector: TextPositionSelector, 959 959 - container: HTMLElement 960 960 - ): Range | null { 961 961 - try { 962 962 - // Uses dom-anchor-text-position library 963 963 - return textPosition.toRange(container, selector); 964 964 - } catch (e) { 965 965 - return null; 966 966 - } 967 967 - } 968 968 - ``` 969 969 - 970 970 - **TextQuoteSelector Matching**: 971 971 - ```typescript 972 972 - function matchTextQuoteSelector( 973 973 - selector: TextQuoteSelector, 974 974 - container: HTMLElement 975 975 - ): Range | null { 976 976 - try { 977 977 - // Uses dom-anchor-text-quote library 978 978 - return textQuote.toRange(container, selector); 979 979 - } catch (e) { 980 980 - return null; 981 981 - } 982 982 - } 983 983 - ``` 984 984 - 985 985 - ### Step 2: Apply Highlight 986 986 - 987 987 - **File**: `lib/highlights/apply.ts` 988 988 - 989 989 - ```typescript 990 990 - function highlightRange(range: Range, annotation: Annotation) { 991 991 - // Create highlight span 992 992 - const highlight = document.createElement('span'); 993 993 - highlight.className = 'synthesis-highlight'; 994 994 - highlight.dataset.annotationId = annotation.uri || annotation.createdAt; 995 995 - highlight.style.cssText = ` 996 996 - background-color: rgba(255, 235, 59, 0.6) !important; 997 997 - cursor: pointer !important; 998 998 - transition: background-color 0.2s !important; 999 999 - `; 1000 1000 - 1001 1001 - // Hover effect 1002 1002 - highlight.addEventListener('mouseenter', () => { 1003 1003 - highlight.style.backgroundColor = 'rgba(255, 235, 59, 0.8)'; 1004 1004 - }); 1005 1005 - 1006 1006 - highlight.addEventListener('mouseleave', () => { 1007 1007 - highlight.style.backgroundColor = 'rgba(255, 235, 59, 0.6)'; 1008 1008 - }); 1009 1009 - 1010 1010 - // Click to show popover 1011 1011 - highlight.addEventListener('click', (e) => { 1012 1012 - e.preventDefault(); 1013 1013 - e.stopPropagation(); 1014 1014 - showAnnotationPopover(annotation, highlight, onSave, onDelete); 1015 1015 - }); 1016 1016 - 1017 1017 - // Wrap the range content 1018 1018 - const contents = range.extractContents(); // Extract nodes from DOM 1019 1019 - highlight.appendChild(contents); // Put them in highlight span 1020 1020 - range.insertNode(highlight); // Insert span back into DOM 1021 1021 - } 1022 1022 - ``` 1023 1023 - 1024 1024 - **Why `extractContents` instead of `surroundContents`?** 1025 1025 - - `surroundContents` fails if the range spans multiple elements (e.g., `<p>some <strong>bold</strong> text</p>`) 1026 1026 - - `extractContents` + `appendChild` + `insertNode` works for all cases 1027 1027 - 1028 1028 - ### Step 3: Clear Highlights 1029 1029 - 1030 1030 - ```typescript 1031 1031 - function clearHighlights(container: HTMLElement = document.body) { 1032 1032 - const highlights = container.querySelectorAll('.synthesis-highlight'); 1033 1033 - 1034 1034 - highlights.forEach(highlight => { 1035 1035 - const parent = highlight.parentNode; 1036 1036 - if (parent) { 1037 1037 - // Move children back to parent (unwrap) 1038 1038 - while (highlight.firstChild) { 1039 1039 - parent.insertBefore(highlight.firstChild, highlight); 1040 1040 - } 1041 1041 - // Remove empty span 1042 1042 - parent.removeChild(highlight); 1043 1043 - // Merge adjacent text nodes 1044 1044 - parent.normalize(); 1045 1045 - } 1046 1046 - }); 1047 1047 - } 1048 1048 - ``` 1049 1049 - 1050 1050 - ### Annotation Popover 1051 1051 - 1052 1052 - **File**: `lib/highlights/popover.ts` 1053 1053 - 1054 1054 - **Purpose**: Show edit/delete UI when clicking a highlight. 1055 1055 - 1056 1056 - ```typescript 1057 1057 - function showAnnotationPopover( 1058 1058 - annotation: Annotation, 1059 1059 - targetElement: HTMLElement, 1060 1060 - onSave: (updatedAnnotation: Annotation) => void, 1061 1061 - onDelete: () => void 1062 1062 - ) { 1063 1063 - const popover = document.createElement('div'); 1064 1064 - popover.className = 'synthesis-popover'; 1065 1065 - 1066 1066 - // Position below the highlight 1067 1067 - const rect = targetElement.getBoundingClientRect(); 1068 1068 - popover.style.left = `${rect.left + window.scrollX}px`; 1069 1069 - popover.style.top = `${rect.bottom + window.scrollY + 5}px`; 1070 1070 - 1071 1071 - // Show quoted text + editable note 1072 1072 - const quote = annotation.target[0]?.selector?.find( 1073 1073 - s => s.$type === 'community.lexicon.annotation.annotation#textQuoteSelector' 1074 1074 - ); 1075 1075 - 1076 1076 - popover.innerHTML = ` 1077 1077 - <div class="quote">${quote?.exact || ''}</div> 1078 1078 - <textarea class="note-input">${annotation.body || ''}</textarea> 1079 1079 - <button class="save-btn">Save</button> 1080 1080 - <button class="delete-btn">Delete</button> 1081 1081 - `; 1082 1082 - 1083 1083 - document.body.appendChild(popover); 1084 1084 - 1085 1085 - // Save handler 1086 1086 - saveBtn.addEventListener('click', () => { 1087 1087 - const updatedAnnotation = { 1088 1088 - ...annotation, 1089 1089 - body: textarea.value.trim() || undefined, 1090 1090 - }; 1091 1091 - onSave(updatedAnnotation); 1092 1092 - hidePopover(); 1093 1093 - }); 1094 1094 - 1095 1095 - // Delete handler 1096 1096 - deleteBtn.addEventListener('click', () => { 1097 1097 - if (confirm('Delete this annotation?')) { 1098 1098 - onDelete(); 1099 1099 - hidePopover(); 1100 1100 - } 1101 1101 - }); 1102 1102 - } 1103 1103 - ``` 1104 1104 - 1105 1105 - **Update Flow (from popover)**: 1106 1106 - ```typescript 1107 1107 - // In lib/highlights/apply.ts 1108 1108 - showAnnotationPopover( 1109 1109 - annotation, 1110 1110 - highlight, 1111 1111 - // onSave callback 1112 1112 - async (updatedAnnotation) => { 1113 1113 - // Update in local storage (legacy) 1114 1114 - const stored = await browser.storage.local.get('annotations'); 1115 1115 - const annotations = stored.annotations || []; 1116 1116 - const index = annotations.findIndex(a => a.createdAt === annotation.createdAt); 1117 1117 - if (index !== -1) { 1118 1118 - annotations[index] = updatedAnnotation; 1119 1119 - await browser.storage.local.set({ annotations }); 1120 1120 - } 1121 1121 - 1122 1122 - // Update in-memory object (so next click shows updated note) 1123 1123 - Object.assign(annotation, updatedAnnotation); 1124 1124 - }, 1125 1125 - // onDelete callback 1126 1126 - async () => { 1127 1127 - // Remove from local storage 1128 1128 - const stored = await browser.storage.local.get('annotations'); 1129 1129 - const filtered = annotations.filter(a => a.createdAt !== annotation.createdAt); 1130 1130 - await browser.storage.local.set({ annotations: filtered }); 1131 1131 - 1132 1132 - // Remove highlight from DOM 1133 1133 - highlight.remove(); 1134 1134 - } 1135 1135 - ); 1136 1136 - ``` 1137 1137 - 1138 1138 - **Note**: Popover save/delete only updates `browser.storage.local`, not the PDS. This is a bug/limitation. 1139 1139 - 1140 1140 - --- 1141 1141 - 1142 1142 - ## Selector System 1143 1143 - 1144 1144 - ### Generation (`lib/selectors/generate.ts`) 1145 1145 - 1146 1146 - **Purpose**: Convert a DOM Selection into portable selectors. 1147 1147 - 1148 1148 - ```typescript 1149 1149 - function generateSelectors(selection: Selection, root?: HTMLElement): Selector[] { 1150 1150 - if (!selection.rangeCount) return []; 1151 1151 - 1152 1152 - const range = selection.getRangeAt(0); 1153 1153 - const container = root || document.body; 1154 1154 - const selectors: Selector[] = []; 1155 1155 - 1156 1156 - // Generate TextQuoteSelector (robust) 1157 1157 - const textQuoteSelector = generateTextQuoteSelector(range, container); 1158 1158 - if (textQuoteSelector) selectors.push(textQuoteSelector); 1159 1159 - 1160 1160 - // Generate TextPositionSelector (precise) 1161 1161 - const textPositionSelector = generateTextPositionSelector(range, container); 1162 1162 - if (textPositionSelector) selectors.push(textPositionSelector); 1163 1163 - 1164 1164 - return selectors; 1165 1165 - } 1166 1166 - ``` 1167 1167 - 1168 1168 - **TextQuoteSelector Generation**: 1169 1169 - ```typescript 1170 1170 - function generateTextQuoteSelector( 1171 1171 - range: Range, 1172 1172 - root: HTMLElement 1173 1173 - ): TextQuoteSelector | null { 1174 1174 - const exact = range.toString().trim(); 1175 1175 - if (!exact) return null; 1176 1176 - 1177 1177 - try { 1178 1178 - // Uses dom-anchor-text-quote library 1179 1179 - const selector = textQuote.fromRange(root, range); 1180 1180 - 1181 1181 - return { 1182 1182 - $type: 'community.lexicon.annotation.annotation#textQuoteSelector', 1183 1183 - exact: selector.exact, 1184 1184 - prefix: selector.prefix || undefined, 1185 1185 - suffix: selector.suffix || undefined 1186 1186 - }; 1187 1187 - } catch (error) { 1188 1188 - console.warn('Failed to generate TextQuoteSelector:', error); 1189 1189 - return null; 1190 1190 - } 1191 1191 - } 1192 1192 - ``` 1193 1193 - 1194 1194 - **How it works**: 1195 1195 - - `exact`: The selected text itself 1196 1196 - - `prefix`: 32 characters before the selection (for context) 1197 1197 - - `suffix`: 32 characters after the selection (for context) 1198 1198 - 1199 1199 - **Example**: 1200 1200 - ``` 1201 1201 - Page text: "The quick brown fox jumps over the lazy dog." 1202 1202 - Selection: "brown fox" 1203 1203 - 1204 1204 - TextQuoteSelector: 1205 1205 - { 1206 1206 - exact: "brown fox", 1207 1207 - prefix: "The quick ", 1208 1208 - suffix: " jumps over" 1209 1209 - } 1210 1210 - ``` 1211 1211 - 1212 1212 - **TextPositionSelector Generation**: 1213 1213 - ```typescript 1214 1214 - function generateTextPositionSelector( 1215 1215 - range: Range, 1216 1216 - root: HTMLElement 1217 1217 - ): TextPositionSelector | null { 1218 1218 - const exact = range.toString().trim(); 1219 1219 - if (!exact) return null; 1220 1220 - 1221 1221 - try { 1222 1222 - // Uses dom-anchor-text-position library 1223 1223 - const selector = textPosition.fromRange(root, range); 1224 1224 - 1225 1225 - return { 1226 1226 - $type: 'community.lexicon.annotation.annotation#textPositionSelector', 1227 1227 - start: selector.start, 1228 1228 - end: selector.end 1229 1229 - }; 1230 1230 - } catch (error) { 1231 1231 - console.warn('Failed to generate TextPositionSelector:', error); 1232 1232 - return null; 1233 1233 - } 1234 1234 - } 1235 1235 - ``` 1236 1236 - 1237 1237 - **How it works**: 1238 1238 - - `start`: Character offset from start of container's text content 1239 1239 - - `end`: Character offset from start of container's text content 1240 1240 - 1241 1241 - **Example**: 1242 1242 - ``` 1243 1243 - Page text: "The quick brown fox jumps over the lazy dog." 1244 1244 - Selection: "brown fox" 1245 1245 - 1246 1246 - TextPositionSelector: 1247 1247 - { 1248 1248 - start: 10, // 0-indexed position of "b" in "brown" 1249 1249 - end: 19 // 0-indexed position after "x" in "fox" 1250 1250 - } 1251 1251 - ``` 1252 1252 - 1253 1253 - ### Matching (`lib/selectors/match.ts`) 1254 1254 - 1255 1255 - **Purpose**: Convert selectors back into DOM Range for highlighting. 1256 1256 - 1257 1257 - **Strategy**: 1258 1258 - 1. Try TextPositionSelector first (fast, precise) 1259 1259 - 2. If fails, try TextQuoteSelector (slower, more robust) 1260 1260 - 1261 1261 - **Why this order?** 1262 1262 - - TextPositionSelector is O(n) where n = text length 1263 1263 - - TextQuoteSelector is O(n*m) where m = search window size 1264 1264 - - But TextQuoteSelector works even if content changed slightly 1265 1265 - 1266 1266 - --- 1267 1267 - 1268 1268 - ## Comment/Reply System 1269 1269 - 1270 1270 - ### Data Model 1271 1271 - 1272 1272 - **AT Protocol Record Type**: `pub.leaflet.comment` 1273 1273 - 1274 1274 - **TypeScript Interface**: 1275 1275 - ```typescript 1276 1276 - interface Comment { 1277 1277 - $type: 'pub.leaflet.comment'; 1278 1278 - subject: string; // URI of annotation being commented on 1279 1279 - plaintext: string; // Comment text 1280 1280 - createdAt: string; 1281 1281 - reply?: { 1282 1282 - parent: string; // URI of parent comment (for replies) 1283 1283 - }; 1284 1284 - facets?: RichtextFacet[]; // For mentions, links, hashtags 1285 1285 - onPage?: string; // URL of page (optional) 1286 1286 - 1287 1287 - uri?: string; // at://did:plc:abc123/collection/rkey 1288 1288 - cid?: string; 1289 1289 - author?: { 1290 1290 - did: string; 1291 1291 - handle: string; 1292 1292 - displayName?: string; 1293 1293 - avatar?: string; 1294 1294 - }; 1295 1295 - } 1296 1296 - ``` 1297 1297 - 1298 1298 - ### Comment Hierarchy 1299 1299 - 1300 1300 - ``` 1301 1301 - Annotation (at://did:plc:abc/annotation/123) 1302 1302 - ├─ Comment 1 (subject: annotation URI, no reply) 1303 1303 - │ ├─ Reply 1.1 (subject: annotation URI, reply.parent: comment1 URI) 1304 1304 - │ └─ Reply 1.2 (subject: annotation URI, reply.parent: comment1 URI) 1305 1305 - │ └─ Reply 1.2.1 (subject: annotation URI, reply.parent: reply1.2 URI) 1306 1306 - └─ Comment 2 (subject: annotation URI, no reply) 1307 1307 - ``` 1308 1308 - 1309 1309 - **Key insight**: All comments/replies have the same `subject` (annotation URI). The `reply.parent` field creates the tree structure. 1310 1310 - 1311 1311 - ### Rendering Algorithm 1312 1312 - 1313 1313 - ```typescript 1314 1314 - // Get top-level comments (no reply field) 1315 1315 - const topLevelComments = allComments.filter(c => 1316 1316 - c.subject === annotation.uri && !c.reply 1317 1317 - ); 1318 1318 - 1319 1319 - // Recursively build thread 1320 1320 - function buildCommentThread(parentUri: string): string { 1321 1321 - const replies = allComments.filter(c => c.reply?.parent === parentUri); 1322 1322 - 1323 1323 - if (collapsedThreads.has(parentUri)) { 1324 1324 - return `<button>▸ ${replies.length} hidden</button>`; 1325 1325 - } 1326 1326 - 1327 1327 - return ` 1328 1328 - <div class="comment-thread"> 1329 1329 - ${replies.map(comment => ` 1330 1330 - <div class="comment"> 1331 1331 - ${comment.plaintext} 1332 1332 - <button class="reply-btn">Reply</button> 1333 1333 - ${buildCommentThread(comment.uri!)} <!-- Recursion --> 1334 1334 - </div> 1335 1335 - `).join('')} 1336 1336 - </div> 1337 1337 - `; 1338 1338 - } 1339 1339 - ``` 1340 1340 - 1341 1341 - ### Creating Comments 1342 1342 - 1343 1343 - **Top-level comment**: 1344 1344 - ```typescript 1345 1345 - await createComment({ 1346 1346 - $type: 'pub.leaflet.comment', 1347 1347 - subject: annotationUri, // at://did:plc:abc/annotation/123 1348 1348 - plaintext: "Great annotation!", 1349 1349 - createdAt: new Date().toISOString(), 1350 1350 - // No reply field 1351 1351 - }); 1352 1352 - ``` 1353 1353 - 1354 1354 - **Reply to comment**: 1355 1355 - ```typescript 1356 1356 - await createComment({ 1357 1357 - $type: 'pub.leaflet.comment', 1358 1358 - subject: annotationUri, // Still the annotation URI 1359 1359 - plaintext: "I agree!", 1360 1360 - createdAt: new Date().toISOString(), 1361 1361 - reply: { 1362 1362 - parent: parentCommentUri // at://did:plc:abc/comment/456 1363 1363 - }, 1364 1364 - }); 1365 1365 - ``` 1366 1366 - 1367 1367 - --- 1368 1368 - 1369 1369 - ## Landing Page 1370 1370 - 1371 1371 - **File**: `public/landing.js` + `public/landing.css` 1372 1372 - 1373 1373 - **Purpose**: Public-facing website at `seams.so` that shows recent annotations from all users. 1374 1374 - 1375 1375 - ### Architecture 1376 1376 - 1377 1377 - ``` 1378 1378 - Landing Page (static HTML/JS) 1379 1379 - │ 1380 1380 - ▼ 1381 1381 - slices.network GraphQL API 1382 1382 - │ 1383 1383 - ▼ 1384 1384 - AT Protocol Network (federated PDS nodes) 1385 1385 - ``` 1386 1386 - 1387 1387 - ### slices.network Integration 1388 1388 - 1389 1389 - **Slice ID**: `at://did:plc:dy6ekftqerqu5bcz76kgy6ux/network.slices.slice/3m3ugigrrz52k` 1390 1390 - 1391 1391 - **GraphQL Endpoint**: `https://api.slices.network/graphql?slice=[SLICE_ID]` 1392 1392 - 1393 1393 - **Query**: 1394 1394 - ```graphql 1395 1395 - query RecentAnnotations($cursor: String) { 1396 1396 - communityLexiconAnnotationAnnotations( 1397 1397 - sortBy: [{ field: "createdAt", direction: desc }] 1398 1398 - first: 20 1399 1399 - after: $cursor 1400 1400 - ) { 1401 1401 - edges { 1402 1402 - cursor 1403 1403 - node { 1404 1404 - uri 1405 1405 - did 1406 1406 - actorHandle 1407 1407 - target { 1408 1408 - source 1409 1409 - selector 1410 1410 - } 1411 1411 - body 1412 1412 - createdAt 1413 1413 - } 1414 1414 - } 1415 1415 - pageInfo { 1416 1416 - hasNextPage 1417 1417 - endCursor 1418 1418 - } 1419 1419 - } 1420 1420 - } 1421 1421 - ``` 1422 1422 - 1423 1423 - ### Data Flow 1424 1424 - 1425 1425 - ```typescript 1426 1426 - // Fetch annotations 1427 1427 - const response = await fetch(GRAPHQL_ENDPOINT, { 1428 1428 - method: 'POST', 1429 1429 - headers: { 'Content-Type': 'application/json' }, 1430 1430 - body: JSON.stringify({ 1431 1431 - query: QUERY, 1432 1432 - variables: { cursor } 1433 1433 - }) 1434 1434 - }); 1435 1435 - 1436 1436 - const data = await response.json(); 1437 1437 - const annotations = data.data.communityLexiconAnnotationAnnotations.edges 1438 1438 - .map(edge => edge.node); 1439 1439 - 1440 1440 - // Render each annotation 1441 1441 - for (const annotation of annotations) { 1442 1442 - const quotedText = getQuotedText(annotation.target); 1443 1443 - const sourceUrl = annotation.target[0]?.source; 1444 1444 - const fragmentUrl = buildTextFragmentUrl(sourceUrl, quotedText); 1445 1445 - 1446 1446 - // Fetch avatar from Bluesky 1447 1447 - const profile = await fetch( 1448 1448 - `https://public.api.bsky.app/xrpc/app.bsky.actor.getProfile?actor=${annotation.did}` 1449 1449 - ); 1450 1450 - const avatarUrl = profile.avatar; 1451 1451 - 1452 1452 - // Render card 1453 1453 - renderAnnotationCard({ 1454 1454 - quote: quotedText, 1455 1455 - body: annotation.body, 1456 1456 - author: annotation.actorHandle, 1457 1457 - avatar: avatarUrl, 1458 1458 - time: annotation.createdAt, 1459 1459 - link: fragmentUrl 1460 1460 - }); 1461 1461 - } 1462 1462 - ``` 1463 1463 - 1464 1464 - ### Text Fragment URL 1465 1465 - 1466 1466 - **Purpose**: Link to the annotated text on the original page. 1467 1467 - 1468 1468 - **Browser Feature**: Chrome supports scroll-to-text-highlight via `#:~:text=` fragment. 1469 1469 - 1470 1470 - **Implementation**: 1471 1471 - ```typescript 1472 1472 - function buildTextFragmentUrl(sourceUrl: string, textQuoteSelector: TextQuoteSelector) { 1473 1473 - if (!sourceUrl || !textQuoteSelector?.exact) { 1474 1474 - return sourceUrl; 1475 1475 - } 1476 1476 - 1477 1477 - try { 1478 1478 - const url = new URL(sourceUrl); 1479 1479 - // Simple version: just exact text 1480 1480 - url.hash = `:~:text=${encodeURIComponent(textQuoteSelector.exact)}`; 1481 1481 - return url.toString(); 1482 1482 - } catch { 1483 1483 - return sourceUrl; 1484 1484 - } 1485 1485 - } 1486 1486 - ``` 1487 1487 - 1488 1488 - **Example**: 1489 1489 - ``` 1490 1490 - Original: https://example.com/article 1491 1491 - With fragment: https://example.com/article#:~:text=brown%20fox 1492 1492 - 1493 1493 - Browser behavior: 1494 1494 - 1. Loads page 1495 1495 - 2. Searches for "brown fox" 1496 1496 - 3. Scrolls to match 1497 1497 - 4. Highlights in yellow (native browser highlight, not extension) 1498 1498 - ``` 1499 1499 - 1500 1500 - **Limitation**: Only works with simple `exact` text. Doesn't use `prefix`/`suffix` for context. 1501 1501 - 1502 1502 - --- 1503 1503 - 1504 1504 - ## Storage Architecture 1505 1505 - 1506 1506 - ### Extension Storage 1507 1507 - 1508 1508 - **API**: `browser.storage.local` (Chrome Extension Storage) 1509 1509 - 1510 1510 - **Keys**: 1511 1511 - | Key | Value | Purpose | 1512 1512 - |-----|-------|---------| 1513 1513 - | `synthesis-oauth:session` | `OAuthSession` | OAuth tokens and user DID | 1514 1514 - | `annotations` | `Annotation[]` | Legacy local storage (not used in current flow) | 1515 1515 - 1516 1516 - **Note**: Current implementation stores annotations primarily on PDS, not in local storage. Local storage is only used by the popover edit/delete feature (which is a bug - it should update PDS). 1517 1517 - 1518 1518 - ### AT Protocol Storage 1519 1519 - 1520 1520 - **Personal Data Server (PDS)**: User's own data repository (e.g., `https://bsky.social/xrpc`) 1521 1521 - 1522 1522 - **Collections**: 1523 1523 - | Collection | Type | Records | 1524 1524 - |------------|------|---------| 1525 1525 - | `community.lexicon.annotation.annotation` | Annotations | User's annotations | 1526 1526 - | `pub.leaflet.comment` | Comments | Comments and replies | 1527 1527 - 1528 1528 - **Record URIs**: 1529 1529 - ``` 1530 1530 - at://[did]/[collection]/[rkey] 1531 1531 - 1532 1532 - Examples: 1533 1533 - - at://did:plc:abc123/community.lexicon.annotation.annotation/3k2j4h5g6f 1534 1534 - - at://did:plc:abc123/pub.leaflet.comment/3k2j4h5g6f 1535 1535 - ``` 1536 1536 - 1537 1537 - ### Storage Flow 1538 1538 - 1539 1539 - ``` 1540 1540 - User creates annotation 1541 1541 - │ 1542 1542 - ▼ 1543 1543 - Sidepanel → PDS Module → com.atproto.repo.createRecord 1544 1544 - │ │ 1545 1545 - │ ▼ 1546 1546 - │ User's PDS (e.g., bsky.social) 1547 1547 - │ │ 1548 1548 - │ ▼ 1549 1549 - │ Record stored with URI + CID 1550 1550 - │ │ 1551 1551 - │ ▼ 1552 1552 - │ Federated to ATProto network 1553 1553 - │ │ 1554 1554 - ▼ ▼ 1555 1555 - (Optional) Local storage slices.network indexes 1556 1556 - ``` 1557 1557 - 1558 1558 - --- 1559 1559 - 1560 1560 - ## Known Issues 1561 1561 - 1562 1562 - ### 1. Race Condition on Sidepanel Load 1563 1563 - 1564 1564 - **Problem**: Sidepanel sends `GET_SELECTION` to content script on load, but content script may not be ready yet. 1565 1565 - 1566 1566 - **Result**: `currentUrl` is empty string, annotations saved with empty `source` field. 1567 1567 - 1568 1568 - **Location**: `entrypoints/sidepanel/main.ts:187-207` 1569 1569 - 1570 1570 - **Fix**: See `STATE_REFACTOR_PLAN.md` for event-driven architecture. 1571 1571 - 1572 1572 - ### 2. No SPA Navigation Tracking 1573 1573 - 1574 1574 - **Problem**: Content script doesn't detect URL changes from `pushState`/`replaceState`. 1575 1575 - 1576 1576 - **Result**: After navigating in a single-page app, annotations for the new page don't load until sidepanel is reopened. 1577 1577 - 1578 1578 - **Fix**: See `STATE_REFACTOR_PLAN.md` for `webNavigation.onHistoryStateUpdated` solution. 1579 1579 - 1580 1580 - ### 3. No Selection Debouncing 1581 1581 - 1582 1582 - **Problem**: `mouseup` event fires even for clicks (no actual selection). 1583 1583 - 1584 1584 - **Result**: Unnecessary `SELECTION_CHANGED` messages sent to sidepanel. 1585 1585 - 1586 1586 - **Fix**: Add 250ms debounce and ignore empty selections. 1587 1587 - 1588 1588 - ### 4. Editable Field Selections Not Filtered 1589 1589 - 1590 1590 - **Problem**: Selections inside `<input>`, `<textarea>`, or `contenteditable` are captured. 1591 1591 - 1592 1592 - **Result**: Confusing UX - user can't annotate form fields, but extension shows form. 1593 1593 - 1594 1594 - **Fix**: Check `document.activeElement` and ignore editable elements. 1595 1595 - 1596 1596 - ### 5. Popover Edit/Delete Doesn't Update PDS 1597 1597 - 1598 1598 - **Problem**: When editing an annotation via highlight popover, it only updates `browser.storage.local`. 1599 1599 - 1600 1600 - **Result**: Changes aren't synced to PDS or visible on other devices. 1601 1601 - 1602 1602 - **Location**: `lib/highlights/apply.ts:85-112` 1603 1603 - 1604 1604 - **Fix**: Call `updateAnnotation()` function in PDS module (needs to be implemented). 1605 1605 - 1606 1606 - ### 6. No Service Worker State Persistence 1607 1607 - 1608 1608 - **Problem**: Background script doesn't persist state across restarts (MV3 service workers suspend). 1609 1609 - 1610 1610 - **Result**: State is lost if service worker is terminated. 1611 1611 - 1612 1612 - **Fix**: Use `chrome.storage.session` (see `STATE_REFACTOR_PLAN.md`). 1613 1613 - 1614 1614 - ### 7. Text Fragment URL Limitation 1615 1615 - 1616 1616 - **Problem**: Landing page only uses `exact` text for text fragments, ignoring `prefix`/`suffix`. 1617 1617 - 1618 1618 - **Result**: If the same text appears multiple times on a page, browser may highlight the wrong instance. 1619 1619 - 1620 1620 - **Location**: `public/landing.js:159-171` 1621 1621 - 1622 1622 - **Fix**: Implement complex text fragment syntax with prefix/suffix (non-trivial). 1623 1623 - 1624 1624 - ### 8. No Cross-Tab Communication 1625 1625 - 1626 1626 - **Problem**: If user has multiple tabs open, creating an annotation in one tab doesn't update highlights in other tabs with the same URL. 1627 1627 - 1628 1628 - **Result**: User must manually reload sidepanel to see new annotations. 1629 1629 - 1630 1630 - **Fix**: Broadcast `ANNOTATIONS_CHANGED` event to all tabs with matching URL. 1631 1631 - 1632 1632 - ### 9. No Error Recovery for Selector Matching 1633 1633 - 1634 1634 - **Problem**: If all selectors fail to match (e.g., page content changed), annotation is silently skipped. 1635 1635 - 1636 1636 - **Result**: User sees annotations in list but no highlights on page. 1637 1637 - 1638 1638 - **Fix**: Show "Could not locate annotation" warning in UI, offer to re-anchor manually. 1639 1639 - 1640 1640 - ### 10. Comment Threading UI Complexity 1641 1641 - 1642 1642 - **Problem**: Nested replies can become deeply indented and hard to read. 1643 1643 - 1644 1644 - **Result**: Poor UX for long discussion threads. 1645 1645 - 1646 1646 - **Fix**: Implement "Show more replies" collapse/expand, or switch to flat threading with "Replying to @user" indicators. 1647 1647 - 1648 1648 - --- 1649 1649 - 1650 1650 - ## Summary Diagram 1651 1651 - 1652 1652 - ``` 1653 1653 - ┌─────────────────────────────────────────────────────────────────┐ 1654 1654 - │ USER ACTIONS │ 1655 1655 - └──────────┬────────────────────────────────────────┬─────────────┘ 1656 1656 - │ │ 1657 1657 - │ Select text │ Click icon 1658 1658 - │ │ 1659 1659 - ┌──────────▼─────────────────┐ ┌─────────▼──────────────┐ 1660 1660 - │ Web Page (Content) │ │ Extension UI │ 1661 1661 - │ │ │ (Sidepanel) │ 1662 1662 - │ ┌────────────────────────┐ │ │ │ 1663 1663 - │ │ Content Script │ │ │ ┌────────────────────┐ │ 1664 1664 - │ │ │ │ │ │ Auth Section │ │ 1665 1665 - │ │ • Track selection │◄┼────────────┼─┤ - Login form │ │ 1666 1666 - │ │ • Generate selectors │ │ GET_SEL │ │ - OAuth flow │ │ 1667 1667 - │ │ • Apply highlights │ │ │ └────────────────────┘ │ 1668 1668 - │ │ • Show popovers │ │ │ ┌────────────────────┐ │ 1669 1669 - │ └──────┬─────────▲───────┘ │ │ │ Content Section │ │ 1670 1670 - │ │ │ │ │ │ - Annotation form │ │ 1671 1671 - │ │ SELECTION│UPDATE │ │ │ - Annotation list │ │ 1672 1672 - │ │ _CHANGED │_HIGHLIGHTS │ │ - Comment threads │ │ 1673 1673 - │ │ │ │ │ └────────────────────┘ │ 1674 1674 - └────────┼─────────┼──────────┘ └─────────┬──────────────┘ 1675 1675 - │ │ │ 1676 1676 - │ │ │ createAnnotation 1677 1677 - │ │ │ listAnnotations 1678 1678 - ▼ │ │ createComment 1679 1679 - ┌────────────────────────────┐ │ 1680 1680 - │ Background Script │ │ 1681 1681 - │ │ │ 1682 1682 - │ • Context menu │ │ 1683 1683 - │ • Auth broadcast │ │ 1684 1684 - │ • Icon click → sidepanel │ │ 1685 1685 - └────────────────────────────┘ │ 1686 1686 - │ 1687 1687 - ┌──────────────────────────────────────────┘ 1688 1688 - │ 1689 1689 - ▼ 1690 1690 - ┌─────────────────────────────────────────────────────┐ 1691 1691 - │ lib/ │ 1692 1692 - │ │ 1693 1693 - │ ┌─────────────┐ ┌──────────────┐ ┌────────────┐ │ 1694 1694 - │ │ oauth.ts │ │ pds.ts │ │ selectors/ │ │ 1695 1695 - │ │ │ │ │ │ │ │ 1696 1696 - │ │ • OAuth │ │ • XRPC calls │ │ • generate │ │ 1697 1697 - │ │ flow │ │ • Create │ │ • match │ │ 1698 1698 - │ │ • Session │ │ • List │ └────────────┘ │ 1699 1699 - │ │ mgmt │ │ • Delete │ ┌────────────┐ │ 1700 1700 - │ └─────────────┘ └──────────────┘ │highlights/ │ │ 1701 1701 - │ │ │ │ 1702 1702 - │ │ • apply │ │ 1703 1703 - │ │ • popover │ │ 1704 1704 - │ └────────────┘ │ 1705 1705 - └──────────────────┬──────────────────────────────────┘ 1706 1706 - │ XRPC 1707 1707 - ▼ 1708 1708 - ┌──────────────────────────────────────────────────────┐ 1709 1709 - │ AT Protocol Infrastructure │ 1710 1710 - │ │ 1711 1711 - │ ┌──────────────────┐ ┌────────────────────┐ │ 1712 1712 - │ │ PDS (bsky.social)│ │ slices.network │ │ 1713 1713 - │ │ │ │ │ │ 1714 1714 - │ │ • OAuth server │────────▶│ • GraphQL API │ │ 1715 1715 - │ │ • Record storage │ indexes │ • Annotation feed │ │ 1716 1716 - │ └──────────────────┘ └────────────────────┘ │ 1717 1717 - └─────────────────────────────────────────────────┬────┘ 1718 1718 - │ 1719 1719 - │ GraphQL 1720 1720 - ▼ 1721 1721 - ┌────────────────┐ 1722 1722 - │ Landing Page │ 1723 1723 - │ (seams.so) │ 1724 1724 - │ │ 1725 1725 - │ • Public feed │ 1726 1726 - │ • Avatar fetch │ 1727 1727 - │ • Text frags │ 1728 1728 - └────────────────┘ 1729 1729 - ``` 1730 1730 - 1731 1731 - --- 1732 1732 - 1733 1733 - This documentation represents the **current state** of the codebase as of the analysis. For the planned refactoring to event-driven architecture, see [`STATE_REFACTOR_PLAN.md`](file:///home/anish/usr/seams.so/STATE_REFACTOR_PLAN.md).

-512

STATE_REFACTOR_PLAN.md

reviewed

··· 1 1 - # State Management Refactoring Plan 2 2 - 3 3 - ## Problem Statement 4 4 - 5 5 - The current extension architecture relies on fragile, on-demand message passing from the sidepanel to the content script to fetch the current URL and selection state. This leads to: 6 6 - 7 7 - - **Race conditions**: Sidepanel tries to pull state from content script on load (may not be ready) 8 8 - - **Empty source URLs**: Annotations saved with empty `source` field 9 9 - - **No SPA navigation tracking**: URL changes via pushState/replaceState aren't detected 10 10 - - **Fragmented state**: Each component maintains its own copy of url/selection state 11 11 - 12 12 - ## Current Architecture 13 13 - 14 14 - ``` 15 15 - Sidepanel (pulls) → Content Script 16 16 - - On mount: browser.tabs.sendMessage({ type: 'GET_SELECTION' }) 17 17 - - Content may not be ready 18 18 - - No proactive updates 19 19 - ``` 20 20 - 21 21 - ## Target Architecture (Oracle-Approved) 22 22 - 23 23 - ``` 24 24 - Content Script → Background (State Manager) ⇄ Sidepanel 25 25 - ↓ 26 26 - storage.session (persistence) 27 27 - ``` 28 28 - 29 29 - ### Key Principles 30 30 - 31 31 - 1. **Event-driven**: Content proactively pushes state updates 32 32 - 2. **MV3-resilient**: State persists in `chrome.storage.session` to survive service worker suspension 33 33 - 3. **Port-based communication**: Long-lived connections keep SW alive and prevent cross-tab leakage 34 34 - 4. **Background-managed URL tracking**: Use browser APIs (`tabs.onUpdated`, `webNavigation.onHistoryStateUpdated`) 35 35 - 5. **Debounced selection**: Avoid spam from `selectionchange` events 36 36 - 6. **Timestamped updates**: Prevent race conditions with `updatedAt` field 37 37 - 38 38 - ## Implementation Plan 39 39 - 40 40 - ### 1. Add webNavigation Permission 41 41 - 42 42 - **File**: `wxt.config.ts` or manifest 43 43 - 44 44 - ```typescript 45 45 - permissions: [ 46 46 - 'storage', 47 47 - 'contextMenus', 48 48 - 'sidePanel', 49 49 - 'webNavigation', // ADD THIS 50 50 - ] 51 51 - ``` 52 52 - 53 53 - ### 2. Background Script State Manager 54 54 - 55 55 - **File**: `entrypoints/background.ts` 56 56 - 57 57 - #### State Shape 58 58 - ```typescript 59 59 - interface TabState { 60 60 - url: string; 61 61 - title: string; 62 62 - selection: { text: string; selectors: Selector[] } | null; 63 63 - updatedAt: number; // Date.now() 64 64 - } 65 65 - 66 66 - // In-memory cache 67 67 - const tabStateCache = new Map<number, TabState>(); 68 68 - 69 69 - // Port registry 70 70 - const sidepanelPorts = new Map<number, chrome.runtime.Port>(); // tabId → port 71 71 - ``` 72 72 - 73 73 - #### Storage Session Integration 74 74 - - Mirror `tabStateCache` to `chrome.storage.session` 75 75 - - Throttle writes to ≤1/sec per tab 76 76 - - On SW restart: restore from `storage.session` 77 77 - 78 78 - #### Event Listeners 79 79 - 80 80 - **tabs.onUpdated** (URL/title changes) 81 81 - ```typescript 82 82 - browser.tabs.onUpdated.addListener((tabId, changeInfo, tab) => { 83 83 - if (changeInfo.url || changeInfo.title) { 84 84 - updateTabState(tabId, { 85 85 - url: tab.url, 86 86 - title: tab.title, 87 87 - selection: null, // Clear selection on navigation 88 88 - updatedAt: Date.now(), 89 89 - }); 90 90 - 91 91 - // Clear highlights on content script 92 92 - browser.tabs.sendMessage(tabId, { type: 'CLEAR_HIGHLIGHTS' }).catch(() => {}); 93 93 - 94 94 - // Notify sidepanel 95 95 - broadcastToSidepanel(tabId); 96 96 - } 97 97 - }); 98 98 - ``` 99 99 - 100 100 - **webNavigation.onHistoryStateUpdated** (SPA navigation) 101 101 - ```typescript 102 102 - browser.webNavigation.onHistoryStateUpdated.addListener((details) => { 103 103 - if (details.frameId === 0) { // Top frame only 104 104 - updateTabState(details.tabId, { 105 105 - url: details.url, 106 106 - selection: null, 107 107 - updatedAt: Date.now(), 108 108 - }); 109 109 - 110 110 - browser.tabs.sendMessage(details.tabId, { type: 'CLEAR_HIGHLIGHTS' }).catch(() => {}); 111 111 - broadcastToSidepanel(details.tabId); 112 112 - } 113 113 - }); 114 114 - ``` 115 115 - 116 116 - **tabs.onRemoved** (cleanup) 117 117 - ```typescript 118 118 - browser.tabs.onRemoved.addListener((tabId) => { 119 119 - tabStateCache.delete(tabId); 120 120 - sidepanelPorts.delete(tabId); 121 121 - browser.storage.session.remove(`tab_${tabId}`); 122 122 - }); 123 123 - ``` 124 124 - 125 125 - #### Message Handlers 126 126 - 127 127 - **TAB_STATE_UPDATE** (from content script) 128 128 - ```typescript 129 129 - // Content sends: { type: 'TAB_STATE_UPDATE', url, title, selection, updatedAt } 130 130 - if (message.type === 'TAB_STATE_UPDATE') { 131 131 - const tabId = sender.tab?.id; 132 132 - if (!tabId) return; 133 133 - 134 134 - const currentState = tabStateCache.get(tabId); 135 135 - 136 136 - // Last-write-wins: only accept if newer 137 137 - if (!currentState || message.updatedAt > currentState.updatedAt) { 138 138 - updateTabState(tabId, message); 139 139 - broadcastToSidepanel(tabId); 140 140 - } 141 141 - 142 142 - sendResponse({ success: true }); 143 143 - return true; 144 144 - } 145 145 - ``` 146 146 - 147 147 - **GET_TAB_STATE** (from sidepanel) 148 148 - ```typescript 149 149 - // Sidepanel sends: { type: 'GET_TAB_STATE', tabId } 150 150 - if (message.type === 'GET_TAB_STATE') { 151 151 - const tabId = message.tabId; 152 152 - let state = tabStateCache.get(tabId); 153 153 - 154 154 - if (!state) { 155 155 - // Try storage.session 156 156 - const stored = await browser.storage.session.get(`tab_${tabId}`); 157 157 - state = stored[`tab_${tabId}`]; 158 158 - } 159 159 - 160 160 - if (!state) { 161 161 - // Cold start: request snapshot from content 162 162 - try { 163 163 - const snapshot = await browser.tabs.sendMessage(tabId, { 164 164 - type: 'GET_TAB_SNAPSHOT' 165 165 - }); 166 166 - state = { ...snapshot, updatedAt: Date.now() }; 167 167 - updateTabState(tabId, state); 168 168 - } catch (error) { 169 169 - // Content script not available (restricted page, PDF, etc.) 170 170 - sendResponse({ 171 171 - success: false, 172 172 - error: 'Content not available on this page' 173 173 - }); 174 174 - return true; 175 175 - } 176 176 - } 177 177 - 178 178 - sendResponse({ success: true, state }); 179 179 - return true; 180 180 - } 181 181 - ``` 182 182 - 183 183 - #### Port Management 184 184 - 185 185 - **Sidepanel connection** 186 186 - ```typescript 187 187 - browser.runtime.onConnect.addListener((port) => { 188 188 - if (port.name === 'sidepanel') { 189 189 - port.onMessage.addListener((message) => { 190 190 - if (message.type === 'REGISTER_TAB') { 191 191 - sidepanelPorts.set(message.tabId, port); 192 192 - } 193 193 - }); 194 194 - 195 195 - port.onDisconnect.addListener(() => { 196 196 - // Remove from registry 197 197 - for (const [tabId, p] of sidepanelPorts.entries()) { 198 198 - if (p === port) { 199 199 - sidepanelPorts.delete(tabId); 200 200 - break; 201 201 - } 202 202 - } 203 203 - }); 204 204 - } 205 205 - }); 206 206 - ``` 207 207 - 208 208 - #### Helper Functions 209 209 - 210 210 - ```typescript 211 211 - function updateTabState(tabId: number, updates: Partial<TabState>) { 212 212 - const current = tabStateCache.get(tabId) || {} as TabState; 213 213 - const newState = { ...current, ...updates }; 214 214 - tabStateCache.set(tabId, newState); 215 215 - 216 216 - // Throttled write to storage.session (implement throttle) 217 217 - throttledSaveToSession(tabId, newState); 218 218 - } 219 219 - 220 220 - function broadcastToSidepanel(tabId: number) { 221 221 - const port = sidepanelPorts.get(tabId); 222 222 - const state = tabStateCache.get(tabId); 223 223 - 224 224 - if (port && state) { 225 225 - port.postMessage({ 226 226 - type: 'TAB_STATE_CHANGED', 227 227 - tabId, 228 228 - state, 229 229 - }); 230 230 - } 231 231 - } 232 232 - ``` 233 233 - 234 234 - ### 3. Content Script Refactor 235 235 - 236 236 - **File**: `entrypoints/content.ts` 237 237 - 238 238 - #### Debounced Selection Tracking 239 239 - 240 240 - ```typescript 241 241 - let selectionDebounceTimer: number | null = null; 242 242 - const SELECTION_DEBOUNCE_MS = 250; 243 243 - 244 244 - document.addEventListener('selectionchange', () => { 245 245 - if (selectionDebounceTimer) { 246 246 - clearTimeout(selectionDebounceTimer); 247 247 - } 248 248 - 249 249 - selectionDebounceTimer = setTimeout(() => { 250 250 - handleSelectionChange(); 251 251 - }, SELECTION_DEBOUNCE_MS); 252 252 - }); 253 253 - 254 254 - // Also handle immediate updates on mouseup/keyup 255 255 - document.addEventListener('mouseup', handleSelectionChange); 256 256 - document.addEventListener('keyup', handleSelectionChange); 257 257 - 258 258 - function handleSelectionChange() { 259 259 - const selection = window.getSelection(); 260 260 - 261 261 - if (!selection || selection.toString().trim().length === 0) { 262 262 - sendStateUpdate(null); 263 263 - currentSelection = null; 264 264 - return; 265 265 - } 266 266 - 267 267 - // Ignore selections in editable fields 268 268 - const activeElement = document.activeElement; 269 269 - if (activeElement && ( 270 270 - activeElement.tagName === 'INPUT' || 271 271 - activeElement.tagName === 'TEXTAREA' || 272 272 - activeElement.hasAttribute('contenteditable') 273 273 - )) { 274 274 - return; 275 275 - } 276 276 - 277 277 - const text = selection.toString().trim(); 278 278 - const root = document.querySelector('main') || document.querySelector('article') || document.body; 279 279 - const selectors = generateSelectors(selection, root); 280 280 - 281 281 - currentSelection = { text, selectors }; 282 282 - sendStateUpdate(currentSelection); 283 283 - } 284 284 - 285 285 - function sendStateUpdate(selection: { text: string; selectors: Selector[] } | null) { 286 286 - browser.runtime.sendMessage({ 287 287 - type: 'TAB_STATE_UPDATE', 288 288 - url: window.location.href, 289 289 - title: document.title, 290 290 - selection, 291 291 - updatedAt: Date.now(), 292 292 - }).catch(() => { 293 293 - // Background might not be ready 294 294 - }); 295 295 - } 296 296 - ``` 297 297 - 298 298 - #### Initial State Push 299 299 - 300 300 - ```typescript 301 301 - // On page load (document_idle is default for WXT) 302 302 - sendStateUpdate(null); // Initial state with no selection 303 303 - ``` 304 304 - 305 305 - #### Snapshot Responder 306 306 - 307 307 - ```typescript 308 308 - browser.runtime.onMessage.addListener((message, sender, sendResponse) => { 309 309 - if (message.type === 'GET_TAB_SNAPSHOT') { 310 310 - sendResponse({ 311 311 - url: window.location.href, 312 312 - title: document.title, 313 313 - selection: currentSelection, 314 314 - }); 315 315 - return true; 316 316 - } 317 317 - 318 318 - // Keep existing handlers: UPDATE_HIGHLIGHTS, CLEAR_HIGHLIGHTS 319 319 - // ... 320 320 - }); 321 321 - ``` 322 322 - 323 323 - #### Remove Old GET_SELECTION Handler 324 324 - 325 325 - ```typescript 326 326 - // DELETE THIS: 327 327 - // if (message.type === 'GET_SELECTION') { 328 328 - // sendResponse({ 329 329 - // selection: currentSelection, 330 330 - // url: window.location.href, 331 331 - // title: document.title 332 332 - // }); 333 333 - // return true; 334 334 - // } 335 335 - ``` 336 336 - 337 337 - ### 4. Sidepanel Refactor 338 338 - 339 339 - **File**: `entrypoints/sidepanel/main.ts` 340 340 - 341 341 - #### Port Connection & Tab Registration 342 342 - 343 343 - ```typescript 344 344 - let currentTabId: number | null = null; 345 345 - let backgroundPort: chrome.runtime.Port | null = null; 346 346 - 347 347 - // On mount 348 348 - (async function() { 349 349 - // Get current tab 350 350 - const tabs = await browser.tabs.query({ active: true, currentWindow: true }); 351 351 - currentTabId = tabs[0]?.id || null; 352 352 - 353 353 - if (!currentTabId) { 354 354 - console.error('No active tab found'); 355 355 - return; 356 356 - } 357 357 - 358 358 - // Connect to background via port 359 359 - backgroundPort = browser.runtime.connect({ name: 'sidepanel' }); 360 360 - 361 361 - // Register this sidepanel with the tab 362 362 - backgroundPort.postMessage({ 363 363 - type: 'REGISTER_TAB', 364 364 - tabId: currentTabId, 365 365 - }); 366 366 - 367 367 - // Request initial state 368 368 - browser.runtime.sendMessage({ 369 369 - type: 'GET_TAB_STATE', 370 370 - tabId: currentTabId, 371 371 - }).then(response => { 372 372 - if (response.success) { 373 373 - updateUIState(response.state); 374 374 - } else { 375 375 - // Show friendly message for restricted pages 376 376 - showRestrictedPageMessage(response.error); 377 377 - } 378 378 - }); 379 379 - 380 380 - // Listen for state changes via port 381 381 - backgroundPort.onMessage.addListener((message) => { 382 382 - if (message.type === 'TAB_STATE_CHANGED' && message.tabId === currentTabId) { 383 383 - updateUIState(message.state); 384 384 - } 385 385 - }); 386 386 - })(); 387 387 - 388 388 - function updateUIState(state: { url: string; title: string; selection: any }) { 389 389 - // Update currentUrl 390 390 - if (currentUrl !== state.url) { 391 391 - currentUrl = state.url; 392 392 - loadAnnotations(currentUrl); // Reload annotations for new URL 393 393 - } 394 394 - 395 395 - // Update currentSelection 396 396 - currentSelection = state.selection; 397 397 - 398 398 - if (currentSelection && currentSelection.text && selectedTextEl) { 399 399 - selectedTextEl.innerHTML = `<blockquote>${currentSelection.text}</blockquote>`; 400 400 - if (annotationForm) annotationForm.style.display = 'block'; 401 401 - } else { 402 402 - if (annotationForm) annotationForm.style.display = 'none'; 403 403 - } 404 404 - } 405 405 - 406 406 - function showRestrictedPageMessage(error: string) { 407 407 - if (annotationsContainer) { 408 408 - annotationsContainer.innerHTML = ` 409 409 - <p class="error">This page doesn't support annotations.</p> 410 410 - <p class="error-detail">${error}</p> 411 411 - `; 412 412 - } 413 413 - if (annotationForm) annotationForm.style.display = 'none'; 414 414 - } 415 415 - ``` 416 416 - 417 417 - #### Remove Old Initialization Code 418 418 - 419 419 - ```typescript 420 420 - // DELETE THIS (lines 187-207): 421 421 - // browser.tabs.query({ active: true, currentWindow: true }).then(tabs => { 422 422 - // if (tabs[0]?.id) { 423 423 - // browser.tabs.sendMessage(tabs[0].id, { type: 'GET_SELECTION' }).then(response => { 424 424 - // currentUrl = response.url; 425 425 - // currentSelection = response.selection; 426 426 - // // ... 427 427 - // }).catch(err => { 428 428 - // console.error('Failed to get selection:', err); 429 429 - // }); 430 430 - // } 431 431 - // }); 432 432 - ``` 433 433 - 434 434 - #### Keep SELECTION_CHANGED Listener (for backward compatibility during transition) 435 435 - 436 436 - ```typescript 437 437 - // Can remove this once background state is fully working 438 438 - browser.runtime.onMessage.addListener((message) => { 439 439 - if (message.type === 'SELECTION_CHANGED') { 440 440 - // Deprecated: background should handle this now 441 441 - console.warn('Deprecated SELECTION_CHANGED message received'); 442 442 - } 443 443 - }); 444 444 - ``` 445 445 - 446 446 - ## Message Protocol Summary 447 447 - 448 448 - ### Content → Background 449 449 - - **TAB_STATE_UPDATE**: `{ type, url, title, selection, updatedAt }` 450 450 - 451 451 - ### Sidepanel → Background 452 452 - - **GET_TAB_STATE**: `{ type, tabId }` 453 453 - - **REGISTER_TAB** (via port): `{ type, tabId }` 454 454 - 455 455 - ### Background → Sidepanel 456 456 - - **TAB_STATE_CHANGED** (via port): `{ type, tabId, state: { url, title, selection, updatedAt } }` 457 457 - 458 458 - ### Background → Content 459 459 - - **GET_TAB_SNAPSHOT**: `{ type }` → Response: `{ url, title, selection }` 460 460 - - **CLEAR_HIGHLIGHTS**: `{ type }` (on URL change) 461 461 - 462 462 - ## Testing Checklist 463 463 - 464 464 - - [ ] Initial page load: sidepanel shows correct URL and no selection 465 465 - - [ ] Text selection: sidepanel updates within 250ms 466 466 - - [ ] Clear selection: sidepanel hides annotation form 467 467 - - [ ] SPA navigation (pushState): URL updates, selection clears, highlights clear 468 468 - - [ ] Traditional navigation: URL updates, selection clears 469 469 - - [ ] Service worker suspend/resume: state persists via storage.session 470 470 - - [ ] Restricted pages (chrome://, PDFs): friendly error message shown 471 471 - - [ ] Multi-tab: each sidepanel only receives updates for its tab 472 472 - - [ ] Selections in input/textarea: ignored 473 473 - - [ ] Rapid selection changes: debounced correctly 474 474 - 475 475 - ## Rollout Strategy 476 476 - 477 477 - 1. **Phase 1**: Add webNavigation permission and background state manager 478 478 - 2. **Phase 2**: Update content script with debouncing and snapshot responder 479 479 - 3. **Phase 3**: Update sidepanel to use ports and new protocol 480 480 - 4. **Phase 4**: Remove deprecated GET_SELECTION handler and SELECTION_CHANGED broadcasts 481 481 - 5. **Phase 5**: Test thoroughly, especially SPA navigation and service worker suspension 482 482 - 483 483 - ## Performance Considerations 484 484 - 485 485 - - **Debouncing**: 250ms prevents excessive message spam 486 486 - - **Throttled storage writes**: Max 1 write/sec per tab to `storage.session` 487 487 - - **Selector generation**: Only on stable selections (after debounce or pointer events) 488 488 - - **Port-based communication**: Keeps SW alive, avoids message routing overhead 489 489 - 490 490 - ## Edge Cases Handled 491 491 - 492 492 - 1. **Service worker suspension**: State persists in `storage.session`, restored on wake 493 493 - 2. **Content script not ready**: Background falls back to snapshot request 494 494 - 3. **Restricted pages**: Graceful error message shown to user 495 495 - 4. **Stale updates**: Timestamped updates prevent out-of-order state changes 496 496 - 5. **Cross-tab contamination**: Port-based delivery ensures tab isolation 497 497 - 6. **Editable fields**: Selections inside inputs/textareas are ignored 498 498 - 7. **Multi-frame pages**: Only top frame (frameId === 0) is tracked 499 499 - 500 500 - ## Future Enhancements (Out of Scope) 501 501 - 502 502 - - Multi-frame annotation support (include frameId in state) 503 503 - - Cross-session recovery (persist to `storage.local`) 504 504 - - Incremental selector generation for performance 505 505 - - Multi-tab sidepanel support with dynamic tab switching 506 506 - 507 507 - ## References 508 508 - 509 509 - - [Chrome Extension Messaging](https://developer.chrome.com/docs/extensions/mv3/messaging/) 510 510 - - [Service Worker Lifecycle](https://developer.chrome.com/docs/extensions/mv3/service_workers/) 511 511 - - [chrome.storage.session API](https://developer.chrome.com/docs/extensions/reference/storage/#property-session) 512 512 - - [webNavigation API](https://developer.chrome.com/docs/extensions/reference/webNavigation/)