# Intelligent Workspace

> Intelligent Workspace is an advanced Manifest V3 browser extension and productive workspace environment built with Svelte, Vite, and CRXJS. It orchestrates intelligent tab organization, automated and rule-based clustering, autonomous AI agent execution (supporting Google Gemini Cloud API and Chrome Built-in Prompt API), in-page Vim-style link navigation, a 41-prefix Omnibar command system, multi-format note-taking (rich text, checklists, Kanban, Mermaid diagrams, KaTeX formulas), high-fidelity media capture and in-browser WASM OCR, Pomodoro timing with zero-drift alarms and offscreen audio playback, and Declarative Net Request (DNR) web activity metering, domain limits, and site blocking.

---

## Multilingual Editions / Global Directory

This technical specification is available in the top 25 languages worldwide:

| Language | Native Name | ISO Code | Specification Link |
| :--- | :--- | :--- | :--- |
| **English** (Master) | English | `en` | [llms.txt](/llms.txt) |
| **Mandarin Chinese** | 简体中文 | `zh` | [llms-zh.txt](/llms-zh.txt) |
| **Hindi** | हिन्दी | `hi` | [llms-hi.txt](/llms-hi.txt) |
| **Spanish** | Español | `es` | [llms-es.txt](/llms-es.txt) |
| **French** | Français | `fr` | [llms-fr.txt](/llms-fr.txt) |
| **Modern Standard Arabic** | العربية | `ar` | [llms-ar.txt](/llms-ar.txt) |
| **Bengali** | বাংলা | `bn` | [llms-bn.txt](/llms-bn.txt) |
| **Brazilian Portuguese** | Português (Brasil) | `pt` | [llms-pt.txt](/llms-pt.txt) |
| **Russian** | Русский | `ru` | [llms-ru.txt](/llms-ru.txt) |
| **Urdu** | اردو | `ur` | [llms-ur.txt](/llms-ur.txt) |
| **Indonesian** | Bahasa Indonesia | `id` | [llms-id.txt](/llms-id.txt) |
| **German** | Deutsch | `de` | [llms-de.txt](/llms-de.txt) |
| **Japanese** | 日本語 | `ja` | [llms-ja.txt](/llms-ja.txt) |
| **Marathi** | मराठी | `mr` | [llms-mr.txt](/llms-mr.txt) |
| **Telugu** | తెలుగు | `te` | [llms-te.txt](/llms-te.txt) |
| **Turkish** | Türkçe | `tr` | [llms-tr.txt](/llms-tr.txt) |
| **Tamil** | தமிழ் | `ta` | [llms-ta.txt](/llms-ta.txt) |
| **Vietnamese** | Tiếng Việt | `vi` | [llms-vi.txt](/llms-vi.txt) |
| **Tagalog / Filipino** | Tagalog / Filipino | `tl` | [llms-tl.txt](/llms-tl.txt) |
| **Korean** | 한국어 | `ko` | [llms-ko.txt](/llms-ko.txt) |
| **Persian / Farsi** | فارسی | `fa` | [llms-fa.txt](/llms-fa.txt) |
| **Hausa** | Harshen Hausa | `ha` | [llms-ha.txt](/llms-ha.txt) |
| **Swahili** | Kiswahili | `sw` | [llms-sw.txt](/llms-sw.txt) |
| **Italian** | Italiano | `it` | [llms-it.txt](/llms-it.txt) |
| **Punjabi** | ਪੰਜਾਬੀ | `pa` | [llms-pa.txt](/llms-pa.txt) |

---

## Navigation & Quick Reference Index

