REX Module Map

This page describes every public REX module: what it does, what it depends on, and when to extend it. Use it to find where a new feature belongs before writing any code. For a plain-language introduction aimed at researchers, see Module Overview.

The rule before you write anything: Search all existing modules first. Use the module as is, or if you need modifications, change it in the repository where it exists. If you are not sure where something belongs, email info@bric.digital before starting.

Decision Guide

I want to…	Look at
Record browsing history	`rex-history`
Rebuild referral chains, including redirects and new-tab openers	`rex-visit-graph`
Record when pages open, close, and gain or lose focus	`rex-page-events`
Detect the participant’s default search engine	`rex-browser-settings`
Record search engine results pages, including AI and news elements	`rex-search-mirror`
Record chatbot questions and answers as they happen	`rex-live-mirror`
Record news homepage headlines and discovery feeds	`rex-live-mirror`
Collect a participant’s past chatbot conversations	`rex-spider` plus a platform plugin (`rex-spider-chatgpt`, `rex-spider-gemini`, `rex-spider-google-ai`, `rex-spider-perplexity`)
Add a new chatbot platform to collect past conversations from	a new `rex-spider-<platform>` plugin on `rex-spider`
Block or redirect specific pages or URLs	`rex-page-manipulation`
Hide, obscure, or restyle elements on a page	`rex-page-manipulation`
Add or change HTTP request headers	`rex-headers`
Replace the new tab page	`rex-default-page`
Store domain and URL lists and match URLs against them	`rex-lists`
Let participants view and edit their lists	`rex-lists-front-end`
Let participants browse and delete their collected history	`rex-history-data-table`
Move participants through study phases or assign conditions	`rex-autorunner`
Redact personal information before data leaves the browser	`rex-content-processing`
Let participants download their own data	`rex-local-download`
Transmit data to a PDK server	`rex-passive-data-kit`
Add a new way to store or export collected data	`rex-data-collection` (subclass it)
Share type definitions across modules	`rex-types`
Add extension infrastructure used by all modules	`rex-core`

When to Propose a New Module

Most features belong in an existing module. Before proposing a new one, check the four criteria in Getting Placement Right. If none apply, extend an existing module instead.

How to Read This Map

Each module entry has:

Repository and Package: where the code lives and the name you install
What it does: the module’s single responsibility
Key capabilities: specific things it provides
Config key: the section of the extension configuration it reads
Records: the name values of the data records it produces
Depends on: other modules it requires, from its package.json on main
Required by: other modules that depend on it
In REX Demo: whether the public demo includes it
Extend this module when: the right reasons to add to it
Do NOT extend this module for: what belongs elsewhere

Modules are grouped by function. All listed modules are public open-source repositories under github.com/bric-digital. Most have no tagged releases yet and are installed from their main branch.

How the modules fit together

Each layer depends only on the layers above it. Every module depends on rex-core.

rex-core
 |
 +-- rex-types, rex-lists, rex-content-processing, rex-spider
 |    |
 |    +-- rex-data-collection        (needs rex-content-processing)
 |    |    +-- rex-local-download
 |    |         +-- rex-history-data-table   (at runtime, with rex-history)
 |    |
 |    +-- rex-passive-data-kit       (needs rex-content-processing)
 |    +-- rex-history, rex-visit-graph, rex-page-events, rex-live-mirror
 |    |                              (need rex-lists and rex-types)
 |    +-- rex-search-mirror          (needs rex-types)
 |    +-- rex-lists-front-end        (needs rex-lists)
 |    +-- rex-spider-chatgpt, rex-spider-gemini,
 |        rex-spider-google-ai, rex-spider-perplexity
 |                                   (need rex-spider and rex-types)
 |
 +-- rex-browser-settings, rex-page-manipulation, rex-headers,
     rex-default-page, rex-autorunner (need only rex-core)

Foundation

rex-core

Repository: bric-digital/rex-core · Package: @bric/rex-core

What it does: The infrastructure every REX extension is built on. Manages the extension lifecycle, chrome.storage, configuration fetching from the study’s server, identifier management, and the message-passing system all other modules use.

Key capabilities:

Fetches and caches extension configuration from configuration_url
Manages the participant identifier
Provides base classes for all module types (REXServiceWorkerModule, REXClientModule, REXExtensionModule) and registerREXModule
Provides dispatchEvent, the event bus other modules log records through
Builds the extension’s pages from the ui configuration section

Config key: configuration_url, ui

Records: None of its own.

Depends on: Nothing. This is the root.

Required by: Every module and every extension.

In REX Demo: Yes.

