### Initialize Extension on Install

Source: https://github.com/0xsouravm/oxichrome/blob/main/_autodocs/api-reference/overview.md

Sets up initial data in storage when the extension is installed. Uses the `oxichrome::on(runtime::on_installed)` attribute.

```rust
#[oxichrome::on(runtime::on_installed)]
async fn on_install(_: JsValue) {
    if let Err(e) = oxichrome::storage::set("setup_done", &true).await {
        oxichrome::log!("Setup error: {}", e);
    }
}
```

--------------------------------

### Generated Manifest Example

Source: https://github.com/0xsouravm/oxichrome/blob/main/_autodocs/INDEX.txt

Shows an example of a generated manifest file, which is crucial for extension configuration and deployment. This illustrates the structure and common fields.

```json
{
  "manifest_version": 3,
  "name": "My Extension",
  "version": "0.1.0",
  "description": "An example extension."
}
```

--------------------------------

### chrome.runtime.onInstalled.addListener

Source: https://github.com/0xsouravm/oxichrome/blob/main/_autodocs/chrome-api-bindings.md

Register a listener for extension installation and update events. The callback function receives details about the installation or update.

```APIDOC
## chrome.runtime.onInstalled.addListener

### Description
Register listener for extension installation and updates.

### Method
POST (conceptual, as it's a function call)

### Endpoint
chrome.runtime.onInstalled.addListener(callback)

### Parameters
#### Request Body
- **callback** (Closure<dyn FnMut(JsValue)>) - Required - Function to be called when the event fires.
  - **details** (JsValue) - Installation details object.
    - **reason** (string) - "install" | "update" | "chrome_update" | "shared_module_update"
    - **previousVersion** (string) - Optional - The previous version of the extension.

### Response
This method does not return a value, but invokes the provided callback upon the event.

### Example
```rust
#[oxichrome::on(runtime::on_installed)]
async fn on_install(details: JsValue) {
    oxichrome::log!("Extension installed: {:?}", details);
}
```
```

--------------------------------

### Listen for Chrome Runtime Installation Events

Source: https://github.com/0xsouravm/oxichrome/blob/main/_autodocs/chrome-api-bindings.md

Registers a listener for extension installation and update events. Use the #[oxichrome::on] macro for convenient event handling.

```rust
#[wasm_bindgen(js_namespace = ["chrome", "runtime", "onInstalled"], js_name = addListener)]
pub fn chrome_runtime_on_installed_add_listener(
    callback: &Closure<dyn FnMut(JsValue)> 
);

// Callback Parameter Details:
// {
//   reason: "install" | "update" | "chrome_update" | "shared_module_update",
//   previousVersion?: string
// }
```

```rust
#[oxichrome::on(runtime::on_installed)]
async fn on_install(details: JsValue) {
    oxichrome::log!("Extension installed: {:?}", details);
}
```

--------------------------------

### Advanced Storage Example with Raw Bindings

Source: https://github.com/0xsouravm/oxichrome/blob/main/_autodocs/chrome-api-bindings.md

Demonstrates using raw JavaScript bindings to interact with `chrome.storage.local`. This example fetches a value associated with 'myKey' asynchronously.

```rust
use oxichrome::core::js_bridge::*
use wasm_bindgen::prelude::*
use wasm_bindgen_futures::JsFuture;

async fn advanced_storage_example() -> Result<JsValue, Box<dyn std::error::Error>> {
    // Use raw binding
    let promise = chrome_storage_local_get(&JsValue::from_str("myKey"));
    let result = JsFuture::from(promise).await?;
    
    // Extract value
    let value = js_sys::Reflect::get(&result, &JsValue::from_str("myKey"))?;
    Ok(value)
}

```

--------------------------------

### Content Script Injection Example with RunAt

Source: https://github.com/0xsouravm/oxichrome/blob/main/_autodocs/types.md

An example of defining a content script using the `#[oxichrome::content_script]` macro, specifying early injection with `RunAt::DocumentStart`.

```rust
use oxichrome::prelude::*;

#[oxichrome::content_script(
    matches = ["<all_urls>"],
    run_at = RunAt::DocumentStart
)]
async fn inject() {
    oxichrome::log!("Script injected early");
}
```

--------------------------------

### Installing cargo-oxichrome

Source: https://github.com/0xsouravm/oxichrome/blob/main/README.md

Installs the `cargo-oxichrome` command-line tool, which is required for building extensions.

```sh
cargo install cargo-oxichrome
```

--------------------------------

### Raw chrome.storage.local.get

Source: https://github.com/0xsouravm/oxichrome/blob/main/_autodocs/chrome-api-bindings.md

An example demonstrating the use of raw bindings to interact with `chrome.storage.local.get`.

```APIDOC
## Raw chrome.storage.local.get

### Description
An example demonstrating the use of raw bindings to interact with `chrome.storage.local.get`.

### Method
Rust Function Call (async)

### Endpoint
`chrome_storage_local_get` (internal raw binding)

### Parameters
#### Key
- **key** (JsValue) - Required - The key to retrieve from local storage.

### Request Example
```rust
use oxichrome::core::js_bridge::chrome_storage_local_get;
use wasm_bindgen::JsValue;

let promise = chrome_storage_local_get(&JsValue::from_str("myKey"));
```

### Response
#### Success Response
- **result** (JsValue) - A JavaScript Promise that resolves to the storage object.

### Response Example
```rust
use wasm_bindgen_futures::JsFuture;
use wasm_bindgen::JsValue;

let promise = chrome_storage_local_get(&JsValue::from_str("myKey"));
let result = JsFuture::from(promise).await?;

// Extract value from the result object
let value = js_sys::Reflect::get(&result, &JsValue::from_str("myKey"))?;
```
```

--------------------------------

### Initial Project Setup

Source: https://github.com/0xsouravm/oxichrome/blob/main/_autodocs/build-and-deployment.md

Create a new Oxichrome extension and build its initial version. This sets up the basic project structure and dependencies.

```bash
# Create new extension
cargo oxichrome new my-extension
cd my-extension

# Build initial version
cargo oxichrome build
```

--------------------------------

### Example: Counter Extension

Source: https://github.com/0xsouravm/oxichrome/blob/main/_autodocs/INDEX.txt

A complete example of a counter extension demonstrating basic Oxichrome functionality, including state management and UI updates.

