Site Adapter Registry

Relevant source files

The following files were used as context for generating this wiki page:

• packages/shared/src/types.ts
• extension/src/background/index.ts
• extension/src/content/index.ts
• extension/src/background/api-client.ts
• README.md
• CHANGELOG.md

The Site Adapter Registry is a configuration management system that defines how the Oddity 1 extension extracts text and detects content stability across different websites. It allows the extension to dynamically adapt its behavior for specific platforms, such as real-time chatbots (ChatGPT, Claude) or article-heavy sites (Medium, Substack), using remotely updateable configurations.

Sources: README.md, CHANGELOG.md

Registry Architecture

The registry operates as a distributed system between the backend database, the extension service worker (background script), and the content scripts injected into web pages.

Data Model

The registry uses the SiteAdapter data structure to store extraction rules. Each adapter specifies how to identify reading regions and when content has finished loading or streaming.

Field	Type	Description
hostname_pattern	string	A pattern (e.g., *.medium.com) to match the current site.
content_selectors	string[]	CSS selectors used to find the main text containers.
extraction_mode	enum	Defines the method: adapter, readability, or custom_heuristic.
response_selector	string | null	Used in chat modes to identify AI-generated messages.
stability_signal	StabilitySignal	Criteria to determine if a dynamic element has finished updating.

Sources: packages/shared/src/types.ts:161-182

Synchronization Flow

The extension manages adapter updates through a background lifecycle that ensures content scripts always use the latest site configurations.

The Service Worker uses a periodic alarm to refresh the registry from the backend. The content script requests this registry during its initialization phase to determine the appropriate detection strategy for the current page.

Sources: extension/src/background/index.ts:101-105, extension/src/background/api-client.ts:316-320, extension/src/content/index.ts:771-775

Content Detection Pipeline

When a user visits a page, the extension executes a multi-tiered fallback chain to find "Reading Regions"—elements containing the primary text to be annotated.

Detection Fallback Chain

The system prioritizes specific adapters over generic heuristics to ensure the highest quality text extraction.

1. Adapter Match: The extension checks the registry for a hostname_pattern matching the current URL. If found, it uses the specific content_selectors defined.
2. Readability: If no adapter matches, the system uses the Mozilla Readability library to detect article-like content.
3. Heuristic: As a final fallback, the system applies text-density and semantic tag scoring to identify substantive prose.

Sources: README.md, extension/src/content/index.ts:776-781

Flow of Detection Logic

The following diagram illustrates how the SiteAdapter determines the extraction path:

Streaming and Stability Handling

For dynamic sites like ChatGPT and Claude, the registry provides configurations to handle content that arrives in chunks.

Stability Signals

The registry defines StabilitySignal objects that tell the extension when an element has reached a "stable" state suitable for annotation. This prevents the AI from attempting to annotate incomplete sentences during a live stream.

• selector_appears: Wait for a specific element (like a "Copy" button) to appear.
• selector_disappears: Wait for a "Stop Generating" or loading indicator to vanish.
• attribute_change: Monitor changes in specific element attributes.

Sources: packages/shared/src/types.ts:154-159, CHANGELOG.md

Chat Observer Integration

When an adapter defines a response_selector, the extension initializes a ChatObserver. This observer uses the registry's stability signals to trigger the annotation pipeline only after a message is complete.

Sources: extension/src/content/index.ts:784-825

Summary of Seeded Adapters

The registry comes pre-configured with several "seeded" adapters in the database to support major platforms immediately.

Site	Pattern	Extraction Mode	Special Features
ChatGPT	chatgpt.com	adapter	Streaming detection via button appearance.
Claude	claude.ai	adapter	Real-time annotation via completion signals.
Medium	medium.com	readability	Article extraction and margin notes.
Substack	*.substack.com	readability	Newsletter content extraction.

Sources: README.md, CHANGELOG.md