PRD-027 · Museums: where the real hardware is on display

Status · Accepted 2026-10-22 (scope clarified by the operator the same day: museums are data linked to existing objects, not a new kind of entry) Date · 2026-10-22 Owner · Marko Closes into · #617 Builds on · the /earth launchpad pins (src/lib/earth-launch-site-adapter.ts) · the object panels (FleetEntryPanel) and /science/history pages · PRD-028 (sister: ground observatories)

Why this is a PRD. It adds museum pins to the /earth globe, a museum card, and a "you can see this in…" block on every object that is on display somewhere, all driven by one new data file. That touches data, /earth, two page types, translations, analytics and e2e, so the shape is agreed before code. It replaces the never-built 2026-06-09 "/science visit-list" draft.

1 · What (operator, 2026-10-22)

1. Museums are data, not entries. One data file lists the museums: name, city, country, location, official website, a short description, and the real Orrery objects each one shows, each with a line saying what exactly is there ("Command module Columbia, flown on Apollo 11"). There is no museum fleet category and no museum collectible card.
2. Museum pins on the /earth globe. A museum layer beside the launchpads. Tapping a pin opens the museum card: name, city and country, short description, a button to the museum's website, and its list of showcased objects, each linking to that object's Orrery page.
3. On every object that is on display: a small block, "You can see this in…", naming each museum (with city) and what is shown there. Each museum has a button to its website (new tab) and an "on the map" link that opens that museum's card on /earth. Several museums are all listed, ordered by country then city, so no museum is favoured.
4. Where the block appears: fleet object panels (FleetEntryPanel) and the /science/history pages.
5. A hero photo on each museum card (operator, later on 2026-10-22). It shows the museum building, or a wide view of the inside where the inside is the landmark (a glass hangar, a shuttle hall); never a single object from the collection. Openly licensed photos only (public domain, CC0, CC BY, CC BY-SA, read from Wikimedia Commons, which mirrors the institutions that license openly); no photos from Google Maps or press-only images. A museum with no such photo shows no hero. Files follow the image pipeline: masters/museums/<id>/01.jpg, the WebP ladder in static/images/museums/<id>/, a provenance row, alt text in 14 locales, credit on /credits.

2 · Rules for what counts (operator, 2026-10-22)

• Real objects only. An object is linked where real hardware is on public display: the flown article, a flight backup / spare, a test article (engineering, qualification or ground-test unit), a flown part (e.g. recovered debris), or an unflown sister unit of the same type (operator, 2026-10-22). Each item line says which it is. Replicas, mock-ups and models get nothing, so the link never leads to a model; where sources disagree, the item line says so (e.g. Mars 3 in Kaluga).
• Any museum in the world, not only ones the operator visited. Geographic spread is a priority: China, Japan, India, Europe and every other country, not only the US and Russia; research searches each in its own language.
• Size does not matter: a museum with a single real object is in, the same as a large collection.
• Evidence for every link. Each object ↔ museum row carries a source showing the object is on display there now, preferably the museum's own page. Museums move and loan objects (Apollo 11 Columbia toured 2017–2021), so the source must be current, not historical.
• The links live once, in the museum data. Object pages derive their block from it, so the two sides cannot disagree.
• In the data (operator, 2026-10-22): rows with confirmed evidence of every kind above, plus Space Shuttle Endeavour at the California Science Center's Samuel Oschin Air and Space Center, Los Angeles, shown as opening on 13 November 2026, and the operator's decisions on the disputed rows: the Soyuz 27, 33 and 40 capsules (7K-T) on the Soyuz 7K-OK page, the Shenzhou 10 capsule in Shaoshan, Buran OK-ML1 at Baikonur, and Mars 3 in Kaluga with the source conflict stated. 38 museums, 88 holdings, 14 countries. Left out: Venera 4 (no Orrery page), LTA-5D (sources place it at White Sands, not a museum), Orion PA-1 in Hampton (may be a replica), a Buran window fragment in Baikonur town (museum not identified). Uncertain rows from the research are added as the operator ticks them on the review page.

