From 6a3bf2c68412649f32af4e768f2e760fb4c80f4f Mon Sep 17 00:00:00 2001
From: "homeboy-ci[bot]" <266378653+homeboy-ci[bot]@users.noreply.github.com>
Date: Sat, 25 Apr 2026 21:47:31 +0000
Subject: [PATCH] docs: fix broken refs and rewrite stale handler docs

- eventbrite/ics/prekindle: rewrite as deprecation notices pointing to WebScraper extractors
- pagination: Calendar_Query.php -> PageBoundary + CalendarAbilities
- calendar-block: .js -> .ts, add day-loader/geo-sync/lazy-render modules, fix Template_Loader path
- universal-web-scraper: add all 35 extractors to directory section and supported sources
---
 docs/calendar-block.md                |  22 ++--
 docs/eventbrite-handler.md            | 103 +++------------
 docs/ics-calendar-handler.md          | 173 ++++----------------------
 docs/pagination-system.md             |  33 +++--
 docs/prekindle-handler.md             | 101 ++++-----------
 docs/universal-web-scraper-handler.md |  60 +++++++--
 6 files changed, 144 insertions(+), 348 deletions(-)

diff --git a/docs/calendar-block.md b/docs/calendar-block.md
index 8827be5..4e51e88 100644
--- a/docs/calendar-block.md
+++ b/docs/calendar-block.md
@@ -11,8 +11,8 @@ The Calendar block renders a Carousel List of events with progressive enhancemen
 
 ## Server Templates & Helpers
 
-- `event-item.php`, `date-group.php`, `navigation.php`, `pagination.php`, `results-counter.php`, `no-events.php`, `filter-bar.php`, `time-gap-separator.php`, and `modal/taxonomy-filter.php` live under `inc/Blocks/Calendar/templates` and are orchestrated by `inc/Core/Template_Loader`.
-- `inc/Core/Taxonomy_Helper` builds hierarchical term data and counts for each template, while `Taxonomy_Badges` renders badge markup that respects `data_machine_events_badge_wrapper_classes`, `data_machine_events_badge_classes`, and `data_machine_events_more_info_button_classes` filters.
+- `event-item.php`, `date-group.php`, `navigation.php`, `pagination.php`, `results-counter.php`, `no-events.php`, `filter-bar.php`, `time-gap-separator.php`, and `modal/taxonomy-filter.php` live under `inc/Blocks/Calendar/templates` and are orchestrated by `inc/Blocks/Calendar/Template_Loader.php`.
+- `inc/Blocks/Calendar/Taxonomy_Helper.php` builds hierarchical term data and counts for each template, while `Taxonomy_Badges` renders badge markup that respects `data_machine_events_badge_wrapper_classes`, `data_machine_events_badge_classes`, and `data_machine_events_more_info_button_classes` filters.
 - The filter modal uses taxonomy helpers to surface dynamic dependencies, counts, and active state indicators before handing control to the filter modal module.
 
 ## REST API Support
@@ -23,14 +23,16 @@ The Calendar block renders a Carousel List of events with progressive enhancemen
 
 ## JavaScript Modules
 
-- `inc/Blocks/Calendar/src/frontend.js` bootstraps each `.data-machine-events-calendar`, wiring the following modules:
-  - `modules/api-client.js` handles REST requests and swaps fragments.
-  - `modules/carousel.js` detects overflow, updates dots, and powers chevrons (with click-and-hold support).
-  - `modules/date-picker.js` integrates Flatpickr for date range filters.
-  - `modules/filter-modal.js` keeps the taxonomy modal accessible and debounced when filters change.
-  - `modules/filter-state.js` centralizes filter state management across URL params, localStorage, and DOM with regex support for both indexed (`tax_filter[taxonomy][0]`) and non-indexed (`tax_filter[taxonomy][]`) array syntax.
-  - `modules/navigation.js` powers past/upcoming toggles, calendar navigation, and pagination link handling.
-  - `modules/state.js` serializes query parameters, manages history state, and debounces search input.
+- `inc/Blocks/Calendar/src/frontend.ts` bootstraps each `.data-machine-events-calendar`, wiring the following modules:
+  - `modules/api-client.ts` handles REST requests and swaps fragments.
+  - `modules/carousel.ts` detects overflow, updates dots, and powers chevrons (with click-and-hold support).
+  - `modules/date-picker.ts` integrates Flatpickr for date range filters.
+  - `modules/day-loader.ts` loads events for a specific date, used by the carousel for on-demand day rendering.
+  - `modules/filter-modal.ts` keeps the taxonomy modal accessible and debounced when filters change.
+  - `modules/filter-state.ts` centralizes filter state management across URL params, localStorage, and DOM with regex support for both indexed (`tax_filter[taxonomy][0]`) and non-indexed (`tax_filter[taxonomy][]`) array syntax.
+  - `modules/geo-sync.ts` handles browser geolocation for nearest-event sorting and the blue dot indicator.
+  - `modules/lazy-render.ts` defers calendar rendering until the block scrolls into view.
+  - `modules/navigation.ts` powers past/upcoming toggles, calendar navigation, and pagination link handling.
 
 ## Filter Modal & Taxonomy Helpers
 
