Camofox-Browser Search Macros: Available Identifiers and Expansion Mechanics

Camofox-browser provides 14 predefined search macros (e.g., @google_search, @youtube_search) defined in 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 (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) 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, 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 (line 1765), the navigation handler receives requests containing optional macro and query fields:

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	Defines the MACROS map, expandMacro(), and getSupportedMacros()
server.js	Invokes macro expansion at line 1765 during navigation request processing
tests/unit/macros.test.js	Validates expansion logic and edge cases

Practical Usage Examples

Manual Expansion in Node.js

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:

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

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

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

Handling Unknown Macros

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 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 (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, 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, 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, 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}