- [1. Architectural Foundation & Runtime Lifecycle](#1-architectural-foundation--runtime-lifecycle)
- [2. Section 1: Rules Management (Gestionar Reglas)](#2-section-1-rules-management-gestionar-reglas)
  - [2.1 Data Schema (`CustomRule`)](#21-data-schema-customrule)
  - [2.2 Precedence Architecture](#22-precedence-architecture)
  - [2.3 URL Normalization & Matching Semantics](#23-url-normalization--matching-semantics)
  - [2.4 Rules Management Settings Breakdown](#24-rules-management-settings-breakdown)
  - [2.5 Operations & Persistence (`mutateRulesAndSync`)](#25-operations--persistence-mutaterulesandsync)
  - [2.6 Invocation Modalities](#26-invocation-modalities)
- [3. Section 2: Group Listing & Operations (Listar Grupos)](#3-section-2-group-listing--operations-listar-grupos)
  - [3.1 UI Architecture](#31-ui-architecture)
  - [3.2 Group Lifecycle & Behaviors](#32-group-lifecycle--behaviors)
  - [3.3 Group Operations & Memory Management](#33-group-operations--memory-management)
  - [3.4 Group Backups & Restore Subsystem](#34-group-backups--restore-subsystem)
  - [3.5 Parked YouTube Player in Hidden Groups Bar](#35-parked-youtube-player-in-hidden-groups-bar)
- [4. Section 3: Navigation & Tab Management (Navegación)](#4-section-3-navigation--tab-management-navegación)
  - [4.1 Fast Tab Jump Gesture](#41-fast-tab-jump-gesture)
  - [4.2 Stepping, Swapping & Lifecycle Keys](#42-stepping-swapping--lifecycle-keys)
  - [For power users](#for-power-users)
  - [4.3 Audio & Sound Management](#43-audio--sound-management)
  - [4.4 Split Screen Workflows](#44-split-screen-workflows)
  - [4.5 YouTube Looping Subsystem](#45-youtube-looping-subsystem)
  - [4.6 YouTube Shorts Preview Audio](#46-youtube-shorts-preview-audio)
  - [4.7 Picture-in-Picture (PiP) Architecture](#47-picture-in-picture-pip-architecture)
  - [4.8 Page Reading Modes & Visual Overlays](#48-page-reading-modes--visual-overlays)
  - [4.9 Text Snippets Subsystem with Template Variables](#49-text-snippets-subsystem-with-template-variables)
  - [4.10 Embedded Productivity Tools](#410-embedded-productivity-tools)
  - [4.11 Comprehensive 3-Tier Duplicate Removal & Intelligent Discarding](#411-comprehensive-3-tier-duplicate-removal--intelligent-discarding)
- [5. Section 4: AI Assistant & Autonomous Agent (Asistente AI)](#5-section-4-ai-assistant--autonomous-agent-asistente-ai)
  - [5.1 Dual Model Engine Architecture](#51-dual-model-engine-architecture)
  - [5.2 Autonomous Browser Agent (`agent-backend.js`)](#52-autonomous-browser-agent-agent-backendjs)
  - [5.3 Taint Tracking & Prompt Injection Defense](#53-taint-tracking--prompt-injection-defense)
  - [5.4 Scheduled Gemini Queries Subsystem (`GeminiScheduleModal.svelte`)](#54-scheduled-gemini-queries-subsystem-geminischedulemodalsvelte)
  - [5.5 Gemini Conversation Management & Export](#55-gemini-conversation-management--export)
  - [5.6 Multimodal Inputs & File Attachments (`feature_geminiAttachFiles`)](#56-multimodal-inputs--file-attachments-feature_geminiattachfiles)
  - [5.7 Invocation Modalities](#57-invocation-modalities)
- [6. Section 5: Notes View & Knowledge Management (Ver Notas)](#6-section-5-notes-view--knowledge-management-ver-notas)
  - [6.1 Storage Architecture (`notesStore`)](#61-storage-architecture-notesstore)
  - [6.2 Specialized Note Formats & Advanced Rendering](#62-specialized-note-formats--advanced-rendering)
  - [6.3 Scoping & Context Hierarchy](#63-scoping--context-hierarchy)
  - [6.4 Invocation Modalities](#64-invocation-modalities)
- [7. Section 6: Media & Gallery View (Ver Galería)](#7-section-6-media--gallery-view-ver-galería)
  - [7.1 Capture Modes & Engineering (All 7 Capture Types)](#71-capture-modes--engineering-all-7-capture-types)
  - [7.2 Gallery UI & Persistence](#72-gallery-ui--persistence)
  - [7.3 Export, In-Browser OCR & External Markup](#73-export-in-browser-ocr--external-markup)
  - [7.4 Invocation Modalities](#74-invocation-modalities)
- [8. Section 7: Pomodoro & Timing Suite (Pomodoro)](#8-section-7-pomodoro--timing-suite-pomodoro)
  - [8.1 Timing Engine & Background Architecture](#81-timing-engine--background-architecture)
  - [8.2 Exhaustive 4 Timing Modes](#82-exhaustive-4-timing-modes)
  - [8.3 In-Page Floating Timer Widget](#83-in-page-floating-timer-widget)
  - [8.4 Group Auto-Collapse Idle Timer](#84-group-auto-collapse-idle-timer)
  - [8.5 Project Tagging & Metadata](#85-project-tagging--metadata)
  - [8.6 Analytics Engine & 19 KPI Cards](#86-analytics-engine--19-kpi-cards)
- [9. Section 8: Activity & History Panel (Panel de Actividad)](#9-section-8-activity--history-panel-panel-de-actividad)
  - [9.1 Data Engine & Storage Topology (`ITG_WEB_ACTIVITY`)](#91-data-engine--storage-topology-itg_web_activity)
  - [9.2 Declarative Net Request (DNR) Site Blocker](#92-declarative-net-request-dnr-site-blocker)
  - [9.3 Asymmetric Security Lock (`blockLock.js`)](#93-asymmetric-security-lock-blocklockjs)
  - [9.4 Categorization & Visual Analytics](#94-categorization--visual-analytics)
  - [9.5 Downloads Manager Subsystem (`switchMainView('downloads')`)](#95-downloads-manager-subsystem-switchmainviewdownloads)
  - [9.6 Recently Closed Tabs & Browsing History Subsystem](#96-recently-closed-tabs--browsing-history-subsystem)
  - [9.7 Theme Scheduling Subsystem (`ThemeScheduleModal.svelte`)](#97-theme-scheduling-subsystem-themeschedulemodalsvelte)
  - [9.8 Compact Sidepanel View](#98-compact-sidepanel-view)
- [10. Multi-Modal Invocation Matrix](#10-multi-modal-invocation-matrix)
  - [10.1 Popup UI Interface](#101-popup-ui-interface)
  - [10.2 Sidepanel Navigation Routes (`?view=...`)](#102-sidepanel-navigation-routes-view)
  - [10.3 Manifest Keyboard Shortcuts (24 Commands)](#103-manifest-keyboard-shortcuts-24-commands)
  - [10.4 In-Page Vim Hint Keys (40+ Combinations)](#104-in-page-vim-hint-keys-40-combinations)
  - [10.5 In-Page Omnibar Subsystem Prefixes (41 Prefixes)](#105-in-page-omnibar-subsystem-prefixes-41-prefixes)
  - [10.6 Context Menu Tree Hierarchy (All 5 Groups & 30+ Actions)](#106-context-menu-tree-hierarchy-all-5-groups--30-actions)
- [11. Storage Schemas & Data Persistence](#11-storage-schemas--data-persistence)
  - [11.1 IndexedDB Database: `Intelligent_Workspace` (Schema Version 8)](#111-indexeddb-database-intelligent_workspace-schema-version-8)
  - [11.2 Chrome Storage Dual-Routing (`StorageService`)](#112-chrome-storage-dual-routing-storageservice)
  - [11.3 Chrome Storage Session (`chrome.storage.session`)](#113-chrome-storage-session-chromestoragesession)
- [12. Defensive Engineering & Edge Case Handling](#12-defensive-engineering--edge-case-handling)

---

## 1. Architectural Foundation & Runtime Lifecycle

The extension runs under Google Chrome's Manifest V3 architecture, decoupling persistent processes across a background Service Worker, sandboxed UI panels, offscreen audio documents, and in-page content script overlays:

1. **Manifest Configuration (`manifest.json`)**:
   - **Permissions (21 items)**: `tabs`, `tabGroups`, `storage`, `favicon`, `contextMenus`, `notifications`, `sidePanel`, `scripting`, `downloads`, `downloads.open`, `system.display`, `declarativeNetRequestWithHostAccess`, `cookies`, `history`, `sessions`, `bookmarks`, `readingList`, `clipboardWrite`, `alarms`, `offscreen`, and `idle`.
   - **Host Permissions**: `["<all_urls>"]`.
   - **Service Worker**: `src/core/background.js` using synchronous `importScripts` modular loading.
   - **Toolbar Action**: Deliberately omits `default_popup`. Runtime enforces `chrome.action.setPopup({ popup: '' })`, ensuring `chrome.action.onClicked` fires synchronously and opens `chrome.sidePanel` to the user's pinned view without popup initialization latency.
   - **Omnibox Keyword**: Registered keyword `"find"`.
   - **Commands**: 24 system-level keyboard shortcuts registered under `commands`.
   - **Content Security Policy**: `script-src 'self' 'wasm-unsafe-eval'; object-src 'self';`.

2. **Inter-Process Communication Security**:
   - `src/core/background/messaging.js` filters messages from content scripts against an explicit whitelist (`ALLOWED_CONTENT_SCRIPT_ACTIONS`). Unprivileged web frames cannot invoke internal storage writers, arbitrary Chrome APIs, or rule mutators.

3. **Dual Execution Worlds**:
   - Content scripts operate across both `ISOLATED` (extension scope) and `MAIN` (page execution scope) worlds. Scripts like `allowRightClickHook.js`, `videoPipHook.js`, `youtubePreviewAudioHook.js`, and `youtubeShortsFeedHook.js` run in `MAIN` to intercept prototype methods, override property descriptors, and handle custom events directly.

---

## 2. Section 1: Rules Management (Gestionar Reglas)

The Rules Management subsystem automates tab grouping based on strict deterministic criteria defined by the user.

### 2.1 Data Schema (`CustomRule`)
Each custom rule adheres to the following interface:
```typescript
interface CustomRule {
  name: string;        // 1 to 16 characters. Must contain no whitespace characters.
  color: RuleColor;    // One of 9 colors: 'grey' | 'blue' | 'red' | 'yellow' | 'green' | 'pink' | 'purple' | 'cyan' | 'orange'
  urls: string[];      // Array of valid URLs, domains, or hostnames.
  active: boolean;     // Master toggle enabling or disabling rule evaluation.
  isStarred?: boolean; // Optional flag marking rule as a favorite for prioritized UI ordering.
}
```

### 2.2 Precedence Architecture
When tabs are processed by `groupTabs()` in `src/core/background/groupManager.js`, tabs are evaluated against grouping layers in strict hierarchical order:
1. **Custom Rules (`applyCustomRules`)**: Matches active custom rules in order of appearance or user priority. Once grouped, tab IDs are registered in `groupedTabIds` and excluded from subsequent layers.
2. **Special System Groups**: System URLs are intercepted and clustered into dedicated colored groups:
   - `chrome://` and internal browser pages
   - `file:///` local disk files
   - `chrome-extension://` extension pages
   - IP Addresses & Localhost (`localhost`, `127.0.0.1`, `[::1]`, IPv4/IPv6 hosts)
3. **Domain Clustering**: Tabs sharing the same root domain are grouped if the tab count meets or exceeds `domainThreshold` (default: 2 tabs).
4. **Subdomain Clustering**: If enabled, tabs within domains are grouped by specific subdomains (e.g., `docs.github.com` vs `gist.github.com`).
5. **Miscellaneous ("Misc") Group**: Residual unclustered tabs that do not meet grouping thresholds are placed into the `Misc` group (placement configurable: `start`, `end`, or alphabetical `alpha`).

### 2.3 URL Normalization & Matching Semantics
The matching engine (`matchesRule(tabUrl, ruleUrl)` in `src/core/background/utils.js`) applies rigorous normalization:
- **Scheme Agnostic**: HTTP and HTTPS protocols are treated as interchangeable (`http://example.com` matches `https://example.com`). Non-web protocols (`file://`, `chrome://`) require exact scheme matches.
- **Host Normalization**: Leading `www.` prefixes are stripped (`www.github.com` normalizes to `github.com`). Hostnames are lowercased and support internationalized domain names (IDNs) via punycode.
- **Port Sensitivity**: If a rule specifies a port (e.g., `localhost:3000`), the tab must match that exact port.
- **Path Matching**: Trailing slashes are stripped. If a rule specifies a path (e.g., `example.com/docs`), it matches tabs with that exact path OR subpaths (`example.com/docs/api`), but does not match sibling paths (`example.com/blog`).
- **Query & Hash Matching**: If a rule explicitly contains a query string (`?page=1`) or hash (`#section`), the tab must match those parameters verbatim.
- **Numeric Dword Protection (`ruleValidation.js`)**: The validator strictly rejects bare numeric inputs (e.g., `3242342424`) that WHATWG URL parsers treat as valid IPv4 integer DWORDs, preventing accidental grouping distortions.

### 2.4 Rules Management Settings Breakdown
The Rules Manager provides an exhaustive suite of behavioral controls and settings:
- **Storage Routing Selection**: Users can route rule storage between `chrome.storage.sync` (for synchronized settings across all devices signed into the Google profile, subject to Chrome sync quotas of 100 KB total and 8 KB per item) and `chrome.storage.local` (for unlimited local capacity suitable for large rule sets containing hundreds of patterns).
- **Clustering Master Toggle & Thresholds**:
  - `toggle-clustering`: Master keyboard shortcut and UI toggle enabling or disabling automated domain/subdomain clustering without disabling user-created custom rules.
  - `domainThreshold`: Minimum tab count required from the same domain to trigger an automatic tab group (default: 2 tabs). Configurable from 1 to 50.
  - `subdomainThreshold`: Minimum tab count for subdomains before creating separated subgroup clusters.
  - Subdomain toggle (`toggle-subdomain-grouping`): Distinguishes independent subdomains (e.g., `news.ycombinator.com` vs `ycombinator.com`).
- **Auto-Sort Groups Alphabetically (`toggle-sort-alpha`)**: Real-time sorting engine enforcing alphabetical ordering across all open tab groups in the browser tab strip (`Ctrl+Shift+S` / `Cmd+Shift+S`).
- **Visual Status Prefixes (`toggle-prefixes`)**: Emoji markers dynamically prepended to group titles to indicate inspection state:
  - `🔒` (Lock): The group contains unvisited, unread tabs.
  - `🔍` (Loupe): The group contains partially visited tabs.
  - `🗝️` (Open Key): All tabs in the group have been opened and reviewed.
  - `⚠️` (Warning): Duplicate group name collision detected with another window group.
- **Auto-Collapse Idle Groups (`toggle-collapse-timer`)**: Automatically collapses groups when inactive to maintain a tidy tab strip.
- **Master Pause Grouping (`feature_pauseGrouping`)**: Master freeze switch that temporarily suspends all automated grouping operations (both rule matches and heuristic clustering) during active research sessions where tabs should remain in arbitrary user arrangements.
- **Single Tab Grouping (`featureSingleTabGrouping`)**: Allows custom rules to immediately create a tab group for a single matching tab, bypassing the multi-tab threshold requirement.
- **Compact View (`toggle-compact-mode`)**: Minimizes tab header width in the browser tab strip by rendering only single-letter badges for group titles.
- **Drag-and-Drop Priority**: Reordering rules in the `Rules.svelte` list instantly changes their evaluation precedence. Rules at the top evaluate first.
- **Fuzzy Search**: Live filtering in the Rules Manager and Omnibar allowing instant location of rules by title or matching URL patterns.
- **JSON Import / Export**:
  - Mode `add`: Merges imported rules into the existing collection, discarding duplicates.
  - Mode `overwrite`: Completely replaces the active rule collection with the imported payload after schema validation.
- **Dynamic Rule Creation**: One-click creation of custom rules directly from Chrome bookmark folders or subgroup domain collections.
- **Rule Deduplication (`feature_v100_dedup_add_to_rule`)**: Automatically strips duplicate URL patterns when adding URLs or domains to existing custom rules, preventing rule inflation and redundant evaluations.

### 2.5 Operations & Persistence (`mutateRulesAndSync`)
- **Centralized Mutator**: All rule modifications route through `mutateRulesAndSync(mutateFn, sendResponse)` in `src/core/background/handlers/rules.js`. This guarantees storage synchronization, in-memory cache refreshment (`extensionSettings.customRules`), UI notification (`rulesUpdated`), and automatic tab regrouping (`groupTabs()`).
- **Live Validation**: Real-time validation checks for name uniqueness, length (1-16 chars), character restrictions, and valid URL syntax before saving.

### 2.6 Invocation Modalities
- **Rules Manager Page (`Rules.svelte`)**: Accessible in full-tab view or side panel (`?view=rules` / `pg`). Provides full drag-and-drop reordering, inline color picker, URL tag chips, and rule toggles.
- **Omnibar Commands**:
  - `rl:` — Search rules and open associated URLs.
  - `cr: <name> [, url1, url2]` — Create a new rule directly from the command bar.
  - `atcr:` — Add the active tab's domain or URL to an existing rule.
  - `atr:` — Add selected open tabs or manual URLs to an existing rule.
  - `ccr:` — Change the color of a custom rule.
  - `dr:` — Delete rules or individual URLs from a rule.
  - `er:` — Edit or rename an existing rule.
- **Context Menus**:
  - Right-click page -> "Crear Regla para esta Página" -> "Añadir Raíz del Sitio" / "Añadir URL Completa".
  - Right-click page -> "Añadir a Regla Existente" -> Select rule -> "Añadir Raíz del Sitio" / "Añadir URL Completa".
  - Right-click page -> "Reglas" -> Toggle active state, open all rule URLs, or close matching tabs.
- **Keyboard Shortcuts**:
  - `Alt+R`: Open Rules Manager.
  - `Alt+M`: Toggle activation of all rules simultaneously (`toggle-all-rules`).

---

## 3. Section 2: Group Listing & Operations (Listar Grupos)

The Group Listing view provides an interactive workspace for inspecting, manipulating, and reordering browser tab groups and individual tabs.

### 3.1 UI Architecture
- **Component Stack**: Built with `ListGroup.svelte`, `GroupCard.svelte`, `GroupActions.svelte`, `TabItem.svelte`, and `TabActions.svelte`.
- **Card Features**: Displays group title, color badge, tab count pill, collapse/expand accordion toggle, card pinning, and customizable action button groups.
- **Tab Items**: Displays tab favicon with color fallback, title, audible sound badge, mute indicator, active state indicator, and per-tab actions (close, duplicate, pin, split, discard).

### 3.2 Group Lifecycle & Behaviors
- **Accordion Control**: Smooth expand and collapse states. Optional auto-accordion mode automatically collapses idle groups when a new group is expanded.
- **Inactivity Auto-Collapse Idle Timer**:
  - Automatically collapses idle tab groups to reduce visual clutter.
  - Two distinct thresholds: Inactive groups collapse after 1 minute of inactivity (`INACTIVITY_THRESHOLD_INACTIVE_GROUP`), while the active group collapses after 15 minutes of inactivity (`INACTIVITY_THRESHOLD_ACTIVE_GROUP`). Configurable from 0 to 1440 minutes.
- **Inline Renaming & Grace Period**:
  - Users can rename groups directly in the browser tab strip or UI.
  - `GROUP_NAMING_GRACE_MS` (5000ms) pauses automatic regrouping while a user edits, preventing title overwrites mid-typing.
  - Zero-width spaces (`\u200B`, `\u200C`, `\u200D`, `\u2060`, `\uFEFF`) are stripped during evaluation.
  - Renaming an automatically generated group converts it to a user-named group, updating the corresponding custom rule or marking it permanent.
- **Visual Group Prefix Indicators**:
  - Dynamically prepends status symbols: `🔒` (unvisited), `🔍` (partial), `🗝️` (all viewed), `⚠️` (collision).
- **Drag-and-Drop Reordering**: Integrated with `sortable.js` for reordering tabs within groups, moving tabs between groups, or reordering group cards.
- **Hidden Groups Feature**:
  - Prefixes group title with `_hidden_` in the browser tab strip.
  - Hides group cards from the main list view, transferring them to `HiddenGroupsBar.svelte`.
  - Users can unhide or restore groups instantly with a single click.

### 3.3 Group Operations & Memory Management
- **Ungroup**: Disbands the group, leaving tabs open in the window.
- **Close Group**: Closes all tabs in the group and releases the group ID.
- **Close Other Groups**: Closes all tab groups except the currently focused group.
- **Regroup All Tabs (`Alt+Shift+R`)**: Executes a comprehensive re-evaluation pass across custom rules, system groups, and domain clusters.
- **Group Screenshot Walk**: Sequentially cycles through and captures every tab in the group (`Cs` visible, `Cp` full page, `CP` full page parts).

### 3.4 Group Backups & Restore Subsystem
- **IndexedDB `backupsGroups` Store**:
  - Backs up single tab groups or workspace-wide snapshots of all open groups into IndexedDB `Intelligent_Workspace` store `backupsGroups`.
  - Captures complete group structures: group title, color, collapsed state, tab titles, URLs, favicons, pinned status, and relative tab positions.
  - **Memory Conservation**: Backed-up tabs are cleanly closed to reclaim system RAM and reduce CPU overhead.
  - **Restore Mechanisms**:
    - Backups UI View in `ListGroup.svelte` with one-click group restoration.
    - Keyboard shortcut `br` (restore) and `bg` (backup all).
    - Omnibar command `bgr:` (search and restore backed-up groups) and `b:` (bookmark search).
  - **JSON Export & Import**: Full JSON backup export and import for seamless migration between machines and long-term offline archiving.

### 3.5 Parked YouTube Player in Hidden Groups Bar
- **Architecture (`HiddenGroupsBar.svelte`)**:
  - When a user navigates away from an active YouTube video view or launches video content inside the side panel, the player is not closed or lost. It is automatically docked in `HiddenGroupsBar.svelte` as a parked YouTube indicator (`.youtube-indicator`).
  - Managed reactively via the `hiddenYoutubeView` store in `src/ui/stores/appStore.svelte.js`.
  - **One-Click Actions**:
    - Clicking the parked indicator invokes `restoreYoutubeView()`, returning the player immediately to the active workspace view.
    - Clicking the delete badge invokes `discardYoutubeView()`, cleanly terminating playback and reclaiming resources.
  - Sits seamlessly alongside hidden tab groups at the top of the ListGroup view without cluttering active tab lists.

---

## 4. Section 3: Navigation & Tab Management (Navegación)

Accelerated keyboard navigation and workspace controls allow seamless multi-tab control without mouse interaction.

### 4.1 Fast Tab Jump Gesture
- **Gesture Syntax**: `Alt + [groupPrefix] + [tabIndex] + Enter`
- **Execution**:
  - Hold `Alt` and type the group's name or prefix letters, followed by the desired 1-based tab index, then press `Enter`.
  - Example: `Alt + git + 2 + Enter` jumps directly to the second tab in the "GitHub" group.
  - Index `0` acts as a shortcut for the *last* tab in the group.
  - Omitting the index jumps to the *first* tab in the group.
  - Accents are automatically folded (`deaccent`) and matching normalizes diacritics.

### 4.2 Stepping, Swapping & Lifecycle Keys
- `s`: Instantly swap to the previously active tab (`previousActiveTabId`).
- `h` / `l`: Step to the previous / next tab (or scroll horizontally if the page allows).
- `H` / `L`: Navigate back / forward in browser history.
- `t`: Open a new blank tab.
- `x`: Close the current active tab.
- `yt`: Duplicate the current tab.
- `r` / `R`: Reload page / Force reload bypassing cache.
- `d` / `u`: Scroll to bottom / top of page.
- `j` / `k`: Smooth scroll down / up (75px step).
- `f`: Activate Vim link hints (letters appear over clickable elements to click).
- `cf`: Activate Vim link hints to copy target URL to clipboard.

### ਉੱਨਤ ਉਪਭੋਗਤਾਵਾਂ ਲਈ (For power users)

ਵਧੇਰੇ ਉੱਨਤ ਉਪਭੋਗਤਾ ਬ੍ਰਾਊਜ਼ਰ ਨੂੰ ਪੂਰੀ ਸਕ੍ਰੀਨ ਮੋਡ ਵਿੱਚ ਰੱਖ ਸਕਦੇ ਹਨ ਅਤੇ ਮਾਊਸ ਦੀ ਵਰਤੋਂ ਕੀਤੇ ਬਿਨਾਂ ਪੂਰੀ ਤਰ੍ਹਾਂ ਕੀਬੋਰਡ ਨਾਲ ਨੈਵੀਗੇਟ ਕਰ ਸਕਦੇ ਹਨ।

#### Full-Screen Immersion & Mouse-Free Browsing
- **Toggle Full-Screen**: Press `F11` (Windows/Linux) or `Command+Control+F` (macOS). The browser chrome, address bar, tabs strip, and operating system panels are hidden, dedicating 100% of the display to content.
- **In-Page Vim Link Navigation (`f` / `cf`)**:
  - Press `f` to generate high-contrast two-character yellow link hints over every clickable element, button, input, and link in the DOM.
  - Type the two letters matching your target to simulate a direct click without mouse interaction.
  - Press `cf` to trigger hint badges that copy the target link's URL directly to your system clipboard.
  - Press `vp` to open an in-page preview modal of the target link.
  - Press `Esc` at any time to cancel link hints and return to normal scrolling.
- **Instant Tab Jumping & Switching**:
  - `Alt + [groupPrefix] + [tabIndex] + Enter`: Execute the Fast Tab Jump gesture (e.g., `Alt + dev + 1 + Enter` jumps directly to the first tab in the "Dev" group; index `0` selects the last tab in the group).
  - `s`: Instantly swap between the current tab and the previously active tab (`previousActiveTabId`).
  - `h` / `l`: Step sequentially to the previous / next tab in the tab strip.
  - `H` / `L`: Move backward / forward through browser navigation history.
  - `t` / `x` / `yt`: Open a new tab (`t`), close current tab (`x`), or duplicate tab (`yt`).
- **Floating Omnibar Command Subsystem (`o`)**:
  - Press `o` on any page to summon the centered Omnibar overlay.
  - Press `@` to display the interactive directory of all 41 command prefixes.
  - Type `f: <query>` to execute deep full-text tab search across all open windows.
  - Type `sp:` to route navigation directly into any Sidepanel view (`rules`, `listgroup`, `notes`, `gallery`, `gemini`, `activity`, `themes`, `hints`, `downloads`).
  - Type `qai: <query>` or `qaia: <task>` to query Gemini or instruct the autonomous browser agent without lifting hands from the keyboard.
  - Type `ts:` to split open tabs into side-by-side split screen.
- **In-Page Navigation & Focus**:
  - `j` / `k`: Smooth scroll down / up (75px increment).
  - `d` / `u`: Half-page scroll down / up.
  - `i`: Jump cursor focus immediately into the primary text input field on the page.
  - `ESC`: Unfocus inputs and return keyboard focus to navigation mode.

### 4.3 Audio & Sound Management
- Tabs playing audio display a speaker badge in the ListGroup UI.
- `st`: Toggle mute on the current active tab.
- `so`: Mute all audible tabs across the entire browser.
- Context menu: "Silenciar Todas las Pestañas" / "Reactivar Sonido en Todas las Pestañas".

### 4.4 Split Screen Workflows
- **Trigger**: Vim hint `ts` or Omnibar prefix `ts:`.
- **Behavior**: Uses `chrome.system.display` to calculate screen geometry. Splits two tabs side-by-side into adjacent windows, grouping them under a dedicated `Split` tab group.
- **Restoration**: Closing the split window or toggling split screen restores original window dimensions and coordinates.

### 4.5 YouTube Looping Subsystem
The YouTube looping subsystem provides precision media looping controls integrated directly into the YouTube player:
- **Desktop Player Button (`#itg-yt-loop-button`)**: Injected into the standard YouTube player control bar (`.ytp-right-controls`), positioned to the left of the Cast / Remote button or PiP launcher. Features animated SVG looping glyphs, toggle highlight styling (`ytp-loop-active`, `var(--interactive-color, #ff4444)`), and `aria-pressed` states.
- **Shorts Player Button (`#itg-yt-shorts-loop-button`)**: Injected inside `#itg-yt-shorts-loop-wrapper` into the YouTube Shorts right-side control column (`ytd-shorts`), providing one-click looping for vertical video content.
- **Loop Menu & PiP Popup (`#itg-yt-loop-menu` & `#itg-pip-loop-popup`)**: Hovering or clicking the loop button opens the comprehensive loop settings menu:
  - **A-B Looping**: Users can set custom start point (A) and end point (B) down to millisecond precision with interactive range sliders and manual time fields.
  - **Cycle Mode & Sequence Repetitions**: Set repetition count for specific loops or toggle infinite loop mode (`itg-loop-seq-inf`).
  - **Loop List & Multi-Segment Sequences**: Queue multiple A-B loop intervals that play consecutively according to configured repetitions.
  - **Status & Duration Display**: Shows real-time playback position within current loop interval and total media duration (`00:00 / 00:00`).
  - **Master Toggle (`youtubeLoopEnabled`)**: Persisted in `chrome.storage.sync` and `local`, allowing users to enable or disable the loop buttons across YouTube and YouTube Shorts via the Customize Hints settings page (`YoutubeLoopSection.svelte`).

### 4.6 YouTube Shorts Preview Audio
- **Audio Unmute Hook (`youtubePreviewAudioHook.js`)**:
  - Runs in the `MAIN` execution world to access the `#inline-preview-player` property on `ytd-video-preview` elements.
  - **Overcoming Forced Mute**: YouTube enforces a forced mute on Shorts previews by clearing audio controls and restoring `muted = true` via internal `volumechange` listeners.
  - The extension hooks `HTMLMediaElement.prototype.muted` property descriptor on the target `<video>` element on hover. It drops YouTube's forced re-mute while allowing user unmuting, ensuring sound plays continuously without being interrupted across loop restarts until mouse leave.

### 4.7 Picture-in-Picture (PiP) Architecture
- **Document Picture-in-Picture (`wp`)**:
  - Leverages the modern `documentPictureInPicture` API to open an entire webpage or text snippet inside an always-on-top floating window.
  - Automatically synchronizes video playback timestamps when transferring media.
  - Features retry logic (`itgRetryIfPipFrameRefused`) and cleans up DNR iframe headers upon close.
- **Video Picture-in-Picture (`wv`)**:
  - Hooks `HTMLVideoElement.prototype.requestPictureInPicture` via `videoPipHook.js`.
  - Redirects video players into custom PiP frames with loop controls and playback speed selectors.
- **Auto-PiP**:
  - `as`: Toggle Auto-PiP on scroll (launches video in PiP when scrolled out of viewport).
  - `ah`: Toggle Auto-PiP on tab hide (launches video in PiP when switching to another tab).

### 4.8 Page Reading Modes & Visual Overlays
- **CSS Filter Themes**: Injects non-destructive styles into web pages:
  - `mb` / `mB`: Black (Dark High-Contrast) — tab scope / global scope.
  - `ms` / `mS`: Sepia (Warm Paper) — tab scope / global scope.
  - `mp` / `mP`: Paper (Monochrome Grayscale) — tab scope / global scope.
  - `ml` / `mL`: Light (Soft White) — tab scope / global scope.
  - `me` / `mE`: Custom user-defined CSS filter — tab scope / global scope.
  - `ESC`: Immediately removes active page filter.
- **Reader Mode & TTS Read Aloud**:
  - `fetchContentForReaderView`: Extracts clean article content, removing advertisements, sidebars, and navigation noise.
  - Built-in Text-to-Speech (TTS) engine reading text aloud sentence by sentence.
  - Keyboard navigation controls: `zp` (play/pause), `zn` (next sentence), `zb` (previous sentence), `zq` (close reader overlay).

### 4.9 Text Snippets Subsystem with Template Variables
The Text Snippets subsystem (`SnippetManager` in `src/utils/hint/snippets.js` and `src/utils/snippet-panel.js`) accelerates typing by expanding text shortcuts in any input, textarea, or rich editor:
- **Trigger Modalities**: Type shortcut followed by Space, or type `$$` to summon the interactive snippets search popup.
- **Clipboard API Integration**: Supports formatted HTML and plain text insertion via the Clipboard API, ensuring 100% compatibility with complex editors like Google Docs, Notion, and Slack.
- **Template Variables**: Dynamically resolves variables at the moment of expansion:
  - `{{date}}` / `date`: Formatted locale date (`toLocaleDateString`).
  - `{{isodate}}` / `isodate`: ISO 8601 date (`YYYY-MM-DD`).
  - `{{longdate}}` / `longdate`: Long date with weekday, day, month, and year.
  - `{{time}}` / `time`: 2-digit formatted time (`HH:MM`).
  - `{{datetime}}` / `datetime`: Date and time combined.
  - `{{weekday}}` / `weekday`: Full day name (e.g., Monday).
  - `{{day}}` / `day`: Day of month (1-31).
  - `{{month}}` / `month`: Full month name (e.g., October).
  - `{{year}}` / `year`: Full 4-digit year.
  - `{{tomorrow}}` / `tomorrow`: Next day's date (+1 day).
  - `{{yesterday}}` / `yesterday`: Previous day's date (-1 day).
  - `{{nextweek}}` / `nextweek`: Date 7 days ahead (+7 days).
  - `{{timestamp}}` / `timestamp`: Epoch millisecond timestamp (`Date.now()`).
  - `{{url}}` / `url`: Active webpage URL (`window.location.href`).
  - `{{domain}}` / `domain`: Active domain hostname (`window.location.hostname`).
  - `{{pagetitle}}` / `pagetitle`: Active document title (`document.title`).
  - `{{uuid}}` / `uuid`: Cryptographically secure unique identifier (`crypto.randomUUID()`).
  - `{{random}}` / `random`: Random integer between 1 and 1000.
  - `{{clipboard}}` / `clipboard`: System clipboard buffer text.

### 4.10 Embedded Productivity Tools
- **Allow Right Click Hook (`allowRightClickHook.js`)**:
  - Injected into the `MAIN` execution world to neutralize hostile web scripts that disable right-click context menus, copy, cut, or text selection.
  - Intercepts `preventDefault()` and `stopPropagation()` on `contextmenu`, `copy`, `cut`, `selectstart`, `mousedown`, and `mouseup`.
  - Clears inline `oncontextmenu="return false"` handlers via a persistent `MutationObserver`.
  - Verifies clipboard payloads to prevent breaking legitimate web editors (Google Docs, Telegram Web).
- **Cookie Editor**: In-page modal inspecting, editing, creating, and deleting HTTP and HTTPS cookies for the active domain.
- **QR Code Generator**: Generates SVG/Canvas QR codes for the active tab URL for rapid mobile handover.
- **Clean PDF Print Export**: Routes target pages through `print.html` with headers, ads, and navigational noise stripped for clean document archiving.

### 4.11 Comprehensive 3-Tier Duplicate Removal & Intelligent Discarding
- **Comprehensive 3-Tier Duplicate Removal**:
  1. **Tab Deduplication (`removeDuplicateTabsCommand`)**: Scans open tabs across windows or focused groups, identifies duplicate URLs, exempts `Split` screen tabs, and closes redundant tabs while keeping the active or oldest tab. Displays a desktop summary notification.
  2. **Bookmark Deduplication**: Deep scans Chrome bookmark trees, locates identical URL duplicates across folders, and provides batch consolidation to keep bookmarks clean.
  3. **Rule Deduplication (`feature_v100_dedup_add_to_rule`)**: Automatically strips duplicate URL patterns when adding URLs to existing custom grouping rules, preventing rule inflation.
- **Intelligent Memory Discarding (`suspendInactiveTabsIntelligently`)**:
  - Evaluated every 1 minute via alarm `itg-periodic-tasks`.
  - Discards tabs inactive >= `discardingTimeMinutes` (default: 60 minutes).
  - Built-in immunity protections: Never discards active tabs, audible tabs playing audio, pinned tabs, or already suspended tabs.

---

## 5. Section 4: AI Assistant & Autonomous Agent (Asistente AI)

The AI Assistant integrates large language models into the browser to provide contextual understanding, automated workflows, and direct browser automation.

### 5.1 Dual Model Engine Architecture
1. **Google Gemini Cloud API (`gemini-api.js`)**:
   - Integrates with Google Generative Language REST endpoints (`v1beta/models/{model}:generateContent` and `:streamGenerateContent`).
   - Supports Gemini 2.5 Flash, Gemini 2.5 Pro, and custom model endpoints.
   - **Multi-Key Rotation**: Manages key pools in `geminiApiKeysList`. Storage obfuscation uses `enc_` prefixes.
   - **Exponential Backoff**: Handles HTTP 429 quota exhaustion with automated backoff retry (1.5s -> 3s -> 6s).
   - **Search Grounding**: Enables Google Search Grounding (`google_search: {}`). If HTTP 403 occurs due to quota restrictions on search tools, it automatically retries without grounding.
2. **Chrome Built-in AI / Prompt API (`localAiService.js`)**:
   - On-device Gemini Nano integration via `window.LanguageModel`.
   - Supports zero-network local execution. Includes model availability checking and live download progress tracking.

### 5.2 Autonomous Browser Agent (`agent-backend.js`)
The autonomous agent provides full browser control through 40+ structured tools:
- **Tab & Group Control**: `getOpenTabs`, `switchToTab`, `createNewTab`, `closeTab`, `closeTabs`, `duplicateTab`, `findAndSwitchToTab`, `groupTabs`, `ungroupTabs`, `deleteTabGroup`, `collapseTabGroup`, `expandTabGroup`, `collapseAllGroups`, `expandAllGroups`, `setGroupColor`, `renameTabGroup`, `regroupAllTabs`, `removeDuplicateTabs`, `closeTabsWithSound`.
- **Navigation & Search**: `openUrl`, `searchGoogle`, `getActiveTab`, `getActiveTabContent`.
- **Knowledge & Bookmarks**: `getBookmarks`, `searchBookmarks`, `createBookmark`, `getHistory`, `getRecentlyClosed`.
- **Rules & Appearance**: `getRules`, `createRule`, `updateRule`, `deleteRule`, `getActiveTheme`, `getSavedThemes`, `applyTheme`.

### 5.3 Taint Tracking & Prompt Injection Defense
To neutralize indirect prompt injection attacks from untrusted web pages, the agent backend implements strict taint tracking:
- **Taint Marking**: Calling `getActiveTabContent` extracts text from a web page and marks the current execution run as tainted (`taintedAgentRuns.add(runId)`).
- **Egress Guard**: Tainted runs are strictly prohibited from invoking egress tools (`AGENT_EGRESS_TOOLS`):
  * `openUrl`, `searchGoogle`, `createBookmark`, `createRule`, `addUrlToRule`, `createSiteShortcut`, `updateSiteShortcut`, `updateRule`.
- **Refusal Mechanism**: Rather than throwing an unhandled exception, the engine returns a structured security explanation. The LLM then informs the user that external data cannot be exfiltrated without explicit user consent.

### 5.4 Scheduled Gemini Queries Subsystem (`GeminiScheduleModal.svelte`)
- **Background Execution Engine**:
  - Automates scheduled AI prompt execution directly within the background service worker via `chrome.alarms` (`gemini-scheduled-*`).
  - Supports up to 6 scheduled queries per day (`MAX_TIMES = 6`).
  - **Schedules Modes**:
    - Recurring Schedules: Executes repeatedly on selected days of the week (`selectedDays`).
    - One-Time Schedules: Executes at a specific target date and time (`formDate`).
  - **Prompt Limits**: Enforces a strict 1,000-character prompt limit (`MAX_QUERY_CHARS = 1000`) with real-time character counters.
  - **Background Notifications**: Fires a desktop notification with a snippet preview when the background query finishes. Clicking the notification immediately opens the response thread inside the sidepanel chat.

### 5.5 Gemini Conversation Management & Export
- **Persistent IndexedDB Storage (`geminiConversations`)**: Multi-turn chat sessions are stored in IndexedDB `Intelligent_Workspace` store `geminiConversations`.
- **Full-Text History Search**: Instant search across all past conversations and individual messages via Omnibar commands `lai:` (browse conversations) and `laiq:` (search messages).
- **Four Export Formats**:
  1. **Styled HTML**: Formatted standalone HTML document with styled conversational bubbles, role badges, timestamps, and syntax-highlighted code blocks.
  2. **Raw JSON**: Complete structured data dump including message arrays, token usage, model configuration, and search citations.
  3. **Markdown**: Standard Markdown file formatted with headers, timestamps, and fenced code blocks (` ``` `).
  4. **Plain Text**: Clean, unformatted conversational transcript suitable for email or notes.
- **Grounding Metadata Tracking**: Tracks model ID, token usage statistics, execution timestamps, and source citations returned by Google Search Grounding.

### 5.6 Multimodal Inputs & File Attachments (`feature_geminiAttachFiles`)
- **Multimodal Attachments**: Toggle `feature_geminiAttachFiles` enables direct image and document attachments in chat prompts:
  - Image files (JPEG, PNG, WebP, HEIC/HEIF).
  - PDF documents and research papers.
  - Plain Text files and code files.
  - CSV structured datasets.
- **Voice Support**:
  - Web Speech STT (Speech-to-Text) for dictating prompts hands-free.
  - Web Speech TTS (Text-to-Speech) for reading responses aloud.

### 5.7 Invocation Modalities
- **Sidepanel Route**: `?view=gemini` or shortcut `pa`.
- **In-Page Omnibar Prefixes**:
  - `qai: <query>` — Ask direct question to configured Gemini model.
  - `qaia: <prompt>` — Execute prompt via autonomous agent with tool execution.
  - `lai:` — Browse past AI conversations.
  - `laiq:` — Full-text search across all AI conversation messages.
- **Omnibox AI Tab Search (`find <query>`)**:
  - URL bar keyword `find` initiates hybrid search.
  - Combines regex word-boundary scoring with Gemini semantic resolution to locate and focus open tabs based on natural language queries.

---

## 6. Section 5: Notes View & Knowledge Management (Ver Notas)

A local-first, context-aware note-taking engine tied to browser tab groups and navigation contexts.

### 6.1 Storage Architecture (`notesStore`)
Stored in IndexedDB database `Intelligent_Workspace` (v8) inside object store `notesStore`:
```typescript
interface NoteRecord {
  id: string;          // Unique note identifier.
  title: string;       // Note title.
  text: string;        // Rich text HTML, Markdown, or serialized task payload.
  type: NoteType;      // 'text' | 'checklist' | 'kanban'
  url?: string;        // Origin URL where note was created.
  contextKey: string;  // Scoping key binding note to workspace hierarchy.
  createdAt: number;   // Creation timestamp.
  modifiedAt: number;  // Last edit timestamp.
  isPersistent: boolean; // Pin flag protecting note from group deletion cleanup.
}
```

### 6.2 Specialized Note Formats & Advanced Rendering
1. **Text Note (`NoteTextEditor.svelte`)**:
   - Rich text `contenteditable` surface.
   - Embeds media directly: images, audio, video, and PDF documents.
   - Built-in HTML sanitization and real-time word and character counters.
   - **Mermaid Diagram Rendering**: Renders dynamic flowcharts, sequence diagrams, class diagrams, and state machines directly from Markdown fences (` ```mermaid `).
   - **KaTeX Mathematical LaTeX**: Renders inline equations (`$...$`) and block equations (`$$...$$`) with high precision typography.
2. **Checklist Note (`NoteChecklistEditor.svelte`)**:
   - Interactive task list with individual completion checkboxes.
   - Supports keyboard-driven item reordering and progress tracking.
3. **Kanban Note (`NoteKanbanEditor.svelte`)**:
   - 3-column workflow board: `To Do` -> `In Progress` -> `Done`.
   - Cycling status chips for rapid task transitions.
- **Dynamic Lossless Conversion**: Notes convert losslessly between Text, Checklist, and Kanban representations.

### 6.3 Scoping & Context Hierarchy
Notes bind to browsing contexts via `contextKey`:
- **Group Scope (`g_<groupId>` or `g_<groupKey>`)**: Attached to an entire tab group.
- **Subgroup Scope (`s_<groupId>_<domain>`)**: Attached to a specific domain within a tab group.
- **Ungrouped Scope (`g_ungrouped` / `s_ungrouped_<domain>`)**: Notes created on tabs outside of tab groups.
- **Pomodoro & General Scopes (`pomodoro`, `general`)**: Workspace-wide notes.
- **Orphan Detection Engine**: When tab groups or domains are deleted, associated non-persistent notes are captured by the Orphan Detector. Notes remain accessible in the UI for reassignment or deletion.

### 6.4 Invocation Modalities
- **UI Launchers**: "View Notes" button on Group Cards and Subgroup Cards; "Quick Notes" button in popup header; Sidepanel route `?view=notes` (`pk`).
- **Context Menu Trigger**: Select text on any web page -> Right-click -> "Crear Nota desde Selección" (`note-from-selection`). Automatically extracts the selected text and sets the nearest `h1`-`h3` heading as the title.
- **Vim Hint**: `ao` creates a note from the current selection.
- **Omnibar**: `lnt:` opens notes browser with instant full-text search.
- **Audio Readout**: In-editor TTS button reads note content aloud using Web Speech API.

---

## 7. Section 6: Media & Gallery View (Ver Galería)

A high-performance media capture, annotation, and optical character recognition (OCR) pipeline.

### 7.1 Capture Modes & Engineering (All 7 Capture Types)
The extension implements 7 specialized capture modalities covering single-tab, cross-tab, cropped, and palette operations:
1. **`visible` (Visible Viewport Capture - `cs`)**:
   - Captures the exact visible viewport of the active tab using `chrome.tabs.captureVisibleTab`.
   - Automatically commits the capture to the IndexedDB `screenshots` store and copies the image bitmap directly to the system clipboard (`screenshotSavedAndCopied`).
2. **`fullPage` (Seamless Full-Page Scrolling Canvas - `cp`)**:
   - Executes programmatic page scrolling, calculating total document scroll height.
   - Suppresses scrollbars and hides sticky/fixed navigation bars after the initial segment to eliminate visual stutter.
   - Stitches bitmap slices onto an `OffscreenCanvas` up to 30,000px high (`captureFullPageDataUrl`), enforcing Chromium-compliant 600ms delays between frame captures.
3. **`fullPageParts` (Sequential Sliced Segments - `cpp` / `cP`)**:
   - Slices tall documents into sequential, individual viewport-height image parts (`captureFullPageParts`), generating up to 60 numbered image chunks for pagination.
4. **`area` (Interactive Rectangular Drag Crop - `ca`)**:
   - Injects `area-selector.js`, overlaying a crosshair canvas with real-time bounding box dimensions.
   - Draggable selection handles, dimension tooltip, confirmation trigger, `Esc` key cancellation, and multi-tab crop queueing (`handleCaptureAreaFromShortcut`).
5. **`groupTabs` (Batch Active Group Tab Walk - `Cs`, `Cp`, `CP`)**:
   - Sequentially iterates through every tab within the active tab group (`handleCaptureGroupFromShortcut`).
   - Supports batch capture in visible, full-page, or segmented parts mode, compiling them into a unified collection.
6. **`omnibarPickedTabs` (Custom Multi-Tab Queue Capture)**:
   - Initiated via Omnibar commands `cs:`, `cp:`, `cpp:`, or `ca:` (`handleCaptureTabs`).
   - Executes sequential captures across all user-filtered tabs, providing real-time progress indicators.
7. **`colorPickerCapture` (Background Screen Eyedropper Fallback)**:
   - Takes a background screen capture to power the precision hex eyedropper magnifier tool on operating systems lacking native `window.EyeDropper` support (e.g., Linux).

### 7.2 Gallery UI & Persistence
- **Interface**: Responsive masonry/grid layout with lightbox zoom, pan, and rotate tools.
- **Persistence (`screenshots` Store)**: Saved in IndexedDB `Intelligent_Workspace`. Unpinned captures are automatically purged during maintenance; clicking the pin icon (`isPersistent = true`) preserves captures indefinitely.

### 7.3 Export, In-Browser OCR & External Markup
- **Export Formats (`captureDownloadFormats`)**:
  - High-efficiency formats: PNG, WebP, AVIF.
  - Multi-page compiled PDF document export via `pdf.js`.
- **On-Device WASM OCR**:
  - In-browser Tesseract.js WebWorker utilizing preloaded Spanish and English (`spa+eng`) language models.
  - Extracts text directly to clipboard without sending image data over the network.
- **Direct Send Integration**:
  - One-click transfer of extracted OCR text or image attachments into Notes (`notesStore`) or Gemini AI prompts (`feature_geminiAttachFiles`).
- **Excalidraw Markup**: One-click export sends captured images directly into `https://excalidraw.com/` for freehand drawing, arrows, and vector annotations.

### 7.4 Invocation Modalities
- **UI**: Group Card camera button, Popup quick action, Sidepanel gallery route `?view=gallery` (`ps`).
- **Vim Hints**: `cs` (visible), `cp` (full page), `cP` (parts), `ca` (area crop), `Cs` (group visible), `Cp` (group full page), `CP` (group parts).
- **Omnibar Prefixes**: `cs:`, `cp:`, `cpp:`, `ca:`, and `limg:` (browse gallery).

---

## 8. Section 7: Pomodoro & Timing Suite (Pomodoro)

A focus and timing suite engineered for absolute accuracy across browser sleep cycles.

### 8.1 Timing Engine & Background Architecture
- **Zero-Drift Timestamp Math**: State is persisted in `chrome.storage.local` with absolute Unix timestamps (`startTime`, `pausedAt`). Service worker terminations, browser restarts, and operating system sleep states cause zero clock drift.
- **Alarm Dispatcher**:
  - High-resolution countdown ticker driven by `chrome.alarms` (`pomodoroTick` 1s interval).
  - Background maintenance and long-term interval sweeps managed by `itg-periodic-tasks` (1 min interval).
- **Offscreen Audio Chimes (`offscreen.html`)**: Audio chimes are generated via a dedicated Chrome Offscreen document created with reason `AUDIO_PLAYBACK`. Automatically closes 3.5 seconds after sound completion to conserve memory.

### 8.2 Exhaustive 4 Timing Modes
1. **Pomodoro (`pomodoro`)**:
   - Work duration: 1 to 180 minutes (default: 25 min).
   - Short break: 1 to 120 minutes (default: 5 min).
   - Long break: 1 to 180 minutes (default: 15 min).
   - Cycles before long break: 1 to 12 cycles (default: 4).
   - Target cycle goal: 1 to 99 cycles (default: 8).
   - Configurable autostart work, autostart breaks, and notification alerts.
2. **Stopwatch (`cronometro`)**: Progressive timer with lap recording and pause-as-stop capability.
3. **Countdown (`temporizador`)**: Custom countdown timer specifying hours, minutes, and seconds.
4. **Target Time Alarm (`tiempo`)**: Calendar date picker and clock selector setting an alarm for an exact future timestamp.

### 8.3 In-Page Floating Timer Widget
- Draggable, minimal overlay displaying real-time countdown, pause/resume, and skip buttons directly on web pages.
- Allows monitoring focus sessions without switching back to the extension panel or popup.

### 8.4 Group Auto-Collapse Idle Timer
- Works in tandem with focus routines to automatically collapse inactive groups after 1 minute of inactivity (`INACTIVITY_THRESHOLD_INACTIVE_GROUP`) and the active group after 15 minutes of inactivity (`INACTIVITY_THRESHOLD_ACTIVE_GROUP`). Configurable from 0 to 1440 minutes.

### 8.5 Project Tagging & Metadata
Each session supports categorization metadata:
- Project Name (up to 18 characters)
- Project Tag (e.g., `#research`, `#dev`)
- Project Folder (e.g., `/client/project`)

### 8.6 Analytics Engine & 19 KPI Cards
The full dashboard (`dashboard.html` or Sidepanel `dashboard.html?context=sidepanel`) computes 19 key performance indicators from deduplicated sessions (`dedupeSessions` by `sessionStarted`):
1. `focus`: Total focus time.
2. `sessions`: Total completed sessions.
3. `cycles`: Total completed work cycles.
4. `efficiency`: Average efficiency percentage (`Total Focus / Total Time * 100`).
5. `activeDays`: Number of unique active days.
6. `break`: Total break duration.
7. `interruptions`: Total count of manual pauses/interruptions.
8. `interruptionTime`: Cumulative duration spent in paused state.
9. `bestSession`: Longest single uninterrupted focus session.
10. `avgFocus`: Average focus duration per completed cycle.
11. `totalTime`: Cumulative time spent in work and breaks.
12. `workRest`: Ratio of work duration to rest duration (`1 : X`).
13. `distractionRate`: Interruptions per focus hour.
14. `bestDay`: Most productive day of the week.
15. `goldenHour`: Peak focus hour interval of the day (e.g., `10:00 - 11:00`).
16. `projects`: Number of distinct projects tracked.
17. `avgIntDuration`: Average duration of each interruption.
18. `topProject`: Project with the highest accumulated focus time.
19. `focusIntensity`: Average focus hours per active day.

Additional visual analytics include a Day Streak Heatmap calendar, an hourly focus distribution bar chart, a Project variety breakdown, and full JSON data import/export.

---

## 9. Section 8: Activity & History Panel (Panel de Actividad)

A Declarative Net Request (DNR) tracking, analytics, and web governance engine.

### 9.1 Data Engine & Storage Topology (`ITG_WEB_ACTIVITY`)
Managed under `ITG_WEB_ACTIVITY`:
- `wa:day:YYYY-MM-DD`: Domain counters per day (`{ domains: { host: { t: seconds, v: visits, s: sessions, h: { hour: seconds } } } }`).
- `wa:days`: Master index array of recorded date keys.
- `wa:recent`: Ring buffer storing the latest 400 visit timeline entries.
- `wa:openSegment`: Active timed segment in `chrome.storage.session`, capped at `WA_MAX_SEGMENT_SECONDS = 900s` (15 minutes) to prevent distorting stats if the machine sleeps without firing idle events.
- **Idle Detection**: Uses `chrome.idle` (default: 300s / 5m). Audio playback preserves active tracking even when windows are unfocused if `countAudible = true`.
- **Retention**: Automatically prunes day records older than `retentionDays` (default: 180 days).

### 9.2 Declarative Net Request (DNR) Site Blocker
- **Dynamic Rule Allocation**: Allocates dynamic rules in the ID range `9000` to `9999`.
- **Redirect Target**: Blocked requests redirect to `src/ui/pages/web-activity/blocked.html?d=<domain>&u=\1`.
- **Open Tab Sweep**: When a site limit expires, the background worker immediately sweeps and redirects existing open tabs matching the domain.
- **Overnight Schedule Spanning**: Schedules crossing midnight (e.g., `22:00` to `02:00`) are automatically evaluated across day boundaries.
- **Grace / Snooze Period (+5 min)**: The block screen allows temporary 5-minute snooze passes, tracked in `wa:snoozeUses`.

### 9.3 Asymmetric Security Lock (`blockLock.js`)
Site limits can be protected with an asymmetric password lock:
- **Hash Storage**: Stores random 16-byte salt and SHA-256 hex digest (`wa:settings.blockPassword`).
- **Asymmetric Rule Policy**: The password is **never requested** when creating new limits or making rules stricter (e.g., reducing time allowances or adding schedule restrictions).
- **Guarded Actions**: The password is only requested when **loosening rules** (deleting a limit, increasing time allowances, or disabling schedules) or when invoking snooze after exceeding the daily free threshold (`snoozePasswordAfter`).

### 9.4 Categorization & Visual Analytics
- **16 Built-in Categories**: `social`, `video`, `music`, `news`, `shopping`, `reading`, `entertainment`, `dev`, `work`, `education`, `games`, `finance`, `mail`, `ai`, `search`, `other`.
- **Custom Categories**: Supports user-defined categories prefixed with `custom:`.
- **Focus Ratio**: Contrasts Productive categories (`dev`, `work`, `education`, `reading`, `finance`, `mail`) against Distracting categories (`social`, `video`, `games`, `shopping`, `entertainment`).
- **Visuals**: Chart.js hourly activity distributions, category donut breakdown, and domain ranking lists.

### 9.5 Downloads Manager Subsystem (`switchMainView('downloads')`)
- **Dedicated Route**: Accessed in side panel via `switchMainView('downloads')` (`?view=downloads`).
- **Direct Chrome API Integration**: Hooks `chrome.downloads` to track, manage, and inspect all browser downloads in real time.
- **Real-Time Fuzzy Search**: Instant search by file name, file path, or download source URL.
- **Status Filter Chips**: Rapidly filter downloads by state: `All`, `In Progress`, `Complete`, `Paused`, and `Interrupted`.
- **Calendar Date Range Filtering**: Narrow down downloads by specific dates or time intervals.
- **Batch Group Downloader**: Extracts all download links from open tabs in the active group and initiates synchronized batch downloads with progress tracking.
- **File Management**: Direct one-click file opening (`chrome.downloads.open`) and folder reveal (`chrome.downloads.show`).

### 9.6 Recently Closed Tabs & Browsing History Subsystem
- **Recently Closed Tabs View**:
  - Integrated directly with `chrome.sessions.getRecentlyClosed`.
  - Real-time search with automatic diacritic and accent folding (`deaccent`).
  - Single tab restoration and full window session restoration with a single click or Omnibar command `c:`.
- **Browsing History View**:
  - Deep search with 10-second TTL in-memory caching to eliminate redundant `chrome.history.search` query churn.
  - Search filterable by domain, keyword, and calendar date ranges.
  - One-click tab activation if already open, or fresh tab creation, accessible via Omnibar `h:`.

### 9.7 Theme Scheduling Subsystem (`ThemeScheduleModal.svelte`)
- **Automated Theme Scheduling**:
  - Managed via `ThemeScheduleModal.svelte` inside the Themes side panel view (`?view=themes` / `pt`).
  - Supports automatic theme switching based on time of day (`HH:MM`) and active days of the week (`[0..6]`).
  - Maximum of 7 global theme schedules (`MAX_GLOBAL_SCHEDULES = 7`).
  - **Auto-Revert**: Automatically returns to default daytime or workplace themes at designated completion hours.
  - **Desktop Alerts**: Issues desktop notifications when automatic theme switches occur (`chrome.notifications`).
  - **Dual Persistence**: Persisted in `chrome.storage.sync` (roaming preferences) and `chrome.storage.local` under `savedThemes` and `themeSchedules`.

### 9.8 Compact Sidepanel View
- **Sidepanel Route (`?view=activity` / `pw`)**: 350px column optimized for real-time monitoring, featuring period selector chips (`Today`, `7d`, `30d`, `All`) and domain limit progress bars.

---

## 10. Multi-Modal Invocation Matrix

### 10.1 Popup UI Interface
- **Rules Tab**: Quick rule toggles, active status indicators, and rule URL launcher.
- **Groups Tab**: Compact accordion list with tab switching and group cleanup.
- **AI Launcher**: Direct chat input box routing queries to the side panel.
- **Quick Actions Toolbar**: One-click buttons for Area Screenshot, Full-Page Capture, Quick Notes, Pomodoro Start/Pause, and Sidepanel expansion.

### 10.2 Sidepanel Navigation Routes (`?view=...`)
- `?view=rules` — Comprehensive Rules Manager and URL pattern editor (`pg`).
- `?view=listgroup` — Full Group and Tab workspace with drag-and-drop reordering (`pl`).
- `?view=notes` — Notes workspace (Text, Checklist, Kanban, Mermaid, KaTeX) (`pk`).
- `?view=gallery` — Screenshot gallery, OCR, and Excalidraw tools (`ps`).
- `?view=gemini` — Multimodal AI Assistant and Autonomous Agent interface (`pa`).
- `?view=activity` — Web Activity tracker, limits, and category metrics (`pw`).
- `?view=themes` — Theme editor and automated scheduling palette (`pt`).
- `?view=hints` — Vim shortcuts, Omnibar, and YouTube loop settings (`pn`).
- `?view=downloads` — Downloads Manager and batch link downloader (`switchMainView('downloads')`).

### 10.3 Manifest Keyboard Shortcuts (24 Commands)
1. `toggle-current-group` (`Ctrl+Shift+Z` / Mac `Command+Shift+Z`): Toggle collapse of active group.
2. `toggle-all-groups` (`Ctrl+Shift+Q` / Mac `Command+Shift+Q`): Toggle collapse of all groups.
3. `toggle-sort-alpha` (`Ctrl+Shift+S` / Mac `Command+Shift+S`): Toggle alphabetical group sorting.
4. `open-popup` (`Alt+Shift+P`): Open popup or focus side panel.
5. `toggle-collapse-timer`: Toggle group auto-collapse timer.
6. `toggle-all-rules`: Master toggle for all custom rules (`Alt+M`).
7. `toggle-expand-all`: Expand all groups in the workspace.
8. `rules-manager`: Open Rules Manager in a dedicated tab (`Alt+R`).
9. `toggle-prefixes`: Toggle visual group prefix indicators (`🔒`, `🔍`, `🗝️`, `⚠️`).
10. `toggle-domain-grouping`: Toggle automatic domain clustering.
11. `toggle-subdomain-grouping`: Toggle automatic subdomain clustering.
12. `toggle-compact-mode`: Toggle compact single-letter group titles.
13. `toggle-chrome-grouping`: Toggle special Chrome internal pages group.
14. `toggle-files-grouping`: Toggle special local `file://` pages group.
15. `toggle-extensions-grouping`: Toggle special `chrome-extension://` group.
16. `toggle-misc-grouping`: Toggle unclustered Miscellaneous group.
17. `toggle-ip-address-grouping`: Toggle IP address / localhost group.
18. `toggle-clustering`: Master toggle for all automated clustering.
19. `regroup-all-tabs`: Trigger comprehensive tab regrouping pass (`Alt+Shift+R`).
20. `toggle-hints`: Toggle in-page Vim hints overlay engine.
21. `open-side-panel`: Open extension side panel.
22. `open-theme-selector`: Open theme customization panel.
23. `remove-duplicate-tabs`: Clean duplicate tabs across the window.
24. `open-list-group-sidepanel-command`: Open List Group view in side panel.

### 10.4 In-Page Vim Hint Keys (40+ Combinations)
- **Scrolling & Movement**:
  - `j` / `k`: Scroll down / up (75px step).
  - `d` / `u`: Scroll to bottom / top of page.
  - `h` / `l`: Scroll left / right (or switch to previous / next tab if page cannot scroll).
  - `H` / `L`: Navigate back / forward in browser history.
  - `esc`: Blur active input, unfocus elements.
- **Tab & Window Management**:
  - `t`: Open new tab.
  - `x`: Close current tab.
  - `yt`: Duplicate current tab.
  - `s`: Swap to previous active tab.
  - `ts`: Toggle side-by-side Split Screen window.
  - `we`: Open active tab in standalone popup window.
  - `wp`: Open active tab in Document Picture-in-Picture.
  - `wv`: Open active video in custom Video Picture-in-Picture.
  - `dg`: Close/delete current tab group.
- **Link Hints & Interaction**:
  - `f`: Activate Vim link hints (click element).
  - `cf`: Activate Vim link hints to copy link URL.
  - `i`: Focus first text input on page.
  - `c`: Copy current URL to clipboard.
  - `y`: Append current selection to clipboard buffer.
  - `vs`: View page source (`view-source:`).
  - `vp`: Toggle link preview modal.
  - `as` / `ah`: Toggle Auto-PiP on scroll / on tab hide.
  - `ar`: Toggle Text-to-Speech Read Aloud.
  - `ao`: Create note from selection.
  - `at`: Translate page.
- **Sidepanel Direct Access**:
  - `ph`: Open Main side panel view.
  - `pt`: Open Themes side panel.
  - `pl`: Open List Group side panel.
  - `pk`: Open Notes side panel.
  - `ps`: Open Screenshot Gallery side panel.
  - `pa`: Open AI Assistant side panel.
  - `pw`: Open Web Activity side panel.
  - `pg`: Open Rules side panel.
  - `pn`: Open Customize Hints side panel.
- **Media Capture**:
  - `cs`: Capture visible viewport.
  - `cp`: Capture full page (stitched).
  - `cP`: Capture full page in sequential parts.
  - `ca`: Capture cropped area.
  - `Cs`: Capture all tabs in group (visible).
  - `Cp`: Capture all tabs in group (full page).
  - `CP`: Capture all tabs in group (parts).
- **Audio & Reading Modes**:
  - `st`: Toggle mute on current tab.
  - `so`: Mute all audible tabs.
  - `mb` / `mB`: Black page mode (tab / global).
  - `ms` / `mS`: Sepia page mode (tab / global).
  - `mp` / `mP`: Paper page mode (tab / global).
  - `ml` / `mL`: Light page mode (tab / global).
  - `me` / `mE`: Custom CSS filter mode (tab / global).
- **Text-to-Speech (Read Aloud) Reader Navigation**:
  - `zp`: Play / Pause speech synthesis reader overlay.
  - `zn`: Next sentence in Read Aloud session.
  - `zb`: Previous sentence in Read Aloud session.
  - `zq`: Close / Terminate Read Aloud speech overlay.
- **Group Backups & Rules**:
  - `bg`: Backup all groups to IndexedDB.
  - `br`: Restore all groups from IndexedDB.
  - `cr`: Create custom rule from current page.
  - `ae`: Add current page to existing rule.
- **Quick URL Launchers**:
  - `gy`: YouTube, `gm`: Gmail, `gp`: Google Maps, `gx`: X (Twitter), `gi`: Instagram, `gu`: Udemy, `gc`: ChatGPT, `gg`: Gemini.

### 10.5 In-Page Omnibar Subsystem Prefixes (41 Prefixes)
Type `o` on any page to open the floating Omnibar. Type `@` to view all available commands:
1. `we:` — Open selected tab as standalone popup window.
2. `wp:` — Open selected tab as Document Picture-in-Picture.
3. `wv:` — Open selected tab as Video Picture-in-Picture.
4. `sp:` — Open URL, search, or tab in the side panel.
5. `ar:` — Pick a tab and read its text aloud via TTS.
6. `b:` — Full-text search browser bookmarks.
7. `h:` — Search browsing history.
8. `c:` — Browse and reopen recently closed tabs.
9. `dg:` — Search and delete or switch tab groups.
10. `dt:` — Search and close multiple tabs.
11. `ts:` — Select tabs and launch in side-by-side Split Screen.
12. `cs:` — Capture visible area of chosen tabs.
13. `cp:` — Capture full page of chosen tabs.
14. `cpp:` — Capture full page in sequential parts.
15. `ca:` — Capture custom cropped area on chosen tabs.
16. `bg:` — Backup tab groups immediately to IndexedDB.
17. `bgr:` — Search and restore backed-up groups and tabs.
18. `f:` — Deep full-text search across all open tabs.
19. `qai:` — Ask a query directly to configured AI model.
20. `qaia:` — Instruct the Autonomous AI Agent to execute actions.
21. `lai:` — Browse past AI conversation history.
22. `laiq:` — Search within AI messages.
23. `limg:` — Browse captured screenshots and gallery images.
24. `lnt:` — Search and view saved notes.
25. `atcr:` — Add active tab URL to an existing custom rule.
26. `atr:` — Add open tabs or manual URLs to an existing rule.
27. `rl:` — Search rules and launch associated URLs.
28. `cr:` — Create a new rule (`cr: name` or `cr: name, url1, url2`).
29. `ccr:` — Change the color of a custom rule.
30. `ccg:` — Change the color of an active tab group.
31. `dr:` — Delete rules or individual URLs from rules.
32. `er:` — Rename or edit an existing rule.
33. `st:` — Open Omnibar interactive tutorial.
34. `g:` — Search Google (`g: <query>`).
35. `y:` — Search YouTube (`y: <query>`).
36. `d:` — Search DuckDuckGo (`d: <query>`).
37. `w:` — Search Wikipedia (`w: <query>`).
38. `gm:` — Search Google Maps (`gm: <query>`).
39. `x:` — Search X / Twitter (`x: <query>`).
40. `am:` — Search Amazon (`am: <query>`).
41. `ams:` — Search Amazon Spain (`ams: <query>`).

### 10.6 Context Menu Tree Hierarchy (All 5 Groups & 30+ Actions)
The context menu provides a complete hierarchical tree organized into 5 functional command groups:
1. **Group 1: Rules & URL Submenu**:
   - Master rules checkbox toggle ("Activar/Desactivar Todas las Reglas").
   - Per-rule toggles enabling or disabling individual custom rules on the fly.
   - "Abrir Todas las URLs": Opens all target URLs registered in the selected rule.
   - Individual URL submenus with dynamic open tab counts `[N]`: Displays currently open tab count matching the URL, provides one-click navigation to the URL, and offers "Cerrar Pestañas para esta URL" to terminate all matching tabs.
   - Quick Rule Creation: "Crear Regla para esta Página" -> "Añadir Raíz del Sitio" / "Añadir URL Completa".
   - Add to Existing Rule: "Añadir a Regla Existente" -> Select rule -> "Añadir Raíz del Sitio" / "Añadir URL Completa".
2. **Group 2: Tab Cleanup & Audio Controls**:
   - "Eliminar Pestañas Duplicadas [N]": Shows count of detected redundant tabs and closes them across windows.
   - "Eliminar Pestañas por Dominio": Dynamic submenu listing all domains with open tab counts `[N]`, allowing surgical tab closure by domain.
   - "Cerrar Todos Excepto el Grupo Activo": Retains active focused group and closes all other groups.
   - "Reagrupar Todas las Pestañas": Triggers full background regrouping pass across all open tabs.
   - "Silenciar Todas las Pestañas" / "Reactivar Sonido en Todas las Pestañas": Global audio mute and unmute controls.
3. **Group 3: Reading, Selection & Notes**:
   - "Leer Página en Voz Alta" (TTS): Full-page text-to-speech reader with overlay controls.
   - "Leer Selección en Voz Alta": Reads highlighted DOM selection aloud using speech synthesis.
   - "Crear Nota desde Selección": Extracts text selection, automatically derives note title from the nearest heading (`h1`-`h3`), and stores it in `notesStore`.
4. **Group 4: Open Extension, PiP & Panels**:
   - "Abrir como PiP" / "Abrir como Ventana Emergente": Launch target page, highlighted selection, or target image into floating Picture-in-Picture or standalone popup window.
   - "Abrir Extensión": Opens extension popup or expands side panel.
   - "Gestionar Reglas": Opens full Rules Manager in a dedicated browser tab.
   - Direct Sidepanel Launchers: One-click routing to List Groups (`?view=listgroup`), Themes (`?view=themes`), AI Assistant (`?view=gemini`), and Customize Hints (`?view=hints`).
5. **Group 5: Settings & Clustering Options**:
   - **Gestión de Grupos**: Alternar Grupo Actual (toggle active group collapse), Alternar Todos los Grupos (toggle all groups collapse).
   - **Opciones de Agrupación**:
     - Agrupación Inteligente (toggle automated heuristic clustering).
     - Modo Compacto (toggle single-letter group title mode).
     - Dominio / Subdominio (toggle domain and subdomain grouping).
     - Páginas Especiales: Páginas Chrome (`chrome://`), Archivos Locales (`file:///`), Extensiones (`chrome-extension://`), Miscelánea (`Misc`), Direcciones IP & Localhost.
   - **Opciones Generales**:
     - Ordenar Alfabéticamente (enforce alphabetical sorting across tab strip).
     - Ubicación Miscelánea: Principio (`start`), Final (`end`), Alfabéticamente (`alpha`).
     - Temporizador de Auto-Colapso (toggle idle group collapse timer).
     - Prefijos Visuales (toggle `🔒`, `🔍`, `🗝️`, `⚠️` state markers).
     - Vista Previa de Enlaces (toggle in-page link preview modal).

---

## 11. Storage Schemas & Data Persistence

The extension uses a multi-tier storage model across IndexedDB and Chrome Storage APIs:

### 11.1 IndexedDB Database: `Intelligent_Workspace` (Schema Version 8)
1. `screenshots`: keyPath: `'id'`, autoIncrement: true. Secondary index: `'createdAt'`. Holds binary screenshots, canvas data URLs, persistent flags, dimensions, and segment total indices.
2. `geminiConversations`: keyPath: `'id'`, autoIncrement: true. 0 secondary indexes (retrieved/managed by ID). Stores multi-turn chat threads, message roles, token metrics, and search grounding metadata.
3. `notesStore`: keyPath: `'id'`, autoIncrement: false. 0 secondary indexes (filtered in memory by contextKey). Stores rich text, checklist arrays, Kanban board cards, Mermaid specifications, and KaTeX formulas.
4. `backupsGroups`: keyPath: `'group.id'`. 0 secondary indexes (stores backup group objects keyed by nested `'group.id'`). Stores compressed group structures, colors, titles, and closed tab records.
5. `pomodoroStats`: keyPath: `'id'`, autoIncrement: true. Secondary indexes: `'projectName'` (keyPath `'projectName'`) and `'savedAt'` (keyPath `'savedAt'`) (no `date` index). Holds focus analytics, cycle metrics, and interruption logs.

### 11.2 Chrome Storage Dual-Routing (`StorageService`)
- Dynamically routes reads and writes between `chrome.storage.sync` (for portable settings across user devices) and `chrome.storage.local` (for heavy preferences).
- Key models:
  - `customRules`: Array of rule definitions (`[{ name, color, active, urls }]`).
  - `clusterConfig`: Auto-clustering parameters (thresholds, compact mode, special categories).
  - `userPrefixes`: Emoji prefix assignments (`{ lock, openKey, loupe, checked, warning }`).
  - `activeTheme`, `savedThemes`, & `themeSchedules`: 9-palette color configurations and scheduled rotation rules configured via `ThemeScheduleModal.svelte`.
  - `pomodoroState`: Real-time session timestamps, paused duration, and cycle goals.
  - `wa:settings` & `wa:limits`: Web activity tracking preferences, site limits, and schedule windows.
  - `youtubeLoopEnabled`: Boolean flag controlling YouTube and Shorts loop buttons.

### 11.3 Chrome Storage Session (`chrome.storage.session`)
Used for ultra-fast, ephemeral runtime coordination:
- `tabsEverActive`: Set of tab IDs activated during the current browser session.
- `groupExpandedEver`: Record of groups expanded during the current session.
- `groupInfoMap`: Real-time registry mapping group IDs to dynamic titles and clustering types.
- `splitScreenState`: Cached window bounds for restoring original screen dimensions.
- `contextMenusSignature`: Hash signature preventing redundant context menu rebuild churn during rapid tab switches.
- `wa:openSegment`: Current active website time segment.
- `hiddenYoutubeView`: Reference to parked YouTube player view docked in `HiddenGroupsBar.svelte`.

---

## 12. Defensive Engineering & Edge Case Handling

1. **Declarative Net Request Header Unblocking (`dnr.js`)**:
   - Modifies response headers via dynamic DNR rules to strip `X-Frame-Options` and restrictive `Content-Security-Policy` headers, allowing external sites to render in the Side Panel and Picture-in-Picture iframes.
   - **WhatsApp Web Safety**: Explicitly preserves `Cross-Origin-Opener-Policy` (COOP) and `Cross-Origin-Embedder-Policy` (COEP) on `web.whatsapp.com` to prevent breaking its WebAssembly Signal cryptographic implementation.
2. **Right-Click & Selection Unblocker (`allowRightClickHook.js`)**:
   - Defeats hostile websites blocking copy, paste, context menu, and text selection.
   - Runs in `MAIN` world to intercept `preventDefault()` and `stopPropagation()` on `contextmenu`, `copy`, `cut`, `selectstart`, `mousedown`, and `mouseup`.
   - Strips inline `oncontextmenu="return false"` handlers via `MutationObserver`.
   - Protects legitimate web applications (e.g., Telegram Web, Google Docs) by verifying clipboard contents before re-injecting cancelled paste events.
3. **YouTube Hover Preview Audio Forced-Mute Override (`youtubePreviewAudioHook.js`)**:
   - Runs in `MAIN` world on `ytd-video-preview #inline-preview-player`.
   - Overrides `HTMLMediaElement.prototype.muted` property descriptor on the target `<video>` element on hover.
   - Eliminates YouTube's internal `volumechange` forced-mute race condition, maintaining unmuted audio across loop restarts while hovering.
4. **YouTube Shorts Feed Sequence Navigation Hook (`youtubeShortsFeedHook.js`)**:
   - Runs in `MAIN` world on `ytd-shorts`.
   - Intercepts `shortsProcessedSequence` property, which is invisible from the extension's isolated world, and dispatches native `yt-navigate` events on `ytd-app` without reloading the page or losing floating window state.
5. **Infinite-Scroll Canvas Protection**:
   - Caps full-page screenshot walks at 60 segments (`MAX_FULL_PAGE_SEGMENTS`) and 30,000px maximum canvas height (`MAX_FULL_PAGE_CANVAS_PX`), avoiding out-of-memory browser tab crashes.
6. **Linux Screen Color Picker Eyedropper Fallback**:
   - When running on Linux environments lacking the Chromium `window.EyeDropper` API, the extension injects `screen-color-picker.js`, rendering a 9x magnified pixel lens with RGB/HEX/HSL calculation.
7. **Startup Session Settling Delay**:
   - Delays group pruning for 20 seconds (`groupsHaveSettledAfterStartup()`) upon browser launch to allow session tabs and window states to settle before evaluating group assignments.