diff --git a/docs/eventbrite-handler.md b/docs/eventbrite-handler.md
index fe8feb4..f87f12d 100644
--- a/docs/eventbrite-handler.md
+++ b/docs/eventbrite-handler.md
@@ -1,105 +1,34 @@
-# Eventbrite Handler
+# Eventbrite Handler (Deprecated)
 
-Import events from public Eventbrite organizer pages via Schema.org JSON-LD extraction.
+This handler has been consolidated into the Universal Web Scraper as the `EventbriteExtractor`.
 
-## Overview
+Previously the handler lived at `inc/Steps/EventImport/Handlers/Eventbrite/Eventbrite.php` with `EventbriteSettings`. That standalone handler and its settings were removed; existing flows should migrate to the scraper-based extractor by reconfiguring the fetch step to use the `UniversalWebScraper` handler, which auto-detects Eventbrite organizer and event pages.
 
-The Eventbrite handler parses public Eventbrite organizer pages to extract events from embedded JSON-LD structured data. No API key or authentication is required - events are extracted directly from the public HTML page.
+See `docs/universal-web-scraper-handler.md` for extraction behavior and `inc/Steps/EventImport/Handlers/WebScraper/Extractors/EventbriteExtractor.php` for the implementation.
 
-## Features
+## Migration
 
-### JSON-LD Extraction
-- **Schema.org Parsing**: Extracts Event schema from `<script type="application/ld+json">` tags
-- **ItemList Support**: Handles both individual Event objects and ItemList containers
-- **Complete Metadata**: Extracts venue, pricing, performer, and image data
+The `EventbriteExtractor` (since v0.15.5) parses Eventbrite pages by:
 
-### Configuration Options
-- **organizer_url**: Full Eventbrite organizer page URL (required)
-- **date_range**: Number of days into the future to import (default: 90)
+1. Detecting `eventbrite.com/o/` or `eventbrite.com/e/` URLs (or `evbuc.com` short links) in the page HTML.
+2. Extracting **all** events from `ItemList` JSON-LD on organizer pages (not just the first event).
+3. Handling individual event pages with a direct `Event` JSON-LD object.
 
-## Usage
-
-### Configuration
-```php
-$config = [
-    'organizer_url' => 'https://www.eventbrite.com/o/lo-fi-brewing-14959647606',
-    'date_range' => 90
-];
-```
-
-### Example Organizer URLs
-- `https://www.eventbrite.com/o/lo-fi-brewing-14959647606`
-- `https://www.eventbrite.com/o/your-organizer-name-12345678`
+No configuration changes are needed — the extractor auto-detects Eventbrite pages from the `source_url`.
 
 ## Data Mapping
 
-### Eventbrite Schema.org to Event Details Block
+The extractor preserves the same Schema.org field mapping:
 
-| Eventbrite Field | Event Details Attribute |
-|------------------|------------------------|
+| Eventbrite JSON-LD Field | Event Details Attribute |
+|--------------------------|------------------------|
 | `name` | title |
-| `startDate` | startDate, startTime |
-| `endDate` | endDate, endTime |
+| `startDate` / `endDate` | date/time fields |
 | `description` | description |
 | `location.name` | venue |
-| `location.address.streetAddress` | venueAddress |
-| `location.address.addressLocality` | venueCity |
-| `location.address.addressRegion` | venueState |
-| `location.address.postalCode` | venueZip |
-| `location.address.addressCountry` | venueCountry |
-| `location.geo` | venueCoordinates |
+| `location.address.*` | venue address components |
+| `location.geo` | venue coordinates |
 | `offers.lowPrice` / `offers.highPrice` | price |
 | `url` | ticketUrl |
 | `performer.name` | artist |
 | `image` | imageUrl |
