cjm-transcript-source-select 0.0.7__tar.gz → 0.0.8__tar.gz

{cjm_transcript_source_select-0.0.7/cjm_transcript_source_select.egg-info → cjm_transcript_source_select-0.0.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: cjm-transcript-source-select
-Version: 0.0.7
+Version: 0.0.8
 Summary: FastHTML source selection component for transcript decomposition workflows, with federated database browsing, drag-drop ordering, and keyboard navigation.
 Home-page: https://github.com/cj-mills/cjm-transcript-source-select
 Author: Christian J. Mills
@@ -28,6 +28,7 @@ Requires-Dist: cjm_workflow_state
 Requires-Dist: cjm_source_provider
 Requires-Dist: cjm_fasthtml_interactions
 Requires-Dist: cjm_fasthtml_viewport_fit
+Requires-Dist: cjm_fasthtml_virtual_collection
 Provides-Extra: dev
 Dynamic: author
 Dynamic: author-email
@@ -63,13 +64,14 @@ pip install cjm_transcript_source_select
     │   ├── selection_queue.ipynb  # Selection queue component with drag-drop reordering
     │   ├── source_browser.ipynb   # Source browser components for displaying and filtering transcription sources
     │   └── step_renderer.ipynb    # Phase 1 step renderer: Source Selection & Ordering with two-column layout and collapsible preview
-    ├── routes/ (6)
-    │   ├── core.ipynb         # Selection step state management helpers
-    │   ├── filtering.ipynb    # Filtering, grouping, and keyboard navigation route handlers
-    │   ├── init.ipynb         # Router assembly for Phase 1 selection routes
-    │   ├── local_files.ipynb  # Local files browser route handlers
-    │   ├── queue.ipynb        # Selection queue route handlers for Phase 1
-    │   └── tabs.ipynb         # Tab switching route handlers
+    ├── routes/ (7)
+    │   ├── core.ipynb            # Selection step state management helpers
+    │   ├── filtering.ipynb       # Filtering, grouping, and keyboard navigation route handlers
+    │   ├── init.ipynb            # Router assembly for Phase 1 selection routes
+    │   ├── local_files.ipynb     # Local files browser route handlers
+    │   ├── queue.ipynb           # Selection queue route handlers for Phase 1
+    │   ├── source_browser.ipynb  # Source browser virtual collection router for Phase 1 selection
+    │   └── tabs.ipynb            # Tab switching route handlers
     ├── services/ (2)
     │   ├── source.ipynb        # Source service for federated transcription queries via DuckDB
     │   └── source_utils.ipynb  # Source record operations for metadata extraction, grouping, and validation
@@ -77,7 +79,7 @@ pip install cjm_transcript_source_select
     ├── models.ipynb    # Data models and URL bundles for Phase 1: Source Selection & Ordering
     └── utils.ipynb     # Display formatting and word counting utilities for the selection step
 
-Total: 17 notebooks across 3 directories
+Total: 18 notebooks across 3 directories
 
 ## Module Dependencies
 
@@ -96,65 +98,69 @@ graph LR
     routes_init[routes.init<br/>init]
     routes_local_files[routes.local_files<br/>local_files]
     routes_queue[routes.queue<br/>queue]
+    routes_source_browser[routes.source_browser<br/>source_browser]
     routes_tabs[routes.tabs<br/>tabs]
     services_source[services.source<br/>source]
     services_source_utils[services.source_utils<br/>source_utils]
     utils[utils<br/>utils]
 
     components_helpers --> models
-    components_local_files --> components_helpers
     components_local_files --> html_ids
+    components_local_files --> components_helpers
     components_preview_panel --> html_ids
     components_selection_queue --> html_ids
-    components_source_browser --> services_source_utils
     components_source_browser --> utils
+    components_source_browser --> services_source_utils
     components_source_browser --> html_ids
-    components_step_renderer --> models
-    components_step_renderer --> components_selection_queue
     components_step_renderer --> components_local_files
-    components_step_renderer --> components_preview_panel
     components_step_renderer --> components_helpers
     components_step_renderer --> html_ids
     components_step_renderer --> components_source_browser
+    components_step_renderer --> models
+    components_step_renderer --> components_selection_queue
+    components_step_renderer --> components_preview_panel
     components_step_renderer --> utils
-    routes_core --> components_selection_queue
-    routes_core --> components_source_browser
+    routes_core --> html_ids
+    routes_core --> models
     routes_core --> components_step_renderer
+    routes_core --> components_selection_queue
     routes_core --> services_source
-    routes_core --> models
-    routes_core --> html_ids
-    routes_filtering --> models
+    routes_filtering --> routes_core
     routes_filtering --> services_source_utils
+    routes_filtering --> models
     routes_filtering --> services_source
-    routes_filtering --> routes_core
-    routes_filtering --> components_source_browser
+    routes_init --> routes_queue
+    routes_init --> routes_local_files
     routes_init --> routes_core
+    routes_init --> routes_tabs
+    routes_init --> routes_filtering
     routes_init --> models
+    routes_init --> routes_source_browser
     routes_init --> services_source
-    routes_init --> routes_queue
-    routes_init --> routes_filtering
-    routes_init --> routes_tabs
-    routes_init --> routes_local_files
     routes_local_files --> components_local_files
-    routes_local_files --> services_source
     routes_local_files --> routes_core
     routes_local_files --> models
-    routes_queue --> routes_core
+    routes_local_files --> services_source
     routes_queue --> services_source_utils
-    routes_queue --> components_preview_panel
+    routes_queue --> routes_core
     routes_queue --> models
+    routes_queue --> components_preview_panel
     routes_queue --> services_source
-    routes_tabs --> components_local_files
-    routes_tabs --> routes_local_files
-    routes_tabs --> components_step_renderer
+    routes_source_browser --> components_source_browser
+    routes_source_browser --> html_ids
+    routes_source_browser --> models
+    routes_source_browser --> services_source_utils
+    routes_source_browser --> components_preview_panel
+    routes_source_browser --> routes_core
+    routes_source_browser --> services_source
+    routes_tabs --> services_source_utils
     routes_tabs --> routes_core
+    routes_tabs --> components_step_renderer
     routes_tabs --> models
-    routes_tabs --> components_source_browser
     routes_tabs --> services_source
-    routes_tabs --> services_source_utils
 ```
 
-*51 cross-module dependencies detected*
+*54 cross-module dependencies detected*
 
 ## CLI Reference
 
@@ -200,12 +206,10 @@ def _find_duplicate_media_source(
 
 ``` python
 def _render_duplicate_flash(
-    candidate_record_id: str,  # Record ID of the row the user clicked
-    candidate_provider_id: str,  # Provider ID of the row the user clicked
-    existing_record_id: str,  # Record ID of the conflicting selected row
-    existing_provider_id: str,  # Provider ID of the conflicting selected row
-) -> Div:  # OOB Div with flash script (replaces previous via innerHTML swap)
-    "Render a fixed-ID container with flash script for two source rows."
+    candidate_row_id: str,  # DOM element ID of the candidate row
+    existing_row_id: Optional[str] = None,  # DOM element ID of the conflicting row (None if off-screen)
+) -> Div:  # OOB Div with flash script
+    "Render a flash animation on one or two rows to indicate duplicate rejection."
 ```
 
 ``` python
