Polish dataset catalog role density

CHANGELOG.md

@@ -7,6 +7,14 @@
 
 # Changelog
 
+## Sprint 68 Data catalog density polish (2026-06-19)
+
+- Added a compact Data catalog summary for Selected, Reference, Candidate and Source layers.
+- Added scan-friendly dataset role badges, source/layer/CRS context and safer title wrapping to dataset cards.
+- Kept candidate as a frontend workbench display role only: persisted dataset roles and API contracts remain unchanged.
+- Added static regression coverage for the dataset catalog density structure and responsive CSS.
+- No API contracts, migrations, backend behavior, provider fetching or AI model behavior changed.
+
 ## Sprint 63 Map overlay ergonomics (2026-06-18)
 
 - Added an active layer provenance rail to the Map workspace, showing layer source, provenance and draw state from existing frontend state.

backend/tests/test_sprint68_dataset_catalog_density.py

@@ -0,0 +1,45 @@
+from pathlib import Path
+
+
+ROOT = Path(__file__).resolve().parents[2]
+
+
+def test_dataset_panel_surfaces_role_summary_and_badges() -> None:
+    dataset_panel = (ROOT / "frontend" / "src" / "components" / "datasets" / "DatasetPanel.tsx").read_text(
+        encoding="utf-8"
+    )
+
+    assert "roleSummaries" in dataset_panel
+    assert "dataset-role-summary-grid" in dataset_panel
+    assert "Selected" in dataset_panel
+    assert "Reference" in dataset_panel
+    assert "Candidate" in dataset_panel
+    assert "Source" in dataset_panel
+    assert "dataset-role-badge" in dataset_panel
+    assert "dataset-role-selected" in dataset_panel
+    assert "dataset-role-reference" in dataset_panel
+    assert "dataset-role-candidate" in dataset_panel
+    assert "dataset-role-source" in dataset_panel
+
+
+def test_dataset_cards_expose_scan_friendly_source_and_crs_context() -> None:
+    dataset_panel = (ROOT / "frontend" / "src" / "components" / "datasets" / "DatasetPanel.tsx").read_text(
+        encoding="utf-8"
+    )
+
+    assert "dataset-card-kicker" in dataset_panel
+    assert "Source: {dataset.source_name ?? dataset.source}" in dataset_panel
+    assert "Layer: {dataset.reference_layer_name}" in dataset_panel
+    assert "CRS: {dataset.crs ?? dataset.vector_summary?.crs ?? 'n/a'}" in dataset_panel
+    assert "dataset-card-title" in dataset_panel
+
+
+def test_dataset_catalog_density_styles_are_responsive() -> None:
+    css = (ROOT / "frontend" / "src" / "styles" / "app.css").read_text(encoding="utf-8")
+
+    assert ".dataset-role-summary-grid" in css
+    assert "repeat(auto-fit, minmax(8.5rem, 1fr))" in css
+    assert ".dataset-role-badge" in css
+    assert ".dataset-role-selected" in css
+    assert ".dataset-card-kicker" in css
+    assert ".dataset-card-title" in css

docs/CODEX_EXECUTION_LOG.md

@@ -2573,3 +2573,31 @@ Limitations:
 
 Next recommended pass:
 - Continue with Data catalog density polish, especially making selected/reference/candidate dataset roles easier to scan in populated demo projects.