-
-## Integration
-
-### EventIdentifierGenerator
-Uses `EventIdentifierGenerator::generate()` for consistent event identity:
-```php
-$event_identifier = EventIdentifierGenerator::generate(
-    $standardized_event['title'],
-    $standardized_event['startDate'],
-    $standardized_event['venue']
-);
-```
-
-### Single-Item Processing
-Processes one event per job execution with duplicate prevention via ProcessedItems tracking.
-
-### Venue Metadata
-Complete venue metadata extraction including:
-- Address components (street, city, state, zip, country)
-- Geographic coordinates
-- Phone and website (when available)
-
-## Handler Registration
-
-Uses `HandlerRegistrationTrait` for self-registration:
-```php
-self::registerHandler(
-    'eventbrite',
-    'event_import',
-    self::class,
-    __('Eventbrite Events', 'data-machine-events'),
-    __('Import events from any public Eventbrite organizer page via JSON-LD extraction', 'data-machine-events'),
-    false,
-    null,
-    EventbriteSettings::class,
-    null
-);
-```
-
-## Advantages
-
-- **No API Key Required**: Works with public organizer pages only
-- **Schema.org Standard**: Leverages structured data that Eventbrite maintains for SEO
-- **Complete Data**: Extracts venue, pricing, performer, and image information
-- **Date Range Filtering**: Configurable future date window for imports
-
-## Limitations
-
-- Only works with public organizer pages
-- Depends on Eventbrite's JSON-LD structure (standard Schema.org format)
-- Cannot access private or draft events
diff --git a/docs/ics-calendar-handler.md b/docs/ics-calendar-handler.md
index c0bf485..f8fab18 100644
--- a/docs/ics-calendar-handler.md
+++ b/docs/ics-calendar-handler.md
@@ -1,162 +1,35 @@
-# ICS Calendar Handler
+# ICS Calendar Handler (Deprecated)
 
-Generic ICS/iCal feed integration for importing events from any calendar feed supporting the ICS format.
+This handler has been consolidated into the Universal Web Scraper as the `IcsExtractor`.
 
-## Overview
+Previously the handler lived at `inc/Steps/EventImport/Handlers/IcsCalendar/IcsCalendar.php` with `IcsCalendarSettings.php`. That standalone handler and its settings were removed; existing flows should migrate to the scraper-based extractor by reconfiguring the fetch step to use the `UniversalWebScraper` handler.
 
-The ICS Calendar handler provides comprehensive support for importing events from any ICS (iCalendar) feed, including popular platforms like Tockify, Outlook, Apple Calendar, and Google Calendar ICS exports. Features automatic protocol conversion, venue override options, and keyword filtering.
+See `docs/universal-web-scraper-handler.md` for extraction behavior and `inc/Steps/EventImport/Handlers/WebScraper/Extractors/IcsExtractor.php` for the implementation.
 
-## Features
+## Migration
 
-### Calendar Feed Support
-- **Universal ICS Support**: Works with any ICS/iCal feed URL
-- **Protocol Conversion**: Automatic `webcal://` to `https://` conversion
-- **Multiple Platforms**: Supports Tockify, Outlook, Apple Calendar, Google Calendar exports, and custom ICS feeds
+The `IcsExtractor` handles ICS/iCal feeds within the Universal Web Scraper:
 
-### Venue Management
-- **Venue Override**: Optional venue name override for consistent venue assignment
-- **Address Override**: Venue address override for accurate location data
-- **Automatic Venue Creation**: Creates venues with complete metadata when overrides are provided
-
-### Event Filtering
-- **Keyword Filtering**: Include/exclude keywords to filter relevant events
-- **Case-Insensitive Matching**: Flexible keyword matching in event titles and descriptions
-- **Multiple Keywords**: Support for comma-separated keyword lists
-
-### Technical Features
-- **Single-Item Processing**: Processes one event per job execution with duplicate prevention
-- **Event Identifier Generation**: Uses EventIdentifierGenerator for consistent event identity
-- **Processed Items Tracking**: Prevents duplicate imports using Data Machine's processed items system
+1. Detects ICS feeds by URL extension (`.ics`) or `webcal://` protocol.
+2. Converts `webcal://` to `https://` automatically.
+3. Parses VEVENT components using the `johngrogg/ics-parser` library.
+4. Applies keyword filtering and venue overrides via standard handler settings.
+5. Supports RRULE recurring events, EXDATE exception dates, and RDATE additional dates.
 
 ## Configuration
 
