cjm-transcript-source-select 0.0.28__tar.gz → 0.0.30__tar.gz

{cjm_transcript_source_select-0.0.28/cjm_transcript_source_select.egg-info → cjm_transcript_source_select-0.0.30}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cjm-transcript-source-select
-Version: 0.0.28
+Version: 0.0.30
 Summary: FastHTML source selection component for transcript decomposition workflows, with federated database browsing, drag-drop ordering, and keyboard navigation.
 Author-email: "Christian J. Mills" <9126128+cj-mills@users.noreply.github.com>
 License: Apache-2.0
@@ -15,13 +15,14 @@ Classifier: Programming Language :: Python :: 3 :: Only
 Requires-Python: >=3.12
 Description-Content-Type: text/markdown
 License-File: LICENSE
+Requires-Dist: python-fasthtml==0.13.4
 Requires-Dist: cjm-plugin-system
 Requires-Dist: cjm-transcription-plugin-system
 Requires-Dist: cjm-fasthtml-app-core
 Requires-Dist: cjm-fasthtml-daisyui
 Requires-Dist: cjm_fasthtml_lucide_icons
-Requires-Dist: cjm_fasthtml_file_browser>=0.0.17
-Requires-Dist: cjm_fasthtml_keyboard_navigation>=0.0.20
+Requires-Dist: cjm_fasthtml_file_browser>=0.0.19
+Requires-Dist: cjm_fasthtml_keyboard_navigation>=0.0.23
 Requires-Dist: duckdb
 Requires-Dist: pandas
 Requires-Dist: cjm_workflow_state
@@ -29,7 +30,7 @@ Requires-Dist: cjm_source_provider
 Requires-Dist: cjm_fasthtml_interactions
 Requires-Dist: cjm_fasthtml_viewport_fit
 Requires-Dist: cjm_fasthtml_virtual_collection
-Requires-Dist: cjm_fasthtml_sortable_queue>=0.0.13
+Requires-Dist: cjm_fasthtml_sortable_queue>=0.0.16
 Requires-Dist: cjm_fasthtml_design_system>=0.0.9
 Dynamic: license-file
 
@@ -95,57 +96,57 @@ graph LR
     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_source_browser --> services_source_utils
     components_source_browser --> html_ids
     components_source_browser --> utils
-    components_step_renderer --> components_preview_panel
-    components_step_renderer --> utils
     components_step_renderer --> components_selection_queue
-    components_step_renderer --> components_source_browser
-    components_step_renderer --> models
     components_step_renderer --> html_ids
+    components_step_renderer --> models
     components_step_renderer --> components_local_files
-    routes_core --> components_step_renderer
+    components_step_renderer --> components_source_browser
+    components_step_renderer --> components_preview_panel
+    components_step_renderer --> utils
     routes_core --> models
-    routes_core --> components_selection_queue
-    routes_core --> services_source
     routes_core --> html_ids
-    routes_filtering --> routes_core
+    routes_core --> components_step_renderer
+    routes_core --> services_source
+    routes_core --> components_selection_queue
     routes_filtering --> services_source_utils
     routes_filtering --> services_source
+    routes_filtering --> routes_core
     routes_filtering --> models
-    routes_init --> routes_local_files
-    routes_init --> routes_source_browser
     routes_init --> routes_core
+    routes_init --> services_source
+    routes_init --> routes_local_files
     routes_init --> routes_queue
     routes_init --> routes_tabs
-    routes_init --> services_source
-    routes_init --> routes_filtering
     routes_init --> models
-    routes_local_files --> routes_core
+    routes_init --> routes_filtering
+    routes_init --> routes_source_browser
     routes_local_files --> components_local_files
     routes_local_files --> services_source
+    routes_local_files --> routes_core
     routes_local_files --> models
-    routes_queue --> components_preview_panel
-    routes_queue --> routes_core
-    routes_queue --> services_source_utils
     routes_queue --> services_source
+    routes_queue --> services_source_utils
+    routes_queue --> routes_core
     routes_queue --> models
-    routes_source_browser --> components_preview_panel
-    routes_source_browser --> components_source_browser
+    routes_queue --> components_preview_panel
     routes_source_browser --> services_source
-    routes_source_browser --> routes_core
+    routes_source_browser --> components_source_browser
+    routes_source_browser --> html_ids
     routes_source_browser --> models
     routes_source_browser --> services_source_utils
-    routes_source_browser --> html_ids
-    routes_tabs --> services_source
+    routes_source_browser --> routes_core
+    routes_source_browser --> components_preview_panel
+    routes_tabs --> models
     routes_tabs --> routes_core
-    routes_tabs --> components_step_renderer
+    routes_tabs --> services_source
     routes_tabs --> services_source_utils
-    routes_tabs --> models
+    routes_tabs --> components_step_renderer
 ```
 
 *52 cross-module dependencies detected*
@@ -524,12 +525,6 @@ def _handle_remove_external_source(
 
 ``` python
 def init_local_files_router(
-    state_store: WorkflowStateStore,  # The workflow state store
-    workflow_id: str,  # The workflow identifier
-    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
-) -> LocalFilesResult:  # Router result with routers, routes, render, restore, and reset
     "Initialize local files browser routes with new file browser API."
 ```
 
@@ -614,6 +609,7 @@ class LocalFilesResult:
     render_panel: Callable  # (error_message?, session_id?) -> rendered panel
     restore_state: Callable = field(...)  # (session_id) -> None, restore persisted state
     reset_state: Callable = field(...)  # () -> None, reset in-memory caches
+    kb_manager: Optional[ZoneManager]  # ZoneManager backing the local file browser's keyboard system — hand to render_keyboard_hints_modal(..., child_managers=[...]) for hierarchical hint display
 ```
 
 ``` python
@@ -628,6 +624,7 @@ class SelectionResult:
     sb_state: Any  # SourceBrowserRouterState
     restore_state: Callable = field(...)  # (session_id) -> None, restore persisted state
     reset_state: Callable = field(...)  # () -> None, reset in-memory caches
+    fb_kb_manager: Optional[ZoneManager]  # ZoneManager from the local file browser; convenience pointer mirroring LocalFilesResult.kb_manager so step renderers can read it directly from SelectionResult without descending into LocalFilesResult
 ```
 
 ### preview_panel (`preview_panel.ipynb`)
@@ -1066,7 +1063,8 @@ from cjm_transcript_source_select.components.source_browser import (
     build_source_items,
     is_source_item_skippable,
     create_source_cell_renderer,
-    render_source_empty
+    render_source_empty,
+    build_source_browser_keyboard_system
 )
 ```
 
@@ -1127,19 +1125,45 @@ def render_source_empty() -> Any:  # Empty state component
     "Render empty state when no transcription sources are available."
 ```
 