Extend this module when: You are adding infrastructure that every module needs: new storage abstractions, new base class capabilities, new core message types.

Do NOT extend this module for: Any data collection, UI, or domain-specific logic. Those belong in their own modules.

rex-types

Repository: bric-digital/rex-types · Package: @bric/rex-types

What it does: Shared TypeScript type definitions used across modules to keep data structures consistent.

Key capabilities: Types for conversations, turns, citations, search results, news blurbs, and page events, plus DateString for timestamps.

Config key: None.

Records: None.

Depends on: rex-core

Required by: rex-history, rex-visit-graph, rex-page-events, rex-search-mirror, rex-live-mirror, and every spider plugin.

In REX Demo: Yes, through other modules.

Extend this module when: You are adding a new data record type that two or more independent modules will need to reference.

Do NOT extend this module for: Module-specific types that are only used internally. Keep those inside the module.

rex-lists

Repository: bric-digital/rex-lists · Package: @bric/rex-lists

What it does: Stores and queries named URL and domain pattern lists in IndexedDB. This is the storage and matching engine, with no UI.

Key capabilities:

Named lists with entries of these pattern types: domain (a registered domain and all of its subdomains), host (one exact hostname), exact_url, host_path_prefix, and regex. subdomain_wildcard is a legacy name that behaves like host.
Matching a URL against any entry in a list
Holds entries from the study configuration, entries participants add, and generated entries
Sync from the lists section of the configuration, bulk create and delete, import and export

Config key: lists

Records: None.

Depends on: rex-core

Required by: rex-history, rex-visit-graph, rex-page-events, rex-live-mirror, rex-lists-front-end

In REX Demo: Yes.

Extend this module when: You need a new pattern type, a new list operation, or improvements to matching performance.

Do NOT extend this module for: UI. That is rex-lists-front-end.

Data Pipeline and Output

rex-data-collection

Repository: bric-digital/rex-data-collection · Package: @bric/rex-data-collection

What it does: The shared pipeline that turns logged events into stored records: it runs content processing, adds the passive-data-metadata block (participant ID, record type, timestamp, time zone, configuration hash), queues records, and saves them to IndexedDB. It is a base class. Output modules subclass it; an extension never registers it directly.

Key capabilities:

REXDataCollectionModule, the abstract base for output modules
Runs every record through rex-content-processing before storing it

Config key: Set by each subclass.

Records: None of its own.

Depends on: rex-core, rex-content-processing

Required by: rex-local-download. (rex-passive-data-kit has its own copy of this pipeline for now; moving it onto this base class is planned.)

In REX Demo: Yes, through rex-local-download.

Extend this module when: You need a change that every output module should share, such as a new metadata field or a change to how records are queued.

Do NOT extend this module for: Anything specific to one output. Subclass it in the output module instead.

rex-content-processing

Repository: bric-digital/rex-content-processing · Package: @bric/rex-content-processing

What it does: Processes and sanitizes content before it is stored or transmitted, primarily by detecting and redacting personal information.

Key capabilities:

Redaction processors: OpenRedaction, regular expressions, and PII sanitizing
Fields whose names end in * (such as content* and title*) are always processed

Config key: content_processing

Records: None.

Depends on: rex-core, openredaction-in-browser

Required by: rex-data-collection, rex-passive-data-kit

In REX Demo: Yes, through rex-local-download.

Extend this module when: You need a new redaction rule or processing step.

Do NOT extend this module for: Data transmission or storage. Those belong in rex-data-collection and the output modules.

openredaction-in-browser

Repository: bric-digital/openredaction-in-browser · Package: openredaction-in-browser

What it does: Browser-focused detection and redaction of personal information using regular expressions. A browser adaptation of the open-source OpenRedaction library, used by rex-content-processing.

Key capabilities:

Pattern matching for personal information such as names, email addresses, phone numbers, and street addresses
Configurable redaction, all running locally in the browser

Config key: None. It is a library.

Records: None.

Depends on: Nothing.

Required by: rex-content-processing

In REX Demo: Yes, through rex-content-processing.

Extend this module when: You need new PII patterns or redaction modes.

Do NOT extend this module for: REX-specific module logic. Keep it a general-purpose library.

rex-local-download

Repository: bric-digital/rex-local-download · Package: @bric/rex-local-download

What it does: Stores collected data in the browser and lets the participant (or researcher) view, delete, and download it as a JSON file. The “no backend” output option.

Key capabilities:

Local storage of every record other modules log
JSON download
Messages other modules use to read and delete stored records (used by rex-history-data-table)

Config key: local_download

Records: None of its own.

Depends on: rex-core, rex-data-collection

Required by: rex-history-data-table (at runtime)