-### Required Settings
-- **ICS URL**: The URL of the ICS feed to import from
-- **Venue Name Override** (optional): Override venue names for consistent assignment
-- **Venue Address Override** (optional): Override venue addresses for accurate geocoding
-
-### Optional Settings
-- **Include Keywords**: Comma-separated keywords to include (events must contain at least one)
-- **Exclude Keywords**: Comma-separated keywords to exclude (events containing these are skipped)
-
-## Usage Examples
-
-### Basic ICS Import
-```php
-$config = [
-    'ics_url' => 'https://example.com/calendar.ics',
-    'venue_name_override' => 'Custom Venue Name',
-    'venue_address_override' => '123 Main St, City, State 12345'
-];
-```
-
-### Filtered Import
-```php
-$config = [
-    'ics_url' => 'https://calendar.google.com/calendar/ical/.../basic.ics',
-    'search' => 'concert,music,jazz',
-    'exclude_keywords' => 'cancelled,postponed'
-];
-```
-
-### WebCal Protocol
-```php
-$config = [
-    'ics_url' => 'webcal://example.com/calendar.ics' // Automatically converted to https://
-];
-```
-
-## Event Processing
-
-### Data Mapping
-- **Title**: Event summary from ICS VEVENT
-- **Start/End Dates**: DTSTART/DTEND from ICS event
-- **Description**: Event description from ICS DESCRIPTION
-- **Location**: Venue information from ICS LOCATION (overridden if configured)
-- **Time Zone**: Respects ICS timezone information
-
-### Duplicate Prevention
-```php
-use DataMachineEvents\Utilities\EventIdentifierGenerator;
-
-// Generate consistent identifier
-$event_identifier = EventIdentifierGenerator::generate($title, $startDate, $venue);
-
-// Check if already processed
-if (apply_filters('datamachine_is_item_processed', false, $flow_step_id, 'ics_calendar', $event_identifier)) {
-    continue;
-}
-
-// Mark as processed
-do_action('datamachine_mark_item_processed', $flow_step_id, 'ics_calendar', $event_identifier, $job_id);
-```
-
-## Integration Architecture
-
-### Handler Structure
-- **IcsCalendar.php**: Main import handler with ICS parsing and event processing
-- **IcsCalendarSettings.php**: Admin interface and configuration forms
-- **johngrogg/ics-parser**: PHP library for reliable ICS parsing
-
-### Data Flow
-1. **Feed Retrieval**: Downloads ICS feed from configured URL
-2. **Protocol Conversion**: Converts webcal:// to https:// if needed
-3. **ICS Parsing**: Parses VEVENT components using ics-parser library
-4. **Event Filtering**: Applies include/exclude keyword filtering
-5. **Venue Processing**: Applies venue overrides or extracts from event location
-6. **Event Mapping**: Converts ICS data to Data Machine event structure
-7. **Duplicate Check**: Uses EventIdentifierGenerator for identity verification
-8. **Event Upsert**: Creates/updates events using EventUpsert handler
-
-## Supported ICS Features
-
-### Event Properties
-- **SUMMARY**: Event title
-- **DESCRIPTION**: Event description
-- **DTSTART/DTEND**: Event start and end times
-- **LOCATION**: Venue information
-- **TZID**: Timezone information
-
-### Recurring Events
-- **RRULE**: Recurrence rules (expanded to individual events)
-- **EXDATE**: Exception dates
-- **RDATE**: Additional recurrence dates
-
-## Error Handling
-
-### Feed Errors
-- **Invalid URL**: Clear error messages for malformed URLs
-- **Network Errors**: Timeout and connection error handling
-- **Parse Errors**: Malformed ICS file detection
-
-### Configuration Errors
-- **Missing URL**: Validation for required ICS URL
-- **Invalid Keywords**: Warning for malformed keyword lists
-
-## Performance Considerations
-
-### Feed Size Limits
-- **Memory Usage**: Efficient parsing of large ICS feeds
-- **Processing Limits**: Single-item processing prevents timeouts
-- **Batch Handling**: Handles feeds with hundreds of events
-
-### Optimization Features
-- **Incremental Processing**: Only processes new/changed events
-- **Caching**: Feed content caching for repeated imports
-- **Error Recovery**: Continues processing after individual event errors
-
-## Troubleshooting
+When using the Universal Web Scraper with an ICS feed:
 
-### Common Issues
-- **WebCal Links**: Ensure webcal:// URLs are accessible (may need manual conversion)
-- **Timezone Issues**: Verify ICS feed timezone settings
-- **Large Feeds**: Consider date range limiting for very large calendars
-- **Encoding Problems**: Check ICS file encoding (UTF-8 recommended)
+- **`source_url`**: The ICS feed URL (`.ics` or `webcal://` links)
+- **`search` / `exclude_keywords`**: Comma-separated filters applied before normalization
+- **Venue override fields**: Available via `VenueFieldsTrait` in handler settings
 
-### Debug Information
-- **Feed Validation**: Test ICS URL accessibility
-- **Event Parsing**: Review parsed event data structure
-- **Filter Matching**: Verify keyword filtering logic
-- **Venue Assignment**: Check venue override application
+## Data Mapping
 
