# Frontend Contract — Public Reference Dataset 05B4

## Read path

Use:

`/data-public-reference/markers.public.v20260520.json`

During implementation, copy or sync the file from:

`/root/.hermes/reports/site-pipeline/site-rerun-subnautica2maps-20260520-clean/subnautica2maps/data-public-reference/markers.public.v20260520.json`

## Top-level shape

```ts
type PublicReferenceDataset = {
  data_version: string;
  generated_at: string;
  readiness: {
    ui_fixture_ready: boolean;
    launch_data_ready_public_reference: boolean;
    seo_index_ready_limited: boolean;
    confirmed_count: number;
    corroborated_count: number;
    needs_verification_count: number;
    indexable_count: number;
  };
  legal: { no_affiliation_disclaimer: string; asset_policy: string };
  markers: Marker[];
}
```

## Marker fields

Required fields present on every marker:

- `marker_id`
- `name`
- `type`: `resource | poi | location | data_box`
- `category`
- `subtype`
- `coordinates`: includes numeric `x/y/z`, `raw`, `system`, `precision`
- `depth`: includes `value_m`, `source`, `precision`
- `region`, `biome`
- `resource_types`
- `description` (original rewritten text)
- `route_note_from_lifepod`
- `route_note_from_current_position_template`
- `prerequisite_gear`, `nearby_resources`, `nearby_poi`
- `verified_game_version`, `source_type`, `confidence`, `source_name`, `source_url`, `retrieved_at`, `source_confidence`, `license_note`, `provenance`
- `index_policy`, `index_policy_reason`, `sitemap_eligible`

## Filtering

Primary filters:

- `type`
- `category`
- `subtype`
- `resource_types[]`
- `biome`
- `confidence`
- `index_policy`

Search fields:

- `name`
- `resource_types[]`
- `biome`
- `region`
- `category`
- `subtype`

## Marker detail UI

Always show:

1. Name/type/category.
2. Coordinates and coordinate system/precision.
3. Depth and precision.
4. Resource/biome/region.
5. Confidence and index policy.
6. Source attribution with outbound link.
7. Early Access warning.
8. No-affiliation disclaimer in footer/legal region.

## Route helper

- If `coordinates.system === source_raw_game8_coordinate_triplet`, treat it as a source coordinate triplet.
- If `coordinates.system === lifepod_relative_estimate_from_public_guide`, display as approximate directional guidance and do not present it as exact in-game coordinate.
- Analytics must bucket distance and must not send raw current player coordinates.

## Source attribution UI

Suggested label:

`Public reference: {source_name} · retrieved {retrieved_at} · confidence {confidence}`

If `index_policy === limited_index`, add:

`This marker is suitable for the map, but not enough for a standalone indexed detail page yet.`

## Risk warning

Subnautica 2 is in Early Access/Game Preview. Public reference data may become outdated after patches. The frontend must avoid `official`, `complete`, `all locations`, and `100% accurate` claims.