+``` python
+def build_source_browser_keyboard_system(
+    sb_state: Any,                              # SourceBrowserRouterState (carries vc_ids, vc_btn_ids, vc_urls)
+    manager_label: Optional[str] = None,        # Human-readable label for the ZoneManager (consumed by render_keyboard_hints_modal section header when this is a child_managers entry)
+) -> KeyboardSystem:                            # Complete rendered KeyboardSystem (carries .manager for hierarchical hints handoff)
+    """
+    Build the source browser's KeyboardSystem standalone.
+    
+    Lifts the manager construction out of `_render_source_browser_vc_content`
+    so the underlying `ZoneManager` is accessible via `KeyboardSystem.manager`
+    for hierarchical hints handoff. Consumers wiring this as a child of the
+    parent selection-step manager pass the manager to
+    `render_keyboard_hints_modal(..., child_managers=[...])` so the modal's
+    section header reads as `manager_label` instead of the technical SB_SYSTEM_ID.
+    """
+```
+
 ``` python
 def _render_source_browser_vc_content(
-    sb_state: Any,  # SourceBrowserRouterState from routes.source_browser
+    sb_state: Any,                                       # SourceBrowserRouterState from routes.source_browser
+    keyboard_system: Optional[KeyboardSystem] = None,    # Pre-built keyboard system (when None, builds internally via build_source_browser_keyboard_system)
 ) -> Any:  # VC content wrapper (without search/grouping header)
-    "Render the VC content portion of the source browser."
+    """
+    Render the VC content portion of the source browser.
+    
+    When `keyboard_system` is provided, the caller has built the system upstream
+    (typically `init_source_browser_router`) and owns the underlying ZoneManager.
+    When None, builds the system internally — preserves pre-C1 behavior for any
+    caller that doesn't need the manager handoff.
+    """
 ```
 
 ``` 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
+    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
+    keyboard_system: Optional[KeyboardSystem] = None,    # Pre-built keyboard system, threaded through to VC content
 ) -> Any:  # Source browser component with virtual collection
     "Render the full source browser panel (header + VC content)."
 ```