-The ICS Calendar handler provides flexible, reliable event import from any ICS-compatible calendar feed with comprehensive filtering and venue management capabilities.
\ No newline at end of file
+| ICS Property | Event Details Attribute |
+|--------------|------------------------|
+| `SUMMARY` | title |
+| `DESCRIPTION` | description |
+| `DTSTART` / `DTEND` | start/end dates and times |
+| `LOCATION` | venue |
+| `TZID` | timezone |
diff --git a/docs/pagination-system.md b/docs/pagination-system.md
index 3e6de98..c317765 100644
--- a/docs/pagination-system.md
+++ b/docs/pagination-system.md
@@ -10,7 +10,7 @@ The Pagination system provides day-based pagination for the Calendar block. Inst
 
 ### Day-Based Pagination
 - **Complete Day Groups**: Events are never split across pages - each day appears in full
-- **5 Days Per Page**: Configurable via `DAYS_PER_PAGE` constant in `Calendar_Query.php`
+- **5 Days Per Page**: Configurable via `DAYS_PER_PAGE` constant in `inc/Blocks/Calendar/Pagination/PageBoundary.php`
 - **Dynamic Event Counts**: Pages may contain varying numbers of events (5 events on a slow week, 250 on a busy week)
 - **User-Friendly Browsing**: Users see natural calendar day boundaries
 
@@ -29,12 +29,16 @@ The Pagination system provides day-based pagination for the Calendar block. Inst
 
 ### Core Components
 
-**`Calendar_Query.php`** - Single source of truth for pagination logic:
+**`PageBoundary.php`** (`inc/Blocks/Calendar/Pagination/PageBoundary.php`) - Day boundary calculation:
 - `DAYS_PER_PAGE` constant (default: 5)
-- `get_unique_event_dates()` - Returns ordered array of unique event dates
+- `get_unique_event_dates()` - Returns ordered array of unique event dates. **Deprecated** in favor of `CalendarAbilities::get_unique_event_dates()`.
 - `get_date_boundaries_for_page()` - Calculates start/end dates for a given page
 
-**`Pagination.php`** - Renders pagination controls with extensibility filters
+**`CalendarAbilities.php`** (`inc/Abilities/CalendarAbilities.php`) - Primary date query logic:
+- `compute_unique_event_dates()` - DB-level `GROUP BY DATE` aggregation (the fast path used by the calendar block)
+- `get_unique_event_dates()` - Wrapper that delegates to `compute_unique_event_dates()`
+
+**`Pagination.php`** (`inc/Blocks/Calendar/Pagination.php`) - Renders pagination controls with extensibility filters
 
 ### Algorithm
 
@@ -56,8 +60,8 @@ Given: page=2, DAYS_PER_PAGE=5
 
 ### Calendar Query Integration
 ```php
-use DataMachineEvents\Blocks\Calendar\Calendar_Query;
-use const DataMachineEvents\Blocks\Calendar\DAYS_PER_PAGE;
+use DataMachineEvents\Blocks\Calendar\Pagination\PageBoundary;
+use DataMachineEvents\Abilities\CalendarAbilities;
 
 // Build base query parameters
 $base_params = [
@@ -66,11 +70,11 @@ $base_params = [
     'tax_filters' => [],
 ];
 
-// Get unique event dates
-$unique_dates = Calendar_Query::get_unique_event_dates($base_params);
+// Get unique event dates (primary path via CalendarAbilities)
+$unique_dates = CalendarAbilities::get_unique_event_dates($base_params);
 
 // Get date boundaries for current page
-$date_boundaries = Calendar_Query::get_date_boundaries_for_page($unique_dates, $current_page);
+$date_boundaries = PageBoundary::get_date_boundaries_for_page($unique_dates, $current_page);
 
 // Calculate max pages
 $max_pages = $date_boundaries['max_pages'];
@@ -211,18 +215,21 @@ add_filter('data_machine_events_calendar_query_args', function($args, $params) {
 
 ### Common Issues
 - **Pagination Not Appearing**: Verify more than 5 unique event days exist
-- **Wrong Page Count**: Check `DAYS_PER_PAGE` constant value
-- **Events Missing**: Verify `_datamachine_event_datetime` meta field is populated
+- **Wrong Page Count**: Check `DAYS_PER_PAGE` constant value in `PageBoundary`
+- **Events Missing**: Verify the `c8c_<blog>_datamachine_event_dates` table has `post_status = 'publish'` rows with valid `start_datetime`
 
 ### Debug Information
 ```php
 // Debug pagination data
-$unique_dates = Calendar_Query::get_unique_event_dates($base_params);
+use DataMachineEvents\Abilities\CalendarAbilities;
+use DataMachineEvents\Blocks\Calendar\Pagination\PageBoundary;
+
+$unique_dates = CalendarAbilities::get_unique_event_dates($base_params);
 error_log('Total unique days: ' . count($unique_dates));
 error_log('First date: ' . ($unique_dates[0] ?? 'none'));
 error_log('Last date: ' . ($unique_dates[count($unique_dates)-1] ?? 'none'));
 
