From 9ee253e75a87b511747aaaa3d8c943ebaab9fe19 Mon Sep 17 00:00:00 2001
From: Paul Elliott <paul@vizworkshop.com>
Date: Thu, 16 Jul 2026 17:12:54 -0400
Subject: [PATCH 1/6] Support declared frame metadata items by marker

Add a frameMetadata item marker as the arbitrary-name counterpart of the
reserved sidecar basenames. Discovery lists marked items alongside
name-declared ones, and postprocess accepts frameMetadataNames to mark
uploaded files by direct name lookup (the sweep regexes never list a
declared .txt). Marked items short-circuit the annotation classifier so
an interrupted marking pass can never parse or remove a sidecar.
---
 server/dive_server/crud_dataset.py          |   7 +-
 server/dive_server/crud_rpc.py              |  98 +++++++++--
 server/dive_server/views_rpc.py             |  21 ++-
 server/dive_utils/constants.py              |   4 +
 server/tests/test_frame_metadata_sources.py |  34 ++++
 server/tests/test_process_items.py          | 179 ++++++++++++++++++++
 6 files changed, 321 insertions(+), 22 deletions(-)

diff --git a/server/dive_server/crud_dataset.py b/server/dive_server/crud_dataset.py
index 4522e90af..7faddca56 100644
--- a/server/dive_server/crud_dataset.py
+++ b/server/dive_server/crud_dataset.py
@@ -420,13 +420,16 @@ def _frame_metadata_source_items(
 ) -> List[Dict[str, str]]:
     """List a folder's declared sidecar items as {itemId, name}, name-sorted (no download).
 
-    Only identity is resolved here: the server classifies sidecars by name and never reads,
-    parses, or joins them. The client downloads and parses the bytes at read time.
+    A sidecar is declared either by the reserved basename or by the explicit-import item
+    marker. Only identity is resolved here: the server classifies sidecars by declaration
+    and never reads, parses, or joins them. The client downloads and parses the bytes at
+    read time.
     """
     items = [
         item
         for item in Folder().childItems(folder)
         if frame_metadata.is_frame_metadata_source_name(item['name'])
+        or asbool(fromMeta(item, constants.FrameMetadataMarker))
     ]
     return [
         {'itemId': str(item['_id']), 'name': item['name']}
diff --git a/server/dive_server/crud_rpc.py b/server/dive_server/crud_rpc.py
index a80aea7d1..50e0d1d4e 100644
--- a/server/dive_server/crud_rpc.py
+++ b/server/dive_server/crud_rpc.py
@@ -652,16 +652,59 @@ def resolve_imported_dataset_info(existing: types.DatasetInfo, meta: dict, addit
     return {**meta, 'datasetInfo': resolved}
 
 
+def _declare_frame_metadata_items(
+    folder: types.GirderModel,
+    frameMetadataNames: List[str],
+) -> List[str]:
+    """Mark the named dataset-folder items as declared frame-metadata sidecars.
+
+    This is the arbitrary-name counterpart of the reserved-basename convention: the client
+    states the user's intent by name, and each matching item is marked with the frame
+    metadata marker and left in place, processed, so the annotation sweep never parses it.
+    Names are looked up directly rather than through the sweep regexes because a declared
+    ``.txt`` sidecar is never swept. Failures are loud: a declaration that cannot be
+    honored must not fall through to annotation classification.
+    """
+    dataset_type = fromMeta(folder, constants.TypeMarker)
+    if dataset_type not in (constants.ImageSequenceType, constants.MultiType):
+        raise RestException('Frame metadata is only supported for image-sequence datasets')
+    warnings: List[str] = []
+    for name in dict.fromkeys(frameMetadataNames):
+        if not name.lower().endswith(('.csv', '.txt')):
+            raise RestException(
+                f'{name} is not a supported frame metadata file type (.csv or .txt)'
+            )
+        items = list(Folder().childItems(folder, filters={'name': name}))
+        if not items:
+            raise RestException(f'{name} was not found in the dataset folder')
+        for item in items:
+            Item().setMetadata(
+                item,
+                {constants.FrameMetadataMarker: True, constants.ProcessedMarker: True},
+            )
+        warnings.append(
+            f'{name} was stored as frame metadata, not annotations; '
+            'it stays in the dataset folder.'
+        )
+    return warnings
+
+
 def process_items(
     folder: types.GirderModel,
     user: types.GirderUserModel,
     additive=False,
     additivePrepend='',
     set='',
+    frameMetadataNames: Optional[List[str]] = None,
 ):
     """
     Discover unprocessed items in a dataset and process them by type in order of creation
     """
+    # Declared-by-name sidecars are marked before the sweep so they drop out of
+    # unprocessed_items via the ProcessedMarker filter below.
+    aggregate_warnings = (
+        _declare_frame_metadata_items(folder, frameMetadataNames) if frameMetadataNames else []
+    )
     unprocessed_items = list(
         Folder().childItems(
             folder,
@@ -693,6 +736,7 @@ def process_items(
         for item in unprocessed_items
         if constants.csvRegex.search(item['name'])
         and not frame_metadata.is_frame_metadata_source_name(item['name'])
+        and not asbool(fromMeta(item, constants.FrameMetadataMarker))
     )
     if len(annotation_csv_names) >= 2:
         raise RestException(
@@ -705,32 +749,47 @@ def process_items(
     # a declared sidecar is classified by name and never joined here.
     image_map = None
     if fromMeta(folder, constants.TypeMarker) == constants.ImageSequenceType and any(
-        not frame_metadata.is_frame_metadata_source_name(item['name']) for item in unprocessed_items
+        not frame_metadata.is_frame_metadata_source_name(item['name'])
+        and not asbool(fromMeta(item, constants.FrameMetadataMarker))
+        for item in unprocessed_items
     ):
         image_map = crud.valid_image_names_dict(crud.valid_images(folder, user))
 
     auxiliary = None
-    aggregate_warnings = []
     for item in unprocessed_items:
         file: Optional[types.GirderModel] = next(Item().childFiles(item), None)
         if file is None:
             raise RestException('Item had no associated files')
 
-        try:
-            results, warnings = _get_data_by_type(file, image_map=image_map)
-            if warnings:
-                aggregate_warnings += warnings
-        except Exception as e:
-            Item().remove(item)
-            if isinstance(e, ValueError):
-                hint = (
-                    ' If this file is frame metadata rather than annotations, rename it to '
-                    'frame-metadata.csv and re-upload.'
-                    if constants.csvRegex.search(file['name'])
-                    else ''
-                )
-                raise RestException(f'Failed to import {file["name"]}: {e}{hint}') from e
-            raise RestException(f'{file["name"]} was not a supported file type: {e}') from e
+        # A marker-declared sidecar must never reach the annotation classifier, even if a
+        # prior marking pass was interrupted before ProcessedMarker was saved.
+        results: Optional[GetDataReturnType]
+        warnings: Optional[List[str]]
+        if asbool(fromMeta(item, constants.FrameMetadataMarker)):
+            results = {
+                'annotations': None,
+                'meta': None,
+                'attributes': None,
+                'type': crud.FileType.FRAME_METADATA,
+            }
+            warnings = None
+        else:
+            try:
+                results, warnings = _get_data_by_type(file, image_map=image_map)
+                if warnings:
+                    aggregate_warnings += warnings
+            except Exception as e:
+                Item().remove(item)
+                if isinstance(e, ValueError):
+                    hint = (
+                        ' If this file is frame metadata rather than annotations, import it '
+                        "with the Import button's Frame Metadata option, or rename it to "
+                        'frame-metadata.csv and re-upload.'
+                        if constants.csvRegex.search(file['name'])
+                        else ''
+                    )
+                    raise RestException(f'Failed to import {file["name"]}: {e}{hint}') from e
+                raise RestException(f'{file["name"]} was not a supported file type: {e}') from e
 
         if results is None:
             Item().remove(item)
@@ -786,6 +845,7 @@ def postprocess(
     additive=False,
     additivePrepend='',
     set='',
+    frameMetadataNames: Optional[List[str]] = None,
 ) -> dict:
     """
     Post-processing to be run after media/annotation import
@@ -921,7 +981,9 @@ def postprocess(
 
         Folder().save(dsFolder)
 
-    aggregate_warnings = process_items(dsFolder, user, additive, additivePrepend, set)
+    aggregate_warnings = process_items(
+        dsFolder, user, additive, additivePrepend, set, frameMetadataNames
+    )
     return {'folder': dsFolder, 'warnings': aggregate_warnings, 'job_ids': created_job_ids}
 
 
diff --git a/server/dive_server/views_rpc.py b/server/dive_server/views_rpc.py
index 911d10419..cb35107e6 100644
--- a/server/dive_server/views_rpc.py
+++ b/server/dive_server/views_rpc.py
@@ -207,10 +207,27 @@ def run_training(self, body, pipelineName, config, annotatedFramesOnly, forceTra
             default='',
             required=False,
         )
+        .jsonParam(
+            "frameMetadataNames",
+            "JSON list of uploaded filenames to store as declared frame metadata sidecars",
+            paramType="formData",
+            requireArray=True,
+            default=None,
+            required=False,
+        )
     )
-    def postprocess(self, folder, skipJobs, skipTranscoding, additive, additivePrepend, set):
+    def postprocess(
+        self, folder, skipJobs, skipTranscoding, additive, additivePrepend, set, frameMetadataNames
+    ):
         return crud_rpc.postprocess(
-            self.getCurrentUser(), folder, skipJobs, skipTranscoding, additive, additivePrepend, set
+            self.getCurrentUser(),
+            folder,
+            skipJobs,
+            skipTranscoding,
+            additive,
+            additivePrepend,
+            set,
+            frameMetadataNames,
         )
 
     @access.user
diff --git a/server/dive_utils/constants.py b/server/dive_utils/constants.py
index cb782614b..cee50c0ff 100644
--- a/server/dive_utils/constants.py
+++ b/server/dive_utils/constants.py
@@ -117,6 +117,10 @@
 JsonCalibrationItemIdMarker = "jsonCalibrationItemId"
 CalibrationOriginalNameMarker = "calibrationOriginalName"
 CalibrationConversionErrorMarker = "calibrationConversionError"
+# Girder item meta: declared frame-metadata sidecar. Set by the explicit import
+# affordances so arbitrary-named sidecars are equivalent to the reserved
+# frame-metadata.csv naming convention for discovery and import classification.
+FrameMetadataMarker = "frameMetadata"
 # Girder item meta: original stereoscopic calibration upload (npz, yml, etc.)
 CalibrationFileMarker = "calibrationFile"
 # Girder item meta: JSON camera-rig used for calibration display
diff --git a/server/tests/test_frame_metadata_sources.py b/server/tests/test_frame_metadata_sources.py
index d20a20e48..efbbddbde 100644
--- a/server/tests/test_frame_metadata_sources.py
+++ b/server/tests/test_frame_metadata_sources.py
@@ -164,6 +164,40 @@ def test_sources_single_camera_no_sidecars_returns_empty(get_clone_root, folder_
     assert result == {'cameras': {}}
 
 
+@patch('dive_server.crud_dataset.Folder')
+@patch('dive_server.crud_dataset.crud.getCloneRoot')
+def test_sources_include_marker_declared_items(get_clone_root, folder_cls):
+    dataset = _dataset_folder()
+    user = {'_id': 'user-id'}
+    get_clone_root.return_value = dataset
+    # An arbitrary-named sidecar declared by explicit import carries the item marker; an
+    # undeclared arbitrary-named CSV is still invisible to discovery.
+    marked = {
+        '_id': 'nav_2024.csv-id',
+        'name': 'nav_2024.csv',
+        'meta': {constants.FrameMetadataMarker: True, constants.ProcessedMarker: True},
+    }
+    unmarked = {'_id': 'notes.csv-id', 'name': 'notes.csv', 'meta': {}}
+    folder_cls.return_value.childItems.return_value = [
+        _source_item('image_0001.jpg'),
+        unmarked,
+        marked,
+        _source_item('frame-metadata.csv'),
+    ]
+
+    result = crud_dataset.load_frame_metadata_sources(dataset, user)
+
+    # Marker- and name-declared sidecars list together, name-sorted.
+    assert result == {
+        'cameras': {
+            'singleCam': [
+                _descriptor('frame-metadata.csv'),
+                _descriptor('nav_2024.csv'),
+            ],
+        },
+    }
+
+
 @pytest.mark.parametrize('dataset_type', [constants.VideoType, constants.LargeImageType])
 @patch('dive_server.crud_dataset.Folder')
 @patch('dive_server.crud_dataset.crud.getCloneRoot')
diff --git a/server/tests/test_process_items.py b/server/tests/test_process_items.py
index 53da7913f..033693aa3 100644
--- a/server/tests/test_process_items.py
+++ b/server/tests/test_process_items.py
@@ -167,6 +167,185 @@ def test_two_plain_csvs_in_folder_side_door_guard(
     get_auxiliary_folder.assert_not_called()
 
 
+def _wire_declared_lookup(folder_cls, item_cls, all_items):
+    """Emulate the two childItems query shapes plus a mutating setMetadata.
+
+    The declaration pass looks items up by exact name; the sweep uses the $and regex/marker
+    filter, emulated here as "unswept csv/json/yml items not yet marked processed".
+    """
+
+    def child_items(_folder, filters=None, sort=None):
+        if filters and 'name' in filters:
+            return [item for item in all_items if item['name'] == filters['name']]
+        return [
+            item
+            for item in all_items
+            if item['name'].lower().rsplit('.', 1)[-1] in ('csv', 'json', 'yml', 'yaml')
+            and item['meta'].get(constants.ProcessedMarker) is not True
+        ]
+
+    def set_metadata(item, metadata):
+        item['meta'].update(metadata)
+        return item
+
+    folder_cls.return_value.childItems.side_effect = child_items
+    item_cls.return_value.setMetadata.side_effect = set_metadata
+
+
+@patch('dive_server.crud_rpc.crud_annotation.save_annotations')
+@patch('dive_server.crud_rpc.crud.get_or_create_auxiliary_folder')
+@patch('dive_server.crud_rpc.File')
+@patch('dive_server.crud_rpc.Item')
+@patch('dive_server.crud_rpc.Folder')
+def test_declared_frame_metadata_names_are_marked_and_kept(
+    folder_cls, item_cls, file_cls, get_auxiliary_folder, save_annotations
+):
+    # Arbitrary-named sidecars declared through frameMetadataNames are marked and left in
+    # place — including .txt, which the sweep regexes never even list.
+    folder = {'_id': 'ds', 'meta': {'type': constants.ImageSequenceType, 'fps': 5}}
+    item_csv = {'_id': 'a', 'name': 'nav_2024.csv', 'meta': {}}
+    item_txt = {'_id': 'b', 'name': 'nav_2024.txt', 'meta': {}}
+    _wire_declared_lookup(folder_cls, item_cls, [item_csv, item_txt])
+
+    warnings = process_items(
+        folder, {'_id': 'user-id'}, frameMetadataNames=['nav_2024.csv', 'nav_2024.txt']
+    )
+
+    assert len(warnings) == 2
+    assert all('stays in the dataset folder' in warning for warning in warnings)
+    for item in (item_csv, item_txt):
+        assert item['meta'][constants.FrameMetadataMarker] is True
+        assert item['meta'][constants.ProcessedMarker] is True
+    item_cls.return_value.move.assert_not_called()
+    item_cls.return_value.remove.assert_not_called()
+    save_annotations.assert_not_called()
+    file_cls.return_value.download.assert_not_called()
+
+
+@patch('dive_server.crud_rpc.Item')
+@patch('dive_server.crud_rpc.Folder')
+def test_declared_name_missing_from_folder_raises(folder_cls, item_cls):
+    folder = {'_id': 'ds', 'meta': {'type': constants.ImageSequenceType, 'fps': 5}}
+    _wire_declared_lookup(folder_cls, item_cls, [])
+
+    with pytest.raises(RestException, match='was not found in the dataset folder'):
+        process_items(folder, {'_id': 'user-id'}, frameMetadataNames=['nav_2024.csv'])
+    item_cls.return_value.setMetadata.assert_not_called()
+
+
+@patch('dive_server.crud_rpc.Item')
+@patch('dive_server.crud_rpc.Folder')
+def test_declared_name_unsupported_extension_raises(folder_cls, item_cls):
+    folder = {'_id': 'ds', 'meta': {'type': constants.ImageSequenceType, 'fps': 5}}
+    item = {'_id': 'a', 'name': 'nav.json', 'meta': {}}
+    _wire_declared_lookup(folder_cls, item_cls, [item])
+
+    with pytest.raises(RestException, match='not a supported frame metadata file type'):
+        process_items(folder, {'_id': 'user-id'}, frameMetadataNames=['nav.json'])
+    item_cls.return_value.setMetadata.assert_not_called()
+
+
+@pytest.mark.parametrize('dataset_type', [constants.VideoType, constants.LargeImageType])
+@patch('dive_server.crud_rpc.Item')
+@patch('dive_server.crud_rpc.Folder')
+def test_declared_names_rejected_for_unsupported_media_type(folder_cls, item_cls, dataset_type):
+    folder = {'_id': 'ds', 'meta': {'type': dataset_type, 'fps': 5}}
+    item = {'_id': 'a', 'name': 'nav_2024.csv', 'meta': {}}
+    _wire_declared_lookup(folder_cls, item_cls, [item])
+
+    with pytest.raises(RestException, match='only supported for image-sequence'):
+        process_items(folder, {'_id': 'user-id'}, frameMetadataNames=['nav_2024.csv'])
+    item_cls.return_value.setMetadata.assert_not_called()
+
+
+@patch('dive_server.crud_rpc.Item')
+@patch('dive_server.crud_rpc.Folder')
+def test_declared_names_allowed_for_multicam_parent(folder_cls, item_cls):
+    # A declaration on the multicam parent folder is the shared-sidecar path.
+    folder = {'_id': 'parent', 'meta': {'type': constants.MultiType, 'fps': 5}}
+    item = {'_id': 'a', 'name': 'nav_2024.csv', 'meta': {}}
+    _wire_declared_lookup(folder_cls, item_cls, [item])
+
+    warnings = process_items(folder, {'_id': 'user-id'}, frameMetadataNames=['nav_2024.csv'])
+
+    assert len(warnings) == 1
+    assert item['meta'][constants.FrameMetadataMarker] is True
+    assert item['meta'][constants.ProcessedMarker] is True
+
+
+@patch('dive_server.crud_rpc.crud_annotation.save_annotations')
+@patch('dive_server.crud_rpc.crud.get_or_create_auxiliary_folder')
+@patch('dive_server.crud_rpc.File')
+@patch('dive_server.crud_rpc.Item')
+@patch('dive_server.crud_rpc.Folder')
+def test_marker_declared_item_short_circuits_sweep(
+    folder_cls, item_cls, file_cls, get_auxiliary_folder, save_annotations
+):
+    # A marked-but-unprocessed item (e.g. a marking pass interrupted before ProcessedMarker
+    # saved) must take the keep-in-place branch, never the annotation classifier.
+    folder = {'_id': 'ds', 'meta': {'type': constants.ImageSequenceType, 'fps': 5}}
+    item = {
+        '_id': 'item-id',
+        'name': 'nav_2024.csv',
+        'meta': {constants.FrameMetadataMarker: True},
+    }
+    file = {'_id': 'file-id', 'name': 'nav_2024.csv', 'exts': ['csv']}
+
+    folder_cls.return_value.childItems.return_value = [item]
+    item_cls.return_value.childFiles.side_effect = _childfiles_side_effect({'item-id': file})
+
+    warnings = process_items(folder, {'_id': 'user-id'})
+
+    assert len(warnings) == 1
+    assert 'stays in the dataset folder' in warnings[0]
+    assert item['meta'][constants.ProcessedMarker] is True
+    item_cls.return_value.save.assert_called_once_with(item)
+    item_cls.return_value.move.assert_not_called()
+    item_cls.return_value.remove.assert_not_called()
+    file_cls.return_value.download.assert_not_called()
+    save_annotations.assert_not_called()
+
+
+@patch('dive_server.crud_rpc.crud_annotation.save_annotations')
+@patch('dive_server.crud_rpc.crud.valid_images')
+@patch('dive_server.crud_rpc.crud.get_or_create_auxiliary_folder')
+@patch('dive_server.crud_rpc.File')
+@patch('dive_server.crud_rpc.Item')
+@patch('dive_server.crud_rpc.Folder')
+def test_marked_csv_does_not_trip_two_csv_guard(
+    folder_cls, item_cls, file_cls, get_auxiliary_folder, valid_images, save_annotations
+):
+    # A marker-declared sidecar CSV alongside one plain annotation CSV is not "two
+    # annotation CSVs": the annotation imports and the sidecar stays put.
+    folder = {'_id': 'ds', 'meta': {'type': constants.ImageSequenceType, 'fps': 5}}
+    marked = {
+        '_id': 'nav',
+        'name': 'nav_2024.csv',
+        'meta': {constants.FrameMetadataMarker: True},
+    }
+    plain = {'_id': 'ann', 'name': 'annotations.csv', 'meta': {}}
+    file_marked = {'_id': 'f-nav', 'name': 'nav_2024.csv', 'exts': ['csv']}
+    file_plain = {'_id': 'f-ann', 'name': 'annotations.csv', 'exts': ['csv']}
+
+    folder_cls.return_value.childItems.return_value = [marked, plain]
+    item_cls.return_value.childFiles.side_effect = _childfiles_side_effect(
+        {'nav': file_marked, 'ann': file_plain}
+    )
+    file_cls.return_value.download.side_effect = _download_side_effect(
+        {'f-ann': _viame_csv().encode()}
+    )
+    get_auxiliary_folder.return_value = {'_id': 'aux-id'}
+    valid_images.return_value = [{'name': 'image_0001.jpg'}]
+
+    warnings = process_items(folder, {'_id': 'user-id'})
+
+    assert len(warnings) == 1
+    assert 'nav_2024.csv' in warnings[0]
+    item_cls.return_value.move.assert_called_once_with(plain, {'_id': 'aux-id'})
+    save_annotations.assert_called_once()
+    assert marked['meta'][constants.ProcessedMarker] is True
+
+
 @patch('dive_server.crud_rpc.crud_annotation.save_annotations')
 @patch('dive_server.crud_rpc.crud.valid_images')
 @patch('dive_server.crud_rpc.crud.get_or_create_auxiliary_folder')

From 6689521d35b8e7fbf2e1f02ca8b41e1ce6ef6563 Mon Sep 17 00:00:00 2001
From: Paul Elliott <paul@vizworkshop.com>
Date: Thu, 16 Jul 2026 17:13:03 -0400
Subject: [PATCH 2/6] Add frame metadata section to the viewer Import menu

The Import card gains a Frame Metadata section, present when the
platform provides importFrameMetadataFile. The picked file may have any
name; the pick itself declares its role. A module-level invalidation
signal lets the import refresh live Frame Info panels through the
session cache.
---
 client/dive-common/apispec.ts                 |  7 +-
 .../components/ImportAnnotations.vue          | 70 +++++++++++++++++++
 client/dive-common/constants.ts               |  7 ++
 .../dive-common/use/useFrameMetadata.spec.ts  | 41 ++++++++++-
 client/dive-common/use/useFrameMetadata.ts    | 20 ++++++
 5 files changed, 143 insertions(+), 2 deletions(-)

diff --git a/client/dive-common/apispec.ts b/client/dive-common/apispec.ts
index 2de12986b..45c0b5a98 100644
--- a/client/dive-common/apispec.ts
+++ b/client/dive-common/apispec.ts
@@ -323,7 +323,7 @@ interface Api {
   saveAttributeTrackFilters(datasetId: string,
     args: SaveAttributeTrackFilterArgs): Promise<unknown>;
   // Non-Endpoint shared functions
-  openFromDisk(datasetType: DatasetType | 'bulk' | 'calibration' | 'annotation' | 'text' | 'zip' | 'transform', directory?: boolean):
+  openFromDisk(datasetType: DatasetType | 'bulk' | 'calibration' | 'annotation' | 'frameMetadata' | 'text' | 'zip' | 'transform', directory?: boolean):
     Promise<{canceled?: boolean; filePaths: string[]; fileList?: File[]; root?: string}>;
   /** Desktop: immediate child directory names under a parent folder (multicam subfolder import). */
   listImmediateSubfolders?(parentPath: string): Promise<string[]>;
@@ -363,6 +363,11 @@ interface Api {
   }): Promise<unknown>;
   importAnnotationFile(id: string, path: string, file?: File,
     additive?: boolean, additivePrepend?: string, set?: string): Promise<boolean | string[]>;
+  /**
+   * Store an arbitrary-named frame metadata sidecar with the dataset (declared by user
+   * intent rather than the reserved basename). Resolves with any import warnings.
+   */
+  importFrameMetadataFile?(id: string, path: string, file?: File): Promise<boolean | string[]>;
   // Desktop-only calibration persistence functions
   getLastCalibration?(): Promise<string | null>;
   saveCalibration?(path: string): Promise<{ savedPath: string; updatedDatasetIds: string[] }>;
diff --git a/client/dive-common/components/ImportAnnotations.vue b/client/dive-common/components/ImportAnnotations.vue
index 7e4bc1351..fbe305946 100644
--- a/client/dive-common/components/ImportAnnotations.vue
+++ b/client/dive-common/components/ImportAnnotations.vue
@@ -5,6 +5,7 @@ import {
 import { useApi } from 'dive-common/apispec';
 import { usePrompt } from 'dive-common/vue-utilities/prompt-service';
 import { clientSettings } from 'dive-common/store/settings';
+import { invalidateFrameMetadata } from 'dive-common/use/useFrameMetadata';
 import clearLengthAttributes from 'dive-common/utils/clearLengthAttributes';
 import warpAnnotationsAcrossCameras from 'dive-common/utils/warpAnnotationsAcrossCameras';
 import { cloneDeep } from 'lodash';
@@ -219,6 +220,42 @@ export default defineComponent({
         processing.value = false;
       }
     };
+    // Frame metadata import works with any filename: the user's pick declares the file's
+    // role, so no reserved basename is needed on this path.
+    const frameMetadataSupported = computed(() => !!api.importFrameMetadataFile);
+    const openFrameMetadataUpload = async () => {
+      if (!api.importFrameMetadataFile) return;
+      try {
+        const ret = await openFromDisk('frameMetadata');
+        if (ret.canceled || !ret.filePaths.length) return;
+        menuOpen.value = false;
+        processing.value = true;
+        const result = await api.importFrameMetadataFile(
+          props.datasetId,
+          ret.filePaths[0],
+          ret.fileList?.[0],
+        );
+        processing.value = false;
+        if (result === false) {
+          await prompt({
+            title: 'Frame Metadata Import Failed',
+            text: ['Could not import the frame metadata file.'],
+            positiveButton: 'OK',
+          });
+          return;
+        }
+        // The Frame Info panel reads through a session cache; drop it so the new
+        // sidecar shows up without reloading the viewer.
+        invalidateFrameMetadata();
+      } catch (error) {
+        processing.value = false;
+        prompt({
+          title: 'Frame Metadata Import Failed',
+          text: [getResponseError(error)],
+          positiveButton: 'OK',
+        });
+      }
+    };
     const openCalibrationUpload = async () => {
       if (!api.importCalibrationFile) return;
       try {
@@ -357,6 +394,8 @@ export default defineComponent({
     };
     return {
       openUpload,
+      frameMetadataSupported,
+      openFrameMetadataUpload,
       openCalibrationUpload,
       openRegistrationUpload,
       applyLastCalibration,
@@ -533,6 +572,37 @@ export default defineComponent({
             </div>
           </v-col>
         </v-container>
+        <template v-if="frameMetadataSupported">
+          <v-divider />
+          <v-card-title class="pt-3">
+            Import Frame Metadata
+          </v-card-title>
+          <v-card-text class="pb-0">
+            Attach a per-frame metadata file (CSV or delimited text) to this dataset.
+            The file can have any name; rows are matched to frames by image filename.
+            <span v-if="isMulticamDataset">
+              Frame metadata is stored with the dataset and shared across cameras.
+            </span>
+            <a
+              href="https://kitware.github.io/dive/Frame-Metadata/"
+              target="_blank"
+            >Frame Metadata Documentation</a>
+          </v-card-text>
+          <v-container>
+            <v-col>
+              <v-row>
+                <v-btn
+                  depressed
+                  block
+                  :disabled="!datasetId || processing"
+                  @click="openFrameMetadataUpload"
+                >
+                  Import
+                </v-btn>
+              </v-row>
+            </v-col>
+          </v-container>
+        </template>
         <template v-if="registrationSupported">
           <v-divider />
           <v-card-title class="pt-3">
diff --git a/client/dive-common/constants.ts b/client/dive-common/constants.ts
index 0000722ce..e2d072198 100644
--- a/client/dive-common/constants.ts
+++ b/client/dive-common/constants.ts
@@ -171,6 +171,12 @@ const inputAnnotationFileTypes = [
   'csv',
 ];
 
+// Accepted extensions for explicit frame metadata import (any basename).
+const frameMetadataFileTypes = [
+  'csv',
+  'txt',
+];
+
 const listFileTypes = [
   'txt',
 ];
@@ -230,6 +236,7 @@ export {
   getLargeImageFileAccept,
   getLargeImageAllowedExtensions,
   inputAnnotationFileTypes,
+  frameMetadataFileTypes,
   listFileTypes,
   transformFileTypes,
   zipFileTypes,
diff --git a/client/dive-common/use/useFrameMetadata.spec.ts b/client/dive-common/use/useFrameMetadata.spec.ts
index 8effa510a..fcd087635 100644
--- a/client/dive-common/use/useFrameMetadata.spec.ts
+++ b/client/dive-common/use/useFrameMetadata.spec.ts
@@ -6,7 +6,9 @@ import {
 } from 'vitest';
 
 import type { FrameMetadataSourcesResponse } from '../apispec';
-import { __resetFrameMetadataSessionCache, useFrameMetadata } from './useFrameMetadata';
+import {
+  __resetFrameMetadataSessionCache, invalidateFrameMetadata, useFrameMetadata,
+} from './useFrameMetadata';
 
 // Drain Vue's watcher scheduler and the promise/microtask + macrotask queues so a dataset switch,
 // an async source load/resolve, and any lazy per-camera pass all settle before we assert.
@@ -76,6 +78,43 @@ describe('useFrameMetadata', () => {
     expect(metadata.error.value).toBeNull();
   });
 
+  it('refetches the current dataset when invalidateFrameMetadata fires (explicit import)', async () => {
+    const before: FrameMetadataSourcesResponse = { cameras: {} };
+    const after: FrameMetadataSourcesResponse = {
+      cameras: {
+        singleCam: [{
+          name: 'nav_2024.csv',
+          text: 'filename,depth\nimg001.png,42\n',
+        }],
+      },
+    };
+    const loadFrameMetadata = vi.fn()
+      .mockResolvedValueOnce(before)
+      .mockResolvedValueOnce(after);
+    const getCameraMediaNames = vi.fn((camera: string) => (
+      camera === 'singleCam' ? ['img001.png'] : undefined
+    ));
+
+    const datasetId = ref('dataset-a');
+    const frame = ref(0);
+    const selectedCamera = ref('singleCam');
+    const metadata = useFrameMetadata({
+      datasetId, frame, selectedCamera, loadFrameMetadata, getCameraMediaNames,
+    });
+
+    await settle();
+    expect(loadFrameMetadata).toHaveBeenCalledTimes(1);
+    expect(metadata.hasMetadataSource.value).toBe(false);
+
+    // An explicit sidecar import bumps the invalidation signal: the same dataset refetches
+    // (negative cache dropped) and the new source resolves without a dataset switch.
+    invalidateFrameMetadata();
+    await settle();
+    expect(loadFrameMetadata).toHaveBeenCalledTimes(2);
+    expect(metadata.hasMetadataSource.value).toBe(true);
+    expect(metadata.currentEntries.value).toEqual([['filename', 'img001.png'], ['depth', '42']]);
+  });
+
   it('negative-caches an empty source listing and never refetches until a dataset switch', async () => {
     const loadFrameMetadata = vi.fn(async () => ({ cameras: {} }));
     const getCameraMediaNames = vi.fn(() => [] as string[]);
diff --git a/client/dive-common/use/useFrameMetadata.ts b/client/dive-common/use/useFrameMetadata.ts
index 687d94cac..eb1df8ec8 100644
--- a/client/dive-common/use/useFrameMetadata.ts
+++ b/client/dive-common/use/useFrameMetadata.ts
@@ -40,6 +40,15 @@ export function __resetFrameMetadataSessionCache() {
   sessionCache = null;
 }
 
+// Bumped when a sidecar is added or removed (e.g. explicit frame metadata import) so live
+// composable instances drop their state and refetch instead of serving stale sources.
+const invalidationCounter = ref(0);
+
+export function invalidateFrameMetadata() {
+  sessionCache = null;
+  invalidationCounter.value += 1;
+}
+
 export function useFrameMetadata({
   datasetId,
   frame,
@@ -232,6 +241,17 @@ export function useFrameMetadata({
     { immediate: true },
   );
 
+  watch(invalidationCounter, async () => {
+    const id = datasetId.value;
+    if (!id) {
+      return;
+    }
+    token += 1;
+    loadedDatasetId = id;
+    reset();
+    await runLoad(id, token);
+  });
+
   // The viewer can expose an empty media list before filenames finish loading.
   const activeCameraMediaCount = computed(() => (
     getCameraMediaNames ? (getCameraMediaNames(selectedCamera.value)?.length ?? 0) : 0

From a081382c4eb244a0fb1189e95abb51348d4668eb Mon Sep 17 00:00:00 2001
From: Paul Elliott <paul@vizworkshop.com>
Date: Thu, 16 Jul 2026 17:13:03 -0400
Subject: [PATCH 3/6] Wire web frame metadata import

Upload the picked file into the parent dataset folder and declare it
via the postprocess frameMetadataNames param, mirroring the annotation
import flow. The frameMetadata picker accepts csv/txt by extension
because Windows browsers report CSV MIME as application/vnd.ms-excel.
---
 client/platform/web-girder/App.vue            |  2 +
 .../web-girder/api/dataset.service.ts         | 39 +++++++++++++++++++
 client/platform/web-girder/api/rpc.service.ts | 10 ++++-
 client/platform/web-girder/utils.ts           | 12 +++++-
 4 files changed, 59 insertions(+), 4 deletions(-)

diff --git a/client/platform/web-girder/App.vue b/client/platform/web-girder/App.vue
index 921b4510a..503e6f111 100644
--- a/client/platform/web-girder/App.vue
+++ b/client/platform/web-girder/App.vue
@@ -25,6 +25,7 @@ import {
   saveAttributeTrackFilters,
   importAnnotationFile,
   importCameraRegistration,
+  importFrameMetadataFile,
   loadDetections,
   saveDetections,
   unwrap,
@@ -86,6 +87,7 @@ export default defineComponent({
       importCalibrationFile,
       importAnnotationFile,
       importCameraRegistration,
+      importFrameMetadataFile,
       getTiles,
       getTileURL,
       getTileHistogram,
diff --git a/client/platform/web-girder/api/dataset.service.ts b/client/platform/web-girder/api/dataset.service.ts
index 106c85dd8..40ff31235 100644
--- a/client/platform/web-girder/api/dataset.service.ts
+++ b/client/platform/web-girder/api/dataset.service.ts
@@ -170,6 +170,44 @@ async function importAnnotationFile(parentId: string, path: string, file?: HTMLF
   return false;
 }
 
+async function importFrameMetadataFile(
+  datasetId: string,
+  path: string,
+  file?: HTMLFile,
+): Promise<boolean | string[]> {
+  if (file === undefined) {
+    return false;
+  }
+  // Frame metadata always lands on the parent dataset folder: for multicam that is the
+  // shared-sidecar location every camera's discovery already scans.
+  const folderId = parentDatasetId(datasetId);
+  const resp = await girderRest.post('/file', null, {
+    params: {
+      parentType: 'folder',
+      parentId: folderId,
+      name: file.name,
+      size: file.size,
+      mimeType: file.type,
+    },
+  });
+  if (resp.status === 200) {
+    const uploadResponse = await girderRest.post('file/chunk', file, {
+      params: {
+        uploadId: resp.data._id,
+        offset: 0,
+      },
+      headers: { 'Content-Type': 'application/octet-stream' },
+    });
+    if (uploadResponse.status === 200) {
+      // The declaration rides on postprocess: the server marks the named item as frame
+      // metadata before its annotation sweep, so the file is never parsed or moved.
+      const final = await postProcess(folderId, true, false, false, '', undefined, [file.name]);
+      return final.status === 200;
+    }
+  }
+  return false;
+}
+
 async function saveAttributes(datasetId: string, args: SaveAttributeArgs) {
   const { folderId } = await resolveDatasetFolderId(datasetId);
   return girderRest.patch(`/dive_dataset/${folderId}/attributes`, args);
@@ -404,6 +442,7 @@ export {
   getDatasetCalibration,
   importAnnotationFile,
   importCameraRegistration,
+  importFrameMetadataFile,
   makeViameFolder,
   saveAttributes,
   saveAttributeTrackFilters,
diff --git a/client/platform/web-girder/api/rpc.service.ts b/client/platform/web-girder/api/rpc.service.ts
index 7bc6ac109..e8016534a 100644
--- a/client/platform/web-girder/api/rpc.service.ts
+++ b/client/platform/web-girder/api/rpc.service.ts
@@ -2,10 +2,16 @@ import girderRest from 'platform/web-girder/plugins/girder';
 import type { GirderModel } from '@girder/components/src';
 import type { Pipe, PipelineParams } from 'dive-common/apispec';
 
-function postProcess(folderId: string, skipJobs = false, skipTranscoding = false, additive = false, additivePrepend = '', set: string | undefined = undefined) {
+function postProcess(folderId: string, skipJobs = false, skipTranscoding = false, additive = false, additivePrepend = '', set: string | undefined = undefined, frameMetadataNames: string[] | undefined = undefined) {
   return girderRest.post<{folder: GirderModel, warnings: string[], job_ids: string[]}>(`dive_rpc/postprocess/${folderId}`, null, {
     params: {
-      skipJobs, skipTranscoding, additive, additivePrepend, set,
+      skipJobs,
+      skipTranscoding,
+      additive,
+      additivePrepend,
+      set,
+      // A json-typed girder param must arrive as one JSON string, not repeated keys.
+      frameMetadataNames: frameMetadataNames ? JSON.stringify(frameMetadataNames) : undefined,
     },
   });
 }
diff --git a/client/platform/web-girder/utils.ts b/client/platform/web-girder/utils.ts
index 91870cbed..dfe8f6dc5 100644
--- a/client/platform/web-girder/utils.ts
+++ b/client/platform/web-girder/utils.ts
@@ -39,13 +39,13 @@ function getRouteFromLocation(location: LocationType): string {
 }
 
 async function openFromDisk(
-  datasetType: DatasetType | 'calibration' | 'annotation' | 'text' | 'zip' | 'transform',
+  datasetType: DatasetType | 'calibration' | 'annotation' | 'frameMetadata' | 'text' | 'zip' | 'transform',
   directory = false,
 ): Promise<{ canceled: boolean; filePaths: string[]; fileList?: File[]; root?: string }> {
   const input: HTMLInputElement = document.createElement('input');
   input.type = 'file';
   const baseTypes: string[] = inputAnnotationFileTypes.map((item) => `.${item}`);
-  if (!['calibration', 'annotation', 'zip'].includes(datasetType)) {
+  if (!['calibration', 'annotation', 'frameMetadata', 'zip'].includes(datasetType)) {
     input.multiple = true;
   }
   if (directory && (datasetType === 'image-sequence' || datasetType === 'video')) {
@@ -65,6 +65,8 @@ async function openFromDisk(
   } else if (datasetType === 'annotation') {
     input.accept = inputAnnotationTypes
       .concat(inputAnnotationFileTypes.map((item) => `.${item}`)).join(',');
+  } else if (datasetType === 'frameMetadata') {
+    input.accept = '.csv,.txt';
   } else if (datasetType === 'zip') {
     input.accept = zipFileTypes.map((item) => `.${item}`).join(',');
   } else if (datasetType === 'transform') {
@@ -85,6 +87,12 @@ async function openFromDisk(
             if (!fileList.every((item) => inputAnnotationTypes.includes(item.type))) {
               reject(new Error('File Types did not match JSON or CSV'));
             }
+          } else if (datasetType === 'frameMetadata') {
+            // Extension check, not MIME: Windows browsers report CSV as
+            // application/vnd.ms-excel and delimited text as text/plain.
+            if (!fileList.every((item) => /\.(csv|txt)$/i.test(item.name))) {
+              reject(new Error('File types did not match CSV or TXT'));
+            }
           } else if (datasetType === 'large-image') {
             const allowed = new Set(getLargeImageAllowedExtensions().map((ext) => ext.toLowerCase()));
             if (!fileList.every((item) => {

From b3a828291b0f17cf405eddc6dbbb25a29f4c99af Mon Sep 17 00:00:00 2001
From: Paul Elliott <paul@vizworkshop.com>
Date: Thu, 16 Jul 2026 17:13:16 -0400
Subject: [PATCH 4/6] Wire desktop frame metadata import

Copy the picked file into the project auxiliary directory keeping its
original basename and record it in meta.json frameMetadataFiles.
Discovery lists declared files ahead of convention-named ones; for
multicam they are shared across cameras like parent-root sidecars while
camera-local files still win. Import-annotation errors now point at the
Import button's Frame Metadata option.
---
 client/platform/desktop/backend/ipcService.ts |  4 +
 .../desktop/backend/native/common.spec.ts     | 81 +++++++++++++++-
 .../platform/desktop/backend/native/common.ts | 96 +++++++++++++++++--
 client/platform/desktop/constants.ts          |  4 +
 client/platform/desktop/frontend/api.ts       | 24 ++++-
 5 files changed, 196 insertions(+), 13 deletions(-)

diff --git a/client/platform/desktop/backend/ipcService.ts b/client/platform/desktop/backend/ipcService.ts
index 3c08df650..cc41858f1 100644
--- a/client/platform/desktop/backend/ipcService.ts
+++ b/client/platform/desktop/backend/ipcService.ts
@@ -252,6 +252,10 @@ export default function register() {
     return ret;
   });
 
+  ipcMain.handle('import-frame-metadata', async (event, {
+    id, path,
+  }: { id: string; path: string }) => common.importFrameMetadataFile(settings.get(), id, path));
+
   ipcMain.handle('get-last-calibration', async () => common.getLastCalibrationPath(settings.get()));
 
   ipcMain.handle('save-calibration', async (_, { path: sourcePath }: { path: string }) => {
diff --git a/client/platform/desktop/backend/native/common.spec.ts b/client/platform/desktop/backend/native/common.spec.ts
index b8fa810eb..898616bed 100644
--- a/client/platform/desktop/backend/native/common.spec.ts
+++ b/client/platform/desktop/backend/native/common.spec.ts
@@ -327,6 +327,16 @@ beforeEach(() => {
         'image_0001.jpg': '',
         'notes.txt': 'note,value\nhello,world\n',
       },
+      // Source files for explicit (arbitrary-name) frame metadata import.
+      frameMetadataImportSource: {
+        'nav_2024.csv': [
+          'filename,depth',
+          'image_0001.jpg,42',
+          '',
+        ].join('\n'),
+        'nav_2024.json': '{}',
+        'empty.csv': '',
+      },
       // Duplicate image basename across subfolders: the read path keys last-wins instead of
       // throwing like the import-path validator.
       frameMetadataDupSource: {
@@ -522,6 +532,30 @@ beforeEach(() => {
           'result_whatever.json': JSON.stringify({}),
           auxiliary: {},
         },
+        projectidFrameMetadataDeclared: {
+          'meta.json': JSON.stringify({
+            version: 1,
+            id: 'projectidFrameMetadataDeclared',
+            type: 'image-sequence',
+            fps: 5,
+            originalBasePath: '/home/user/data/frameMetadataSource',
+            originalImageFiles: [
+              'image_0001.jpg',
+              'image_0002.jpg',
+              'image_0003.jpg',
+            ],
+            // One live declared sidecar and one stale entry whose file is gone.
+            frameMetadataFiles: ['auxiliary/nav_2024.csv', 'auxiliary/gone.csv'],
+          }),
+          'result_whatever.json': JSON.stringify({}),
+          auxiliary: {
+            'nav_2024.csv': [
+              'filename,depth',
+              'image_0001.jpg,42',
+              '',
+            ].join('\n'),
+          },
+        },
         projectidMulticamRootDedup: {
           'meta.json': JSON.stringify({
             version: 1,
@@ -1581,6 +1615,49 @@ describe('frame metadata read path (source text loading)', () => {
     await expect(common.loadFrameMetadata(settings, 'projectid1VideoGood'))
       .resolves.toEqual({ cameras: {} });
   });
+
+  it('lists declared sidecars before convention-named ones and skips stale entries', async () => {
+    const data = await common.loadFrameMetadata(settings, 'projectidFrameMetadataDeclared');
+    // 'auxiliary/gone.csv' has no file behind it and must not sink the scan.
+    expect(data.cameras.singleCam.map((source) => source.name))
+      .toEqual(['nav_2024.csv', 'frame-metadata.txt']);
+    expect(data.cameras.singleCam[0].text).toContain('depth');
+  });
+});
+
+describe('explicit frame metadata import', () => {
+  it('copies the file into auxiliary, records it in meta.json, and discovery lists it first', async () => {
+    const source = '/home/user/data/frameMetadataImportSource/nav_2024.csv';
+    await expect(common.importFrameMetadataFile(settings, 'projectidFrameMetadata', source))
+      .resolves.toBe(true);
+
+    const projectDir = npath.join(settings.dataPath, 'DIVE_Projects', 'projectidFrameMetadata');
+    expect(fs.existsSync(npath.join(projectDir, 'auxiliary', 'nav_2024.csv'))).toBe(true);
+    const meta = JSON.parse(await fs.readFile(npath.join(projectDir, 'meta.json'), 'utf-8'));
+    expect(meta.frameMetadataFiles).toEqual([npath.join('auxiliary', 'nav_2024.csv')]);
+
+    const data = await common.loadFrameMetadata(settings, 'projectidFrameMetadata');
+    expect(data.cameras.singleCam.map((source_) => source_.name))
+      .toEqual(['nav_2024.csv', 'frame-metadata.txt']);
+
+    // Re-importing the same file overwrites the copy without duplicating the declaration.
+    await expect(common.importFrameMetadataFile(settings, 'projectidFrameMetadata', source))
+      .resolves.toBe(true);
+    const meta2 = JSON.parse(await fs.readFile(npath.join(projectDir, 'meta.json'), 'utf-8'));
+    expect(meta2.frameMetadataFiles).toEqual([npath.join('auxiliary', 'nav_2024.csv')]);
+  });
+
+  it('rejects unsupported extensions', async () => {
+    await expect(common.importFrameMetadataFile(settings, 'projectidFrameMetadata', '/home/user/data/frameMetadataImportSource/nav_2024.json')).rejects.toThrow('not a supported frame metadata file type');
+  });
+
+  it('rejects an empty file', async () => {
+    await expect(common.importFrameMetadataFile(settings, 'projectidFrameMetadata', '/home/user/data/frameMetadataImportSource/empty.csv')).rejects.toThrow('is empty');
+  });
+
+  it('rejects non-image-sequence datasets', async () => {
+    await expect(common.importFrameMetadataFile(settings, 'projectid1VideoGood', '/home/user/data/frameMetadataImportSource/nav_2024.csv')).rejects.toThrow('only supported for image-sequence');
+  });
 });
 
 describe('frame metadata discovery', () => {
@@ -1661,12 +1738,12 @@ describe('frame metadata import gates', () => {
     )).rejects.toThrow(/frame metadata file/);
   });
 
-  it('adds a rename hint when a plain frame-metadata-shaped CSV fails VIAME import', async () => {
+  it('hints at the explicit import path when a plain frame-metadata-shaped CSV fails VIAME import', async () => {
     await expect(common.ingestDataFiles(
       settings,
       'projectid1',
       ['/home/user/data/fmGateViameFail/nav.csv'],
-    )).rejects.toThrow(/rename it to frame-metadata\.csv/);
+    )).rejects.toThrow(/Import button's Frame Metadata option/);
   });
 });
 
diff --git a/client/platform/desktop/backend/native/common.ts b/client/platform/desktop/backend/native/common.ts
index 184f4bbfd..6c5794351 100644
--- a/client/platform/desktop/backend/native/common.ts
+++ b/client/platform/desktop/backend/native/common.ts
@@ -548,6 +548,29 @@ async function gatherFrameMetadataCandidates(
   return ([] as FrameMetadataCandidate[]).concat(...perDirectory);
 }
 
+// Explicitly imported sidecars recorded in meta.json (any basename), resolved against the
+// project directory. A missing or unreadable entry is skipped like any other candidate.
+async function declaredFrameMetadataCandidates(
+  projectBasePath: string,
+  projectMetaData: JsonMeta,
+): Promise<FrameMetadataCandidate[]> {
+  const declared = projectMetaData.frameMetadataFiles ?? [];
+  const candidates = await Promise.all(declared
+    .map(async (relativePath): Promise<FrameMetadataCandidate | null> => {
+      try {
+        const absolutePath = npath.resolve(projectBasePath, relativePath);
+        const stat = await fs.stat(absolutePath);
+        if (!stat.isFile()) {
+          return null;
+        }
+        return { name: npath.basename(relativePath), absolutePath };
+      } catch {
+        return null;
+      }
+    }));
+  return candidates.filter((candidate): candidate is FrameMetadataCandidate => candidate !== null);
+}
+
 // Read each candidate's text (memoized by path so a sidecar shared across cameras is read once),
 // returning [sourceName, text] pairs in candidate (precedence) order. An unreadable candidate is
 // skipped rather than sinking the others.
@@ -598,6 +621,7 @@ function commonParentDirectory(paths: string[]): string | null {
 
 async function loadMulticamFrameMetadata(
   projectMetaData: JsonMeta,
+  declaredCandidates: FrameMetadataCandidate[],
 ): Promise<FrameMetadataSourcesResponse> {
   const { multiCam } = projectMetaData;
   if (!multiCam) {
@@ -631,9 +655,12 @@ async function loadMulticamFrameMetadata(
     const cameraCandidates = await gatherFrameMetadataCandidates(cameraDirectories);
     // Root dedup (mirror of the server's folder-id dedup): a camera whose own media dir is the
     // root already gathered the root's sidecars, so do not concatenate them a second time.
-    const candidates = resolvedRoot !== null && !cameraDirectories.includes(resolvedRoot)
-      ? cameraCandidates.concat(rootCandidates)
-      : cameraCandidates;
+    // Explicitly imported sidecars are shared across cameras like the parent/root folder,
+    // but outrank convention-discovered shared files; camera-local files still win overall.
+    const sharedCandidates = declaredCandidates.concat(
+      resolvedRoot !== null && !cameraDirectories.includes(resolvedRoot) ? rootCandidates : [],
+    );
+    const candidates = cameraCandidates.concat(sharedCandidates);
     const texts = await readCandidateTexts(candidates, textMemo);
     if (texts.length) {
       cameras[cameraName] = texts.map(([name, text]) => ({ name, text }));
@@ -650,17 +677,22 @@ async function loadFrameMetadata(
   const parentId = parentDatasetId(datasetId);
   const projectDirData = await getValidatedProjectDir(settings, parentId);
   const projectMetaData = await loadJsonMetadata(projectDirData.metaFileAbsPath);
+  const declaredCandidates = await declaredFrameMetadataCandidates(
+    projectDirData.basePath,
+    projectMetaData,
+  );
 
   if (projectMetaData.type === MultiType) {
-    return loadMulticamFrameMetadata(projectMetaData);
+    return loadMulticamFrameMetadata(projectMetaData, declaredCandidates);
   }
   if (projectMetaData.type !== 'image-sequence') {
     return { cameras: {} };
   }
 
-  const candidates = await gatherFrameMetadataCandidates(
+  // Explicitly imported sidecars outrank convention-discovered ones.
+  const candidates = declaredCandidates.concat(await gatherFrameMetadataCandidates(
     frameMetadataSourceDirectories(projectMetaData),
-  );
+  ));
   const textMemo = new Map<string, string>();
   const texts = await readCandidateTexts(candidates, textMemo);
   if (!texts.length) {
@@ -673,6 +705,50 @@ async function loadFrameMetadata(
   };
 }
 
+/**
+ * importFrameMetadataFile stores an arbitrary-named frame metadata sidecar with the
+ * dataset: the file is copied into the project auxiliary directory (original basename
+ * kept — it is user-facing as the source name) and recorded in meta.json, where
+ * read-time discovery picks it up ahead of convention-named files beside the media.
+ */
+async function importFrameMetadataFile(
+  settings: Settings,
+  datasetId: string,
+  path: string,
+): Promise<boolean> {
+  if (!fs.existsSync(path) || !fs.statSync(path).isFile()) {
+    throw new Error(`file ${path} does not exist`);
+  }
+  if (!/\.(csv|txt)$/i.test(path)) {
+    throw new Error(
+      `${npath.basename(path)} is not a supported frame metadata file type (.csv or .txt)`,
+    );
+  }
+  if (fs.statSync(path).size === 0) {
+    throw new Error(`${npath.basename(path)} is empty`);
+  }
+  const parentId = parentDatasetId(datasetId);
+  const projectDirData = await getValidatedProjectDir(settings, parentId);
+  const projectMetaData = await loadJsonMetadata(projectDirData.metaFileAbsPath);
+  if (projectMetaData.type !== 'image-sequence' && projectMetaData.type !== MultiType) {
+    throw new Error('Frame metadata is only supported for image-sequence datasets');
+  }
+  const destName = npath.basename(path);
+  const destAbsPath = npath.join(projectDirData.auxDirAbsPath, destName);
+  await fs.copy(path, destAbsPath, { overwrite: true });
+  const relativePath = npath.join(AuxFolderName, destName);
+  const release = await _acquireLock(projectDirData.basePath, projectDirData.metaFileAbsPath, 'meta');
+  const existing = await loadJsonMetadata(projectDirData.metaFileAbsPath);
+  const declared = existing.frameMetadataFiles ?? [];
+  if (!declared.includes(relativePath)) {
+    declared.push(relativePath);
+  }
+  existing.frameMetadataFiles = declared;
+  await _saveAsJson(projectDirData.metaFileAbsPath, existing);
+  await release();
+  return true;
+}
+
 /**
  * Look through DIVE project path, find subfolders that
  * look like datasets, and return them.
@@ -1027,7 +1103,7 @@ async function _ingestFilePath(
   // Frame-metadata sidecars are read from the media folder, so importing one as annotations would
   // copy it into the wrong storage path.
   if (isFrameMetadataSourceName(path)) {
-    throw new Error(`${npath.basename(path)} is a frame metadata file. Place it in the dataset's media folder; it is read automatically and cannot be imported as annotations.`);
+    throw new Error(`${npath.basename(path)} is a frame metadata file. Use the Import button's Frame Metadata option, or place it in the dataset's media folder; it cannot be imported as annotations.`);
   }
   let warnings: string[] = [];
   // Make a copy of the file in aux
@@ -1065,8 +1141,9 @@ async function _ingestFilePath(
     try {
       data = await viameSerializers.parseFile(path, imageMap);
     } catch (e) {
-      // A plain CSV that fails to parse as annotations is often frame metadata: hint at the rename.
-      throw new Error(`${(e as Error).message} If this file is frame metadata rather than annotations, rename it to frame-metadata.csv.`);
+      // A plain CSV that fails to parse as annotations is often frame metadata: hint at the
+      // explicit import path.
+      throw new Error(`${(e as Error).message} If this file is frame metadata rather than annotations, use the Import button's Frame Metadata option.`);
     }
     annotations.tracks = data[0].tracks;
     annotations.groups = data[0].groups;
@@ -1972,6 +2049,7 @@ export {
   loadFrameMetadata,
   frameMetadataSourceDirectories,
   frameMetadataCandidateDescriptors,
+  importFrameMetadataFile,
   openLink,
   openPathInFileManager,
   ingestDataFiles,
diff --git a/client/platform/desktop/constants.ts b/client/platform/desktop/constants.ts
index 49905f550..a427ad23a 100644
--- a/client/platform/desktop/constants.ts
+++ b/client/platform/desktop/constants.ts
@@ -139,6 +139,10 @@ export interface JsonMeta extends DatasetMetaMutable {
   // image enhancement settings
   imageEnhancement?: ImageEnhancements;
 
+  // Explicitly imported frame-metadata sidecar files, relative to the project directory.
+  // Read-time discovery reads these in addition to reserved-name files beside the media.
+  frameMetadataFiles?: string[];
+
   // Stereo or multi-camera datasets with uniform type (all images, all video)
   multiCam: MultiCamDesktop | null;
 
diff --git a/client/platform/desktop/frontend/api.ts b/client/platform/desktop/frontend/api.ts
index ed2554818..42598dfc3 100644
--- a/client/platform/desktop/frontend/api.ts
+++ b/client/platform/desktop/frontend/api.ts
@@ -12,7 +12,7 @@ import type {
 
 import {
   fileVideoTypes, calibrationFileTypes,
-  inputAnnotationFileTypes, listFileTypes,
+  frameMetadataFileTypes, inputAnnotationFileTypes, listFileTypes,
   largeImageDesktopTypes, transformFileTypes,
 } from 'dive-common/constants';
 import {
@@ -47,7 +47,7 @@ function joinPath(dir: string, filename: string) {
  * Native functions that run entirely in the renderer
  */
 
-async function openFromDisk(datasetType: DatasetType | 'bulk' | 'calibration' | 'annotation' | 'text' | 'transform', directory = false) {
+async function openFromDisk(datasetType: DatasetType | 'bulk' | 'calibration' | 'annotation' | 'frameMetadata' | 'text' | 'transform', directory = false) {
   let filters: FileFilter[] = [];
   const allFiles = { name: 'All Files', extensions: ['*'] };
   if (datasetType === 'video') {
@@ -73,6 +73,12 @@ async function openFromDisk(datasetType: DatasetType | 'bulk' | 'calibration' |
       allFiles,
     ];
   }
+  if (datasetType === 'frameMetadata') {
+    filters = [
+      { name: 'frame metadata', extensions: frameMetadataFileTypes },
+      allFiles,
+    ];
+  }
   if (datasetType === 'transform') {
     filters = [
       { name: 'Transform / calibration', extensions: transformFileTypes },
@@ -98,6 +104,14 @@ async function openFromDisk(datasetType: DatasetType | 'bulk' | 'calibration' |
       throw Error('File Types did not match JSON or CSV');
     }
   }
+  if (datasetType === 'frameMetadata') {
+    const allowed = new Set(frameMetadataFileTypes.map((ext) => ext.toLowerCase()));
+    if (!results.filePaths.every(
+      (item) => allowed.has(getExtension(item)),
+    )) {
+      throw Error('File Types did not match CSV or TXT');
+    }
+  }
   if (datasetType === 'large-image') {
     const allowed = new Set(largeImageDesktopTypes.map((ext) => ext.toLowerCase()));
     if (!results.filePaths.every(
@@ -242,6 +256,11 @@ function importAnnotationFile(id: string, path: string, _htmlFile = undefined, a
   });
 }
 
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+function importFrameMetadataFile(id: string, path: string, _htmlFile = undefined): Promise<boolean | string[]> {
+  return window.diveDesktop.invoke('import-frame-metadata', { id, path });
+}
+
 function finalizeImport(args: DesktopMediaImportResponse): Promise<ConversionArgs> {
   // Have this return JsonMeta as well as everything needed to start a job?
   return window.diveDesktop.invoke('finalize-import', args);
@@ -738,6 +757,7 @@ export {
   deleteDataset,
   checkDataset,
   importAnnotationFile,
+  importFrameMetadataFile,
   importMultiCam,
   scanMultiCamBatch,
   openLink,

From f516472087e03ea751531d7473bf94e5ba7b01e0 Mon Sep 17 00:00:00 2001
From: Paul Elliott <paul@vizworkshop.com>
Date: Thu, 16 Jul 2026 17:13:16 -0400
Subject: [PATCH 5/6] Document explicit frame metadata import

---
 docs/Frame-Metadata.md | 48 ++++++++++++++++++++++++++++++------------
 1 file changed, 34 insertions(+), 14 deletions(-)

diff --git a/docs/Frame-Metadata.md b/docs/Frame-Metadata.md
index 911ba4087..8c0cd4f9f 100644
--- a/docs/Frame-Metadata.md
+++ b/docs/Frame-Metadata.md
@@ -4,17 +4,32 @@ DIVE can display read-only frame metadata for image-sequence datasets in the
 [Dataset Info panel](UI-DatasetInfo.md#frame-metadata). Common examples are
 timestamp, latitude, longitude, depth, altitude, or vehicle state.
 
-Frame metadata is not annotation data. DIVE reads it from a sidecar file next to
-the imagery when the dataset opens. The values are not edited in DIVE, imported
-as annotations, or included in annotation exports.
+Frame metadata is not annotation data. DIVE reads it from a sidecar file stored
+with the dataset when the dataset opens. The values are not edited in DIVE,
+imported as annotations, or included in annotation exports.
 
-## Filename
+## Adding Frame Metadata
 
-Name the file `frame-metadata.csv` or `frame-metadata.txt`. The snake_case names
-`frame_metadata.csv` and `frame_metadata.txt` are also accepted.
+There are two ways to declare a file as frame metadata:
 
-The filename identifies the file as frame metadata. Other CSV or text files are
-handled by the normal annotation import flow.
+* **Import button (any filename).** In the annotation viewer, open the Import
+  menu and use its **Frame Metadata** section to pick a `.csv` or `.txt` file.
+  The file keeps its original name, is stored with the dataset, and appears in
+  the Dataset Info panel immediately.
+* **Reserved filename.** Name the file `frame-metadata.csv` or
+  `frame-metadata.txt` (the snake_case names `frame_metadata.csv` and
+  `frame_metadata.txt` are also accepted) and include it with the imagery. The
+  name alone identifies the file as frame metadata on every ingestion path:
+  dataset uploads, zip archives, assetstore/S3 imports, and desktop folder
+  imports.
+
+Use the reserved filename for automated or bulk ingestion and for datasets that
+will be exported and re-imported elsewhere — the filename is the only
+declaration that travels with the file. Files declared through the Import
+button are recorded with the dataset itself, so that declaration does not
+survive a dataset export.
+
+Other CSV or text files are handled by the normal annotation import flow.
 
 ## File Format
 
@@ -42,8 +57,11 @@ not infer units or data types from the column names.
 
 ## Placement
 
-For a single-camera image sequence, place the sidecar in the dataset folder
-beside the images.
+Files added through the Import button are stored with the dataset
+automatically; no placement is needed.
+
+For reserved-name sidecars in a single-camera image sequence, place the file in
+the dataset folder beside the images.
 
 For a multicamera image sequence, use either:
 
@@ -52,15 +70,17 @@ For a multicamera image sequence, use either:
 
 A shared multicamera file can contain one filename column per camera, such as
 `port_image` and `starboard_image`. Each active camera displays the rows that
-match that camera's images.
+match that camera's images. Files added through the Import button are shared
+across cameras the same way.
 
 When both shared and camera-specific sidecars are present, their columns are
 combined. For a column both files define, the camera-specific value is used
 where available; columns only the shared file defines are filled from the
-shared file.
+shared file. In that per-column order, an imported file is used ahead of other
+shared sidecars.
 
 ## Limits
 
 Frame metadata sidecars are supported for image-sequence datasets. Frame
-metadata for videos, embedded KLV, embedded EXIF, and choosing a sidecar from
-another location are not currently supported.
+metadata for videos, embedded KLV, and embedded EXIF are not currently
+supported.

From ee62105b48180fb30dd0bf30dd30b356fa0df783 Mon Sep 17 00:00:00 2001
From: Paul Elliott <paul@vizworkshop.com>
Date: Fri, 17 Jul 2026 10:35:04 -0400
Subject: [PATCH 6/6] Harden explicit frame metadata import

Address the merged review of the arbitrary-name import path. The load-bearing
change is that declaration is now keyed by the uploaded item id rather than the
filename, which closes several web-path defects at once.

- Declare by item id: postprocess param frameMetadataNames -> frameMetadataItemIds;
  the server loads each item, checks folder membership and extension, and marks all
  only after validating all (no partial marks, non-string ids rejected as 400).
- Re-import now replaces in place: the web client deletes a prior same-name declared
  sidecar before uploading, so a corrected file is not stranded as "name (1)" while
  stale values persist. A same-name pending annotation CSV is left untouched.
- The uploaded item is removed if postprocess rejects, so a failed import cannot
  strand a file for the next annotation sweep to misclassify and delete.
- Precedence: declared (imported) sidecars sort ahead of reserved-name ones so an
  imported file wins column conflicts, matching desktop and the docs.
- The viewer's Frame Metadata import section is gated on image-sequence/multicam
  media type, mirroring the sibling sections.
- The Frame Metadata panel recovers after a failed refetch instead of sticking on
  error; a reserved-name import through Import Annotations now refreshes the panel.
- Empty-file guard on web, boolean return type, shared file-extension constant and
  upload helper, restored desktop rename hint, and predicate/string dedup.
---
 client/dive-common/apispec.ts                 |   7 +-
 .../components/ImportAnnotations.vue          |  23 +++-
 client/dive-common/constants.ts               |   5 +
 .../dive-common/use/useFrameMetadata.spec.ts  |  39 +++++++
 client/dive-common/use/useFrameMetadata.ts    |  20 ++--
 .../platform/desktop/backend/native/common.ts |  13 ++-
 client/platform/desktop/frontend/api.ts       |   2 +-
 .../frontend/components/ViewerLoader.vue      |   1 +
 .../web-girder/api/dataset.service.ts         | 106 +++++++++--------
 client/platform/web-girder/api/rpc.service.ts |   4 +-
 client/platform/web-girder/utils.ts           |  10 +-
 .../web-girder/views/ViewerLoader.vue         |   1 +
 server/dive_server/crud_dataset.py            |  22 ++--
 server/dive_server/crud_rpc.py                | 108 +++++++++---------
 server/dive_server/views_rpc.py               |  15 ++-
 server/dive_utils/frame_metadata.py           |  13 +++
 server/tests/test_frame_metadata_sources.py   |   5 +-
 server/tests/test_process_items.py            |  75 ++++++++----
 18 files changed, 305 insertions(+), 164 deletions(-)

diff --git a/client/dive-common/apispec.ts b/client/dive-common/apispec.ts
index 45c0b5a98..3745841c4 100644
--- a/client/dive-common/apispec.ts
+++ b/client/dive-common/apispec.ts
@@ -363,11 +363,8 @@ interface Api {
   }): Promise<unknown>;
   importAnnotationFile(id: string, path: string, file?: File,
     additive?: boolean, additivePrepend?: string, set?: string): Promise<boolean | string[]>;
-  /**
-   * Store an arbitrary-named frame metadata sidecar with the dataset (declared by user
-   * intent rather than the reserved basename). Resolves with any import warnings.
-   */
-  importFrameMetadataFile?(id: string, path: string, file?: File): Promise<boolean | string[]>;
+  /** Store an arbitrary-named frame metadata sidecar with the dataset; resolves true on success. */
+  importFrameMetadataFile?(id: string, path: string, file?: File): Promise<boolean>;
   // Desktop-only calibration persistence functions
   getLastCalibration?(): Promise<string | null>;
   saveCalibration?(path: string): Promise<{ savedPath: string; updatedDatasetIds: string[] }>;
diff --git a/client/dive-common/components/ImportAnnotations.vue b/client/dive-common/components/ImportAnnotations.vue
index fbe305946..6f41ca224 100644
--- a/client/dive-common/components/ImportAnnotations.vue
+++ b/client/dive-common/components/ImportAnnotations.vue
@@ -6,6 +6,7 @@ import { useApi } from 'dive-common/apispec';
 import { usePrompt } from 'dive-common/vue-utilities/prompt-service';
 import { clientSettings } from 'dive-common/store/settings';
 import { invalidateFrameMetadata } from 'dive-common/use/useFrameMetadata';
+import isFrameMetadataSourceName from 'dive-common/frameMetadata/naming';
 import clearLengthAttributes from 'dive-common/utils/clearLengthAttributes';
 import warpAnnotationsAcrossCameras from 'dive-common/utils/warpAnnotationsAcrossCameras';
 import { cloneDeep } from 'lodash';
@@ -27,6 +28,10 @@ export default defineComponent({
       type: String as PropType<string | null>,
       default: null,
     },
+    mediaType: {
+      type: String as PropType<string | null>,
+      default: null,
+    },
     calibrationFile: {
       type: String as PropType<string | null>,
       default: null,
@@ -192,6 +197,12 @@ export default defineComponent({
 
           if (importFile) {
             await reloadAnnotations();
+            // Importing a reserved-name frame-metadata.csv/.txt through this path creates an
+            // in-viewer sidecar; drop the session cache so the Frame Metadata panel shows it
+            // without a viewer reload, matching the explicit Import Frame Metadata button.
+            if (isFrameMetadataSourceName(ret.fileList?.[0]?.name ?? path)) {
+              invalidateFrameMetadata();
+            }
             if (
               warpToAllCameras.value
               && canWarpToAllCameras.value
@@ -220,9 +231,13 @@ export default defineComponent({
         processing.value = false;
       }
     };
-    // Frame metadata import works with any filename: the user's pick declares the file's
-    // role, so no reserved basename is needed on this path.
-    const frameMetadataSupported = computed(() => !!api.importFrameMetadataFile);
+    // Frame metadata is only meaningful for image-sequence datasets (single-camera or a
+    // multicam rig of image sequences); mirror the sibling sections and gate on media type
+    // so it never renders on video/large-image datasets, where an import can only fail.
+    const frameMetadataSupported = computed(
+      () => !!api.importFrameMetadataFile
+        && (props.mediaType === 'image-sequence' || isMulticamDataset.value),
+    );
     const openFrameMetadataUpload = async () => {
       if (!api.importFrameMetadataFile) return;
       try {
@@ -244,7 +259,7 @@ export default defineComponent({
           });
           return;
         }
-        // The Frame Info panel reads through a session cache; drop it so the new
+        // The Frame Metadata panel reads through a session cache; drop it so the new
         // sidecar shows up without reloading the viewer.
         invalidateFrameMetadata();
       } catch (error) {
diff --git a/client/dive-common/constants.ts b/client/dive-common/constants.ts
index e2d072198..9bdb6ac81 100644
--- a/client/dive-common/constants.ts
+++ b/client/dive-common/constants.ts
@@ -177,6 +177,10 @@ const frameMetadataFileTypes = [
   'txt',
 ];
 
+// Girder item meta key marking a declared frame-metadata sidecar. Keep in sync with the
+// server constant FrameMetadataMarker (dive_utils/constants.py).
+const frameMetadataItemMarker = 'frameMetadata';
+
 const listFileTypes = [
   'txt',
 ];
@@ -237,6 +241,7 @@ export {
   getLargeImageAllowedExtensions,
   inputAnnotationFileTypes,
   frameMetadataFileTypes,
+  frameMetadataItemMarker,
   listFileTypes,
   transformFileTypes,
   zipFileTypes,
diff --git a/client/dive-common/use/useFrameMetadata.spec.ts b/client/dive-common/use/useFrameMetadata.spec.ts
index fcd087635..b80fb9d52 100644
--- a/client/dive-common/use/useFrameMetadata.spec.ts
+++ b/client/dive-common/use/useFrameMetadata.spec.ts
@@ -115,6 +115,45 @@ describe('useFrameMetadata', () => {
     expect(metadata.currentEntries.value).toEqual([['filename', 'img001.png'], ['depth', '42']]);
   });
 
+  it('recovers after a failed load instead of stranding the panel on error (FIX 4)', async () => {
+    const good: FrameMetadataSourcesResponse = {
+      cameras: {
+        port: [{ name: 'nav.csv', text: 'filename,depth\nport001.png,10\n' }],
+        starboard: [{ name: 'nav.csv', text: 'filename,depth\nstar001.png,20\n' }],
+      },
+    };
+    // The first load rejects (transient network blip); the next succeeds.
+    const loadFrameMetadata = vi.fn()
+      .mockRejectedValueOnce(new Error('network blip'))
+      .mockResolvedValueOnce(good);
+    const getCameraMediaNames = vi.fn((camera: string) => ({
+      port: ['port001.png'],
+      starboard: ['star001.png'],
+    }[camera]));
+
+    const datasetId = ref('dataset-a');
+    const frame = ref(0);
+    const selectedCamera = ref('port');
+    const metadata = useFrameMetadata({
+      datasetId, frame, selectedCamera, loadFrameMetadata, getCameraMediaNames,
+    });
+
+    await settle();
+    // The initial load rejected: the panel is in an error state, not silently "loaded".
+    expect(loadFrameMetadata).toHaveBeenCalledTimes(1);
+    expect(metadata.error.value).not.toBeNull();
+    expect(metadata.hasMetadataSource.value).toBe(false);
+
+    // A camera change re-runs ensure(). A failed load must not have committed the dataset as
+    // loaded, or this would short-circuit and leave the panel stuck forever; instead it retries.
+    selectedCamera.value = 'starboard';
+    await settle();
+    expect(loadFrameMetadata).toHaveBeenCalledTimes(2);
+    expect(metadata.error.value).toBeNull();
+    expect(metadata.hasMetadataSource.value).toBe(true);
+    expect(metadata.currentEntries.value).toEqual([['filename', 'star001.png'], ['depth', '20']]);
+  });
+
   it('negative-caches an empty source listing and never refetches until a dataset switch', async () => {
     const loadFrameMetadata = vi.fn(async () => ({ cameras: {} }));
     const getCameraMediaNames = vi.fn(() => [] as string[]);
diff --git a/client/dive-common/use/useFrameMetadata.ts b/client/dive-common/use/useFrameMetadata.ts
index eb1df8ec8..4ffa75d9d 100644
--- a/client/dive-common/use/useFrameMetadata.ts
+++ b/client/dive-common/use/useFrameMetadata.ts
@@ -192,6 +192,11 @@ export function useFrameMetadata({
     } catch (err) {
       if (requestToken === token) {
         error.value = getResponseError(err);
+        // A failed load must not leave loadedDatasetId committed: ensure()'s same-dataset
+        // short-circuit would then treat the panel as loaded and never retry, stranding it
+        // on the error. Clearing it lets the next ensure() (camera/frame change, remount, or
+        // invalidation) re-attempt the fetch.
+        loadedDatasetId = null;
       }
     } finally {
       endWork(requestToken);
@@ -241,15 +246,12 @@ export function useFrameMetadata({
     { immediate: true },
   );
 
-  watch(invalidationCounter, async () => {
-    const id = datasetId.value;
-    if (!id) {
-      return;
-    }
-    token += 1;
-    loadedDatasetId = id;
-    reset();
-    await runLoad(id, token);
+  watch(invalidationCounter, () => {
+    // A sidecar was added or removed. Forget the loaded dataset so ensure() re-runs its
+    // dataset-switch branch (bump token, reset, refetch) rather than duplicating it here;
+    // invalidateFrameMetadata() already cleared the session cache, so ensure() refetches.
+    loadedDatasetId = null;
+    ensure();
   });
 
   // The viewer can expose an empty media list before filenames finish loading.
diff --git a/client/platform/desktop/backend/native/common.ts b/client/platform/desktop/backend/native/common.ts
index 6c5794351..50a8d42e8 100644
--- a/client/platform/desktop/backend/native/common.ts
+++ b/client/platform/desktop/backend/native/common.ts
@@ -41,7 +41,7 @@ import kpf from 'platform/desktop/backend/serializers/kpf';
 import { checkMedia } from 'platform/desktop/backend/native/mediaJobs';
 import {
   websafeImageTypes, websafeVideoTypes, otherImageTypes, otherVideoTypes, fileVideoTypes,
-  MultiType, JsonMetaRegEx, largeImageDesktopTypes,
+  MultiType, JsonMetaRegEx, largeImageDesktopTypes, frameMetadataFileTypes,
 } from 'dive-common/constants';
 import {
   JsonMeta, Settings, JsonMetaCurrentVersion, DesktopMetadata,
@@ -719,7 +719,8 @@ async function importFrameMetadataFile(
   if (!fs.existsSync(path) || !fs.statSync(path).isFile()) {
     throw new Error(`file ${path} does not exist`);
   }
-  if (!/\.(csv|txt)$/i.test(path)) {
+  const ext = npath.extname(path).replace('.', '').toLowerCase();
+  if (!frameMetadataFileTypes.includes(ext)) {
     throw new Error(
       `${npath.basename(path)} is not a supported frame metadata file type (.csv or .txt)`,
     );
@@ -1141,9 +1142,11 @@ async function _ingestFilePath(
     try {
       data = await viameSerializers.parseFile(path, imageMap);
     } catch (e) {
-      // A plain CSV that fails to parse as annotations is often frame metadata: hint at the
-      // explicit import path.
-      throw new Error(`${(e as Error).message} If this file is frame metadata rather than annotations, use the Import button's Frame Metadata option.`);
+      // A plain CSV that fails to parse as annotations is often frame metadata. This parse
+      // runs during initial dataset import (before a viewer exists) as well as in-viewer, so
+      // offer both remedies: the rename convention is actionable pre-import, the Import button
+      // once the dataset is open.
+      throw new Error(`${(e as Error).message} If this file is frame metadata rather than annotations, import it with the Import button's Frame Metadata option, or rename it to frame-metadata.csv and re-upload.`);
     }
     annotations.tracks = data[0].tracks;
     annotations.groups = data[0].groups;
diff --git a/client/platform/desktop/frontend/api.ts b/client/platform/desktop/frontend/api.ts
index 42598dfc3..9eb63f109 100644
--- a/client/platform/desktop/frontend/api.ts
+++ b/client/platform/desktop/frontend/api.ts
@@ -257,7 +257,7 @@ function importAnnotationFile(id: string, path: string, _htmlFile = undefined, a
 }
 
 // eslint-disable-next-line @typescript-eslint/no-unused-vars
-function importFrameMetadataFile(id: string, path: string, _htmlFile = undefined): Promise<boolean | string[]> {
+function importFrameMetadataFile(id: string, path: string, _htmlFile = undefined): Promise<boolean> {
   return window.diveDesktop.invoke('import-frame-metadata', { id, path });
 }
 
diff --git a/client/platform/desktop/frontend/components/ViewerLoader.vue b/client/platform/desktop/frontend/components/ViewerLoader.vue
index edc887870..036eda6b7 100644
--- a/client/platform/desktop/frontend/components/ViewerLoader.vue
+++ b/client/platform/desktop/frontend/components/ViewerLoader.vue
@@ -1893,6 +1893,7 @@ export default defineComponent({
         <ImportAnnotations
           :dataset-id="modifiedId"
           :sub-type="subTypeList[0]"
+          :media-type="datasets[id] && datasets[id].type"
           :calibration-file="datasets[id] && datasets[id].calibration"
           v-bind="{ buttonOptions, menuOptions, readOnlyMode }"
           block-on-unsaved
diff --git a/client/platform/web-girder/api/dataset.service.ts b/client/platform/web-girder/api/dataset.service.ts
index 40ff31235..0b568a3d0 100644
--- a/client/platform/web-girder/api/dataset.service.ts
+++ b/client/platform/web-girder/api/dataset.service.ts
@@ -8,7 +8,7 @@ import {
   DatasetMetaMutable, DatasetType, FrameImage,
   SaveAttributeArgs, SaveAttributeTrackFilterArgs,
 } from 'dive-common/apispec';
-import { calibrationFileMarker, jsonCalibrationFileMarker } from 'dive-common/constants';
+import { calibrationFileMarker, frameMetadataItemMarker, jsonCalibrationFileMarker } from 'dive-common/constants';
 import { attachFrameTimestamps } from 'dive-common/frameTimestamp';
 import { parentDatasetId } from 'dive-common/compositeDatasetId';
 import { isStereoCalibrationFileName } from 'dive-common/stereoParentFolder';
@@ -136,10 +136,12 @@ function makeViameFolder({
   );
 }
 
-async function importAnnotationFile(parentId: string, path: string, file?: HTMLFile, additive = false, additivePrepend = '', set: string | undefined = undefined): Promise<boolean | string[]> {
-  if (file === undefined) {
-    return false;
-  }
+/**
+ * Girder's two-request upload to a folder: initialize the file, then push its single chunk.
+ * Resolves with the completed file document (which carries `itemId`, the id of the item
+ * Girder created for it) or null if either request did not succeed.
+ */
+async function uploadFileToFolder(parentId: string, file: File): Promise<{ itemId: string } | null> {
   const resp = await girderRest.post('/file', null, {
     params: {
       parentType: 'folder',
@@ -149,63 +151,73 @@ async function importAnnotationFile(parentId: string, path: string, file?: HTMLF
       mimeType: file.type,
     },
   });
-  if (resp.status === 200) {
-    const uploadResponse = await girderRest.post('file/chunk', file, {
-      params: {
-        uploadId: resp.data._id,
-        offset: 0,
-      },
-      headers: { 'Content-Type': 'application/octet-stream' },
-    });
-    if (uploadResponse.status === 200) {
-      const final = await postProcess(parentId, true, false, additive, additivePrepend, set);
-      if (final.data.warnings !== undefined) {
-        const { warnings } = final.data;
-        return warnings;
-      }
+  if (resp.status !== 200) {
+    return null;
+  }
+  const uploadResponse = await girderRest.post('file/chunk', file, {
+    params: {
+      uploadId: resp.data._id,
+      offset: 0,
+    },
+    headers: { 'Content-Type': 'application/octet-stream' },
+  });
+  return uploadResponse.status === 200 ? uploadResponse.data : null;
+}
 
-      return final.status === 200;
-    }
+async function importAnnotationFile(parentId: string, path: string, file?: HTMLFile, additive = false, additivePrepend = '', set: string | undefined = undefined): Promise<boolean | string[]> {
+  if (file === undefined) {
+    return false;
   }
-  return false;
+  const uploaded = await uploadFileToFolder(parentId, file);
+  if (uploaded === null) {
+    return false;
+  }
+  const final = await postProcess(parentId, true, false, additive, additivePrepend, set);
+  if (final.data.warnings !== undefined) {
+    const { warnings } = final.data;
+    return warnings;
+  }
+  return final.status === 200;
 }
 
 async function importFrameMetadataFile(
   datasetId: string,
   path: string,
   file?: HTMLFile,
-): Promise<boolean | string[]> {
-  if (file === undefined) {
+): Promise<boolean> {
+  if (file === undefined || file.size === 0) {
     return false;
   }
   // Frame metadata always lands on the parent dataset folder: for multicam that is the
   // shared-sidecar location every camera's discovery already scans.
   const folderId = parentDatasetId(datasetId);
-  const resp = await girderRest.post('/file', null, {
-    params: {
-      parentType: 'folder',
-      parentId: folderId,
-      name: file.name,
-      size: file.size,
-      mimeType: file.type,
-    },
+  // Re-import replaces in place (matching desktop, which overwrites the sidecar): delete any
+  // prior declared sidecar of the same name first so the new upload keeps its name instead
+  // of colliding into "name (1)". Only declared sidecars are removed; a same-named pending
+  // annotation CSV carries no marker and is left untouched.
+  const { data: siblings } = await girderRest.get<{ _id: string; name: string; meta?: Record<string, unknown> }[]>('item', {
+    params: { folderId, name: file.name },
   });
-  if (resp.status === 200) {
-    const uploadResponse = await girderRest.post('file/chunk', file, {
-      params: {
-        uploadId: resp.data._id,
-        offset: 0,
-      },
-      headers: { 'Content-Type': 'application/octet-stream' },
-    });
-    if (uploadResponse.status === 200) {
-      // The declaration rides on postprocess: the server marks the named item as frame
-      // metadata before its annotation sweep, so the file is never parsed or moved.
-      const final = await postProcess(folderId, true, false, false, '', undefined, [file.name]);
-      return final.status === 200;
-    }
+  await Promise.all(
+    siblings
+      .filter((item) => item.name === file.name && item.meta?.[frameMetadataItemMarker])
+      .map((item) => girderRest.delete(`item/${item._id}`)),
+  );
+  const uploaded = await uploadFileToFolder(folderId, file);
+  if (uploaded === null) {
+    return false;
+  }
+  try {
+    // The declaration rides on postprocess: the server marks the uploaded item as frame
+    // metadata by id before its annotation sweep, so the file is never parsed or moved.
+    const final = await postProcess(folderId, true, false, false, '', undefined, [uploaded.itemId]);
+    return final.status === 200;
+  } catch (error) {
+    // A rejected declaration (e.g. wrong media type) would otherwise strand the upload for
+    // the next annotation sweep to misclassify and delete; remove it so the folder stays clean.
+    await girderRest.delete(`item/${uploaded.itemId}`).catch(() => undefined);
+    throw error;
   }
-  return false;
 }
 
 async function saveAttributes(datasetId: string, args: SaveAttributeArgs) {
diff --git a/client/platform/web-girder/api/rpc.service.ts b/client/platform/web-girder/api/rpc.service.ts
index e8016534a..a46040711 100644
--- a/client/platform/web-girder/api/rpc.service.ts
+++ b/client/platform/web-girder/api/rpc.service.ts
@@ -2,7 +2,7 @@ import girderRest from 'platform/web-girder/plugins/girder';
 import type { GirderModel } from '@girder/components/src';
 import type { Pipe, PipelineParams } from 'dive-common/apispec';
 
-function postProcess(folderId: string, skipJobs = false, skipTranscoding = false, additive = false, additivePrepend = '', set: string | undefined = undefined, frameMetadataNames: string[] | undefined = undefined) {
+function postProcess(folderId: string, skipJobs = false, skipTranscoding = false, additive = false, additivePrepend = '', set: string | undefined = undefined, frameMetadataItemIds: string[] | undefined = undefined) {
   return girderRest.post<{folder: GirderModel, warnings: string[], job_ids: string[]}>(`dive_rpc/postprocess/${folderId}`, null, {
     params: {
       skipJobs,
@@ -11,7 +11,7 @@ function postProcess(folderId: string, skipJobs = false, skipTranscoding = false
       additivePrepend,
       set,
       // A json-typed girder param must arrive as one JSON string, not repeated keys.
-      frameMetadataNames: frameMetadataNames ? JSON.stringify(frameMetadataNames) : undefined,
+      frameMetadataItemIds: frameMetadataItemIds ? JSON.stringify(frameMetadataItemIds) : undefined,
     },
   });
 }
diff --git a/client/platform/web-girder/utils.ts b/client/platform/web-girder/utils.ts
index dfe8f6dc5..3e8488525 100644
--- a/client/platform/web-girder/utils.ts
+++ b/client/platform/web-girder/utils.ts
@@ -1,6 +1,6 @@
 import { UploadManager, Location } from '@girder/components/src';
 import {
-  calibrationFileTypes, inputAnnotationFileTypes, inputAnnotationTypes,
+  calibrationFileTypes, frameMetadataFileTypes, inputAnnotationFileTypes, inputAnnotationTypes,
   getLargeImageAllowedExtensions, getLargeImageFileAccept,
   otherImageTypes, otherVideoTypes, transformFileTypes,
   websafeImageTypes, websafeVideoTypes, zipFileTypes,
@@ -66,7 +66,7 @@ async function openFromDisk(
     input.accept = inputAnnotationTypes
       .concat(inputAnnotationFileTypes.map((item) => `.${item}`)).join(',');
   } else if (datasetType === 'frameMetadata') {
-    input.accept = '.csv,.txt';
+    input.accept = frameMetadataFileTypes.map((item) => `.${item}`).join(',');
   } else if (datasetType === 'zip') {
     input.accept = zipFileTypes.map((item) => `.${item}`).join(',');
   } else if (datasetType === 'transform') {
@@ -90,7 +90,11 @@ async function openFromDisk(
           } else if (datasetType === 'frameMetadata') {
             // Extension check, not MIME: Windows browsers report CSV as
             // application/vnd.ms-excel and delimited text as text/plain.
-            if (!fileList.every((item) => /\.(csv|txt)$/i.test(item.name))) {
+            const allowed = new Set(frameMetadataFileTypes.map((ext) => ext.toLowerCase()));
+            if (!fileList.every((item) => {
+              const ext = item.name.split('.').pop()?.toLowerCase();
+              return ext !== undefined && allowed.has(ext);
+            })) {
               reject(new Error('File types did not match CSV or TXT'));
             }
           } else if (datasetType === 'large-image') {
diff --git a/client/platform/web-girder/views/ViewerLoader.vue b/client/platform/web-girder/views/ViewerLoader.vue
index e3cdac25c..4f58320e8 100644
--- a/client/platform/web-girder/views/ViewerLoader.vue
+++ b/client/platform/web-girder/views/ViewerLoader.vue
@@ -350,6 +350,7 @@ export default defineComponent({
         :read-only-mode="!!jobs.getDatasetRunningState(id) || revisionNum !== undefined"
         :dataset-id="id"
         :sub-type="subTypeList[0]"
+        :media-type="typeList[0]"
         :calibration-file="calibrationFile"
         block-on-unsaved
         @calibration-imported="onCalibrationImported"
diff --git a/server/dive_server/crud_dataset.py b/server/dive_server/crud_dataset.py
index 7faddca56..615221d53 100644
--- a/server/dive_server/crud_dataset.py
+++ b/server/dive_server/crud_dataset.py
@@ -418,22 +418,30 @@ def get_media(
 def _frame_metadata_source_items(
     folder: types.GirderModel,
 ) -> List[Dict[str, str]]:
-    """List a folder's declared sidecar items as {itemId, name}, name-sorted (no download).
+    """List a folder's declared sidecar items as {itemId, name}, marker items first (no download).
 
     A sidecar is declared either by the reserved basename or by the explicit-import item
-    marker. Only identity is resolved here: the server classifies sidecars by declaration
-    and never reads, parses, or joins them. The client downloads and parses the bytes at
-    read time.
+    marker. Explicitly imported (marker-declared) sidecars are listed ahead of reserved-name
+    ones so the client's column-level first-wins resolver honors an imported file over the
+    convention-named sidecars it shares a folder with -- matching desktop's declared-first
+    order and the Frame-Metadata docs. Ties within a tier are name-sorted. Only identity is
+    resolved here: the server classifies sidecars by declaration and never reads, parses, or
+    joins them. The client downloads and parses the bytes at read time.
     """
     items = [
         item
         for item in Folder().childItems(folder)
-        if frame_metadata.is_frame_metadata_source_name(item['name'])
-        or asbool(fromMeta(item, constants.FrameMetadataMarker))
+        if frame_metadata.is_declared_frame_metadata(item)
     ]
     return [
         {'itemId': str(item['_id']), 'name': item['name']}
-        for item in sorted(items, key=lambda entry: str(entry['name']).lower())
+        for item in sorted(
+            items,
+            key=lambda entry: (
+                not asbool(fromMeta(entry, constants.FrameMetadataMarker)),
+                str(entry['name']).lower(),
+            ),
+        )
     ]
 
 
diff --git a/server/dive_server/crud_rpc.py b/server/dive_server/crud_rpc.py
index 50e0d1d4e..f36a08436 100644
--- a/server/dive_server/crud_rpc.py
+++ b/server/dive_server/crud_rpc.py
@@ -523,6 +523,21 @@ def run_training(
 )
 
 
+def _frame_metadata_result() -> GetDataReturnType:
+    """The classifier result for a declared sidecar: identity only, never parsed here."""
+    return {
+        'annotations': None,
+        'meta': None,
+        'attributes': None,
+        'type': crud.FileType.FRAME_METADATA,
+    }
+
+
+def _frame_metadata_kept_warning(name: str) -> str:
+    """Notice that a file was kept as a frame-metadata sidecar rather than imported."""
+    return f'{name} was stored as frame metadata, not annotations; it stays in the dataset folder.'
+
+
 def _get_data_by_type(
     file: types.GirderModel,
     image_map: Optional[Dict[str, int]] = None,
@@ -542,12 +557,7 @@ def _get_data_by_type(
     # reading, parsing, or joining. Their content is read only at read time, by the
     # client's shared TypeScript parser, never here.
     if frame_metadata.is_frame_metadata_source_name(file['name']):
-        return {
-            'annotations': None,
-            'meta': None,
-            'attributes': None,
-            'type': crud.FileType.FRAME_METADATA,
-        }, None
+        return _frame_metadata_result(), None
     file_generator = File().download(file, headers=False)()
     # Annotation content is decoded strictly (utf-8-sig tolerates a BOM but not other
     # non-UTF-8 bytes): a decode failure surfaces as the loud "Failed to import" path.
@@ -654,39 +664,44 @@ def resolve_imported_dataset_info(existing: types.DatasetInfo, meta: dict, addit
 
 def _declare_frame_metadata_items(
     folder: types.GirderModel,
-    frameMetadataNames: List[str],
+    user: types.GirderUserModel,
+    frameMetadataItemIds: List[str],
 ) -> List[str]:
-    """Mark the named dataset-folder items as declared frame-metadata sidecars.
-
-    This is the arbitrary-name counterpart of the reserved-basename convention: the client
-    states the user's intent by name, and each matching item is marked with the frame
-    metadata marker and left in place, processed, so the annotation sweep never parses it.
-    Names are looked up directly rather than through the sweep regexes because a declared
-    ``.txt`` sidecar is never swept. Failures are loud: a declaration that cannot be
-    honored must not fall through to annotation classification.
+    """Mark the given dataset-folder items as declared frame-metadata sidecars.
+
+    This is the arbitrary-name counterpart of the reserved-basename convention. The client
+    uploads a file and then declares that exact item *by id*, so the item marked is always the
+    one just uploaded -- never a stale same-name item, nor a pending annotation CSV that
+    Girder auto-renamed the new upload past (both of which name-based lookup could mismatch).
+    Every id is validated (folder membership and supported extension) before any item is
+    marked, so a rejected request leaves no partial marks. Failures are loud: a declaration
+    that cannot be honored must not fall through to annotation classification.
     """
     dataset_type = fromMeta(folder, constants.TypeMarker)
     if dataset_type not in (constants.ImageSequenceType, constants.MultiType):
         raise RestException('Frame metadata is only supported for image-sequence datasets')
-    warnings: List[str] = []
-    for name in dict.fromkeys(frameMetadataNames):
-        if not name.lower().endswith(('.csv', '.txt')):
+    seen: set = set()
+    items: List[types.GirderModel] = []
+    for item_id in frameMetadataItemIds:
+        if not isinstance(item_id, str):
+            raise RestException('frameMetadataItemIds must be a list of item id strings')
+        if item_id in seen:
+            continue
+        seen.add(item_id)
+        item = Item().load(item_id, level=AccessType.WRITE, user=user)
+        if item is None or str(item['folderId']) != str(folder['_id']):
+            raise RestException(f'{item_id} is not an item in the dataset folder')
+        if not item['name'].lower().endswith(('.csv', '.txt')):
             raise RestException(
-                f'{name} is not a supported frame metadata file type (.csv or .txt)'
-            )
-        items = list(Folder().childItems(folder, filters={'name': name}))
-        if not items:
-            raise RestException(f'{name} was not found in the dataset folder')
-        for item in items:
-            Item().setMetadata(
-                item,
-                {constants.FrameMetadataMarker: True, constants.ProcessedMarker: True},
+                f"{item['name']} is not a supported frame metadata file type (.csv or .txt)"
             )
-        warnings.append(
-            f'{name} was stored as frame metadata, not annotations; '
-            'it stays in the dataset folder.'
+        items.append(item)
+    for item in items:
+        Item().setMetadata(
+            item,
+            {constants.FrameMetadataMarker: True, constants.ProcessedMarker: True},
         )
-    return warnings
+    return [_frame_metadata_kept_warning(item['name']) for item in items]
 
 
 def process_items(
@@ -695,15 +710,17 @@ def process_items(
     additive=False,
     additivePrepend='',
     set='',
-    frameMetadataNames: Optional[List[str]] = None,
+    frameMetadataItemIds: Optional[List[str]] = None,
 ):
     """
     Discover unprocessed items in a dataset and process them by type in order of creation
     """
-    # Declared-by-name sidecars are marked before the sweep so they drop out of
+    # Declared-by-id sidecars are marked before the sweep so they drop out of
     # unprocessed_items via the ProcessedMarker filter below.
     aggregate_warnings = (
-        _declare_frame_metadata_items(folder, frameMetadataNames) if frameMetadataNames else []
+        _declare_frame_metadata_items(folder, user, frameMetadataItemIds)
+        if frameMetadataItemIds
+        else []
     )
     unprocessed_items = list(
         Folder().childItems(
@@ -735,8 +752,7 @@ def process_items(
         item['name']
         for item in unprocessed_items
         if constants.csvRegex.search(item['name'])
-        and not frame_metadata.is_frame_metadata_source_name(item['name'])
-        and not asbool(fromMeta(item, constants.FrameMetadataMarker))
+        and not frame_metadata.is_declared_frame_metadata(item)
     )
     if len(annotation_csv_names) >= 2:
         raise RestException(
@@ -749,9 +765,7 @@ def process_items(
     # a declared sidecar is classified by name and never joined here.
     image_map = None
     if fromMeta(folder, constants.TypeMarker) == constants.ImageSequenceType and any(
-        not frame_metadata.is_frame_metadata_source_name(item['name'])
-        and not asbool(fromMeta(item, constants.FrameMetadataMarker))
-        for item in unprocessed_items
+        not frame_metadata.is_declared_frame_metadata(item) for item in unprocessed_items
     ):
         image_map = crud.valid_image_names_dict(crud.valid_images(folder, user))
 
@@ -766,12 +780,7 @@ def process_items(
         results: Optional[GetDataReturnType]
         warnings: Optional[List[str]]
         if asbool(fromMeta(item, constants.FrameMetadataMarker)):
-            results = {
-                'annotations': None,
-                'meta': None,
-                'attributes': None,
-                'type': crud.FileType.FRAME_METADATA,
-            }
+            results = _frame_metadata_result()
             warnings = None
         else:
             try:
@@ -801,10 +810,7 @@ def process_items(
             # annotations, move it, or remove it.
             item['meta'][constants.ProcessedMarker] = True
             Item().save(item)
-            aggregate_warnings.append(
-                f'{file["name"]} was stored as frame metadata, not annotations; '
-                'it stays in the dataset folder.'
-            )
+            aggregate_warnings.append(_frame_metadata_kept_warning(file['name']))
             continue
 
         if auxiliary is None:
@@ -845,7 +851,7 @@ def postprocess(
     additive=False,
     additivePrepend='',
     set='',
-    frameMetadataNames: Optional[List[str]] = None,
+    frameMetadataItemIds: Optional[List[str]] = None,
 ) -> dict:
     """
     Post-processing to be run after media/annotation import
@@ -982,7 +988,7 @@ def postprocess(
         Folder().save(dsFolder)
 
     aggregate_warnings = process_items(
-        dsFolder, user, additive, additivePrepend, set, frameMetadataNames
+        dsFolder, user, additive, additivePrepend, set, frameMetadataItemIds
     )
     return {'folder': dsFolder, 'warnings': aggregate_warnings, 'job_ids': created_job_ids}
 
diff --git a/server/dive_server/views_rpc.py b/server/dive_server/views_rpc.py
index cb35107e6..b7b07f037 100644
--- a/server/dive_server/views_rpc.py
+++ b/server/dive_server/views_rpc.py
@@ -208,8 +208,8 @@ def run_training(self, body, pipelineName, config, annotatedFramesOnly, forceTra
             required=False,
         )
         .jsonParam(
-            "frameMetadataNames",
-            "JSON list of uploaded filenames to store as declared frame metadata sidecars",
+            "frameMetadataItemIds",
+            "JSON list of uploaded item ids to declare as frame metadata sidecars",
             paramType="formData",
             requireArray=True,
             default=None,
@@ -217,7 +217,14 @@ def run_training(self, body, pipelineName, config, annotatedFramesOnly, forceTra
         )
     )
     def postprocess(
-        self, folder, skipJobs, skipTranscoding, additive, additivePrepend, set, frameMetadataNames
+        self,
+        folder,
+        skipJobs,
+        skipTranscoding,
+        additive,
+        additivePrepend,
+        set,
+        frameMetadataItemIds,
     ):
         return crud_rpc.postprocess(
             self.getCurrentUser(),
@@ -227,7 +234,7 @@ def postprocess(
             additive,
             additivePrepend,
             set,
-            frameMetadataNames,
+            frameMetadataItemIds,
         )
 
     @access.user
diff --git a/server/dive_utils/frame_metadata.py b/server/dive_utils/frame_metadata.py
index b57318e4d..d9c7c65b8 100644
--- a/server/dive_utils/frame_metadata.py
+++ b/server/dive_utils/frame_metadata.py
@@ -9,6 +9,8 @@
 
 import re
 
+from dive_utils import asbool, constants, fromMeta
+
 FRAME_METADATA_SOURCE_NAMES = {
     'frame-metadata.csv',
     'frame-metadata.txt',
@@ -22,3 +24,14 @@ def is_frame_metadata_source_name(name: str) -> bool:
     """A frame metadata sidecar is declared by basename."""
     basename = PATH_SPLIT_RE.split(name)[-1]
     return basename.lower() in FRAME_METADATA_SOURCE_NAMES
+
+
+def is_declared_frame_metadata(item: dict) -> bool:
+    """A folder item is a declared frame-metadata sidecar.
+
+    Declared either by the reserved basename or by the explicit-import item marker. Both
+    the discovery path and the annotation sweep exclude these from annotation classification.
+    """
+    return is_frame_metadata_source_name(item['name']) or asbool(
+        fromMeta(item, constants.FrameMetadataMarker)
+    )
diff --git a/server/tests/test_frame_metadata_sources.py b/server/tests/test_frame_metadata_sources.py
index efbbddbde..f5fe75eb0 100644
--- a/server/tests/test_frame_metadata_sources.py
+++ b/server/tests/test_frame_metadata_sources.py
@@ -187,12 +187,13 @@ def test_sources_include_marker_declared_items(get_clone_root, folder_cls):
 
     result = crud_dataset.load_frame_metadata_sources(dataset, user)
 
-    # Marker- and name-declared sidecars list together, name-sorted.
+    # The explicitly imported (marker-declared) sidecar precedes reserved-name ones so it
+    # wins column conflicts in the client's first-wins resolver, matching desktop and docs.
     assert result == {
         'cameras': {
             'singleCam': [
-                _descriptor('frame-metadata.csv'),
                 _descriptor('nav_2024.csv'),
+                _descriptor('frame-metadata.csv'),
             ],
         },
     }
diff --git a/server/tests/test_process_items.py b/server/tests/test_process_items.py
index 033693aa3..73fdd8a5f 100644
--- a/server/tests/test_process_items.py
+++ b/server/tests/test_process_items.py
@@ -168,15 +168,18 @@ def test_two_plain_csvs_in_folder_side_door_guard(
 
 
 def _wire_declared_lookup(folder_cls, item_cls, all_items):
-    """Emulate the two childItems query shapes plus a mutating setMetadata.
+    """Emulate declare-by-id (Item().load) plus a mutating setMetadata and the sweep query.
 
-    The declaration pass looks items up by exact name; the sweep uses the $and regex/marker
-    filter, emulated here as "unswept csv/json/yml items not yet marked processed".
+    Declaration now loads each item by id; the sweep uses the $and regex/marker filter,
+    emulated here as "unswept csv/json/yml items not yet marked processed" — a just-marked
+    sidecar drops out of it via its ProcessedMarker.
     """
+    items_by_id = {item['_id']: item for item in all_items}
+
+    def load_item(item_id, level=None, user=None):
+        return items_by_id.get(item_id)
 
     def child_items(_folder, filters=None, sort=None):
-        if filters and 'name' in filters:
-            return [item for item in all_items if item['name'] == filters['name']]
         return [
             item
             for item in all_items
@@ -189,6 +192,7 @@ def set_metadata(item, metadata):
         return item
 
     folder_cls.return_value.childItems.side_effect = child_items
+    item_cls.return_value.load.side_effect = load_item
     item_cls.return_value.setMetadata.side_effect = set_metadata
 
 
@@ -197,19 +201,17 @@ def set_metadata(item, metadata):
 @patch('dive_server.crud_rpc.File')
 @patch('dive_server.crud_rpc.Item')
 @patch('dive_server.crud_rpc.Folder')
-def test_declared_frame_metadata_names_are_marked_and_kept(
+def test_declared_frame_metadata_items_are_marked_and_kept(
     folder_cls, item_cls, file_cls, get_auxiliary_folder, save_annotations
 ):
-    # Arbitrary-named sidecars declared through frameMetadataNames are marked and left in
+    # Arbitrary-named sidecars declared through frameMetadataItemIds are marked and left in
     # place — including .txt, which the sweep regexes never even list.
     folder = {'_id': 'ds', 'meta': {'type': constants.ImageSequenceType, 'fps': 5}}
-    item_csv = {'_id': 'a', 'name': 'nav_2024.csv', 'meta': {}}
-    item_txt = {'_id': 'b', 'name': 'nav_2024.txt', 'meta': {}}
+    item_csv = {'_id': 'a', 'folderId': 'ds', 'name': 'nav_2024.csv', 'meta': {}}
+    item_txt = {'_id': 'b', 'folderId': 'ds', 'name': 'nav_2024.txt', 'meta': {}}
     _wire_declared_lookup(folder_cls, item_cls, [item_csv, item_txt])
 
-    warnings = process_items(
-        folder, {'_id': 'user-id'}, frameMetadataNames=['nav_2024.csv', 'nav_2024.txt']
-    )
+    warnings = process_items(folder, {'_id': 'user-id'}, frameMetadataItemIds=['a', 'b'])
 
     assert len(warnings) == 2
     assert all('stays in the dataset folder' in warning for warning in warnings)
@@ -224,49 +226,74 @@ def test_declared_frame_metadata_names_are_marked_and_kept(
 
 @patch('dive_server.crud_rpc.Item')
 @patch('dive_server.crud_rpc.Folder')
-def test_declared_name_missing_from_folder_raises(folder_cls, item_cls):
+def test_declared_item_missing_from_folder_raises(folder_cls, item_cls):
     folder = {'_id': 'ds', 'meta': {'type': constants.ImageSequenceType, 'fps': 5}}
+    # An id that loads nothing (or an item in another folder) is not in this dataset folder.
     _wire_declared_lookup(folder_cls, item_cls, [])
 
-    with pytest.raises(RestException, match='was not found in the dataset folder'):
-        process_items(folder, {'_id': 'user-id'}, frameMetadataNames=['nav_2024.csv'])
+    with pytest.raises(RestException, match='is not an item in the dataset folder'):
+        process_items(folder, {'_id': 'user-id'}, frameMetadataItemIds=['missing-id'])
+    item_cls.return_value.setMetadata.assert_not_called()
+
+
+@patch('dive_server.crud_rpc.Item')
+@patch('dive_server.crud_rpc.Folder')
+def test_declared_item_in_other_folder_raises(folder_cls, item_cls):
+    folder = {'_id': 'ds', 'meta': {'type': constants.ImageSequenceType, 'fps': 5}}
+    stray = {'_id': 'a', 'folderId': 'other', 'name': 'nav_2024.csv', 'meta': {}}
+    _wire_declared_lookup(folder_cls, item_cls, [stray])
+
+    with pytest.raises(RestException, match='is not an item in the dataset folder'):
+        process_items(folder, {'_id': 'user-id'}, frameMetadataItemIds=['a'])
     item_cls.return_value.setMetadata.assert_not_called()
 
 
 @patch('dive_server.crud_rpc.Item')
 @patch('dive_server.crud_rpc.Folder')
-def test_declared_name_unsupported_extension_raises(folder_cls, item_cls):
+def test_declared_item_unsupported_extension_raises(folder_cls, item_cls):
     folder = {'_id': 'ds', 'meta': {'type': constants.ImageSequenceType, 'fps': 5}}
-    item = {'_id': 'a', 'name': 'nav.json', 'meta': {}}
+    item = {'_id': 'a', 'folderId': 'ds', 'name': 'nav.json', 'meta': {}}
     _wire_declared_lookup(folder_cls, item_cls, [item])
 
     with pytest.raises(RestException, match='not a supported frame metadata file type'):
-        process_items(folder, {'_id': 'user-id'}, frameMetadataNames=['nav.json'])
+        process_items(folder, {'_id': 'user-id'}, frameMetadataItemIds=['a'])
     item_cls.return_value.setMetadata.assert_not_called()
 
 
+@patch('dive_server.crud_rpc.Item')
+@patch('dive_server.crud_rpc.Folder')
+def test_declared_item_non_string_id_raises(folder_cls, item_cls):
+    folder = {'_id': 'ds', 'meta': {'type': constants.ImageSequenceType, 'fps': 5}}
+    _wire_declared_lookup(folder_cls, item_cls, [])
+
+    # A scripted client could send a non-string element; reject it as a 400, not a 500.
+    with pytest.raises(RestException, match='list of item id strings'):
+        process_items(folder, {'_id': 'user-id'}, frameMetadataItemIds=[{'not': 'a string'}])
+    item_cls.return_value.load.assert_not_called()
+
+
 @pytest.mark.parametrize('dataset_type', [constants.VideoType, constants.LargeImageType])
 @patch('dive_server.crud_rpc.Item')
 @patch('dive_server.crud_rpc.Folder')
-def test_declared_names_rejected_for_unsupported_media_type(folder_cls, item_cls, dataset_type):
+def test_declared_items_rejected_for_unsupported_media_type(folder_cls, item_cls, dataset_type):
     folder = {'_id': 'ds', 'meta': {'type': dataset_type, 'fps': 5}}
-    item = {'_id': 'a', 'name': 'nav_2024.csv', 'meta': {}}
+    item = {'_id': 'a', 'folderId': 'ds', 'name': 'nav_2024.csv', 'meta': {}}
     _wire_declared_lookup(folder_cls, item_cls, [item])
 
     with pytest.raises(RestException, match='only supported for image-sequence'):
-        process_items(folder, {'_id': 'user-id'}, frameMetadataNames=['nav_2024.csv'])
+        process_items(folder, {'_id': 'user-id'}, frameMetadataItemIds=['a'])
     item_cls.return_value.setMetadata.assert_not_called()
 
 
 @patch('dive_server.crud_rpc.Item')
 @patch('dive_server.crud_rpc.Folder')
-def test_declared_names_allowed_for_multicam_parent(folder_cls, item_cls):
+def test_declared_items_allowed_for_multicam_parent(folder_cls, item_cls):
     # A declaration on the multicam parent folder is the shared-sidecar path.
     folder = {'_id': 'parent', 'meta': {'type': constants.MultiType, 'fps': 5}}
-    item = {'_id': 'a', 'name': 'nav_2024.csv', 'meta': {}}
+    item = {'_id': 'a', 'folderId': 'parent', 'name': 'nav_2024.csv', 'meta': {}}
     _wire_declared_lookup(folder_cls, item_cls, [item])
 
-    warnings = process_items(folder, {'_id': 'user-id'}, frameMetadataNames=['nav_2024.csv'])
+    warnings = process_items(folder, {'_id': 'user-id'}, frameMetadataItemIds=['a'])
 
     assert len(warnings) == 1
     assert item['meta'][constants.FrameMetadataMarker] is True