```Rust
use oxichrome::prelude::*

#[oxichrome::background]
fn background_script() {
    // Initialize state or event listeners
}

#[oxichrome::popup]
fn popup_ui() {
    // UI for the popup
}

#[oxichrome::content_script]
fn content_script() {
    // Logic to run in web pages
}

#[oxichrome::extension]
fn main() {
    // Main extension setup
    oxichrome::runtime::run_background(background_script);
    oxichrome::runtime::run_popup(popup_ui);
    oxichrome::runtime::run_content_script(content_script);
}
```

--------------------------------

### Dist/Firefox Output Structure

Source: https://github.com/0xsouravm/oxichrome/blob/main/_autodocs/build-and-deployment.md

Example of the browser_specific_settings for Firefox manifest.json.

```json
{
  "browser_specific_settings": {
    "gecko": {
      "id": "extension@example.com",
      "strict_min_version": "109.0"
    }
  }
}
```

--------------------------------

### Generated lib.rs for New Project

Source: https://github.com/0xsouravm/oxichrome/blob/main/_autodocs/build-and-deployment.md

Example lib.rs file for a new oxichrome extension, demonstrating the use of #[oxichrome::extension], #[oxichrome::background], and #[oxichrome::popup] macros.

```rust
use oxichrome::prelude::*;

#[oxichrome::extension(
    name = "My Extension",
    version = "0.1.0"
)]
struct MyExtension;

#[oxichrome::background]
async fn start() {
    oxichrome::log!("Hello from background!");
}

#[oxichrome::popup]
fn Popup() -> impl IntoView {
    view! { <p>"Hello from popup!"</p> }
}
```

--------------------------------

### Chrome Runtime API Usage

Source: https://github.com/0xsouravm/oxichrome/blob/main/README.md

Examples of getting resource URLs and sending messages using the Chrome runtime API.

```rust
// Runtime
let url = oxichrome::runtime::get_url("icon.png");
oxichrome::runtime::send_message(&msg).await?;
```

--------------------------------

### Get and Set Storage

Source: https://github.com/0xsouravm/oxichrome/blob/main/_autodocs/api-reference/overview.md

Demonstrates retrieving and setting data in the extension's local storage. Data is automatically serialized and deserialized.

```rust
let count: Option<i32> = oxichrome::storage::get("counter").await?;
oxichrome::storage::set("counter", &42).await?;
```

--------------------------------

### Chrome Storage API Usage

Source: https://github.com/0xsouravm/oxichrome/blob/main/README.md

Examples of interacting with the Chrome storage API for getting, setting, and removing key-value pairs.

```rust
// Storage
let val: Option<i32> = oxichrome::storage::get("key").await?;
oxichrome::storage::set("key", &42).await?;
oxichrome::storage::remove("key").await?;
```

--------------------------------

### Generated Cargo.toml for New Project

Source: https://github.com/0xsouravm/oxichrome/blob/main/_autodocs/build-and-deployment.md

Example Cargo.toml file for a newly scaffolded oxichrome extension, including essential dependencies.

```toml
[package]
name = "<name>"
version = "0.1.0"
edition = "2021"

[dependencies]
oxichrome = "0.2"
wasm-bindgen = "0.2"
leptos = { version = "0.8", features = ["csr"] }
serde = { version = "1", features = ["derive"] }
```

--------------------------------

### JsError Creation Example

Source: https://github.com/0xsouravm/oxichrome/blob/main/_autodocs/api-reference/errors.md

Shows how to create a JsError from a JsValue and print its message.

```rust
use oxichrome::core::error::JsError;
use wasm_bindgen::JsValue;

let js_val = JsValue::from_str("Something went wrong");
let error = JsError::new(js_val);
println!("Error: {}", error);
```

--------------------------------

### Oxichrome Dependency in Cargo.toml

Source: https://github.com/0xsouravm/oxichrome/blob/main/README.md

Example `Cargo.toml` configuration showing the required dependencies for an Oxichrome project.

```toml
[dependencies]
oxichrome = { version = "0.2" }
wasm-bindgen = "0.2"
serde = { version = "1", features = ["derive"] }
```

--------------------------------

### Inject Content Script Early

Source: https://github.com/0xsouravm/oxichrome/blob/main/_autodocs/guide-common-patterns.md

Injects a content script into example.com pages before the DOM construction begins. Useful for early modifications or setup.

```rust
use oxichrome::prelude::*;

#[oxichrome::content_script(
    matches = ["https://example.com/*"],
    run_at = RunAt::DocumentStart
)]
async fn early_injection() {
    oxichrome::log!("Injected before DOM construction");
}
```

--------------------------------

### Example manifest.json for Oxichrome Extension

Source: https://github.com/0xsouravm/oxichrome/blob/main/_autodocs/build-and-deployment.md

A sample manifest.json file generated by the #[oxichrome::extension] macro, detailing extension metadata, background scripts, action buttons, and icons.

```json
{
  "manifest_version": 3,
  "name": "Extension Name",
  "version": "1.0.0",
  "description": "Optional description",
  "permissions": ["storage", "tabs"],
  "background": {
    "service_worker": "background.js"
  },
  "action": {
    "default_popup": "popup.html",
    "default_icon": {
      "16": "icons/icon-16.png",
      "48": "icons/icon-48.png",
      "128": "icons/icon-128.png"
    }
  },
  "options_page": "options.html",
  "icons": {
    "16": "icons/icon-16.png",
    "48": "icons/icon-48.png",
    "128": "icons/icon-128.png"
  }
}
```

--------------------------------

### Runtime API Operations

Source: https://github.com/0xsouravm/oxichrome/blob/main/_autodocs/quick-reference.md

Demonstrates getting extension resource URLs and sending messages using the Runtime API.

```rust
use oxichrome::runtime;

// Get extension resource URL
let url = runtime::get_url("icon.png");

// Send message
let response = runtime::send_message(&msg).await?;
```

--------------------------------

### Example of RunAt Enum

Source: https://github.com/0xsouravm/oxichrome/blob/main/_autodocs/INDEX.txt

Demonstrates the RunAt enum, which specifies when content scripts should be executed. This is a key configuration option for content scripts.

```rust
enum RunAt { DocumentStart, DocumentEnd, Idle }
```

--------------------------------

### Oxichrome Extension Metadata Configuration