In REX Demo: Yes.

Extend this module when: You need changes to local storage or download behavior.

Do NOT extend this module for: Server-based transmission (use rex-passive-data-kit).

rex-passive-data-kit

Repository: bric-digital/rex-passive-data-kit · Package: @bric/rex-passive-data-kit

What it does: Transmits data collected by other modules to a Passive Data Kit (PDK) server.

Key capabilities:

Queues records in IndexedDB and uploads them in batches
Configurable endpoint and authorization token
Optional encryption of fields for the server

Config key: passive_data_kit

Records: pdk-system-status

Depends on: rex-core, rex-content-processing

Required by: Extensions that use a PDK server.

In REX Demo: No. The demo keeps data on the device.

Extend this module when: The PDK transmission format or protocol changes, or you need new upload behaviors.

Do NOT extend this module for: Local storage or download (use rex-local-download).

Browsing

rex-history

Repository: bric-digital/rex-history · Package: @bric/rex-history

What it does: Collects browsing history through the chrome.history API at configurable intervals.

Key capabilities:

Periodic history collection with a configurable lookback window
Allow lists, filter lists, categories, and domain-only recording, all through rex-lists
Progress and error events so researchers can see whether collection is working

Config key: history

Records: rex-history-visit, rex-history-visit-aggregate, and pdk-app-event status events

Depends on: rex-core, rex-lists, rex-types

Required by: rex-history-data-table (for its data)

In REX Demo: Yes.

Extend this module when: You need changes to how history is sampled, filtered, or categorized.

Do NOT extend this module for: Real-time page events (use rex-page-events) or redirect and opener chains (use rex-visit-graph).

rex-visit-graph

Repository: bric-digital/rex-visit-graph · Package: @bric/rex-visit-graph · Latest release: v1.1.3

What it does: Repairs referral chains that browser history alone leaves broken, from the day the extension is installed. It records the redirect hops that chrome.history.search() hides, and links a page opened in a new tab to the page that opened it.

Key capabilities:

Redirect hops (such as search ad redirects) with their visit and referrer IDs, so they can be joined to rex-history records
New-tab opener links, which Chrome’s history does not record
By default records IDs only, not URLs

Config key: visit_graph

Records: rex-visit-graph-hop, rex-visit-graph-opener

Depends on: rex-core, rex-lists, rex-types

Required by: Nothing.

In REX Demo: No.

Extend this module when: You need another kind of link between visits that history does not record.

Do NOT extend this module for: The visits themselves (use rex-history).

rex-page-events

Repository: bric-digital/rex-page-events · Package: @bric/rex-page-events

What it does: Records page lifecycle events (when pages open, close, change URL, and gain or lose focus) along with tab and window events. Records dwell time even for URLs that are redacted.

Key capabilities:

Page, tab, and window events with timestamps, dwell time, and focus time
URL redaction through rex-lists (time on a blocked site is recorded without the URL)

Config key: page_events

Records: rex-page-event, rex-page-url-active

Depends on: rex-core, rex-lists, rex-types

Required by: Nothing.

In REX Demo: No.

Extend this module when: You want to record a new kind of page lifecycle signal (e.g., scroll depth, idle detection).

Do NOT extend this module for: DOM manipulation, blocking, or content recording. Those are separate modules.

rex-browser-settings

Repository: bric-digital/rex-browser-settings · Package: @bric/rex-browser-settings

What it does: Detects browser-level settings, currently the participant’s default search engine.

Key capabilities:

Default search engine detection, both actively and from address-bar searches

Config key: browser_settings

Records: rex-browser-settings-search-engine

Depends on: rex-core

Required by: Nothing.

In REX Demo: No.

Extend this module when: You need to detect a new browser-level setting.

Do NOT extend this module for: Page content, user behavior, or anything requiring DOM access.

Search and AI Mirrors

rex-search-mirror

Repository: bric-digital/rex-search-mirror · Package: @bric/rex-search-mirror

What it does: Records search engine results pages: what results the participant saw for a given query.

Key capabilities:

Results from Google, Bing, and DuckDuckGo
Optional capture of AI-generated elements (such as Google AI Overviews) and news elements
Search suggestions

Config key: search_mirror

Records: search-mirror-result, search-mirror-result-ai, search-mirror-result-news, search-suggestions-result

Depends on: rex-core, rex-types

Required by: Nothing.

In REX Demo: No.

Extend this module when: You need to support a new search engine or capture an additional result field.

Do NOT extend this module for: General page content capture or chatbot mirroring (use rex-live-mirror).

rex-live-mirror

Repository: bric-digital/rex-live-mirror · Package: @bric/rex-live-mirror