@@ -1186,10 +1210,6 @@ from cjm_transcript_source_select.routes.source_browser import (
 
 ``` 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."
 ```
 
@@ -1214,6 +1234,7 @@ class SourceBrowserRouterState:
     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
+    kb_manager: Optional[ZoneManager]  # ZoneManager backing the source browser's VC keyboard system — hand to render_keyboard_hints_modal(..., child_managers=[...]) for hierarchical hint display
 ```
 
 ### source_utils (`source_utils.ipynb`)
@@ -1380,7 +1401,22 @@ from cjm_transcript_source_select.components.step_renderer import (
 
 ``` python
 def _create_parent_keyboard_manager() -> ZoneManager:  # Parent keyboard manager for hierarchy
-    "Create the parent keyboard manager with two ghost zones for column switching."
+    """
+    Create the parent keyboard manager with two ghost zones for column switching.
+    
+    Each ghost zone declares `activate_child_callback` so the library-baked
+    Enter/Space dispatch (`ZoneManager.activate_keys` defaults to `("Enter", " ")`)
+    invokes the consumer-defined JS function — `window.activateBrowserChild`
+    and `window.activateQueueChild` are wired in `_generate_hierarchy_js`. The
+    callback path is used (vs. the declarative `activate_child_id` path) because
+    the browser ghost zone's active child depends on the currently-selected
+    tab (`db` → source-browser child; `files` → file-browser child); this
+    dynamic resolution can't be a static declarative mapping.
+    
+    Each ghost zone's `label` surfaces as the section header for that zone's
+    derived rows in the hints modal (e.g., the parent's "Source Browser" /
+    "Selection Queue" — Activate row appears under those labels).
+    """
 ```
 
 ``` python
@@ -1427,15 +1463,6 @@ def _generate_hierarchy_js(
 
 ``` python
 def render_selection_step(
-    sources: List[Dict[str, Any]],  # Available source plugins
-    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"
-    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."
 ```
 

{cjm_transcript_source_select-0.0.28 → cjm_transcript_source_select-0.0.30}/README.md

@@ -60,57 +60,57 @@ graph LR
     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_source_browser --> services_source_utils
     components_source_browser --> html_ids
     components_source_browser --> utils
-    components_step_renderer --> components_preview_panel
-    components_step_renderer --> utils
     components_step_renderer --> components_selection_queue
-    components_step_renderer --> components_source_browser
-    components_step_renderer --> models
     components_step_renderer --> html_ids
+    components_step_renderer --> models
     components_step_renderer --> components_local_files
-    routes_core --> components_step_renderer
+    components_step_renderer --> components_source_browser
+    components_step_renderer --> components_preview_panel
+    components_step_renderer --> utils
     routes_core --> models
-    routes_core --> components_selection_queue
-    routes_core --> services_source
     routes_core --> html_ids
-    routes_filtering --> routes_core
+    routes_core --> components_step_renderer
+    routes_core --> services_source
+    routes_core --> components_selection_queue
     routes_filtering --> services_source_utils
     routes_filtering --> services_source
+    routes_filtering --> routes_core
     routes_filtering --> models
-    routes_init --> routes_local_files
-    routes_init --> routes_source_browser
     routes_init --> routes_core
+    routes_init --> services_source
+    routes_init --> routes_local_files
     routes_init --> routes_queue
     routes_init --> routes_tabs
-    routes_init --> services_source
-    routes_init --> routes_filtering
     routes_init --> models
-    routes_local_files --> routes_core
+    routes_init --> routes_filtering
+    routes_init --> routes_source_browser
     routes_local_files --> components_local_files
     routes_local_files --> services_source
+    routes_local_files --> routes_core
     routes_local_files --> models
-    routes_queue --> components_preview_panel
-    routes_queue --> routes_core
-    routes_queue --> services_source_utils
     routes_queue --> services_source
+    routes_queue --> services_source_utils
+    routes_queue --> routes_core
     routes_queue --> models
-    routes_source_browser --> components_preview_panel
-    routes_source_browser --> components_source_browser
+    routes_queue --> components_preview_panel
     routes_source_browser --> services_source
-    routes_source_browser --> routes_core
+    routes_source_browser --> components_source_browser
+    routes_source_browser --> html_ids
     routes_source_browser --> models
     routes_source_browser --> services_source_utils
-    routes_source_browser --> html_ids
-    routes_tabs --> services_source
+    routes_source_browser --> routes_core
+    routes_source_browser --> components_preview_panel
+    routes_tabs --> models
     routes_tabs --> routes_core
-    routes_tabs --> components_step_renderer
+    routes_tabs --> services_source
     routes_tabs --> services_source_utils
-    routes_tabs --> models
+    routes_tabs --> components_step_renderer
 ```
 
 *52 cross-module dependencies detected*
@@ -489,12 +489,6 @@ def _handle_remove_external_source(
 
 ``` python
 def init_local_files_router(
-    state_store: WorkflowStateStore,  # The workflow state store
-    workflow_id: str,  # The workflow identifier
-    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
-) -> LocalFilesResult:  # Router result with routers, routes, render, restore, and reset
     "Initialize local files browser routes with new file browser API."
 ```
 
@@ -579,6 +573,7 @@ class LocalFilesResult:
     render_panel: Callable  # (error_message?, session_id?) -> rendered panel
     restore_state: Callable = field(...)  # (session_id) -> None, restore persisted state
     reset_state: Callable = field(...)  # () -> None, reset in-memory caches
+    kb_manager: Optional[ZoneManager]  # ZoneManager backing the local file browser's keyboard system — hand to render_keyboard_hints_modal(..., child_managers=[...]) for hierarchical hint display
 ```
 
 ``` python
@@ -593,6 +588,7 @@ class SelectionResult:
     sb_state: Any  # SourceBrowserRouterState
     restore_state: Callable = field(...)  # (session_id) -> None, restore persisted state
     reset_state: Callable = field(...)  # () -> None, reset in-memory caches
+    fb_kb_manager: Optional[ZoneManager]  # ZoneManager from the local file browser; convenience pointer mirroring LocalFilesResult.kb_manager so step renderers can read it directly from SelectionResult without descending into LocalFilesResult
 ```
 
 ### preview_panel (`preview_panel.ipynb`)
@@ -1031,7 +1027,8 @@ from cjm_transcript_source_select.components.source_browser import (
     build_source_items,
     is_source_item_skippable,
     create_source_cell_renderer,
-    render_source_empty
+    render_source_empty,
+    build_source_browser_keyboard_system
 )
 ```
 
@@ -1092,19 +1089,45 @@ def render_source_empty() -> Any:  # Empty state component
     "Render empty state when no transcription sources are available."
 ```
 
+``` python
+def build_source_browser_keyboard_system(
+    sb_state: Any,                              # SourceBrowserRouterState (carries vc_ids, vc_btn_ids, vc_urls)
+    manager_label: Optional[str] = None,        # Human-readable label for the ZoneManager (consumed by render_keyboard_hints_modal section header when this is a child_managers entry)
+) -> KeyboardSystem:                            # Complete rendered KeyboardSystem (carries .manager for hierarchical hints handoff)
+    """
+    Build the source browser's KeyboardSystem standalone.
+    
+    Lifts the manager construction out of `_render_source_browser_vc_content`
+    so the underlying `ZoneManager` is accessible via `KeyboardSystem.manager`
+    for hierarchical hints handoff. Consumers wiring this as a child of the
+    parent selection-step manager pass the manager to
+    `render_keyboard_hints_modal(..., child_managers=[...])` so the modal's
+    section header reads as `manager_label` instead of the technical SB_SYSTEM_ID.
+    """
+```
+
 ``` python
 def _render_source_browser_vc_content(
-    sb_state: Any,  # SourceBrowserRouterState from routes.source_browser
+    sb_state: Any,                                       # SourceBrowserRouterState from routes.source_browser
+    keyboard_system: Optional[KeyboardSystem] = None,    # Pre-built keyboard system (when None, builds internally via build_source_browser_keyboard_system)
 ) -> Any:  # VC content wrapper (without search/grouping header)
-    "Render the VC content portion of the source browser."
+    """
+    Render the VC content portion of the source browser.
+    
+    When `keyboard_system` is provided, the caller has built the system upstream
+    (typically `init_source_browser_router`) and owns the underlying ZoneManager.
+    When None, builds the system internally — preserves pre-C1 behavior for any
+    caller that doesn't need the manager handoff.
+    """
 ```
 
 ``` 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
+    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
+    keyboard_system: Optional[KeyboardSystem] = None,    # Pre-built keyboard system, threaded through to VC content
 ) -> Any:  # Source browser component with virtual collection
     "Render the full source browser panel (header + VC content)."
 ```
@@ -1151,10 +1174,6 @@ from cjm_transcript_source_select.routes.source_browser import (
 
 ``` 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."
 ```
 
@@ -1179,6 +1198,7 @@ class SourceBrowserRouterState:
     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
+    kb_manager: Optional[ZoneManager]  # ZoneManager backing the source browser's VC keyboard system — hand to render_keyboard_hints_modal(..., child_managers=[...]) for hierarchical hint display
 ```
 
 ### source_utils (`source_utils.ipynb`)
@@ -1345,7 +1365,22 @@ from cjm_transcript_source_select.components.step_renderer import (
 
 ``` python
 def _create_parent_keyboard_manager() -> ZoneManager:  # Parent keyboard manager for hierarchy
-    "Create the parent keyboard manager with two ghost zones for column switching."
+    """
+    Create the parent keyboard manager with two ghost zones for column switching.
+    
+    Each ghost zone declares `activate_child_callback` so the library-baked
+    Enter/Space dispatch (`ZoneManager.activate_keys` defaults to `("Enter", " ")`)
+    invokes the consumer-defined JS function — `window.activateBrowserChild`
+    and `window.activateQueueChild` are wired in `_generate_hierarchy_js`. The
+    callback path is used (vs. the declarative `activate_child_id` path) because
+    the browser ghost zone's active child depends on the currently-selected
+    tab (`db` → source-browser child; `files` → file-browser child); this
+    dynamic resolution can't be a static declarative mapping.
+    
+    Each ghost zone's `label` surfaces as the section header for that zone's
+    derived rows in the hints modal (e.g., the parent's "Source Browser" /
+    "Selection Queue" — Activate row appears under those labels).
+    """
 ```
 
 ``` python
@@ -1392,15 +1427,6 @@ def _generate_hierarchy_js(
 
 ``` python
 def render_selection_step(
-    sources: List[Dict[str, Any]],  # Available source plugins
-    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"
-    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."
 ```
 

cjm_transcript_source_select-0.0.30/cjm_transcript_source_select/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.0.30"

{cjm_transcript_source_select-0.0.28 → cjm_transcript_source_select-0.0.30}/cjm_transcript_source_select/_modidx.py

@@ -45,6 +45,8 @@ d = { 'settings': { 'branch': 'main',
                                                                                                                                                               'cjm_transcript_source_select/components/source_browser.py'),
                                                                         'cjm_transcript_source_select.components.source_browser._render_source_browser_vc_content': ( 'components/source_browser.html#_render_source_browser_vc_content',
                                                                                                                                                                       'cjm_transcript_source_select/components/source_browser.py'),
+                                                                        'cjm_transcript_source_select.components.source_browser.build_source_browser_keyboard_system': ( 'components/source_browser.html#build_source_browser_keyboard_system',
+                                                                                                                                                                         'cjm_transcript_source_select/components/source_browser.py'),
                                                                         'cjm_transcript_source_select.components.source_browser.build_source_items': ( 'components/source_browser.html#build_source_items',
                                                                                                                                                        'cjm_transcript_source_select/components/source_browser.py'),
                                                                         'cjm_transcript_source_select.components.source_browser.create_source_cell_renderer': ( 'components/source_browser.html#create_source_cell_renderer',

{cjm_transcript_source_select-0.0.28 → cjm_transcript_source_select-0.0.30}/cjm_transcript_source_select/components/source_browser.py

@@ -4,7 +4,7 @@
 
 # %% auto #0
 __all__ = ['SOURCE_BROWSER_COLUMNS', 'SB_SYSTEM_ID', 'SourceBrowserItem', 'build_source_items', 'is_source_item_skippable',
-           'create_source_cell_renderer', 'render_source_empty']
+           'create_source_cell_renderer', 'render_source_empty', 'build_source_browser_keyboard_system']
 
 # %% ../../nbs/components/source_browser.ipynb #7b2e89c5
 import json
@@ -53,7 +53,7 @@ from cjm_fasthtml_virtual_collection.js.scrollbar import generate_scrollbar_js
 from cjm_fasthtml_virtual_collection.js.auto_fit import generate_auto_fit_js, auto_fit_callback_name
 
 from cjm_fasthtml_keyboard_navigation.core.manager import ZoneManager
-from cjm_fasthtml_keyboard_navigation.components.system import render_keyboard_system
+from cjm_fasthtml_keyboard_navigation.components.system import render_keyboard_system, KeyboardSystem
 
 from cjm_fasthtml_viewport_fit.models import ViewportFitConfig
 from cjm_fasthtml_viewport_fit.components import render_viewport_fit_script
@@ -306,10 +306,52 @@ _SB_VC_WRAPPER_ID = "sb-vc-wrapper"
 SB_SYSTEM_ID = "sb-collection"
 
 
+def build_source_browser_keyboard_system(
+    sb_state: Any,                              # SourceBrowserRouterState (carries vc_ids, vc_btn_ids, vc_urls)
+    manager_label: Optional[str] = None,        # Human-readable label for the ZoneManager (consumed by render_keyboard_hints_modal section header when this is a child_managers entry)
+) -> KeyboardSystem:                            # Complete rendered KeyboardSystem (carries .manager for hierarchical hints handoff)
+    """Build the source browser's KeyboardSystem standalone.
+
+    Lifts the manager construction out of `_render_source_browser_vc_content`
+    so the underlying `ZoneManager` is accessible via `KeyboardSystem.manager`
+    for hierarchical hints handoff. Consumers wiring this as a child of the
+    parent selection-step manager pass the manager to
+    `render_keyboard_hints_modal(..., child_managers=[...])` so the modal's
+    section header reads as `manager_label` instead of the technical SB_SYSTEM_ID.
+    """
+    vc_ids = sb_state.ids
+    vc_btn_ids = sb_state.btn_ids
+    vc_urls = sb_state.urls
+
+    zone = create_collection_focus_zone(vc_ids)
+    nav_actions = create_collection_nav_actions(zone.id, vc_btn_ids)
+    manager = ZoneManager(
+        zones=(zone,),
+        actions=nav_actions,
+        system_id=SB_SYSTEM_ID,
+        label=manager_label,
+    )
+    url_map = build_collection_url_map(vc_btn_ids, vc_urls)
+    target_map = {btn_id: f"#{vc_ids.rows}" for btn_id in url_map}
+    swap_map = {btn_id: "none" for btn_id in url_map}
+    kb_system = render_keyboard_system(
+        manager, url_map=url_map, target_map=target_map, swap_map=swap_map,
+    )
+    apply_nav_sync(kb_system, vc_ids)
+    return kb_system
+
+
 def _render_source_browser_vc_content(
-    sb_state: Any,  # SourceBrowserRouterState from routes.source_browser
+    sb_state: Any,                                       # SourceBrowserRouterState from routes.source_browser
+    keyboard_system: Optional[KeyboardSystem] = None,    # Pre-built keyboard system (when None, builds internally via build_source_browser_keyboard_system)
 ) -> Any:  # VC content wrapper (without search/grouping header)
-    """Render the VC content portion of the source browser."""
+    """Render the VC content portion of the source browser.
+
+    When `keyboard_system` is provided, the caller has built the system upstream
+    (typically `init_source_browser_router`) and owns the underlying ZoneManager.
+    When None, builds the system internally — preserves pre-C1 behavior for any
+    caller that doesn't need the manager handoff.
+    """
     vc_ids = sb_state.ids
     vc_btn_ids = sb_state.btn_ids
     vc_config = sb_state.config
@@ -323,15 +365,8 @@ def _render_source_browser_vc_content(
         render_empty=render_source_empty,
     )
 
-    # Keyboard system for VC navigation
-    zone = create_collection_focus_zone(vc_ids)
-    nav_actions = create_collection_nav_actions(zone.id, vc_btn_ids)
-    manager = ZoneManager(zones=(zone,), actions=nav_actions, system_id=SB_SYSTEM_ID)
-    url_map = build_collection_url_map(vc_btn_ids, vc_urls)
-    target_map = {btn_id: f"#{vc_ids.rows}" for btn_id in url_map}
-    swap_map = {btn_id: "none" for btn_id in url_map}
-    kb_system = render_keyboard_system(manager, url_map=url_map, target_map=target_map, swap_map=swap_map)
-    apply_nav_sync(kb_system, vc_ids)
+    # Keyboard system — use caller-supplied or build internally.
+    kb_system = keyboard_system if keyboard_system is not None else build_source_browser_keyboard_system(sb_state)
 
     # Auto-fit JS
     auto_fit_js = generate_auto_fit_js(
@@ -372,13 +407,14 @@ def _render_source_browser_vc_content(
 
 
 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
+    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
+    keyboard_system: Optional[KeyboardSystem] = None,    # Pre-built keyboard system, threaded through to VC content
 ) -> Any:  # Source browser component with virtual collection
     """Render the full source browser panel (header + VC content)."""
-    vc_content = _render_source_browser_vc_content(sb_state)
+    vc_content = _render_source_browser_vc_content(sb_state, keyboard_system=keyboard_system)
 
     return Div(
         # Header bar with search and grouping selector

{cjm_transcript_source_select-0.0.28 → cjm_transcript_source_select-0.0.30}/cjm_transcript_source_select/components/step_renderer.py

@@ -87,43 +87,47 @@ _ZONE_FOCUS_CLASSES = (str(shadow.lg), str(shadow_dui.primary))
 
 
 def _create_parent_keyboard_manager() -> ZoneManager:  # Parent keyboard manager for hierarchy
-    """Create the parent keyboard manager with two ghost zones for column switching."""
+    """Create the parent keyboard manager with two ghost zones for column switching.
+
+    Each ghost zone declares `activate_child_callback` so the library-baked
+    Enter/Space dispatch (`ZoneManager.activate_keys` defaults to `("Enter", " ")`)
+    invokes the consumer-defined JS function — `window.activateBrowserChild`
+    and `window.activateQueueChild` are wired in `_generate_hierarchy_js`. The
+    callback path is used (vs. the declarative `activate_child_id` path) because
+    the browser ghost zone's active child depends on the currently-selected
+    tab (`db` → source-browser child; `files` → file-browser child); this
+    dynamic resolution can't be a static declarative mapping.
+
+    Each ghost zone's `label` surfaces as the section header for that zone's
+    derived rows in the hints modal (e.g., the parent's "Source Browser" /
+    "Selection Queue" — Activate row appears under those labels).
+    """
     # Ghost zone for browser area (wraps source tabs — child systems live here)
     ghost_browser_zone = FocusZone(
         id=SelectionHtmlIds.GHOST_BROWSER,
+        label="Source Browser",
         item_selector=None,
         navigation=ScrollOnly(),
         zone_focus_classes=_ZONE_FOCUS_CLASSES,
+        activate_child_callback="activateBrowserChild",
     )
 
     # Ghost zone for queue area (wraps queue panel — queue child system lives here)
     ghost_queue_zone = FocusZone(
         id=SelectionHtmlIds.GHOST_QUEUE,
+        label="Selection Queue",
         item_selector=None,
         navigation=ScrollOnly(),
         zone_focus_classes=_ZONE_FOCUS_CLASSES,
+        activate_child_callback="activateQueueChild",
     )
 
-    # Parent-level actions (no queue-scoped actions — those live in queue child system)
+    # Parent-level actions (no queue-scoped actions — those live in queue child system).
+    # The previous per-zone Enter KeyActions for child activation have been removed —
+    # library-baked Enter/Space dispatch via FocusZone.activate_child_callback handles
+    # activation. Tab switching stays here because Ctrl+Shift+{/} doesn't fit the
+    # activation seam (different keys, different dispatch path).
     actions = (
-        # Enter activates the browser child when ghost-browser zone is active
-        KeyAction(
-            key="Enter",
-            js_callback="activateBrowserChild",
-            zone_ids=(SelectionHtmlIds.GHOST_BROWSER,),
-            description="Activate browser",
-            hint_group="Navigation",
-        ),
-
-        # Enter activates the queue child when ghost-queue zone is active
-        KeyAction(
-            key="Enter",
-            js_callback="activateQueueChild",
-            zone_ids=(SelectionHtmlIds.GHOST_QUEUE,),
-            description="Activate queue",
-            hint_group="Navigation",
-        ),
-
         # Tab switching — no zone_ids so it fires from any parent zone
         # and bubbles up from children (children don't handle Ctrl+Shift+{/})
         KeyAction(
@@ -146,6 +150,7 @@ def _create_parent_keyboard_manager() -> ZoneManager:  # Parent keyboard manager
         zones=(ghost_browser_zone, ghost_queue_zone),
         actions=actions,
         system_id=SelectionHtmlIds.PARENT_SYSTEM_ID,
+        label="Source Selection",
         prev_zone_key="ArrowLeft",
         next_zone_key="ArrowRight",
         state_hidden_inputs=True,
@@ -377,6 +382,7 @@ def render_selection_step(
     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
+    fb_kb_manager: Optional[Any] = None,  # File browser ZoneManager (from LocalFilesResult.kb_manager / SelectionResult.fb_kb_manager) for the hints modal's hierarchical child_managers
 ) -> Any:  # FastHTML component
     """Render Phase 1: Source Selection & Ordering step with two-column layout."""
     # Create parent keyboard manager (two ghost zones for column switching)
@@ -407,6 +413,8 @@ def render_selection_step(
 
     # Build queue keyboard system (self-contained child system from sortable-queue library)
     # data_attributes includes "key" for remove route + "record-id"/"provider-id" for preview
+    # manager_label surfaces as the section header for the queue's kb_manager in
+    # the hints modal's hierarchical child_managers section.
     queue_kb = create_queue_keyboard_system(
         config=SD_QUEUE_CONFIG,
         ids=SD_QUEUE_IDS,
@@ -414,6 +422,7 @@ def render_selection_step(
         data_attributes=("key", "record-id", "provider-id"),
         on_focus_change="triggerPreviewUpdate",
         hidden_input_prefix="sd-focused",
+        manager_label="Selection Queue",
     )
 
     # Build include selector for preview hidden inputs
@@ -472,8 +481,23 @@ def render_selection_step(
     # Hierarchy wiring script (must come after all keyboard systems are rendered)
     hierarchy_js = _generate_hierarchy_js(active_tab)
 
-    # Keyboard hints modal
-    hints_modal, hints_trigger, hints_script = render_keyboard_hints_modal(kb_manager)
+    # Keyboard hints modal — hierarchical mode with all three children.
+    # Pass all three regardless of active_tab (modal is a reference, not a
+    # "what's active right now" indicator — user benefits from seeing all
+    # available actions across DB / Files / Queue). None entries are filtered
+    # so the modal handles missing managers gracefully (e.g. before host
+    # wiring is complete during tests).
+    child_managers = tuple(
+        m for m in (
+            sb_state.kb_manager if sb_state is not None else None,
+            fb_kb_manager,
+            queue_kb.manager,
+        ) if m is not None
+    )
+    hints_modal, hints_trigger, hints_script = render_keyboard_hints_modal(
+        kb_manager,
+        child_managers=child_managers if child_managers else None,
+    )
 
     return Div(
         # Header with keyboard hints trigger

{cjm_transcript_source_select-0.0.28 → cjm_transcript_source_select-0.0.30}/cjm_transcript_source_select/models.py

@@ -12,6 +12,8 @@ from dataclasses import dataclass, field
 
 from fasthtml.common import APIRouter
 
+from cjm_fasthtml_keyboard_navigation.core.manager import ZoneManager
+
 from cjm_source_provider.models import SelectedSource
 
 # %% ../nbs/models.ipynb #selection-step-state
@@ -71,6 +73,7 @@ class LocalFilesResult:
     render_panel: Callable                # (error_message?, session_id?) -> rendered panel
     restore_state: Callable = field(default=_no_op_restore)  # (session_id) -> None, restore persisted state
     reset_state: Callable = field(default=_no_op_reset)  # () -> None, reset in-memory caches
+    kb_manager: Optional[ZoneManager] = None  # ZoneManager backing the local file browser's keyboard system — hand to render_keyboard_hints_modal(..., child_managers=[...]) for hierarchical hint display
 
 @dataclass
 class SelectionResult:
@@ -82,3 +85,4 @@ class SelectionResult:
     sb_state: Any = None                  # SourceBrowserRouterState
     restore_state: Callable = field(default=_no_op_restore)  # (session_id) -> None, restore persisted state
     reset_state: Callable = field(default=_no_op_reset)  # () -> None, reset in-memory caches
+    fb_kb_manager: Optional[ZoneManager] = None  # ZoneManager from the local file browser; convenience pointer mirroring LocalFilesResult.kb_manager so step renderers can read it directly from SelectionResult without descending into LocalFilesResult

{cjm_transcript_source_select-0.0.28 → cjm_transcript_source_select-0.0.30}/cjm_transcript_source_select/routes/init.py

@@ -42,13 +42,20 @@ def init_selection_routers(
     filtering_router, filtering_routes = init_filtering_router(
         state_store, workflow_id, source_service, f"{prefix}/filtering", urls
     )
+    # manager_label="Local Files" surfaces as the section header for the file
+    # browser's kb_manager in the Phase 1 hints modal (rendered via
+    # render_keyboard_hints_modal in step_renderer).
     local_files = init_local_files_router(
-        state_store, workflow_id, source_service, f"{prefix}/local_files", urls
+        state_store, workflow_id, source_service, f"{prefix}/local_files", urls,
+        manager_label="Local Files",
     )
+    # manager_label="Source Browser" surfaces as the section header for the
+    # source browser's VC kb_manager in the Phase 1 hints modal.
     sb_state = init_source_browser_router(
         source_service=source_service,
         urls=urls,
         prefix=f"{prefix}/browser",
+        manager_label="Source Browser",
     )
 
     # Wire the module-level refs
@@ -128,4 +135,5 @@ def init_selection_routers(
         sb_state=sb_state,
         restore_state=local_files.restore_state,
         reset_state=local_files.reset_state,
+        fb_kb_manager=local_files.kb_manager,
     )

{cjm_transcript_source_select-0.0.28 → cjm_transcript_source_select-0.0.30}/cjm_transcript_source_select/routes/local_files.py

@@ -103,6 +103,7 @@ 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
+    manager_label: Optional[str] = None,  # Human-readable label for the local file browser's ZoneManager — surfaces in the hints modal section header when LocalFilesResult.kb_manager is passed as a child_managers entry
 ) -> LocalFilesResult:  # Router result with routers, routes, render, restore, and reset
     """Initialize local files browser routes with new file browser API."""
     provider = _get_local_files_provider()
@@ -253,6 +254,7 @@ def init_local_files_router(
         route_prefix=f"{prefix}/browser",
         callbacks=fb_callbacks,
         home_path=home_path,
+        manager_label=manager_label,
     )
 
     # --- Render function for the full local files panel ---
@@ -314,4 +316,5 @@ def init_local_files_router(
         render_panel=_render_panel,
         restore_state=_restore_state,
         reset_state=_reset_state,
+        kb_manager=fb_routers.kb_manager,
     )

{cjm_transcript_source_select-0.0.28 → cjm_transcript_source_select-0.0.30}/cjm_transcript_source_select/routes/source_browser.py

@@ -20,6 +20,8 @@ from cjm_fasthtml_virtual_collection.core.windowing import find_nearest_focusabl
 from cjm_fasthtml_virtual_collection.routes.router import init_virtual_collection_router
 from cjm_fasthtml_virtual_collection.components.table import render_cell_oob
 
+from cjm_fasthtml_keyboard_navigation.core.manager import ZoneManager
+
 from ..html_ids import SelectionHtmlIds
 from ..models import SelectionUrls
 from ..services.source import SourceService
@@ -29,6 +31,7 @@ from cjm_transcript_source_select.components.source_browser import (
     SourceBrowserItem, SOURCE_BROWSER_COLUMNS,
     build_source_items, is_source_item_skippable,
     render_source_empty, _render_header_cell, _render_record_cell,
+    build_source_browser_keyboard_system,
 )
 from ..components.preview_panel import _render_preview_panel
 
@@ -50,12 +53,14 @@ class SourceBrowserRouterState:
     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
+    kb_manager: Optional[ZoneManager] = None  # ZoneManager backing the source browser's VC keyboard system — hand to render_keyboard_hints_modal(..., child_managers=[...]) for hierarchical hint display
 
 # %% ../../nbs/routes/source_browser.ipynb #sb-init-router
 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
+    manager_label: Optional[str] = None,  # Human-readable label for the source browser's ZoneManager (used as the modal section header when wired into a hierarchical hints display via SourceBrowserRouterState.kb_manager)
 ) -> SourceBrowserRouterState:  # Router state with all VC objects and helpers
     """Initialize the source browser virtual collection router."""
     # --- VC config and state (closure) ---
@@ -157,6 +162,12 @@ def init_source_browser_router(
         return None
 
     # --- Rebuild and render ---
+    # `_kb_system_ref` carries the kb_system after it's built at the bottom of
+    # this function (built once, reused across renders). rebuild_and_render
+    # threads it down to source_browser components so the same kb_system —
+    # and thus the same exposed kb_manager — is reused on every render.
+    _kb_system_ref: list = [None]
+
     def rebuild_and_render(
         transcriptions: List[Dict[str, Any]],  # Transcription records
         selected_sources: List[Dict[str, str]],  # Current selections
@@ -167,13 +178,17 @@ def init_source_browser_router(
         rebuild_items(transcriptions, selected_sources, grouping_mode)
         if content_only:
             from cjm_transcript_source_select.components.source_browser import _render_source_browser_vc_content
-            return _render_source_browser_vc_content(sb_state=_sb_state_ref[0])
+            return _render_source_browser_vc_content(
+                sb_state=_sb_state_ref[0],
+                keyboard_system=_kb_system_ref[0],
+            )
         from cjm_transcript_source_select.components.source_browser import _render_source_browser_vc
         return _render_source_browser_vc(
             sb_state=_sb_state_ref[0],
             filter_url=urls.filter,
             grouping_mode=grouping_mode,
             grouping_change_url=urls.grouping_change,
+            keyboard_system=_kb_system_ref[0],
         )
 
     # --- VC callbacks ---
@@ -228,4 +243,16 @@ def init_source_browser_router(
         get_vc_row_id_for=get_vc_row_id_for,
     )
     _sb_state_ref[0] = result
+
+    # --- Build the kb_system once now that sb_state is wired up ---
+    # The kb_system's DOM elements (script, hidden_inputs, action_buttons) are
+    # static across renders; only the item list rebuilds. Building once at init
+    # ensures kb_manager is identity-stable across renders and gives single
+    # source of truth for the manager exposed on SourceBrowserRouterState.
+    kb_system = build_source_browser_keyboard_system(
+        sb_state=result,
+        manager_label=manager_label,
+    )
+    _kb_system_ref[0] = kb_system
+    result.kb_manager = kb_system.manager
     return result

{cjm_transcript_source_select-0.0.28 → cjm_transcript_source_select-0.0.30/cjm_transcript_source_select.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cjm-transcript-source-select
-Version: 0.0.28
+Version: 0.0.30
 Summary: FastHTML source selection component for transcript decomposition workflows, with federated database browsing, drag-drop ordering, and keyboard navigation.
 Author-email: "Christian J. Mills" <9126128+cj-mills@users.noreply.github.com>
 License: Apache-2.0
@@ -15,13 +15,14 @@ Classifier: Programming Language :: Python :: 3 :: Only
 Requires-Python: >=3.12
 Description-Content-Type: text/markdown
 License-File: LICENSE
+Requires-Dist: python-fasthtml==0.13.4
 Requires-Dist: cjm-plugin-system
 Requires-Dist: cjm-transcription-plugin-system
 Requires-Dist: cjm-fasthtml-app-core
 Requires-Dist: cjm-fasthtml-daisyui
 Requires-Dist: cjm_fasthtml_lucide_icons
-Requires-Dist: cjm_fasthtml_file_browser>=0.0.17
-Requires-Dist: cjm_fasthtml_keyboard_navigation>=0.0.20
+Requires-Dist: cjm_fasthtml_file_browser>=0.0.19
+Requires-Dist: cjm_fasthtml_keyboard_navigation>=0.0.23
 Requires-Dist: duckdb
 Requires-Dist: pandas
 Requires-Dist: cjm_workflow_state
@@ -29,7 +30,7 @@ Requires-Dist: cjm_source_provider
 Requires-Dist: cjm_fasthtml_interactions
 Requires-Dist: cjm_fasthtml_viewport_fit
 Requires-Dist: cjm_fasthtml_virtual_collection
-Requires-Dist: cjm_fasthtml_sortable_queue>=0.0.13
+Requires-Dist: cjm_fasthtml_sortable_queue>=0.0.16
 Requires-Dist: cjm_fasthtml_design_system>=0.0.9
 Dynamic: license-file
 
@@ -95,57 +96,57 @@ graph LR
     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_source_browser --> services_source_utils
     components_source_browser --> html_ids
     components_source_browser --> utils
-    components_step_renderer --> components_preview_panel
-    components_step_renderer --> utils
     components_step_renderer --> components_selection_queue
-    components_step_renderer --> components_source_browser
-    components_step_renderer --> models
     components_step_renderer --> html_ids
+    components_step_renderer --> models
     components_step_renderer --> components_local_files
-    routes_core --> components_step_renderer
+    components_step_renderer --> components_source_browser
+    components_step_renderer --> components_preview_panel
+    components_step_renderer --> utils
     routes_core --> models
-    routes_core --> components_selection_queue
-    routes_core --> services_source
     routes_core --> html_ids
-    routes_filtering --> routes_core
+    routes_core --> components_step_renderer
+    routes_core --> services_source
+    routes_core --> components_selection_queue
     routes_filtering --> services_source_utils
     routes_filtering --> services_source
+    routes_filtering --> routes_core
     routes_filtering --> models
-    routes_init --> routes_local_files
-    routes_init --> routes_source_browser
     routes_init --> routes_core
+    routes_init --> services_source
+    routes_init --> routes_local_files
     routes_init --> routes_queue
     routes_init --> routes_tabs
-    routes_init --> services_source
-    routes_init --> routes_filtering
     routes_init --> models
-    routes_local_files --> routes_core
+    routes_init --> routes_filtering
+    routes_init --> routes_source_browser
     routes_local_files --> components_local_files
     routes_local_files --> services_source
+    routes_local_files --> routes_core
     routes_local_files --> models
-    routes_queue --> components_preview_panel
-    routes_queue --> routes_core
-    routes_queue --> services_source_utils
     routes_queue --> services_source
+    routes_queue --> services_source_utils
+    routes_queue --> routes_core
     routes_queue --> models
-    routes_source_browser --> components_preview_panel
-    routes_source_browser --> components_source_browser
+    routes_queue --> components_preview_panel
     routes_source_browser --> services_source
-    routes_source_browser --> routes_core
+    routes_source_browser --> components_source_browser
+    routes_source_browser --> html_ids
     routes_source_browser --> models
     routes_source_browser --> services_source_utils
-    routes_source_browser --> html_ids
-    routes_tabs --> services_source
+    routes_source_browser --> routes_core
+    routes_source_browser --> components_preview_panel
+    routes_tabs --> models
     routes_tabs --> routes_core
-    routes_tabs --> components_step_renderer
+    routes_tabs --> services_source
     routes_tabs --> services_source_utils
-    routes_tabs --> models
+    routes_tabs --> components_step_renderer
 ```
 
 *52 cross-module dependencies detected*
@@ -524,12 +525,6 @@ def _handle_remove_external_source(
 
 ``` python
 def init_local_files_router(
-    state_store: WorkflowStateStore,  # The workflow state store
-    workflow_id: str,  # The workflow identifier
-    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
-) -> LocalFilesResult:  # Router result with routers, routes, render, restore, and reset
     "Initialize local files browser routes with new file browser API."
 ```
 
@@ -614,6 +609,7 @@ class LocalFilesResult:
     render_panel: Callable  # (error_message?, session_id?) -> rendered panel
     restore_state: Callable = field(...)  # (session_id) -> None, restore persisted state
     reset_state: Callable = field(...)  # () -> None, reset in-memory caches
+    kb_manager: Optional[ZoneManager]  # ZoneManager backing the local file browser's keyboard system — hand to render_keyboard_hints_modal(..., child_managers=[...]) for hierarchical hint display
 ```
 
 ``` python
@@ -628,6 +624,7 @@ class SelectionResult:
     sb_state: Any  # SourceBrowserRouterState
     restore_state: Callable = field(...)  # (session_id) -> None, restore persisted state
     reset_state: Callable = field(...)  # () -> None, reset in-memory caches
+    fb_kb_manager: Optional[ZoneManager]  # ZoneManager from the local file browser; convenience pointer mirroring LocalFilesResult.kb_manager so step renderers can read it directly from SelectionResult without descending into LocalFilesResult
 ```
 
 ### preview_panel (`preview_panel.ipynb`)
@@ -1066,7 +1063,8 @@ from cjm_transcript_source_select.components.source_browser import (
     build_source_items,
     is_source_item_skippable,
     create_source_cell_renderer,
-    render_source_empty
+    render_source_empty,
+    build_source_browser_keyboard_system
 )
 ```
 
@@ -1127,19 +1125,45 @@ def render_source_empty() -> Any:  # Empty state component
     "Render empty state when no transcription sources are available."
 ```
 
+``` python
+def build_source_browser_keyboard_system(
+    sb_state: Any,                              # SourceBrowserRouterState (carries vc_ids, vc_btn_ids, vc_urls)
+    manager_label: Optional[str] = None,        # Human-readable label for the ZoneManager (consumed by render_keyboard_hints_modal section header when this is a child_managers entry)
+) -> KeyboardSystem:                            # Complete rendered KeyboardSystem (carries .manager for hierarchical hints handoff)
+    """
+    Build the source browser's KeyboardSystem standalone.
+    
+    Lifts the manager construction out of `_render_source_browser_vc_content`
+    so the underlying `ZoneManager` is accessible via `KeyboardSystem.manager`
+    for hierarchical hints handoff. Consumers wiring this as a child of the
+    parent selection-step manager pass the manager to
+    `render_keyboard_hints_modal(..., child_managers=[...])` so the modal's
+    section header reads as `manager_label` instead of the technical SB_SYSTEM_ID.
+    """
+```
+
 ``` python
 def _render_source_browser_vc_content(
-    sb_state: Any,  # SourceBrowserRouterState from routes.source_browser
+    sb_state: Any,                                       # SourceBrowserRouterState from routes.source_browser
+    keyboard_system: Optional[KeyboardSystem] = None,    # Pre-built keyboard system (when None, builds internally via build_source_browser_keyboard_system)
 ) -> Any:  # VC content wrapper (without search/grouping header)
-    "Render the VC content portion of the source browser."
+    """
+    Render the VC content portion of the source browser.
+    
+    When `keyboard_system` is provided, the caller has built the system upstream
+    (typically `init_source_browser_router`) and owns the underlying ZoneManager.
+    When None, builds the system internally — preserves pre-C1 behavior for any
+    caller that doesn't need the manager handoff.
+    """
 ```
 
 ``` 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
+    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
+    keyboard_system: Optional[KeyboardSystem] = None,    # Pre-built keyboard system, threaded through to VC content
 ) -> Any:  # Source browser component with virtual collection
     "Render the full source browser panel (header + VC content)."
 ```
@@ -1186,10 +1210,6 @@ from cjm_transcript_source_select.routes.source_browser import (
 
 ``` 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."
 ```
 
@@ -1214,6 +1234,7 @@ class SourceBrowserRouterState:
     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
+    kb_manager: Optional[ZoneManager]  # ZoneManager backing the source browser's VC keyboard system — hand to render_keyboard_hints_modal(..., child_managers=[...]) for hierarchical hint display
 ```
 
 ### source_utils (`source_utils.ipynb`)
@@ -1380,7 +1401,22 @@ from cjm_transcript_source_select.components.step_renderer import (
 
 ``` python
 def _create_parent_keyboard_manager() -> ZoneManager:  # Parent keyboard manager for hierarchy
-    "Create the parent keyboard manager with two ghost zones for column switching."
+    """
+    Create the parent keyboard manager with two ghost zones for column switching.
+    
+    Each ghost zone declares `activate_child_callback` so the library-baked
+    Enter/Space dispatch (`ZoneManager.activate_keys` defaults to `("Enter", " ")`)
+    invokes the consumer-defined JS function — `window.activateBrowserChild`
+    and `window.activateQueueChild` are wired in `_generate_hierarchy_js`. The
+    callback path is used (vs. the declarative `activate_child_id` path) because
+    the browser ghost zone's active child depends on the currently-selected
+    tab (`db` → source-browser child; `files` → file-browser child); this
+    dynamic resolution can't be a static declarative mapping.
+    
+    Each ghost zone's `label` surfaces as the section header for that zone's
+    derived rows in the hints modal (e.g., the parent's "Source Browser" /
+    "Selection Queue" — Activate row appears under those labels).
+    """
 ```
 
 ``` python
@@ -1427,15 +1463,6 @@ def _generate_hierarchy_js(
 
 ``` python
 def render_selection_step(
-    sources: List[Dict[str, Any]],  # Available source plugins
-    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"
-    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."
 ```
 

{cjm_transcript_source_select-0.0.28 → cjm_transcript_source_select-0.0.30}/cjm_transcript_source_select.egg-info/requires.txt

@@ -1,10 +1,11 @@
+python-fasthtml==0.13.4
 cjm-plugin-system
 cjm-transcription-plugin-system
 cjm-fasthtml-app-core
 cjm-fasthtml-daisyui
 cjm_fasthtml_lucide_icons
-cjm_fasthtml_file_browser>=0.0.17
-cjm_fasthtml_keyboard_navigation>=0.0.20
+cjm_fasthtml_file_browser>=0.0.19
+cjm_fasthtml_keyboard_navigation>=0.0.23
 duckdb
 pandas
 cjm_workflow_state
@@ -12,5 +13,5 @@ cjm_source_provider
 cjm_fasthtml_interactions
 cjm_fasthtml_viewport_fit
 cjm_fasthtml_virtual_collection
-cjm_fasthtml_sortable_queue>=0.0.13
+cjm_fasthtml_sortable_queue>=0.0.16
 cjm_fasthtml_design_system>=0.0.9

{cjm_transcript_source_select-0.0.28 → cjm_transcript_source_select-0.0.30}/pyproject.toml

@@ -12,7 +12,7 @@ license = {text = "Apache-2.0"}
 authors = [{name = "Christian J. Mills", email = "9126128+cj-mills@users.noreply.github.com"}]
 keywords = ['nbdev', 'jupyter', 'notebook', 'python']
 classifiers = ["Natural Language :: English", "Intended Audience :: Developers", "Development Status :: 3 - Alpha", "Programming Language :: Python :: 3", "Programming Language :: Python :: 3 :: Only"]
-dependencies = ['cjm-plugin-system', 'cjm-transcription-plugin-system', 'cjm-fasthtml-app-core', 'cjm-fasthtml-daisyui', 'cjm_fasthtml_lucide_icons', 'cjm_fasthtml_file_browser>=0.0.17', 'cjm_fasthtml_keyboard_navigation>=0.0.20', 'duckdb', 'pandas', 'cjm_workflow_state', 'cjm_source_provider', 'cjm_fasthtml_interactions', 'cjm_fasthtml_viewport_fit', 'cjm_fasthtml_virtual_collection', 'cjm_fasthtml_sortable_queue>=0.0.13', 'cjm_fasthtml_design_system>=0.0.9']
+dependencies = ['python-fasthtml==0.13.4', 'cjm-plugin-system', 'cjm-transcription-plugin-system', 'cjm-fasthtml-app-core', 'cjm-fasthtml-daisyui', 'cjm_fasthtml_lucide_icons', 'cjm_fasthtml_file_browser>=0.0.19', 'cjm_fasthtml_keyboard_navigation>=0.0.23', 'duckdb', 'pandas', 'cjm_workflow_state', 'cjm_source_provider', 'cjm_fasthtml_interactions', 'cjm_fasthtml_viewport_fit', 'cjm_fasthtml_virtual_collection', 'cjm_fasthtml_sortable_queue>=0.0.16', 'cjm_fasthtml_design_system>=0.0.9']
 
 [project.urls]
 Repository = "https://github.com/cj-mills/cjm-transcript-source-select"

cjm_transcript_source_select-0.0.28/cjm_transcript_source_select/__init__.py

@@ -1 +0,0 @@
-__version__ = "0.0.28"