Source: https://github.com/0xsouravm/oxichrome/blob/main/_autodocs/types.md

An example of configuring extension metadata using the `#[oxichrome::extension]` macro, including name, version, description, and permissions.

```rust
#[oxichrome::extension(
    name = "My Extension",
    version = "1.0.0",
    description = "A useful extension",
    permissions = ["storage", "tabs", "runtime"]
)]
struct Extension;
```

--------------------------------

### Create a Popup UI with Leptos

Source: https://github.com/0xsouravm/oxichrome/blob/main/_autodocs/quick-reference.md

Build reactive user interfaces for popups using Leptos. This example shows a simple counter that increments on button click.

```rust
use leptos::prelude::*;

#[oxichrome::popup]
fn Popup() -> impl IntoView {
    let count = RwSignal::new(0);

    let increment = move |_| count.update(|c| *c += 1);

    view! {
        <div>
            <p>{move || count.get()}</p>
            <button on:click=increment>"+"</button>
        </div>
    }
}
```

--------------------------------

### Reactive UI with Storage

Source: https://github.com/0xsouravm/oxichrome/blob/main/_autodocs/api-reference/overview.md

Example of a reactive UI component (popup) that reads from and writes to persistent storage. Uses `leptos` for UI and `wasm-bindgen-futures` for async operations.

```rust
#[oxichrome::popup]
fn Popup() -> impl IntoView {
    let count = RwSignal::new(0i32);

    Effect::new(move || {
        wasm_bindgen_futures::spawn_local(async move {
            if let Ok(Some(val)) = oxichrome::storage::get::<i32>("count").await {
                count.set(val);
            }
        });
    });

    let increment = move |_| {
        count.update(|c| *c += 1);
        wasm_bindgen_futures::spawn_local(async move {
            let _ = oxichrome::storage::set("count", &count.get_untracked()).await;
        });
    };

    view! {
        <div>
            <p>{move || count.get()}</p>
            <button on:click=increment>"+"</button>
        </div>
    }
}
```

--------------------------------

### OxichromeError Example Usage

Source: https://github.com/0xsouravm/oxichrome/blob/main/_autodocs/api-reference/errors.md

Demonstrates how to handle OxichromeError when retrieving data from storage, printing the error if one occurs.

```rust
use oxichrome::{storage, OxichromeError};

async fn get_count() -> Result<Option<i32>, OxichromeError> {
    match storage::get("count").await {
        Ok(val) => Ok(val),
        Err(e) => {
            eprintln!("Storage error: {}", e);
            Err(e)
        }
    }
}
```

--------------------------------

### Full-Featured Oxichrome Extension Configuration

Source: https://github.com/0xsouravm/oxichrome/blob/main/_autodocs/configuration.md

A comprehensive example of an Oxichrome extension configuration using various macros for background scripts, popups, options pages, content scripts, and event listeners.

```rust
use oxichrome::prelude::*;

#[oxichrome::extension(
    name = "Advanced Extension",
    version = "0.5.0",
    description = "A complete example extension",
    permissions = ["storage", "tabs", "scripting", "activeTab"]
)]
struct Extension;

#[oxichrome::background]
async fn start() {
    oxichrome::log!("Background worker ready");
}

#[oxichrome::popup]
fn Popup() -> impl IntoView {
    view! { <h1>"Hello"</h1> }
}

#[oxichrome::options_page]
fn Options() -> impl IntoView {
    view! { <h1>"Settings"</h1> }
}

#[oxichrome::content_script(
    matches = ["https://example.com/*"],
    run_at = RunAt::DocumentEnd
)]
async fn inject() {
    oxichrome::log!("Injected into page");
}

#[oxichrome::on(runtime::on_installed)]
async fn on_install(details: JsValue) {
    oxichrome::log!("Extension installed");
}
```

--------------------------------

### Compile-Time Environment Variable Check

Source: https://github.com/0xsouravm/oxichrome/blob/main/_autodocs/build-and-deployment.md

Example of checking build-time environment variables within Rust code using cfg! macro.

```rust
// Read environment variables at compile time
if cfg!(debug_assertions) {
    oxichrome::log!("Debug build");
}
```

--------------------------------

### Generated Manifest JSON Structure

Source: https://github.com/0xsouravm/oxichrome/blob/main/_autodocs/configuration.md

An example of the `manifest.json` structure generated by the `#[oxichrome::extension]` macro. The actual manifest includes additional entries for web-accessible resources and content scripts.

```json
{
  "manifest_version": 3,
  "name": "Extension Name",
  "version": "1.0.0",
  "description": "Extension description",
  "permissions": ["storage", "tabs"],
  "background": {
    "service_worker": "background.js"
  },
  "action": {
    "default_popup": "popup.html"
  },
  "options_page": "options.html"
}
```

--------------------------------

### Load Extension in Chrome/Chromium/Edge/Brave

Source: https://github.com/0xsouravm/oxichrome/blob/main/_autodocs/build-and-deployment.md

Instructions for loading an unpacked extension. Ensure developer mode is enabled.

```bash
1. Open `chrome://extensions/`
2. Enable "Developer mode" (toggle in top-right)
3. Click "Load unpacked"
4. Select the `dist/chromium/` directory
5. The extension appears in the list

**Reload:**

- After rebuilding, click the reload icon next to the extension name

**Inspect:**

- Click "background page" to see console
- Click "popup.html" to inspect popup UI
- Right-click page element → "Inspect" to see content script
```

--------------------------------

### Testing Workflow

Source: https://github.com/0xsouravm/oxichrome/blob/main/_autodocs/build-and-deployment.md

Run Rust tests and manually test the extension in the browser. Loading the extension requires a prior build.

```bash
# Run Rust tests
cargo test

# Run extension in browser (manual)
# 1. cargo oxichrome build
# 2. Load dist/chromium/ in Chrome or dist/firefox/manifest.json in Firefox
# 3. Test functionality manually
```

--------------------------------

### Options Page for Configuration

Source: https://github.com/0xsouravm/oxichrome/blob/main/_autodocs/guide-common-patterns.md

Provides a full-featured settings UI for an extension, allowing users to configure API endpoints, keys, and sync settings. It uses Leptos for the UI and Oxichrome's storage API to save and load configurations.

```rust
use leptos::prelude::*;
use oxichrome::prelude::*;
use serde::{Serialize, Deserialize};