-$boundaries = Calendar_Query::get_date_boundaries_for_page($unique_dates, $current_page);
+$boundaries = PageBoundary::get_date_boundaries_for_page($unique_dates, $current_page);
 error_log('Page ' . $current_page . ' boundaries: ' . $boundaries['start_date'] . ' to ' . $boundaries['end_date']);
 error_log('Max pages: ' . $boundaries['max_pages']);
 ```
diff --git a/docs/prekindle-handler.md b/docs/prekindle-handler.md
index 8456843..7d1a9f0 100644
--- a/docs/prekindle-handler.md
+++ b/docs/prekindle-handler.md
@@ -1,87 +1,32 @@
-# Prekindle Handler
+# Prekindle Handler (Deprecated)
 
-The Prekindle handler (`inc/Steps/EventImport/Handlers/Prekindle/Prekindle.php`, `PrekindleSettings`) plugs into `EventImportStep` through `HandlerRegistrationTrait` so it can be selected inside a Data Machine pipeline. Each execution follows the single-item pattern: it imports events from Prekindle organizer widget pages using org_id, combining JSON-LD event data with HTML-extracted start times.
+This handler has been consolidated into the Universal Web Scraper as the `PrekindleExtractor`.
 
-## Configuration & Authentication
+Previously the handler lived at `inc/Steps/EventImport/Handlers/Prekindle/Prekindle.php` with `PrekindleSettings`. That standalone handler and its settings were removed; existing flows should migrate to the scraper-based extractor by reconfiguring the fetch step to use the `UniversalWebScraper` handler, which auto-detects Prekindle widgets.
 
-- **Org ID** (`org_id`): Prekindle organizer ID used by the embedded calendar widget (required, example: `531433528849134007`).
-- **Venue Fields**: Optional static venue data configuration using `VenueFieldsTrait` to override extracted venue information.
-- **Keyword Filtering**: `search` for include keywords and `exclude_keywords` for filtering event titles and descriptions.
-- **Authentication**: No authentication required - accesses public Prekindle widget data.
+See `docs/universal-web-scraper-handler.md` for extraction behavior and `inc/Steps/EventImport/Handlers/WebScraper/Extractors/PrekindleExtractor.php` for the implementation.
 
-## Data Mapping
-
-- **Event Details**: Title, start/end dates, descriptions, performers, organizers, and pricing from JSON-LD structured data.
-- **Time Information**: Start times extracted from HTML listing and matched to events by title.
-- **Venue Metadata**: Address components, coordinates, and venue details from JSON-LD location data, with optional override via handler settings.
-- **Pricing & Tickets**: Price ranges, currencies, availability, and purchase URLs from offers data.
-- **Images & Media**: Event images from JSON-LD and stored in `EventEngineData` for download by `WordPressPublishHelper`.
-- **Taxonomy Info**: Performer names and organizer information for promoter taxonomy integration.
-
-## Unique Capabilities
-
-Prekindle combines JSON-LD structured data with HTML-parsed time information for comprehensive event extraction. The handler constructs widget URLs from org_id, extracts events from Schema.org JSON-LD, matches start times from the HTML listing using title-based correlation, and provides flexible venue override capabilities. It handles multiple performer names, complex pricing structures, and organizer information from the Prekindle widget format.
-
-## Data Extraction Process
-
-The handler processes Prekindle widget pages in two phases:
-
-```php
-// Phase 1: JSON-LD Event Extraction
-// - Fetches widget HTML from constructed URL
-// - Parses application/ld+json script tags
-// - Extracts event objects from @graph or direct arrays
+## Migration
 