+
+## Sprint 68 Data catalog density polish (2026-06-19)
+
+Changed:
+- Added a compact role summary to the Data catalog for Selected, Reference, Candidate and Source datasets.
+- Added scan-friendly dataset card badges plus source, reference layer and CRS context.
+- Treated non-reference vector/GeoJSON datasets as QA Candidate display roles in the frontend only, preserving persisted `dataset_role` values and API contracts.
+- Added responsive role-summary and role-badge CSS.
+- Added `backend/tests/test_sprint68_dataset_catalog_density.py`.
+- Updated `frontend/README.md`, `docs/TODO.md` and `CHANGELOG.md`.
+
+Tested:
+- Red step: `python -m pytest backend/tests/test_sprint68_dataset_catalog_density.py -q` failed on missing role summary, role badges and responsive CSS.
+- `python -m pytest backend/tests/test_sprint68_dataset_catalog_density.py backend/tests/test_sprint67_map_empty_state_quick_actions.py backend/tests/test_sprint30_workbench_components.py -q` (`10 passed`)
+- `cd frontend && npm run typecheck`
+- `cd frontend && npm run build`
+- Local browser check against `http://127.0.0.1:5175` with live API proxy: Data workspace showed Selected, Reference, Candidate and Source summary cards, with 1 Reference, 1 Candidate and 0 Source in the demo catalog; dataset badges rendered correctly on desktop and mobile, no console warnings/errors and no horizontal overflow.
+- Screenshots captured under `artifacts/sprint68-dataset-catalog-density/`.
+- `bash scripts/run_readiness_check.sh` (`243 passed`)
+
+Open:
+- Run full readiness, redeploy Tower and verify the live Data catalog after deployment.
+
+Limitations:
+- This is a frontend density/readability pass only. It does not change dataset persistence, backend role validation, API contracts, migrations, provider fetching or AI/model behavior.
+
+Next recommended pass:
+- Continue with Data workspace action polish, especially making QA/export affordances clearer once candidate and reference layers are present.

docs/TODO.md

@@ -339,3 +339,4 @@ This file now starts with the current implementation status. Older preparation/b
 - [x] Add export/report handoff polish for artifact readiness, action grouping and export provenance.
 - [x] Polish lightweight HTML project report readability, print styling and handoff sections.
 - [x] Add Map empty-state quick actions for ready vector datasets.
+- [x] Add Data catalog role-density polish for reference/candidate/source scanning.

frontend/README.md

@@ -235,6 +235,7 @@ The workbench now uses a task-based shell instead of a single long panel stack.
 - Mobile workbench navigation uses horizontal rails for the primary nav and command bar, avoiding a tall menu stack before the active workspace content.
 - The Map workspace shows active layer source/provenance/draw-state context and selected-feature property chips before the raw JSON inspector.
 - When the Map workspace has no active result layer, it lists ready vector/GeoJSON datasets as direct quick actions so populated demo projects can jump straight from the empty state to map inspection.
+- The Data catalog shows a compact selected/reference/candidate/source summary and scan-friendly badges. Persisted `reference` datasets are shown as Reference, non-reference vector/GeoJSON layers are shown as QA Candidates for workbench scanning, and raster/other uploads remain Source.
 
 ## Raster dependency visibility
 

frontend/src/components/datasets/DatasetPanel.tsx

@@ -53,6 +53,30 @@ function formatBounds(bounds: Record<string, number> | null | undefined): string
   return `${bounds.min_x?.toFixed(4)}, ${bounds.min_y?.toFixed(4)} -> ${bounds.max_x?.toFixed(4)}, ${bounds.max_y?.toFixed(4)}`
 }
 