@@ -226,8 +230,7 @@ def _build_queue_response(
     selected_sources: List[Dict[str, str]],  # Current selected sources after mutation
     urls: SelectionUrls,  # URL bundle for rendering
     include_stats: bool = True,  # Include OOB stats swap
-    include_source_list: bool = True,  # Include conditional OOB source list swap
-    grouping_mode: str = None,  # Override grouping mode for source list rendering
+    include_checkbox_oobs: bool = True,  # Include OOB checkbox cells for visible rows
 ) -> Union[Any, Tuple]:  # Single component or tuple of components with OOB swaps
     "Build the standard response for queue-mutating handlers."
 ```
@@ -241,6 +244,12 @@ def _update_step_state(
 
 ``` python
 DEBUG_SELECTION_STATE = False
+_rebuild_and_render_ref: list
+_sync_items_ref: list
+_get_checkbox_oobs_ref: list
+_get_checkbox_oob_for_ref: list
+_get_vc_row_id_for_ref: list
+_activate_toggle_ref: list
 ```
 
 ### filtering (`filtering.ipynb`)
@@ -266,7 +275,7 @@ def _handle_source_filter(
     sess,  # FastHTML session object
     search: str,  # Search term from input
     urls: SelectionUrls,  # URL bundle for rendering
-):  # Filtered source list component
+):  # VC content wrapper (direct swap, not OOB)
     "Filter transcription sources by search term."
 ```
 