-// Phase 2: Time Matching
-// - Parses HTML event blocks with name="pk-eachevent"
-// - Extracts titles from pk-headline divs
-// - Matches times from pk-times divs by normalized title
-// - Correlates JSON-LD events with HTML times
-```
+The `PrekindleExtractor` (since v0.8.12) handles Prekindle pages within the Universal Web Scraper:
 
-This dual-extraction approach ensures complete event data capture from Prekindle's widget format.
+1. Auto-detects Prekindle widgets (`pk-cal-widget`) or organizer links in page HTML.
+2. Automatically extracts the `org_id` from widget attributes or script source URLs.
+3. Uses hybrid extraction: fetches the Prekindle mobile grid widget for both JSON-LD event data and HTML time blocks.
+4. Scrapes `pk-times` HTML blocks for precise door/show times missing from standard JSON-LD.
 
-## Event Flow
+No manual `org_id` configuration is needed — the extractor auto-detects it from the page.
 
-1. `EventImportStep` instantiates `Prekindle` and reads `PrekindleSettings` values.
-2. Handler constructs widget URL from org_id and fetches HTML content.
-3. Extracts JSON-LD event data and HTML time listings.
-4. Maps Prekindle events to standardized format with title-based time matching.
-5. Applies keyword filtering and venue configuration overrides.
-6. Normalizes identity via `EventIdentifierGenerator`, checks processing status.
-7. Stores venue metadata and image URLs in `EventEngineData`.
-8. Returns first eligible `DataPacket` for incremental processing.
-9. `EventUpsert` receives the data and creates/updates the WordPress event.
-
-Every EventUpsert run uses the same identifier hash to prevent duplicates, and venue metadata stays consistent through `VenueService`/`Venue_Taxonomy` helpers.
-
-## JSON-LD Mapping Details
-
-### Event Properties
-- **Title**: `name` field from JSON-LD event object
-- **Dates**: `startDate`/`endDate` in ISO format
-- **Description**: `description` field with HTML content
-- **Location**: `location` object with address components
-- **Performers**: `performer` array with individual artist names
-- **Organizer**: `organizer` object with name and URL
-- **Offers**: `offers` object with pricing and availability
-- **Images**: `image` field for event artwork
-
-### Address Resolution
-- **Street Address**: `location.address.streetAddress`
-- **City**: `location.address.addressLocality`
-- **State**: `location.address.addressRegion`
-- **ZIP**: `location.address.postalCode`
-- **Country**: `location.address.addressCountry`
-
-### Time Extraction
-- Parses "Start HH:MM am/pm" patterns from HTML
-- Matches times to events by normalized title comparison
-- Handles various time format variations
-- Falls back to empty time if no match found
+## Data Mapping
 
-### Venue Override
-- Optional static venue configuration overrides extracted data
-- Useful when Prekindle location data is incomplete
-- Maintains flexibility for venue standardization</content>
-<parameter name="filePath">docs/prekindle-handler.md
\ No newline at end of file
+The extractor uses the same dual-phase extraction as the legacy handler:
+
+| Source | Field | Event Details Attribute |
+|--------|-------|------------------------|
+| JSON-LD | `name` | title |
+| JSON-LD | `startDate` / `endDate` | date fields |
+| JSON-LD | `description` | description |
+| JSON-LD | `location.*` | venue + address |
+| JSON-LD | `performer[].name` | artists |
+| JSON-LD | `offers.*` | pricing |
+| HTML | `pk-times` | precise door/show times |
diff --git a/docs/universal-web-scraper-handler.md b/docs/universal-web-scraper-handler.md
index 7dfb070..650de25 100644
--- a/docs/universal-web-scraper-handler.md
+++ b/docs/universal-web-scraper-handler.md
@@ -10,7 +10,7 @@ The Universal Web Scraper handler prioritizes structured data extraction for max
 
 ### Structured Data Extraction (Priority Order)
 
-The handler registers 22 extraction layers (21 specialized extractors + HTML fallback) in `UniversalWebScraper::getExtractors()`.
+The handler registers extraction layers (specialized extractors + HTML fallback) in `UniversalWebScraper::getExtractors()`.
 
 1. **AEG/AXS JSON feed** (`AegAxsExtractor`): Extracts events from AEG/AXS venue JSON feeds
 2. **Red Rocks** (`RedRocksExtractor`): Parses Red Rocks Amphitheatre event pages (@since v0.8.0)
@@ -222,20 +222,42 @@ Websites without structured data (AI fallback):
 ### Extractors (Extractors/ directory)
 
 - **ExtractorInterface.php**: Contract for all extractor implementations
+- **BaseExtractor.php**: Shared extraction utilities (date parsing, address normalization, coordinate extraction)
 - **AegAxsExtractor.php**: Parses AEG/AXS JSON feeds
-- **RedRocksExtractor.php**: Parses Red Rocks Amphitheatre event pages
-- **FreshtixExtractor.php**: Parses Freshtix platform pages
+- **BandzoogleExtractor.php**: Extracts events from Bandzoogle-powered venue calendar pages
+- **CraftpeakExtractor.php**: Parses Craftpeak brewery/venue calendar pages
+- **DoStuffExtractor.php**: Parses DoStuff Media API JSON feeds (replaces legacy DoStuffMediaApi handler)
+- **DuskFmExtractor.php**: Extracts events from Dusk.fm venue pages
+- **ElfsightEventsExtractor.php**: Parses Elfsight Event Calendar widget data
+- **EmbeddedCalendarExtractor.php**: Detects and scrapes embedded Google Calendar, SeeTickets, and Turntable widgets
+- **EventbriteExtractor.php**: Parses Eventbrite organizer/event page JSON-LD (ItemList + single Event)
 - **FirebaseExtractor.php**: Fetches events from Firebase Realtime Database REST API
-- **SquarespaceExtractor.php**: Parses Squarespace context JSON
-- **SpotHopperExtractor.php**: Detects SpotHopper and parses their API
-- **WixEventsExtractor.php**: Parses Wix warmup-data JSON
-- **RhpEventsExtractor.php**: Parses RHP Events plugin HTML
-- **OpenDateExtractor.php**: Handles OpenDate.io listing/detail extraction
+- **FreshtixExtractor.php**: Parses Freshtix platform pages
+- **GenericHtmlEventsExtractor.php**: Generic HTML event list extraction via structured selectors
+- **GigwellExtractor.php**: Detects gigwell-gigstream embeds and extracts from Gigwell API
+- **GoDaddyExtractor.php**: Extracts events from GoDaddy Website Builder calendars with REST API
+- **IcsExtractor.php**: Parses ICS/iCal feeds (replaces legacy IcsCalendar handler)
 - **JsonLdExtractor.php**: Parses Schema.org JSON-LD script tags
 - **MicrodataExtractor.php**: Parses Schema.org microdata attributes
-- **ElfsightEventsExtractor.php**: Parses Elfsight Event Calendar widget data
-- **CraftpeakExtractor.php**: Parses Craftpeak brewery/venue calendar pages
 - **MusicItemExtractor.php**: Extracts Schema.org MusicEvent items
+- **NocodeflowExtractor.php**: Extracts events from Nocodeflow-powered event pages
+- **OpenDateExtractor.php**: Handles OpenDate.io listing/detail extraction
+- **PrekindleExtractor.php**: Auto-detects Prekindle widgets and extracts via mobile API (replaces legacy Prekindle handler)
+- **RedRocksExtractor.php**: Parses Red Rocks Amphitheatre event pages
+- **RhpEventsExtractor.php**: Parses RHP Events plugin HTML
+- **ShowareExtractor.php**: Extracts events from Showare ticketing platform pages
+- **ShowtimeExtractor.php**: Extracts events from Showtime ticketing/venue pages
+- **SofarSoundsExtractor.php**: Extracts events from Sofar Sounds pages
+- **SpotHopperExtractor.php**: Detects SpotHopper and parses their API
+- **SquareOnlineExtractor.php**: Extracts events from Square Online store pages
+- **SquarespaceExtractor.php**: Parses Squarespace context JSON
+- **TimelyExtractor.php**: Specialized extractor for Time.ly All-in-One Event Calendar
+- **VenuePilotExtractor.php**: Extracts events from VenuePilot embeds (including Wix HtmlComponent resolution)
+- **VisionExtractor.php**: AI-powered event extraction from arbitrary page screenshots
+- **WebflowExtractor.php**: Extracts events from Webflow CMS pages
+- **WeeblyExtractor.php**: Extracts events from Weebly event listings (including multi-artist showcase patterns)
+- **WixEventsExtractor.php**: Parses Wix warmup-data JSON
+- **WordPressExtractor.php**: Extracts events from external WordPress sites via REST API or structured HTML
 
 ### DataPacket Format
 
@@ -302,3 +324,21 @@ When using HTML fallback:
 - AEG/AXS venue feeds embedded/linked from venue pages
 - Google Calendar (via EmbeddedCalendarExtractor)
 - External WordPress Events (via WordPressExtractor)
+- Eventbrite organizer and event pages (via EventbriteExtractor)
+- ICS/iCal feeds (via IcsExtractor)
+- DoStuff Media API feeds (via DoStuffExtractor)
+- Dusk.fm venue pages (via DuskFmExtractor)
+- Bandzoogle venue calendars (via BandzoogleExtractor)
+- GoDaddy Website Builder calendars (via GoDaddyExtractor)
+- Gigwell embeds (via GigwellExtractor)
+- Time.ly All-in-One Event Calendar (via TimelyExtractor)
+- Elfsight Event Calendar widgets (via ElfsightEventsExtractor)
+- Craftpeak brewery/venue pages (via CraftpeakExtractor)
+- Nocodeflow pages (via NocodeflowExtractor)
+- Showare ticketing (via ShowareExtractor)
+- Showtime ticketing (via ShowtimeExtractor)
+- Sofar Sounds (via SofarSoundsExtractor)
+- Square Online stores (via SquareOnlineExtractor)
+- VenuePilot embeds (via VenuePilotExtractor)
+- Webflow CMS pages (via WebflowExtractor)
+- Weebly event listings (via WeeblyExtractor)