+function isVectorDatasetType(datasetType: string): boolean {
+  return datasetType === 'vector' || datasetType === 'geojson'
+}
+
+function normalizeDatasetRole(dataset: DatasetCreateResponse): 'reference' | 'candidate' | 'source' {
+  if (dataset.dataset_role === 'reference') {
+    return 'reference'
+  }
+  if (dataset.dataset_role === 'derived' || isVectorDatasetType(dataset.dataset_type)) {
+    return 'candidate'
+  }
+  return 'source'
+}
+
+function datasetRoleLabel(role: string): string {
+  if (role === 'reference') {
+    return 'Reference'
+  }
+  if (role === 'candidate') {
+    return 'Candidate'
+  }
+  return 'Source'
+}
+
 export function DatasetPanel({
   selectedProjectId,
   selectedDatasetId,
@@ -68,6 +92,36 @@ export function DatasetPanel({
   onOpenDatasetExport,
 }: DatasetPanelProps) {
   const readyDatasets = datasets.filter((dataset) => dataset.status === 'ready').length
+  const roleSummaries = [
+    {
+      key: 'selected',
+      label: 'Selected',
+      count: selectedDatasetId ? 1 : 0,
+      hint: 'Active',
+      className: 'dataset-role-selected',
+    },
+    {
+      key: 'reference',
+      label: 'Reference',
+      count: datasets.filter((dataset) => normalizeDatasetRole(dataset) === 'reference').length,
+      hint: 'QA truth',
+      className: 'dataset-role-reference',
+    },
+    {
+      key: 'candidate',
+      label: 'Candidate',
+      count: datasets.filter((dataset) => normalizeDatasetRole(dataset) === 'candidate').length,
+      hint: 'QA candidate',
+      className: 'dataset-role-candidate',
+    },
+    {
+      key: 'source',
+      label: 'Source',
+      count: datasets.filter((dataset) => normalizeDatasetRole(dataset) === 'source').length,
+      hint: 'Uploads',
+      className: 'dataset-role-source',
+    },
+  ]
 
   return (
     <section className="workspace-panel" data-testid="dataset-panel">
@@ -126,6 +180,16 @@ export function DatasetPanel({
         </button>
       </form>
 
+      <div className="dataset-role-summary-grid" aria-label="Dataset role summary">
+        {roleSummaries.map((summary) => (
+          <div className={`dataset-role-summary ${summary.className}`} key={summary.key}>
+            <span>{summary.label}</span>
+            <strong>{summary.count}</strong>
+            <small>{summary.hint}</small>
+          </div>
+        ))}
+      </div>
+
       {loadingDatasets ? <p>Loading datasets...</p> : null}
       {datasets.length === 0 ? (
         <div className="empty-state">
@@ -134,57 +198,65 @@ export function DatasetPanel({
         </div>
       ) : null}
       <ul className="dataset-list">
-        {datasets.map((dataset) => (
+        {datasets.map((dataset) => {
-          <li className={dataset.id === selectedDatasetId ? 'dataset-card dataset-card-active' : 'dataset-card'} key={dataset.id}>
+          const datasetRole = normalizeDatasetRole(dataset)
-            <div className="dataset-card-header">
+          const roleLabel = datasetRoleLabel(datasetRole)
-              <div>
+          return (
-                <strong>{dataset.name}</strong>
+            <li className={dataset.id === selectedDatasetId ? 'dataset-card dataset-card-active' : 'dataset-card'} key={dataset.id}>
-                <div className="entity-meta">
+              <div className="dataset-card-header">
-                  <span>{dataset.dataset_type}</span>
+                <div>
-                  <span>{dataset.dataset_role ?? 'source'}</span>
+                  <div className="dataset-card-kicker">
-                  <span>{dataset.status}</span>
+                    <span className={`dataset-role-badge dataset-role-${datasetRole}`}>{roleLabel}</span>
+                    <span>{dataset.dataset_type}</span>
+                  </div>
+                  <strong className="dataset-card-title">{dataset.name}</strong>
+                  <div className="entity-meta">
+                    <span>Source: {dataset.source_name ?? dataset.source}</span>
+                    {dataset.reference_layer_name ? <span>Layer: {dataset.reference_layer_name}</span> : null}
+                    <span>CRS: {dataset.crs ?? dataset.vector_summary?.crs ?? 'n/a'}</span>
+                  </div>
                 </div>
+                <span className={dataset.status === 'ready' ? 'status-badge status-badge-ready' : 'status-badge'}>
+                  {dataset.status === 'ready' ? 'ready' : dataset.status === 'failed' ? 'failed' : 'pending'}
+                </span>
               </div>
-              <span className={dataset.status === 'ready' ? 'status-badge status-badge-ready' : 'status-badge'}>
+              <div className="dataset-metrics data-density-grid">
-                {dataset.status === 'ready' ? 'ready' : dataset.status === 'failed' ? 'failed' : 'pending'}
+                <span>size: {formatBytes(dataset.size_bytes)}</span>
-              </span>
+                <span>features: {dataset.feature_count ?? dataset.vector_summary?.feature_count ?? 'n/a'}</span>
-            </div>
+                <span>bbox: {formatBounds(dataset.bounds_json ?? dataset.vector_summary?.bounds_json)}</span>
-            <div className="dataset-metrics data-density-grid">
+              </div>
-              <span>size: {formatBytes(dataset.size_bytes)}</span>
+              <div className="button-row">
-              <span>features: {dataset.feature_count ?? dataset.vector_summary?.feature_count ?? 'n/a'}</span>
+                <button
-              <span>bbox: {formatBounds(dataset.bounds_json ?? dataset.vector_summary?.bounds_json)}</span>
+                  className="primary-action"
-            </div>
+                  type="button"
-            <div className="button-row">
+                  onClick={() => onLoadDatasetDetails(selectedProjectId ?? '', dataset)}
-              <button
+                  data-testid={`dataset-select-${dataset.id}`}
-                className="primary-action"
+                >
-                type="button"
+                  Select / details
-                onClick={() => onLoadDatasetDetails(selectedProjectId ?? '', dataset)}
+                </button>
-                data-testid={`dataset-select-${dataset.id}`}
+                <button className="secondary-action" type="button" onClick={() => onOpenDatasetInMap(dataset)}>
-              >
+                  Open in map
-                Select / details
+                </button>
-              </button>
+                <button
-              <button className="secondary-action" type="button" onClick={() => onOpenDatasetInMap(dataset)}>
+                  className="secondary-action"
-                Open in map
+                  type="button"
-              </button>
+                  onClick={() => onOpenDatasetExport(dataset)}
-              <button
+                  disabled={!(dataset.dataset_type === 'vector' || dataset.dataset_type === 'geojson')}
-                className="secondary-action"
+                >
-                type="button"
+                  Export / QA
-                onClick={() => onOpenDatasetExport(dataset)}
+                </button>
-                disabled={!(dataset.dataset_type === 'vector' || dataset.dataset_type === 'geojson')}
+                <button
-              >
+                  className="secondary-action"
-                Export / QA
+                  type="button"
-              </button>
+                  onClick={() => onRefreshMetadata(dataset.id)}
-              <button
+                  disabled={dataset.dataset_type === 'raster'}
-                className="secondary-action"
+                >
-                type="button"
+                  Refresh metadata
-                onClick={() => onRefreshMetadata(dataset.id)}
+                </button>
-                disabled={dataset.dataset_type === 'raster'}
+              </div>
-              >
+            </li>
-                Refresh metadata
+          )
-              </button>
+        })}
-            </div>
-          </li>
-        ))}
       </ul>
     </section>
   )

frontend/src/styles/app.css

@@ -946,6 +946,61 @@ section th {
   background: #ffffff;
 }
 
+.dataset-role-summary-grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(8.5rem, 1fr));
+  gap: 0.55rem;
+  margin-top: 0.75rem;
+}
+
+.dataset-role-summary {
+  display: grid;
+  gap: 0.12rem;
+  min-width: 0;
+  border: 1px solid var(--line);
+  border-radius: 8px;
+  padding: 0.65rem;
+  background: #ffffff;
+}
+
+.dataset-role-summary span,
+.dataset-role-summary small {
+  color: var(--muted);
+  font-size: 0.76rem;
+  font-weight: 800;
+  text-transform: uppercase;
+}
+
+.dataset-role-summary strong {
+  color: var(--ink);
+  font-size: 1.18rem;
+  line-height: 1;
+}
+
+.dataset-role-selected {
+  border-color: rgba(15, 23, 42, 0.24);
+  background: #f1f5f9;
+  color: #0f172a;
+}
+
+.dataset-role-reference {
+  border-color: rgba(15, 118, 110, 0.28);
+  background: #ecfdf5;
+  color: #115e59;
+}
+
+.dataset-role-candidate {
+  border-color: rgba(37, 99, 235, 0.24);
+  background: #eff6ff;
+  color: #1d4ed8;
+}
+
+.dataset-role-source {
+  border-color: rgba(100, 116, 139, 0.22);
+  background: #f8fafc;
+  color: #334155;
+}
+
 .entity-list,
 .dataset-list,
 .model-list,
@@ -1037,6 +1092,36 @@ button.entity-card {
   align-items: start;
 }
 
+.dataset-card-kicker {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0.35rem;
+  align-items: center;
+  margin-bottom: 0.28rem;
+  color: var(--muted);
+  font-size: 0.75rem;
+  font-weight: 800;
+  text-transform: uppercase;
+}
+
+.dataset-role-badge {
+  display: inline-flex;
+  align-items: center;
+  max-width: 100%;
+  min-height: 1.45rem;
+  border: 1px solid currentColor;
+  border-radius: 999px;
+  padding: 0.16rem 0.5rem;
+  font-size: 0.72rem;
+  line-height: 1;
+}
+
+.dataset-card-title {
+  display: block;
+  overflow-wrap: anywhere;
+  line-height: 1.25;
+}
+
 .model-card p {
   grid-column: 1 / -1;
   margin: 0.25rem 0 0;