@@ -279,8 +288,8 @@ def _handle_grouping_change(
     sess,  # FastHTML session object
     grouping_mode: str,  # New grouping mode: "media_path" or "batch_id"
     urls: SelectionUrls,  # URL bundle for rendering
-):  # Updated source list component
-    "Change the grouping mode and re-render the source list."
+):  # VC content wrapper (direct swap, not OOB)
+    "Change the grouping mode and re-render the VC content."
 ```
 
 ``` python
@@ -427,7 +436,7 @@ def init_selection_routers(
     source_service: SourceService,  # The source service for queries
     workflow_id: str,  # The workflow identifier
     prefix: str,  # Base prefix for selection routes (e.g., "/workflow/selection")
-) -> Tuple[List[APIRouter], SelectionUrls, Dict[str, Callable]]:  # (routers, urls, merged_routes)
+) -> Tuple[List[APIRouter], SelectionUrls, Dict[str, Callable], Callable, "SourceBrowserRouterState"]
     "Initialize and return all selection routers with URL bundle."
 ```
 
@@ -474,22 +483,24 @@ def _create_db_browser_config() -> FileBrowserConfig:  # Configured FileBrowserC
 def _render_external_sources_list(
     external_paths: List[str],  # List of added external database paths
     remove_url: str,  # URL for removing external source
-) -> Any:  # External sources list component
+    oob: bool = False,  # Whether to render as OOB swap
+) -> Any:  # External sources section component (always rendered for OOB targeting)
     "Render the list of added external database sources with scrollable paths."
 ```
 
+``` python
+def _render_error_alert(
+    error_message: Optional[str] = None,  # Error message to display (None = clear)
+    oob: bool = False,  # Whether to render as OOB swap
+) -> Any:  # Error alert container (always present for OOB targeting)
+    "Render the error alert container for the local files browser."
+```
+
 ``` python
 def _render_local_files_browser(
-    browser_state: Optional[BrowserState] = None,  # Current browser state
+    render_fn: Optional[Callable] = None,  # FileBrowserRouters.render callable
     external_paths: Optional[List[str]] = None,  # List of added external database paths
-    provider: Optional[LocalFileSystemProvider] = None,  # File system provider
-    config: Optional[FileBrowserConfig] = None,  # Browser configuration
-    navigate_url: str = "",  # URL for browsing directories
-    select_url: str = "",  # URL for adding external source (maps path to db_path)
     remove_url: str = "",  # URL for removing external source
-    refresh_url: str = "",  # URL for refreshing browser
-    path_input_url: str = "",  # URL for direct path input
-    home_path: Optional[str] = None,  # Home directory path
     error_message: Optional[str] = None,  # Error message to display
 ) -> Any:  # Local files browser component
     "Render the local files browser for adding external .db files."
@@ -517,49 +528,17 @@ def _get_local_files_provider() -> LocalFileSystemProvider:
     "Get or create the local files provider singleton."
 ```
 
-``` python
-def _handle_browse_directory(
-    state_store: WorkflowStateStore,  # The workflow state store
-    workflow_id: str,  # The workflow identifier
-    source_service: SourceService,  # The source service for external db ops
-    request,  # FastHTML request object
-    sess,  # FastHTML session object
-    path: str,  # Directory path to browse
-    urls: SelectionUrls,  # URL bundle for rendering
-):  # Local files browser component
-    "Browse a directory and return the local files browser component."
-```
-
-``` python
-def _get_local_files_config() -> FileBrowserConfig:
-    """Get or create the local files config singleton."""
-    global _local_files_config
-    if _local_files_config is None
-    "Get or create the local files config singleton."
-```
-
-``` python
-def _handle_add_external_source(
-    state_store: WorkflowStateStore,  # The workflow state store
-    workflow_id: str,  # The workflow identifier
-    source_service: SourceService,  # The source service for external db ops
-    request,  # FastHTML request object
-    sess,  # FastHTML session object
-    path: str,  # Path to the .db file (from file-browser select_url)
-    urls: SelectionUrls,  # URL bundle for rendering
-):  # Local files browser component
-    "Toggle an external database source (add if not present, remove if present)."
-```
-
 ``` python
 def _handle_remove_external_source(
     state_store: WorkflowStateStore,  # The workflow state store
     workflow_id: str,  # The workflow identifier
     source_service: SourceService,  # The source service for external db ops
-    request,  # FastHTML request object
     sess,  # FastHTML session object
     db_path: str,  # Path to the .db file to remove
-    urls: SelectionUrls,  # URL bundle for rendering
+    external_db_paths_ref: List[str],  # Shared external paths list (mutated in place)
+    fb_state_getter: Callable[[], BrowserState],  # File browser state getter
+    fb_state_setter: Callable[[BrowserState], None],  # File browser state setter
+    render_panel_fn: Callable,  # Function to render the full local files panel
 ):  # Local files browser component
     "Remove an external database source from the Added Sources list."
 ```