#[derive(Serialize, Deserialize, Clone)]
struct AppConfig {
    api_endpoint: String,
    api_key: String,
    auto_sync: bool,
    sync_interval_seconds: u32,
}

#[oxichrome::options_page]
fn Options() -> impl IntoView {
    let config = RwSignal::new(AppConfig {
        api_endpoint: String::new(),
        api_key: String::new(),
        auto_sync: true,
        sync_interval_seconds: 3600,
    });

    let status = RwSignal::new("");

    Effect::new(move || {
        wasm_bindgen_futures::spawn_local(async move {
            if let Ok(Some(c)) = oxichrome::storage::get::<AppConfig>("config").await {
                config.set(c);
            }
        });
    });

    let save_config = move |_| {
        let cfg = config.get_untracked();
        wasm_bindgen_futures::spawn_local(async move {
            match oxichrome::storage::set("config", &cfg).await {
                Ok(_) => status.set("✓ Settings saved"),
                Err(e) => status.set(&format!("✗ Error: {}", e)),
            }
        });
    };

    view! {
        <div style="max-width: 600px; margin: 2rem auto; font-family: sans-serif;">
            <h1>"Settings"</h1>
            
            <div>
                <label>
                    "API Endpoint"
                    <input
                        type="text"
                        value=move || config.get().api_endpoint
                        on:input=move |e| {
                            let value = event_target_value(&e);
                            config.update(|c| c.api_endpoint = value);
                        }
                    />
                </label>
            </div>

            <div>
                <label>
                    "API Key"
                    <input
                        type="password"
                        value=move || config.get().api_key
                        on:input=move |e| {
                            let value = event_target_value(&e);
                            config.update(|c| c.api_key = value);
                        }
                    />
                </label>
            </div>

            <div>
                <label>
                    <input
                        type="checkbox"
                        checked=move || config.get().auto_sync
                        on:change=move |_| {
                            config.update(|c| c.auto_sync = !c.auto_sync);
                        }
                    />
                    "Auto-sync enabled"
                </label>
            </div>

            <div>
                <label>
                    "Sync interval (seconds)"
                    <input
                        type="number"
                        min="60"
                        max="86400"
                        value=move || config.get().sync_interval_seconds.to_string()
                        on:input=move |e| {
                            if let Ok(val) = event_target_value(&e).parse::<u32>() {
                                config.update(|c| c.sync_interval_seconds = val);
                            }
                        }
                    />
                </label>
            </div>

            <button on:click=save_config>"Save Settings"</button>
            <p>{move || status.get()}</p>
        </div>
    }
}
```

--------------------------------

### Add WASM Target

Source: https://github.com/0xsouravm/oxichrome/blob/main/_autodocs/build-and-deployment.md

Install the wasm32-unknown-unknown target if it's missing, which is required for WASM compilation.

```bash
rustup target add wasm32-unknown-unknown
```

--------------------------------

### Create a New Oxichrome Project

Source: https://github.com/0xsouravm/oxichrome/blob/main/_autodocs/quick-reference.md

Creates a new Oxichrome extension project and navigates into its directory.

```bash
cargo oxichrome new my-extension
cd my-extension
```

--------------------------------

### Content Script Configuration: Basic Syntax

Source: https://github.com/0xsouravm/oxichrome/blob/main/_autodocs/configuration.md

Demonstrates the basic syntax for configuring a content script using the `#[oxichrome::content_script]` macro. It specifies URL matches, injection timing, frame scope, and associated CSS files.

```rust
#[oxichrome::content_script(
    matches = ["https://example.com/*"],
    run_at = RunAt::DocumentEnd,
    all_frames = true,
    css = ["styles.css"]
)]
async fn inject() {
    // content script code
}
```

--------------------------------

### Example of JsError Structure

Source: https://github.com/0xsouravm/oxichrome/blob/main/_autodocs/INDEX.txt

Illustrates the structure of a JavaScript error, which can be part of the OxichromeError enum. Useful for debugging.

```rust
struct JsError { message: String, stack: Option<String> }
```

--------------------------------

### Get Extension URL

Source: https://github.com/0xsouravm/oxichrome/blob/main/_autodocs/INDEX.txt

Retrieves the URL for a given extension resource. Useful for accessing bundled assets.

```Rust
let url = oxichrome::runtime::get_url("icon.png");
```

--------------------------------

### Load Extension in Firefox

Source: https://github.com/0xsouravm/oxichrome/blob/main/_autodocs/build-and-deployment.md

Instructions for loading a temporary add-on. Select the manifest.json file for Firefox.

```bash
1. Open `about:debugging#/runtime/this-firefox`
2. Click "Load Temporary Add-on"
3. Select `dist/firefox/manifest.json`
4. The extension appears in the list

**Reload:**

- After rebuilding, click the reload icon next to the extension name

**Inspect:**

- Click "Inspect" to see background worker logs
- Open extension popup and press F12 for popup console
```

--------------------------------

### Runtime API

Source: https://github.com/0xsouravm/oxichrome/blob/main/_autodocs/INDEX.txt

Functions for interacting with the extension's runtime environment, such as getting extension URLs and sending messages.

```APIDOC
## oxichrome::runtime::get_url

### Description
Retrieves the URL for a given extension resource.

### Method
(Not applicable - Rust function)

### Endpoint
(Not applicable - Rust function)

### Parameters
(Not explicitly detailed in source)

### Request Example
(Not applicable - Rust function)

### Response
(Not explicitly detailed in source)

## oxichrome::runtime::send_message

### Description
Sends a message to an event listener in the extension.

### Method
(Not applicable - Rust function)

### Endpoint
(Not applicable - Rust function)

### Parameters
(Not explicitly detailed in source)

### Request Example
(Not applicable - Rust function)

### Response
(Not explicitly detailed in source)
```

--------------------------------

### Development Build Cycle

Source: https://github.com/0xsouravm/oxichrome/blob/main/_autodocs/build-and-deployment.md

Rebuild the extension after making changes to src/lib.rs. Remember to reload the extension in your browser after rebuilding.

```bash
# Edit src/lib.rs

# Rebuild
cargo oxichrome build