What it does: Captures chatbot questions and answers as the participant uses them, and captures news content from homepages and discovery feeds.

Key capabilities:

Question-and-answer pairs and sources from ChatGPT, Gemini, and Perplexity
Perplexity Discover and Finance content
Headlines and market tickers from news homepages (currently CNBC, Bloomberg, and Yahoo Finance)
Title, byline, and excerpt of pages on allow-listed domains

Config key: live_mirror (with llm_capture and page_capture sections), and lists

Records: llm-chatbot-interaction, perplexity-discover-news, perplexity-discover-article, perplexity-finance-sources, news-homepage-blurb, news-market-tickers, page-capture

Depends on: rex-core, rex-lists, rex-types

Required by: Nothing.

In REX Demo: No.

Extend this module when: You need to add support for a new chatbot or news site, or capture an additional field from an existing one.

Do NOT extend this module for: Collecting past conversations (use rex-spider and a platform plugin). Live mirror captures conversations as they happen; spiders collect conversations that already exist.

Spiders

Spiders collect content a participant already has on a site where they are logged in, such as their past chatbot conversations. rex-spider is the shared framework; each platform is a separate plugin. All spider plugins produce rex-conversation records in the same format, documented for ChatGPT in the data reference, and share the same detail_level setting.

rex-spider

Repository: bric-digital/rex-spider · Package: @bric/rex-spider

What it does: The shared framework for collecting content from websites where the participant is logged in. Handles scheduling, the time window, deduplication, the level of detail, and the crawl loop. Required by every platform plugin.

Key capabilities:

Configurable crawl schedule and lookback window
Levels of detail, from conversation times only up to full text (detail_level)
Deduplication of already-collected records
A watchdog for crawls that get stuck
Plugin interface for platform-specific spiders

Config key: spider (with one section per platform, such as spider.chatgpt)

Records: rex-spider-result, and pdk-app-event completion events

Depends on: rex-core

Required by: rex-spider-chatgpt, rex-spider-gemini, rex-spider-google-ai, rex-spider-perplexity

In REX Demo: No.

Extend this module when: You need to improve the shared crawl infrastructure (scheduling, deduplication, levels of detail, error handling) in a way that benefits all spider plugins.

Do NOT extend this module for: Platform-specific logic. Create a new rex-spider-<platform> plugin instead.

rex-spider-chatgpt

Repository: bric-digital/rex-spider-chatgpt · Package: @bric/rex-spider-chatgpt

What it does: Collects a participant’s ChatGPT conversations through the chatgpt.com backend API, including conversations inside Projects.

Key capabilities:

Conversations broken into turns, with search results and citations at the full level
See the ChatGPT data reference for the record format

Config key: spider.chatgpt

Records: rex-conversation

Depends on: rex-core, rex-spider, rex-types

Required by: Nothing.

In REX Demo: No.

Extend this module when: The ChatGPT API changes, new conversation fields are needed, or Projects enumeration needs improvement.

Do NOT extend this module for: Other platforms. Create a new rex-spider-<platform> plugin.

rex-spider-gemini

Repository: bric-digital/rex-spider-gemini · Package: @bric/rex-spider-gemini

What it does: Collects a participant’s chats from the Gemini app at gemini.google.com.

Key capabilities:

Conversation records with platform google-ai-gemini

Config key: spider

Records: rex-conversation

Depends on: rex-core, rex-spider, rex-types

Required by: Nothing.

In REX Demo: No.

Extend this module when: The Gemini app changes or new fields are needed.

Do NOT extend this module for: Google Search AI Mode (use rex-spider-google-ai) or other platforms.

rex-spider-google-ai

Repository: bric-digital/rex-spider-google-ai · Package: @bric/rex-spider-google-ai

What it does: Collects a participant’s Google Search AI Mode threads from google.com.

Key capabilities:

Conversation records with platform google-ai-mode
Does not collect AI Overviews on ordinary search pages; rex-search-mirror records those

Config key: spider

Records: rex-conversation

Depends on: rex-core, rex-spider, rex-types

Required by: Nothing.

In REX Demo: No.

Extend this module when: AI Mode changes or new fields are needed.

Do NOT extend this module for: The Gemini app (use rex-spider-gemini) or other platforms.

rex-spider-perplexity

Repository: bric-digital/rex-spider-perplexity · Package: @bric/rex-spider-perplexity

What it does: Collects a participant’s Perplexity threads through perplexity.ai.

Key capabilities:

Conversation records broken into turns

Config key: spider.perplexity

Records: rex-conversation

Depends on: rex-core, rex-spider, rex-types