@@ -571,15 +550,14 @@ def init_local_files_router(
     source_service: SourceService,  # The source service for external db ops
     prefix: str,  # Route prefix (e.g., "/workflow/selection/local_files")
     urls: SelectionUrls,  # URL bundle for rendering
-) -> Tuple[APIRouter, Dict[str, Callable]]:  # (router, route_dict)
-    "Initialize local files browser routes."
+) -> Tuple[List, Dict[str, Callable], Callable]:  # (routers, route_dict, render_panel_fn)
+    "Initialize local files browser routes with new file browser API."
 ```
 
 #### Variables
 
 ``` python
 _local_files_provider: Optional[LocalFileSystemProvider] = None
-_local_files_config: Optional[FileBrowserConfig] = None
 ```
 
 ### models (`models.ipynb`)
@@ -609,6 +587,7 @@ class SelectionUrls:
     
     add: str = ''  # Add source to queue
     remove: str = ''  # Remove source from queue
+    toggle: str = ''  # Toggle source selection (add/remove based on current state)
     reorder: str = ''  # Reorder queue items
     clear: str = ''  # Clear all from queue
     select_all: str = ''  # Select all in a group
@@ -658,6 +637,20 @@ from cjm_transcript_source_select.routes.queue import (
 
 #### Functions
 
+``` python
+def _handle_selection_toggle(
+    state_store: WorkflowStateStore,  # The workflow state store
+    workflow_id: str,  # The workflow identifier
+    source_service: SourceService,  # The source service for queries
+    request,  # FastHTML request object
+    sess,  # FastHTML session object
+    record_id: str,  # Job ID to toggle
+    provider_id: str,  # Plugin name for the source
+    urls: SelectionUrls,  # URL bundle for rendering
+):  # Queue component with OOB stats (no checkbox OOBs -- checkbox already correct)
+    "Toggle a source's selection state (add if absent, remove if present)."
+```
+
 ``` python
 def _handle_selection_add(
     state_store: WorkflowStateStore,  # The workflow state store
@@ -668,7 +661,7 @@ def _handle_selection_add(
     record_id: str,  # Job ID to add
     provider_id: str,  # Plugin name for the source
     urls: SelectionUrls,  # URL bundle for rendering
-):  # Queue component with OOB stats, optionally with OOB source list
+):  # Queue component with OOB stats and visible checkbox OOBs
     "Add a source to the selection queue."
 ```
 
@@ -682,7 +675,7 @@ def _handle_selection_remove(
     record_id: str,  # Job ID to remove
     provider_id: str,  # Plugin name for the source
     urls: SelectionUrls,  # URL bundle for rendering
-):  # Queue component with OOB stats, optionally with OOB source list
+):  # Queue component with OOB stats and visible checkbox OOBs
     "Remove a source from the selection queue."
 ```
 
@@ -1023,7 +1016,15 @@ VALID_DB_EXTENSIONS = [3 items]
 #### Import
 
 ``` python
-from cjm_transcript_source_select.components.source_browser import *
+from cjm_transcript_source_select.components.source_browser import (
+    SOURCE_BROWSER_COLUMNS,
+    SB_SYSTEM_ID,
+    SourceBrowserItem,
+    build_source_items,
+    is_source_item_skippable,
+    create_source_cell_renderer,
+    render_source_empty
+)
 ```
 
 #### Functions
