# Camofox-Browser Search Macros: Available Identifiers and Expansion Mechanics

> Discover available Camofox-browser search macros and understand macro expansion mechanics. Learn how this tool transforms your queries into URLs for enhanced browsing.

- Repository: [jo/camofox-browser](https://github.com/jo-inc/camofox-browser)
- Tags: api-reference
- Published: 2026-04-15

---

**Camofox-browser provides 14 predefined search macros (e.g., `@google_search`, `@youtube_search`) defined in [`lib/macros.js`](https://github.com/jo-inc/camofox-browser/blob/main/lib/macros.js) that transform into URLs via the `expandMacro()` function, which encodes queries using `encodeURIComponent` and falls back to `null` for unrecognized identifiers.**

The **jo-inc/camofox-browser** repository implements a lightweight macro system for programmatic navigation. Search macros allow agents to request navigation to popular platforms using concise `@` prefixed identifiers rather than constructing full URLs manually.

## Available Camofox-Browser Search Macros

The macro library defines 14 supported identifiers in **[`lib/macros.js`](https://github.com/jo-inc/camofox-browser/blob/main/lib/macros.js)** (lines 2-15). Each macro generates a platform-specific search URL:

- **`@google_search`** → `https://www.google.com/search?q={encoded_query}`
- **`@youtube_search`** → `https://www.youtube.com/results?search_query={encoded_query}`
- **`@amazon_search`** → `https://www.amazon.com/s?k={encoded_query}`
- **`@reddit_search`** → `https://www.reddit.com/search.json?q={encoded_query}&limit=25`
- **`@reddit_subreddit`** → `https://www.reddit.com/r/{encoded_query}.json?limit=25`
- **`@wikipedia_search`** → `https://en.wikipedia.org/wiki/Special:Search?search={encoded_query}`
- **`@twitter_search`** → `https://twitter.com/search?q={encoded_query}`
- **`@yelp_search`** → `https://www.yelp.com/search?find_desc={encoded_query}`
- **`@spotify_search`** → `https://open.spotify.com/search/{encoded_query}`
- **`@netflix_search`** → `https://www.netflix.com/search?q={encoded_query}`
- **`@linkedin_search`** → `https://www.linkedin.com/search/results/all/?keywords={encoded_query}`
- **`@instagram_search`** → `https://www.instagram.com/explore/tags/{encoded_query}`
- **`@tiktok_search`** → `https://www.tiktok.com/search?q={encoded_query}`
- **`@twitch_search`** → `https://www.twitch.tv/search?term={encoded_query}`

The **`getSupportedMacros()`** function (line 24 in [`lib/macros.js`](https://github.com/jo-inc/camofox-browser/blob/main/lib/macros.js)) returns an array of all available macro keys for runtime discovery and UI population.

## How Macro Expansion Works

The expansion process follows a three-step pipeline implemented across the core library and server components.

### The expandMacro Function

Located in **[`lib/macros.js`](https://github.com/jo-inc/camofox-browser/blob/main/lib/macros.js)**, `expandMacro(macro, query)` performs lookup and URL generation:

1. **Lookup**: Retrieves the function associated with the macro identifier from the internal `MACROS` map.
2. **Generation**: Executes the function with the provided query (defaulting to empty string), which returns a URL with the query encoded via `encodeURIComponent`.
3. **Fallback**: Returns `null` if the macro identifier is not recognized, enabling the server to handle the error gracefully.

### Server Integration

In **[`server.js`](https://github.com/jo-inc/camofox-browser/blob/main/server.js)** (line 1765), the navigation handler receives requests containing optional `macro` and `query` fields:

```javascript
targetUrl = expandMacro(macro, query) || url;

```

If `expandMacro` returns a valid URL, the server navigates to that destination. If it returns `null` (unknown macro), the server falls back to the raw `url` field from the client request.

## Implementation Details and Source Files

| File | Purpose |
|------|---------|
| **[`lib/macros.js`](https://github.com/jo-inc/camofox-browser/blob/main/lib/macros.js)** | Defines the `MACROS` map, `expandMacro()`, and `getSupportedMacros()` |
| **[`server.js`](https://github.com/jo-inc/camofox-browser/blob/main/server.js)** | Invokes macro expansion at line 1765 during navigation request processing |
| **[`tests/unit/macros.test.js`](https://github.com/jo-inc/camofox-browser/blob/main/tests/unit/macros.test.js)** | Validates expansion logic and edge cases |

## Practical Usage Examples

### Manual Expansion in Node.js

```javascript
import { expandMacro } from './lib/macros.js';

const url = expandMacro('@google_search', 'camofox browser');
// Result: https://www.google.com/search?q=camofox%20browser
console.log(url);

```

### HTTP API Navigation

Send a POST request to the tab navigation endpoint:

```http
POST /tabs/abc123/navigate
Content-Type: application/json

{
  "userId": "agent1",
  "macro": "@youtube_search",
  "query": "funny cats"
}

```

The server expands this to:

```

https://www.youtube.com/results?search_query=funny%20cats

```

### Retrieving Supported Macros

```javascript
import { getSupportedMacros } from './lib/macros.js';

const available = getSupportedMacros();
console.log(available);
// Output: ['@google_search', '@youtube_search', ..., '@twitch_search']

```

### Handling Unknown Macros

```javascript
import { expandMacro } from './lib/macros.js';

const result = expandMacro('@invalid_macro', 'test');
console.log(result); // null

```

When `expandMacro` returns `null`, the server ignores the macro and uses the provided `url` field instead.

## Summary

- **Camofox-browser** provides 14 predefined search macros in [`lib/macros.js`](https://github.com/jo-inc/camofox-browser/blob/main/lib/macros.js) for popular platforms including Google, YouTube, Reddit, and LinkedIn.
- **`expandMacro()`** handles expansion by looking up identifiers in the `MACROS` map, encoding queries with `encodeURIComponent`, and returning fully qualified URLs.
- The server implementation in **[`server.js`](https://github.com/jo-inc/camofox-browser/blob/main/server.js)** (line 1765) integrates macro expansion into navigation requests, falling back to raw URLs when macros are unrecognized.
- **`getSupportedMacros()`** enables runtime discovery of available identifiers for dynamic UI generation.
- All macros handle empty queries gracefully and return `null` for invalid identifiers to ensure robust fallback behavior.

## Frequently Asked Questions

### What happens if I use an unsupported macro in camofox-browser?

If you provide an unrecognized macro identifier, `expandMacro()` returns `null`. According to the implementation in [`server.js`](https://github.com/jo-inc/camofox-browser/blob/main/server.js), the server then falls back to using the raw `url` field supplied in the request, ensuring the navigation still proceeds if a direct URL is available.

### How does camofox-browser handle special characters in search queries?

The macro expansion system automatically applies `encodeURIComponent()` to all query strings. This occurs within each macro function defined in [`lib/macros.js`](https://github.com/jo-inc/camofox-browser/blob/main/lib/macros.js), ensuring that spaces, symbols, and Unicode characters are safely encoded for URL transmission.

### Can I add custom search macros to camofox-browser?

While the repository provides 14 built-in macros in [`lib/macros.js`](https://github.com/jo-inc/camofox-browser/blob/main/lib/macros.js), you can extend the system by adding new entries to the `MACROS` object following the pattern: `'@custom_name': (query) => 'https://example.com/search?q=${encodeURIComponent(query || '')}'`. The `expandMacro()` function will automatically include your custom macro in its lookup logic.

### Where is the macro expansion logic called in the server?

The server invokes macro expansion at **line 1765** of [`server.js`](https://github.com/jo-inc/camofox-browser/blob/main/server.js) within the navigation request handler. The code assigns `targetUrl` by calling `expandMacro(macro, query)` and using the logical OR operator to fall back to the client-provided `url` parameter if expansion returns `null`.