# Reload extension in browser
# For Chrome: Click reload button in chrome://extensions
# For Firefox: Click reload button in about:debugging
```

--------------------------------

### Get Data from Local Storage

Source: https://github.com/0xsouravm/oxichrome/blob/main/_autodocs/INDEX.txt

Retrieves data from the browser's local storage. The key must be a string.

```Rust
let data = oxichrome::storage::get("my_key").await;
```

--------------------------------

### Firefox-Compatible Build Command

Source: https://github.com/0xsouravm/oxichrome/blob/main/_autodocs/api-reference/overview.md

Command to create a build specifically compatible with Firefox.

```bash
cargo oxichrome build --target firefox
```

--------------------------------

### Chrome Tabs API Usage

Source: https://github.com/0xsouravm/oxichrome/blob/main/README.md

Examples of querying, creating, and sending messages to tabs using the Chrome tabs API.

```rust
// Tabs
let tabs: Vec<Tab> = oxichrome::tabs::query(&query).await?;
let tab: Tab = oxichrome::tabs::create(&props).await?;
oxichrome::tabs::send_message(tab_id, &msg).await?;
```

--------------------------------

### Storage API

Source: https://github.com/0xsouravm/oxichrome/blob/main/_autodocs/INDEX.txt

Functions for managing extension data using local storage, including getting, setting, and removing items.

```APIDOC
## oxichrome::storage::get

### Description
Retrieves an item from local storage.

### Method
(Not applicable - Rust function)

### Endpoint
(Not applicable - Rust function)

### Parameters
(Not explicitly detailed in source)

### Request Example
(Not applicable - Rust function)

### Response
(Not explicitly detailed in source)

## oxichrome::storage::set

### Description
Sets an item in local storage.

### Method
(Not applicable - Rust function)

### Endpoint
(Not applicable - Rust function)

### Parameters
(Not explicitly detailed in source)

### Request Example
(Not applicable - Rust function)

### Response
(Not explicitly detailed in source)

## oxichrome::storage::remove

### Description
Removes an item from local storage.

### Method
(Not applicable - Rust function)

### Endpoint
(Not applicable - Rust function)

### Parameters
(Not explicitly detailed in source)

### Request Example
(Not applicable - Rust function)

### Response
(Not explicitly detailed in source)
```

--------------------------------

### Async/Await Pattern for Chrome API Interactions

Source: https://github.com/0xsouravm/oxichrome/blob/main/_autodocs/README.md

Demonstrates the use of `async`/`await` for interacting with Chrome APIs, which are inherently asynchronous. Shows how to fetch data and spawn background tasks.

```rust
// Always use await
let value = oxichrome::storage::get("key").await?;

// Or spawn in background
wasm_bindgen_futures::spawn_local(async {
    let _ = oxichrome::storage::set("key", &value).await;
});
```

--------------------------------

### create

Source: https://github.com/0xsouravm/oxichrome/blob/main/_autodocs/api-reference/tabs.md

Creates a new tab with the specified properties. It takes a serializable properties object and returns the created tab data.

```APIDOC
## create

### Description
Creates a new tab with the specified properties. It takes a serializable properties object and returns the created tab data.

### Function Signature
`pub async fn create<P: Serialize, T: DeserializeOwned>(props: &P) -> Result<T>`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
* **props** (`&P` where `P: Serialize`) - Required - Properties for the new tab. Serializable to JSON

### Request Example
```rust
use oxichrome::tabs;
use serde::{Serialize, Deserialize};

#[derive(Serialize)]
struct CreateTabProps {
    url: String,
    active: bool,
}

#[derive(Deserialize)]
struct Tab {
    id: i32,
    url: Option<String>,
}

async fn create_tab() -> Result<(), Box<dyn std::error::Error>> {
    let props = CreateTabProps {
        url: "https://example.com".to_string(),
        active: true,
    };
    let tab: Tab = tabs::create(&props).await?;
    println!("Created tab with ID: {}", tab.id);
    Ok(())
}
```

### Response
#### Success Response
* **T** - The created tab deserialized as type `T`.

#### Response Example
(See Request Example for usage)

### Errors
* **OxichromeError::Serde**: If serialization of properties or deserialization of the result fails
* **OxichromeError::Js**: If the underlying JavaScript promise rejects
```

--------------------------------

### Example Usage of Oxichrome Result

Source: https://github.com/0xsouravm/oxichrome/blob/main/_autodocs/types.md

Demonstrates how to use the `Result` type alias in an asynchronous function that returns a successful string value.

```rust
use oxichrome::Result;

async fn example() -> Result<String> {
    Ok("success".to_string())
}
```

--------------------------------

### chrome.runtime.getURL

Source: https://github.com/0xsouravm/oxichrome/blob/main/_autodocs/chrome-api-bindings.md

Get the full URL of an extension resource. This function takes a path and returns the complete URL for that resource within the extension.

```APIDOC
## chrome.runtime.getURL

### Description
Get the full URL of an extension resource.