@@ -1037,65 +1038,139 @@ def _render_grouping_selector(
 ```
 
 ``` python
-def _render_source_row(
-    record: Dict[str, Any],  # Transcription record
-    is_selected: bool,  # Whether this source is selected
-    add_url: str,  # URL for adding to queue
-    remove_url: str,  # URL for removing from queue
-    preview_url: str,  # URL for previewing content
-    is_first: bool = False,  # Whether this is the first row (gets initial focus)
-    row_index: int = 0,  # Index among selectable rows (for keyboard focus sync)
-) -> Any:  # Table row element
-    "Render a single source row in the browser table."
+def build_source_items(
+    transcriptions: List[Dict[str, Any]],  # Available transcription records
+    selected_sources: List[Dict[str, str]],  # Currently selected sources
+    grouping_mode: str = "media_path",  # Grouping mode: "media_path" or "batch_id"
+) -> List[SourceBrowserItem]:  # Flat list with interleaved headers and records
+    "Build the items list for the source browser virtual collection."
 ```
 
 ``` python
-def _render_group_header(
-    group_key: str,  # The group key (media_path or batch_id value)
-    record_count: int,  # Number of records in this group
-    select_all_url: str,  # URL for selecting all in group
-    grouping_mode: str = "media_path",  # Current grouping mode
-) -> Any:  # Table row for group header
-    "Render a group header row."
+def is_source_item_skippable(
+    item: SourceBrowserItem,  # Item to check
+) -> bool:  # True if item is a group header (cursor should skip)
+    "Predicate for virtual collection is_skippable parameter."
 ```
 
 ``` python
-def _render_audio_group_header(
-    media_path: str,  # Path to audio file
-    record_count: int,  # Number of records in this group
-    select_all_url: str,  # URL for selecting all in group
-) -> Any:  # Table row for group header
-    "Render a group header row for an audio file (legacy wrapper)."
+def _render_header_cell(
+    item: SourceBrowserItem,  # Header item
+    ctx: CellRenderContext,  # Cell render context
+    select_all_url: str = "",  # URL for selecting all in group
+) -> Any:  # Cell content for a group header row
+    "Render cell content for a group header item."
 ```
 
 ``` python
-def _render_source_list(
-    transcriptions: List[Dict[str, Any]],  # Available transcription records
-    selected_sources: List[Dict[str, str]],  # Currently selected sources
-    add_url: str,  # URL for adding to queue
-    remove_url: str,  # URL for removing from queue
-    preview_url: str,  # URL for previewing content
-    select_all_url: str,  # URL for selecting all in a group
-    grouping_mode: str = "media_path",  # Grouping mode: "media_path" or "batch_id"
-    oob: bool = False,  # Whether to include hx-swap-oob for out-of-band swap
-) -> Any:  # Source list container with table
-    "Render the source list table with grouped rows."
+def _render_record_cell(
+    item: SourceBrowserItem,  # Record item
+    ctx: CellRenderContext,  # Cell render context
+    toggle_url: str = "",  # URL for toggling source selection
+) -> Any:  # Cell content for a data record row
+    "Render cell content for a data record item."
 ```
 
 ``` python
-def _render_source_browser(
-    transcriptions: List[Dict[str, Any]],  # Available transcription records
-    sources: List[Dict[str, Any]],  # Available source plugins (unused, kept for API compat)
-    selected_sources: List[Dict[str, str]],  # Currently selected sources
-    add_url: str,  # URL for adding to queue
-    remove_url: str,  # URL for removing from queue
-    preview_url: str,  # URL for previewing content
-    select_all_url: str,  # URL for selecting all in a group
-    filter_url: str,  # URL for filtering sources
+def create_source_cell_renderer(
+    toggle_url: str = "",  # URL for toggling source selection
+    select_all_url: str = "",  # URL for selecting all in a group
+) -> Callable:  # render_cell(item: SourceBrowserItem, ctx: CellRenderContext) -> Any
+    "Create a render_cell callback for the source browser virtual collection."
+```
+
+``` python
+def render_source_empty() -> Any:  # Empty state component
+    "Render empty state when no transcription sources are available."
+```
+
+``` python
+def _render_source_browser_vc_content(
+    sb_state: Any,  # SourceBrowserRouterState from routes.source_browser
+) -> Any:  # VC content wrapper (without search/grouping header)
+    "Render the VC content portion of the source browser."
+```
+
+``` python
+def _render_source_browser_vc(
+    sb_state: Any,  # SourceBrowserRouterState from routes.source_browser
+    filter_url: str = "",  # URL for filtering sources
     grouping_mode: str = "media_path",  # Current grouping mode
     grouping_change_url: str = "",  # URL for changing grouping mode
-) -> Any:  # Source browser component
-    "Render the source browser panel with search filtering and grouped table."
+) -> Any:  # Source browser component with virtual collection
+    "Render the full source browser panel (header + VC content)."
+```
+
+#### Classes
+
+``` python
+@dataclass
+class SourceBrowserItem:
+    "Item in the source browser virtual collection (header or record)."
+    
+    item_type: str  # "header" or "record"
+    group_key: str = ''  # Group key (media_path or batch_id value)
+    group_display: str = ''  # Formatted display text for group header
+    group_count: int = 0  # Number of records in this group
+    grouping_mode: str = ''  # Grouping mode used ("media_path" or "batch_id")
+    record: Optional[Dict[str, Any]]  # Original transcription record dict
+    is_selected: bool = False  # Whether currently in queue
+```
+
+#### Variables
+
+``` python
+SOURCE_BROWSER_COLUMNS
+_SB_CONTENT_ID = 'sb-content'
+_SB_VC_WRAPPER_ID = 'sb-vc-wrapper'
+SB_SYSTEM_ID = 'sb-collection'
+```
+
+### source_browser (`source_browser.ipynb`)
+
+> Source browser virtual collection router for Phase 1 selection
+
+#### Import
+
+``` python
+from cjm_transcript_source_select.routes.source_browser import (
+    SourceBrowserRouterState,
+    init_source_browser_router
+)
+```
+
+#### Functions
+
+``` python
+def init_source_browser_router(
+    source_service: SourceService,  # Source service for querying transcriptions
+    urls: SelectionUrls,  # URL bundle (toggle, select_all, filter, grouping_change)
+    prefix: str = "/browser",  # Route prefix for VC routes
+) -> SourceBrowserRouterState:  # Router state with all VC objects and helpers
+    "Initialize the source browser virtual collection router."
+```
+
+#### Classes
+
+``` python
+@dataclass
+class SourceBrowserRouterState:
+    "Return value from init_source_browser_router."
+    
+    router: APIRouter  # VC routes (nav, focus, activate, sort, viewport)
+    urls: VirtualCollectionUrls  # VC URL bundle
+    ids: VirtualCollectionHtmlIds  # VC HTML IDs
+    btn_ids: VirtualCollectionButtonIds  # VC keyboard button IDs
+    config: VirtualCollectionConfig  # VC config
+    state: VirtualCollectionState  # VC state (mutable)
+    items: List[SourceBrowserItem]  # Shared items list (mutable)
+    render_cell: Callable  # Cell render callback
+    rebuild_and_render: Callable  # (transcriptions, selected_sources, grouping_mode, content_only) -> Div
+    rebuild_items: Callable  # (transcriptions, selected_sources, grouping_mode) -> None
+    sync_items_selection: Callable  # (selected_sources) -> None
+    get_visible_checkbox_oobs: Callable  # () -> tuple of OOB elements
+    get_checkbox_oob_for: Callable  # (record_id, provider_id) -> OOB element or None
+    get_vc_row_id_for: Callable  # (record_id, provider_id) -> str or None
 ```
 
 ### source_utils (`source_utils.ipynb`)
@@ -1252,13 +1327,13 @@ def validate_browse_path(
 from cjm_transcript_source_select.components.step_renderer import (
     SD_FOCUSED_RECORD_ID_INPUT,
     SD_FOCUSED_PROVIDER_ID_INPUT,
-    SD_TOGGLE_BTN,
     SD_REMOVE_BTN,
     SD_REORDER_UP_BTN,
     SD_REORDER_DOWN_BTN,
     SD_TAB_PREV_BTN,
     SD_TAB_NEXT_BTN,
     SD_PREVIEW_BTN,
+    FB_SYSTEM_ID,
     render_selection_step
 )
 ```
@@ -1266,8 +1341,8 @@ from cjm_transcript_source_select.components.step_renderer import (
 #### Functions
 
 ``` python
-def _create_selection_keyboard_manager() -> ZoneManager:  # Configured keyboard zone manager
-    "Create the keyboard zone manager for Phase 1 selection step."
+def _create_parent_keyboard_manager() -> ZoneManager:  # Parent keyboard manager for hierarchy
+    "Create the parent keyboard manager for the selection step."
 ```
 
 ``` python
@@ -1313,19 +1388,10 @@ def _render_source_tabs(
 ```
 
 ``` python
-def _get_step_renderer_provider() -> LocalFileSystemProvider:
-    """Get or create the local files provider for step renderer."""
-    global _step_renderer_provider
-    if _step_renderer_provider is None
-    "Get or create the local files provider for step renderer."
-```
-
-``` python
-def _get_step_renderer_config():
-    """Get or create the local files config for step renderer."""
-    global _step_renderer_config
-    if _step_renderer_config is None
-    "Get or create the local files config for step renderer."
+def _generate_hierarchy_js(
+    active_tab: str,  # Active tab: "db" or "files"
+) -> Script:  # Script element with hierarchy wiring and activation logic
+    "Generate JavaScript for keyboard system hierarchy and child activation."
 ```
 
 ``` python
@@ -1334,10 +1400,10 @@ def render_selection_step(
     transcriptions: List[Dict[str, Any]],  # Available transcription records
     selected_sources: List[Dict[str, str]],  # Ordered selection
     grouping_mode: str,  # Grouping mode: "media_path" or "batch_id"
-    external_db_paths: List[str],  # External database paths
-    file_browser_state: Dict[str, Any],  # Serialized BrowserState from file-browser library
     active_tab: str,  # Active tab: "db" or "files"
     urls: SelectionUrls,  # URL bundle for selection routes
+    render_local_files_panel: Optional[Callable] = None,  # Render fn for Files tab content
+    sb_state: Any = None,  # SourceBrowserRouterState for DB tab VC rendering
 ) -> Any:  # FastHTML component
     "Render Phase 1: Source Selection & Ordering step with two-column layout."
 ```
@@ -1347,14 +1413,13 @@ def render_selection_step(
 ``` python
 SD_FOCUSED_RECORD_ID_INPUT = 'sd-focused-record-id'
 SD_FOCUSED_PROVIDER_ID_INPUT = 'sd-focused-provider-id'
-SD_TOGGLE_BTN = 'sd-toggle-btn'
 SD_REMOVE_BTN = 'sd-remove-btn'
 SD_REORDER_UP_BTN = 'sd-reorder-up-btn'
 SD_REORDER_DOWN_BTN = 'sd-reorder-down-btn'
 SD_TAB_PREV_BTN = 'sd-tab-prev-btn'
 SD_TAB_NEXT_BTN = 'sd-tab-next-btn'
 SD_PREVIEW_BTN = 'sd-preview-btn'
-_step_renderer_provider: Optional[LocalFileSystemProvider] = None
+FB_SYSTEM_ID = 'lfb-collection'
 _VIEWPORT_FIT_CONFIG
 ```
 
@@ -1381,7 +1446,9 @@ def _handle_tab_switch(
     sess,  # FastHTML session object
     direction: str,  # Direction: "prev", "next", "db", or "files"
     urls: SelectionUrls,  # URL bundle for rendering
-):  # Tuple of inner content and OOB tab headers
+    render_local_files_panel: Optional[Callable] = None,  # Render fn for Files tab
+    sb_state: Any = None,  # SourceBrowserRouterState for DB tab VC rendering
+):  # Tuple of inner content, OOB tab headers, and tab switch script
     "Switch between Plugin DB and Local Files tabs."
 ```
 
@@ -1392,6 +1459,8 @@ def init_tabs_router(
     source_service: SourceService,  # The source service for queries
     prefix: str,  # Route prefix (e.g., "/workflow/selection/tabs")
     urls: SelectionUrls,  # URL bundle for rendering
+    render_local_files_panel: Optional[Callable] = None,  # Render fn for Files tab content
+    sb_state: Any = None,  # SourceBrowserRouterState for DB tab VC rendering
 ) -> Tuple[APIRouter, Dict[str, Callable]]:  # (router, route_dict)
     "Initialize tab switching routes."
 ```