3 · Data shape

static/data/museums.json (schema museum.schema.json):

type MuseumBase = {       // src/types/museum.ts
  id: string;              // kebab-case, e.g. 'nasm-washington'
  country: string;         // ISO 3166-1 alpha-2
  lat: number;
  lon: number;
  website: string;         // official site, https
  holds: Array<{
    ref: string;           // fleet id or '/science/history/<slug>'
    kind: 'flown' | 'backup' | 'test-article' | 'flown-part' | 'sister-unit';
    evidence: string;      // URL showing it is on display there
    checked: string;       // date the evidence was read, YYYY-MM-DD
    from?: string;         // on display from this date (YYYY-MM-DD), e.g. a museum not yet open
  }>;
};

The English text and each translation live in one file per museum, i18n-src/<locale>/museums/<id>.json: { name, city, description, items: { [ref]: string } } (schema museum-overlay.schema.json); the base file carries no text. Loader: getMuseums(locale) in src/lib/data/museums.ts.

validate-data checks: schema; every ref resolves to a fleet entry or a history page; every URL https; every row has evidence and a date; kind one of the five above; every museum has at least one row; every locale overlay covers every museum and row.

4 · Names and translations

• Labels (the block, the card, the layer chip): translated by hand into the 13 locales.
• Museum names and cities follow the facility and places rule the site already uses (native-terms.json facility / place): the form each language's own sources use, in every locale (National Air and Space Museum → 国家航空航天博物馆; 中国科学技术馆 → China Science and Technology Museum in English). Where a language has no established form, the museum's own name is kept. Museum names are therefore left out of the translation checker's verbatim-name list.
• Descriptions and item lines: translated per locale (free route: in-session agents with the house glossary rules), Serbian reviewed by the operator.

5 · Measurement

outbound Umami event on the website buttons (target museum, plus the museum id); the "on the map" link and pin taps as in-app navigation events.

6 · Steps

1. Research — done for pass 1 (198 candidate rows, docs/wip/2026-10-22-museum-research/); pass 4 for China, India, the rest of Asia, Latin America and Africa with a fresh search budget.
2. Review — the operator ticks rows on the review page.
3. Build — data + schema + validation, the block on object panels and history pages, the /earth layer and museum card, deep link from the block to the card, translations, analytics, tests.
4. Grow — ticked rows and new research rows are added to museums.json; nothing else changes.

7 · Done

• Every row in museums.json renders: the block on the object page, the object on the museum card, the pin on /earth.
• validate-data green with the museum checks.
• e2e: an object with one museum (website link opens a new tab; "on the map" opens its card), an object with several museums, a pin on /earth opening its card, desktop and mobile.
• All labels, names, descriptions and item lines in the 13 locales.

8 · Non-goals

• A museum fleet category, museum collectible cards (scope clarified 2026-10-22). Hero photos were first out of scope too; the operator added them later the same day (§1, item 5).
• Links to the operator's photo galleries on airandspacehistory.com: #618, after that site's rework.
• Replicas and models, however good (§2).
• Opening hours, tickets, reviews: Orrery is not a travel site.
• Planetariums and observatories (PRD-028).

9 · Risks

• Exhibits move. Loans, tours and renovations. The checked date on each row makes staleness visible; a periodic re-check of the evidence links is part of maintenance.
• Flown vs backup vs replica is easy to get wrong, and museums don't always say. A row whose evidence does not state which it is stays out.
• Coverage skews to the US and Europe, where collections are documented online. Russian, Chinese, Indian and Japanese collections are searched in their own languages first.

References

• #617 (museum button), #618 (gallery links, later)
• docs/wip/2026-10-22-museum-research/README.md (research state, review page, tools)
• src/lib/earth-launch-site-adapter.ts (the /earth pin pattern)
• Naming rules: scripts/i18n-tools/native-terms.json