### Method
GET (conceptual, as it's a function call)

### Endpoint
chrome.runtime.getURL(path)

### Parameters
#### Path Parameters
- **path** (string) - Required - The path to the extension resource.

### Response
#### Success Response
- **url** (string) - The full URL of the extension resource.

### Response Example
```json
{
  "url": "chrome-extension://xyz/icons/icon.png"
}
```
```

--------------------------------

### Store and Retrieve User Settings with Storage

Source: https://github.com/0xsouravm/oxichrome/blob/main/_autodocs/guide-common-patterns.md

Use oxichrome's storage API to persist user preferences across sessions. Initialize default settings if none exist.

```rust
use oxichrome::prelude::*;
use serde::{Serialize, Deserialize};

#[derive(Serialize, Deserialize, Clone, Copy)]
struct UserSettings {
    theme: u8,  // 0 = light, 1 = dark
    notifications_enabled: bool,
}

#[oxichrome::background]
async fn start() {
    // Initialize default settings on first run
    if let Ok(None) = oxichrome::storage::get::<UserSettings>("settings").await {
        let defaults = UserSettings {
            theme: 0,
            notifications_enabled: true,
        };
        let _ = oxichrome::storage::set("settings", &defaults).await;
    }
}

#[oxichrome::popup]
fn Popup() -> impl IntoView {
    let settings = RwSignal::new(UserSettings {
        theme: 0,
        notifications_enabled: true,
    });

    Effect::new(move || {
        wasm_bindgen_futures::spawn_local(async move {
            if let Ok(Some(s)) = oxichrome::storage::get("settings").await {
                settings.set(s);
            }
        });
    });

    let toggle_notifications = move |_| {
        settings.update(|s| s.notifications_enabled = !s.notifications_enabled);
        let s = settings.get_untracked();
        wasm_bindgen_futures::spawn_local(async move {
            let _ = oxichrome::storage::set("settings", &s).await;
        });
    };

    view! {
        <div>
            <h2>"Settings"</h2>
            <label>
                <input
                    type="checkbox"
                    checked=move || settings.get().notifications_enabled
                    on:change=toggle_notifications
                />
                "Enable Notifications"
            </label>
        </div>
    }
}
```

--------------------------------

### oxichrome::options_page

Source: https://github.com/0xsouravm/oxichrome/blob/main/_autodocs/api-reference/macros.md

Marks a Leptos component as the extension options page UI. The component must be a function returning `impl IntoView`, conventionally named `Options`, and can leverage all Leptos features for a reactive UI within the full-page options context.

```APIDOC
## #[oxichrome::options_page]

Marks a Leptos component as the extension options page UI.

### Signature:

```rust
#[oxichrome::options_page]
fn Options() -> impl IntoView {
    view! {
        // Leptos JSX syntax
    }
}
```

### Notes:

- Component must be a function that returns `impl IntoView`
- Uses Leptos for reactive UI
- Component name should be `Options` (capitalized) by convention
- Renders in the full-page options page context
- Can use all Leptos features
- Typically larger and more complex than the popup UI

### Example:

```rust
use leptos::prelude::*
use oxichrome::prelude::*

#[oxichrome::options_page]
fn Options() -> impl IntoView {
    view! {
        <div>
            <h1>"Extension Settings"</h1>
            <p>"Configure your extension preferences here."</p>
        </div>
    }
}
```
```

--------------------------------

### Storage API Operations

Source: https://github.com/0xsouravm/oxichrome/blob/main/_autodocs/quick-reference.md

Demonstrates reading, writing, and deleting data using the Storage API.

```rust
use oxichrome::storage;

// Read
let count: Option<i32> = storage::get("count").await?;

// Write
storage::set("count", &42).await?;

// Delete
storage::remove("count").await?;
```

--------------------------------

### Event Listeners Macro

Source: https://github.com/0xsouravm/oxichrome/blob/main/_autodocs/api-reference/overview.md

Registers handlers for various Chrome events, such as extension installation, message reception, tab updates, and storage changes.

```APIDOC
## Event Listeners

### Description
Register handlers for Chrome events.

### Macro Signature
```rust
#[oxichrome::on(event_identifier)]
async fn handler(details: JsValue) {
    // event handling logic
}
```

### Supported Events
- `runtime::on_installed`
- `runtime::on_message`
- `tabs::on_updated`
- `tabs::on_activated`
- `storage::on_changed`
```

--------------------------------

### Basic Error Handling with Match

Source: https://github.com/0xsouravm/oxichrome/blob/main/_autodocs/api-reference/errors.md

Illustrates basic error handling for storage operations using a match statement to handle Ok, None, and Err cases.

```rust
use oxichrome::storage;

async fn load_setting() {
    match storage::get::<String>("theme").await {
        Ok(Some(theme)) => println!("Theme: {}", theme),
        Ok(None) => println!("No theme set"),
        Err(e) => eprintln!("Error: {}", e),
    }
}
```

--------------------------------

### Result Type Alias Usage Example

Source: https://github.com/0xsouravm/oxichrome/blob/main/_autodocs/api-reference/errors.md

Demonstrates using the Result type alias for ergonomic error handling with the `?` operator in an async function.

```rust
use oxichrome::{storage, Result};

async fn example() -> Result<()> {
    let count: Option<i32> = storage::get("count").await?;
    storage::set("count", &(count.unwrap_or(0) + 1)).await?;
    Ok(())
}
```

--------------------------------

### Options Page UI Component

Source: https://github.com/0xsouravm/oxichrome/blob/main/README.md

Marks a Leptos component as the extension's options page UI using the `#[oxichrome::options_page]` macro.

```rust
#[oxichrome::options_page]
fn Options() -> impl IntoView {
    view! { <h1>"Settings"</h1> }
}
```

--------------------------------

### oxichrome::runtime

Source: https://github.com/0xsouravm/oxichrome/blob/main/_autodocs/api-reference/overview.md

Access extension runtime and utilities. Provides functions to get extension resource URLs and send messages to background or other frames.

```APIDOC
## oxichrome::runtime

### Description
Access extension runtime and utilities.

### Functions
#### get_url(path: &str)
- **Purpose**: Get extension resource URL
- **Return Type**: `String`

#### send_message(msg)
- **Purpose**: Send to background or other frames
- **Return Type**: `Result<JsValue>`

### Example
```rust
let icon_url = oxichrome::runtime::get_url("icons/16.png");
let response = oxichrome::runtime::send_message(&msg).await?;
```
```

--------------------------------

### Get Data from Storage API

Source: https://github.com/0xsouravm/oxichrome/blob/main/_autodocs/INDEX.txt

Retrieves data stored persistently. Use this function to access previously saved extension settings or data.

```rust
storage::get("key")
```

--------------------------------

### Define Options Page with Macro

Source: https://github.com/0xsouravm/oxichrome/blob/main/_autodocs/INDEX.txt

The `#[oxichrome::options_page]` macro specifies the function that will render the extension's options page.

```Rust
#[oxichrome::options_page]
fn options_page() {
    // Options page rendering
}
```

--------------------------------

### Get URL in Runtime API

Source: https://github.com/0xsouravm/oxichrome/blob/main/_autodocs/INDEX.txt

Retrieves the URL for a given resource within the extension's runtime. This is useful for accessing extension assets.

```rust
runtime::get_url("path/to/resource")
```

--------------------------------

### Load Temporary Add-on in Firefox

Source: https://github.com/0xsouravm/oxichrome/blob/main/_autodocs/api-reference/overview.md

Instructions for loading a temporary Oxichrome add-on in Firefox via `about:debugging`.

```text
- **Firefox:** `about:debugging` → "Load Temporary Add-on" → select `dist/firefox/manifest.json`
```

--------------------------------

### Example of OxichromeError Enum

Source: https://github.com/0xsouravm/oxichrome/blob/main/_autodocs/INDEX.txt

Shows the variants of the OxichromeError enum, which is used for error handling throughout the framework. Helps in understanding possible failure scenarios.

```rust
enum OxichromeError { JsError(JsError), IoError(String), OtherError(String) }
```

--------------------------------

### Get Chrome Extension Resource URL

Source: https://github.com/0xsouravm/oxichrome/blob/main/_autodocs/chrome-api-bindings.md

Retrieves the full URL for an extension resource. Use this to construct valid URLs for assets within your extension.

```rust
#[wasm_bindgen(js_namespace = ["chrome", "runtime"], js_name = getURL)]
pub fn chrome_runtime_get_url(path: &str) -> String;
```

```javascript
chrome.runtime.getURL(path)
```

```rust
let url = oxichrome::runtime::get_url("icons/icon.png");
// Returns: "chrome-extension://xyz/icons/icon.png"
```

--------------------------------

### Error Propagation with the `?` Operator

Source: https://github.com/0xsouravm/oxichrome/blob/main/_autodocs/errors.md

Use the `?` operator for ergonomic error propagation up the call stack when performing storage operations like getting and setting values.

```rust
use oxichrome::{storage, Result};

async fn get_and_increment() -> Result<()> {
    let count: Option<i32> = storage::get("count").await?;
    let new = count.unwrap_or(0) + 1;
    storage::set("count", &new).await?;
    Ok(())
}

// In calling code:
match get_and_increment().await {
    Ok(_) => println!("Success"),
    Err(e) => eprintln!("Error: {}", e),
}
```

--------------------------------

### Development Build Command

Source: https://github.com/0xsouravm/oxichrome/blob/main/_autodocs/api-reference/overview.md

Command to create a development build for the Oxichrome extension.

```bash
cargo oxichrome build
```

--------------------------------

### Oxichrome Extension File Structure

Source: https://github.com/0xsouravm/oxichrome/blob/main/_autodocs/quick-reference.md

Illustrates a typical file structure for an Oxichrome extension, including the main library file, manifest, and assets.

```text
src/
├── lib.rs                     # Extension root
│   ├── #[extension(...)]      # Metadata
│   ├── #[background] start()  # Service worker
│   ├── #[popup] Popup()       # Popup UI
│   └── #[on(...)] handlers()  # Event listeners
Cargo.toml                      # Dependencies
assets/
├── icon.png                   # Extension icon
└── styles.css                 # Styles (for content scripts)
```

--------------------------------

### Initialize Extension Resources in Background Worker

Source: https://github.com/0xsouravm/oxichrome/blob/main/_autodocs/errors.md

Use the `#[oxichrome::background]` macro to initialize resources and ensure Chrome APIs are safe to use after extension initialization.

```rust
#[oxichrome::background]
async fn start() {
    // Initialize resources here
    oxichrome::log!("Background worker started");
    
    // Now it's safe to use storage
    let _ = oxichrome::storage::set("initialized", &true).await;
}
```

--------------------------------

### Background Service Worker Entry Point

Source: https://github.com/0xsouravm/oxichrome/blob/main/README.md

Marks an asynchronous function as the entry point for the extension's background service worker using `#[oxichrome::background]`.

```rust
#[oxichrome::background]
async fn start() {
    oxichrome::log!("Started.");
}
```

--------------------------------

### Get Data from Chrome Local Storage

Source: https://github.com/0xsouravm/oxichrome/blob/main/_autodocs/chrome-api-bindings.md

Retrieves values from the browser's local storage. Pass a key, an array of keys, or null to retrieve all stored items.

```rust
#[wasm_bindgen(js_namespace = ["chrome", "storage", "local"], js_name = get)]
pub fn chrome_storage_local_get(keys: &JsValue) -> js_sys::Promise;
```

```javascript
chrome.storage.local.get(keys)
```

--------------------------------

### Load Unpacked Extension in Chrome

Source: https://github.com/0xsouravm/oxichrome/blob/main/_autodocs/api-reference/overview.md

Instructions for loading an unpacked Oxichrome extension in Chrome via `chrome://extensions`.

```text
- **Chrome:** `chrome://extensions` → "Load unpacked" → select `dist/chromium/`
```

--------------------------------

### Macros

Source: https://github.com/0xsouravm/oxichrome/blob/main/_autodocs/INDEX.txt

Documentation for Oxichrome's procedural macros used for defining extension components.

```APIDOC
## #[oxichrome::extension]

### Description
Attribute macro to define the main entry point of an extension.

### Method
(Not applicable - Macro attribute)

### Endpoint
(Not applicable - Macro attribute)

### Parameters
(Not explicitly detailed in source)

### Request Example
(Not applicable - Macro attribute)

### Response
(Not applicable - Macro attribute)

## #[oxichrome::background]

### Description
Attribute macro to define a background script for the extension.

### Method
(Not applicable - Macro attribute)

### Endpoint
(Not applicable - Macro attribute)

### Parameters
(Not explicitly detailed in source)

### Request Example
(Not applicable - Macro attribute)

### Response
(Not applicable - Macro attribute)

## #[oxichrome::on]

### Description
Attribute macro for event handling within the extension.

### Method
(Not applicable - Macro attribute)

### Endpoint
(Not applicable - Macro attribute)

### Parameters
(Not explicitly detailed in source)

### Request Example
(Not applicable - Macro attribute)

### Response
(Not applicable - Macro attribute)

## #[oxichrome::popup]

### Description
Attribute macro to define a popup UI for the extension.

### Method
(Not applicable - Macro attribute)

### Endpoint
(Not applicable - Macro attribute)

### Parameters
(Not explicitly detailed in source)

### Request Example
(Not applicable - Macro attribute)

### Response
(Not applicable - Macro attribute)

## #[oxichrome::options_page]

### Description
Attribute macro to define the options page for the extension.

### Method
(Not applicable - Macro attribute)

### Endpoint
(Not applicable - Macro attribute)

### Parameters
(Not explicitly detailed in source)

### Request Example
(Not applicable - Macro attribute)

### Response
(Not applicable - Macro attribute)

## #[oxichrome::content_script]

### Description
Attribute macro to define a content script for the extension.

### Method
(Not applicable - Macro attribute)

### Endpoint
(Not applicable - Macro attribute)

### Parameters
(Not explicitly detailed in source)

### Request Example
(Not applicable - Macro attribute)

### Response
(Not applicable - Macro attribute)
```

--------------------------------

### Release Build with Wasm-Opt

Source: https://github.com/0xsouravm/oxichrome/blob/main/_autodocs/build-and-deployment.md

Combine release build optimization with wasm-opt for maximum WASM file size reduction and performance improvement.

```bash
cargo oxichrome build --release --wasm-opt
```

--------------------------------

### Get Value from Local Storage

Source: https://github.com/0xsouravm/oxichrome/blob/main/_autodocs/api-reference/storage.md

Retrieves a value associated with a given key from local storage. The value is deserialized into the specified type T. Returns None if the key does not exist.

```rust
use oxichrome::storage;

async fn get_counter() -> Result<(), Box<dyn std::error::Error>> {
    let count: Option<i32> = storage::get("counter").await?;
    match count {
        Some(val) => println!("Current count: {}", val),
        None => println!("Counter not initialized"),
    }
    Ok(())
}
```

--------------------------------

### Build Oxichrome Extension

Source: https://github.com/0xsouravm/oxichrome/blob/main/_autodocs/quick-reference.md

Builds the Oxichrome extension for Chromium or Firefox.

```bash
cargo oxichrome build              # Chromium
cargo oxichrome build --target firefox  # Firefox
```

--------------------------------

### Get data from storage

Source: https://github.com/0xsouravm/oxichrome/blob/main/_autodocs/module-index.md

Asynchronously retrieves data from persistent local storage using a specified key. The data is deserialized into the provided type T. Returns Ok(None) if the key does not exist.

```rust
pub async fn get<T: DeserializeOwned>(key: &str) -> Result<Option<T>>
```

--------------------------------

### Logging Messages

Source: https://github.com/0xsouravm/oxichrome/blob/main/_autodocs/quick-reference.md

Shows how to log messages with different formatting options using the `oxichrome::log!` macro.

```rust
oxichrome::log!("Hello");
oxichrome::log!("Value: {}", 42);
oxichrome::log!("Debug: {:?}", obj);
```

--------------------------------

### get

Source: https://github.com/0xsouravm/oxichrome/blob/main/_autodocs/api-reference/storage.md

Retrieves a value from local storage by its key. The value is deserialized into the specified type `T`. Returns `Ok(Some(value))` if found, `Ok(None)` if not found, or an error on deserialization or JavaScript promise rejection.

```APIDOC
## get

### Description
Retrieves a value from local storage.

### Method
`async fn get<T: DeserializeOwned>(key: &str) -> Result<Option<T>>`

### Parameters
#### Path Parameters
- **key** (`&str`) - Required - The key to retrieve from storage

### Response
#### Success Response
- **Option<T>** - `Some(value)` if the key exists and can be deserialized as type `T`, `None` if the key does not exist.

### Errors
- `OxichromeError::Serde` - If deserialization of the stored value fails
- `OxichromeError::Js` - If the underlying JavaScript promise rejects

### Example
```rust
use oxichrome::storage;

async fn get_counter() -> Result<(), Box<dyn std::error::Error>> {
    let count: Option<i32> = storage::get("counter").await?;
    match count {
        Some(val) => println!("Current count: {}", val),
        None => println!("Counter not initialized"),
    }
    Ok(())
}
```
```

--------------------------------

### Get Extension Resource URL

Source: https://github.com/0xsouravm/oxichrome/blob/main/_autodocs/api-reference/runtime.md

Retrieves the full URL for a given resource path relative to the extension's root. This is useful for referencing assets like icons or HTML files within your extension.

```Rust
pub fn get_url(path: &str) -> String
```

```Rust
use oxichrome::runtime;

fn load_icon() {
    let icon_url = runtime::get_url("icon.png");
    println!("Icon URL: {}", icon_url);
}
```

--------------------------------

### Common Oxichrome Imports

Source: https://github.com/0xsouravm/oxichrome/blob/main/_autodocs/module-index.md

Import the prelude for easy access to common Oxichrome features like extensions, backgrounds, popups, and storage.

```rust
use oxichrome::prelude::*;
```

--------------------------------

### Reinstall Cargo-Oxichrome

Source: https://github.com/0xsouravm/oxichrome/blob/main/_autodocs/build-and-deployment.md

Troubleshoot wasm-bindgen version mismatches by forcefully reinstalling cargo-oxichrome.

```bash
# Remove cargo-oxichrome and reinstall
cargo install --force cargo-oxichrome
```

--------------------------------

### Background Service Worker Entry Point

Source: https://github.com/0xsouravm/oxichrome/blob/main/_autodocs/api-reference/overview.md

The `#[background]` proc macro marks the entry point for the extension's background service worker. This function runs once when the extension is loaded.

```rust
#[oxichrome::background]
async fn start() {
    oxichrome::log!("Running!");
}
```

--------------------------------

### Define Popup with Macro

Source: https://github.com/0xsouravm/oxichrome/blob/main/_autodocs/INDEX.txt

The `#[oxichrome::popup]` macro is used to define the entry point for the extension's popup UI.

```Rust
#[oxichrome::popup]
fn popup_ui() {
    // Popup UI logic
}
```

--------------------------------

### Basic Extension Metadata Configuration

Source: https://github.com/0xsouravm/oxichrome/blob/main/_autodocs/configuration.md

Defines the essential metadata for an Oxichrome extension, including its name and version. This is the minimum required configuration for any extension.

```rust
#[oxichrome::extension(
    name = "Extension Name",
    version = "1.0.0",
    description = "Optional description",
    permissions = ["storage", "tabs"]
)]
struct Extension;
```

--------------------------------

### Create New Tab

Source: https://github.com/0xsouravm/oxichrome/blob/main/_autodocs/api-reference/overview.md

Creates a new browser tab with specified properties. Returns the newly created Tab object.

```rust
let tab: Tab = oxichrome::tabs::create(&props).await?;
```

--------------------------------

### Initialize on First Run

Source: https://github.com/0xsouravm/oxichrome/blob/main/_autodocs/quick-reference.md

Execute initialization logic once when the extension first runs. This snippet checks if an 'initialized' flag is set in storage and sets it if not.

```rust
#[oxichrome::background]
async fn start() {
    if let Ok(None) = oxichrome::storage::get::<bool>("initialized").await {
        let _ = oxichrome::storage::set("initialized", &true).await;
    }
}
```