Required by: Nothing.

In REX Demo: No.

Extend this module when: The Perplexity API changes or new fields are needed.

Do NOT extend this module for: Other platforms.

Interventions

rex-page-manipulation

Repository: bric-digital/rex-page-manipulation · Package: @bric/rex-page-manipulation

What it does: Changes what participants see in the browser to deliver experimental interventions: blocking or redirecting URLs, obscuring pages, and hiding or restyling page elements, all driven by the study configuration.

Key capabilities:

URL blocks and redirects through Chrome’s declarativeNetRequest API
Page obscuring with a configurable delay
Hiding elements or adding classes to them, targeted by CSS and jQuery selectors

Config key: page_manipulation

Records: page-manipulation

Depends on: rex-core

Required by: Nothing.

In REX Demo: Yes.

Extend this module when:

You need a new kind of page intervention
You need a new DOM action type
The feature is generic enough that any researcher could use it

Do NOT extend this module for:

Study-specific block lists (those go in the study configuration, not module code)
Data collection (use rex-page-events or another data module)

rex-headers

Repository: bric-digital/rex-headers · Package: @bric/rex-headers

What it does: Adds or changes HTTP request headers, and adds or updates fields in POST request bodies, on URLs that match configured patterns.

Key capabilities:

Header and POST body changes configured in the study configuration

Config key: requests

Records: None.

Depends on: rex-core

Required by: Nothing.

In REX Demo: No.

Extend this module when: You need to change a new kind of request.

Do NOT extend this module for: Page content, DOM manipulation, or data collection. Those belong in their own modules.

rex-default-page

Repository: bric-digital/rex-default-page · Package: @bric/rex-default-page

What it does: Replaces the browser’s new tab page with a page the extension configures.

Key capabilities:

Intercepts new tab navigation
Shows a loading page, then the configured page

Config key: default_page

Records: None.

Depends on: rex-core

Required by: Nothing.

In REX Demo: No.

Extend this module when: You need changes to the new tab behavior or loading page.

Do NOT extend this module for: Data collection or page manipulation. Those belong in their own modules.

Participant UI

rex-lists-front-end

Repository: bric-digital/rex-lists-front-end · Package: @bric/rex-lists-front-end

What it does: An extension page for viewing and editing the lists stored by rex-lists, and a scheduled sync of the study’s lists from the configuration.

Key capabilities:

Participants can add, edit, and delete their own entries, and import or export lists as JSON
Entries from the study configuration are read-only, unless allow_delete_backend_entries is on (deleted entries return at the next sync)
Syncs lists from the configuration on a schedule (hourly by default) or on demand
An optional action button, for example to rescan history after lists change

Config key: lists_front_end

Records: pdk-app-event

Depends on: rex-core, rex-lists

Required by: Nothing.

In REX Demo: Yes.

Extend this module when: You need UI changes to list viewing or editing.

Do NOT extend this module for: Storage or matching logic (that is rex-lists).

rex-history-data-table

Repository: bric-digital/rex-history-data-table · Package: @bric/rex-history-data-table

What it does: A searchable, sortable table of the browsing history collected on the participant’s device, with a per-domain view. Participants can delete records before sharing them. Based on Web Historian.

Key capabilities:

Table of rex-history-visit records, with search and sorting
Per-domain summary
Deleting selected records
Configurable introduction text

Config key: history_data_table

Records: None.

Depends on: rex-core. At runtime it also needs rex-local-download (which stores the records) and rex-history (which produces them).

Required by: Nothing.

In REX Demo: Yes.

Extend this module when: You need changes to how participants review their collected history.

Do NOT extend this module for: Collecting or storing history (use rex-history and rex-local-download).

Study Orchestration

rex-autorunner

Repository: bric-digital/rex-autorunner · Package: @bric/rex-autorunner · Latest release: v0.3.0

What it does: Moves each participant through an ordered list of study phases and applies each phase’s configuration. Can assign participants to conditions at random.

Key capabilities:

Phases that advance on a timer, when a data upload completes, or both
Random assignment to a condition, uniform or weighted, once per participant
A forced condition for testing

Config key: autorunner (the extension passes it in)

Records: None of its own; the extension decides what to log when a phase starts.

Depends on: rex-core

Required by: Nothing.

In REX Demo: No.

Extend this module when: You need a new kind of phase trigger or assignment rule.

Do NOT extend this module for: The interventions or data collection a phase turns on. Those stay in their own modules and are switched by the phase’s configuration.

Private Modules

Some REX capability modules are not open source and are not available for external contribution. These cover specialized research areas and are maintained internally by BRIC. They are not listed here by name.