@museumwnf/viewer-core 1.15.0 → 1.16.0

package/README.md

@@ -44,7 +44,25 @@ The `defineViewerConfig` helper returns a Vite config object with the shared set
 
 ## Usage
 
-`main.js` (this is the whole website entry point):
+`main.js`, once its own CSS imports and locale glob are done (see
+`createStandardViewer` below for exactly what a website still writes):
+
+```js
+import { createStandardViewer } from '@museumwnf/viewer-core'
+import { catalogues } from '@museumwnf/viewer-i18n/gallery'
+import config from './dataset.config.js'
+import SiteShell from './SiteShell.vue'
+
+const ownMessages = {}
+for (const [path, module] of Object.entries(import.meta.glob('../locales/*.json', { eager: true }))) {
+  ownMessages[path.split('/').pop().replace(/\.json$/, '')] = module.default
+}
+
+createStandardViewer(config, SiteShell, { dictionary: catalogues, ownMessages })
+```
+
+A website that wants the lower-level building block on its own — no shell
+wiring, no message merge, caller mounts it — calls `createViewer()` directly:
 
 ```js
 import { createViewer } from '@museumwnf/viewer-core'
@@ -54,6 +72,46 @@ createViewer(config).mount('#app')
 
 ## API
 
+### `createStandardViewer(config, siteClass, options)` → the mounted Vue app
+
+The one-call form of the `main.js` pattern above: merges `options.dictionary`
+(a `@museumwnf/viewer-i18n/{standalone|gallery|exhibition}` catalogue) with
+`options.ownMessages` (a website's own texts, local wins — same rule as
+[`mergeMessages`](#texts)), calls `createViewer()` with `siteClass` as the
+shell (only when `config.shell` isn't already set — an existing
+`dataset.config.js` that sets `shell` itself keeps working unchanged),
+mounts the result at `options.el` (`'#app'` by default) and returns the
+mounted app.
+
+| Argument | Type | Required | Meaning |
+| --- | --- | --- | --- |
+| `config` | object | yes | the website's `dataset.config.js` object, exactly as passed to `createViewer` |
+| `siteClass` | Vue component | no | the website's `SiteShell`; used as `config.shell` when `config.shell` is unset |
+| `options.dictionary` | object | no | the family catalogue from `@museumwnf/viewer-i18n` |
+| `options.ownMessages` | object | no | the website's own catalogue (e.g. from the `import.meta.glob` loop); overloads `dictionary`, local wins |
+| `options.el` | string \| Element | no | mount target, defaults to `'#app'` |
+
+Without `options.dictionary`, the merge step is skipped and `config.messages`
+(or `options.ownMessages` on its own) is used as-is — a website that has
+already merged its texts, or has none to merge, needs neither.
+
+`viewer-core` does not import `@museumwnf/viewer-i18n` itself: its three
+family dictionaries are separate subpath entry points precisely so a
+website's bundle carries only the one it uses, and choosing between them at
+runtime from a string would cost that tree-shaking (or force every consumer
+to depend on the whole package). The website still imports its own family's
+`catalogues` and passes it in.
+
+What a website's `main.js` still writes, and why it cannot move here:
+
+- its own CSS imports (`@museumwnf/viewer-layout/style.css`, theme and site
+  stylesheets) — each is a static, site-relative specifier only the site's
+  own module can write;
+- the `import.meta.glob('../locales/*.json', { eager: true })` loop — a
+  glob is resolved relative to the file that calls it, so from inside this
+  package it would look for `locales/` next to viewer-core, not next to the
+  website.
+
 ### `createViewer(config)` → Vue app (caller mounts it)
 
 `config` is the website's `dataset.config.js` object:
@@ -119,7 +177,7 @@ interpolation, no pluralisation, no HTML. A value produced at run time — a
 number, a date, a count — is rendered by the component *next to* the text,
 never inside it, which is what lets a text be translated freely.
 
-Shared texts come from [`@museumwnf/viewer-i18n`](https://github.com/metanull/viewer-i18n);
+Shared texts come from [`@museumwnf/viewer-i18n`](https://github.com/museumwithnofrontiers/viewer-i18n);
 a website's own texts come from its `locales/<lang>.json`. The website merges
 them and passes the result as `config.messages` — local wins, and that is the
 only merge rule:
@@ -137,6 +195,11 @@ for (const [path, module] of Object.entries(import.meta.glob('../locales/*.json'
 createViewer({ ...config, messages: mergeMessages(catalogues, local) }).mount('#app')
 ```
 
+`createStandardViewer(config, siteClass, { dictionary, ownMessages })` (see
+[above](#createstandardviewerconfig-siteclass-options--the-mounted-vue-app))
+does exactly this merge, plus the shell wiring and the mount — a website
+normally reaches for that instead of calling `mergeMessages` itself.
+
 | Export | Use |
 | --- | --- |
 | `$t(key)` | in a template |
@@ -433,6 +496,52 @@ needs it; the standalone sites never import it.
 | `partnerFromKey(partners, countries, countryCode, legacyId)` | the partner a legacy `/partner/:country/:id` route names, or null — `partnerKey` in reverse |
 | `itemFromUidPath(items, path)` | the item a legacy dbUid *path* names, or null — `backward_compatibility` with `:` swapped for `/`, matched case-insensitively (Sharing History stores its keys lowercase) |
 
+### `@museumwnf/viewer-core/dxa`
+
+The gallery/exhibition-pair composables the four live DXA sites each wrote
+for themselves — `useCollection`/`useGalleryData`, the timeline, the
+partner specs and the item sheet — byte-identical within each pair
+(carpets/amulets — a gallery; the-use-of-colours-in-art/water-in-islam — an
+exhibition). Promoted here per family, never as one composable that papers
+over the two: the cross-family diff is real behaviour (the exhibition
+shape's per-language-build 404 gate, its own local-vs-country timeline
+switch, its manifest-driven citation line), confirmed file by file against
+both pairs' `origin/main` (epic metanull/inventory-app#1730). A separate
+entry point because only a gallery/exhibition site needs it.
+
+A site composes its own data/catalogue/timeline/partner/sheet module from
+these, threading the `data` object one family's
+`useGalleryData()`/`useExhibitionData()` call returns into the rest — the
+same explicit parameter every function below takes, rather than each
+re-reading a module-level singleton:
+
+```js
+import {
+  useGalleryData, useGalleryCollection, useGalleryTimeline, useGalleryPartner, useGallerySheet,
+} from '@museumwnf/viewer-core/dxa'
+
+const data = useGalleryData()
+const collection = useGalleryCollection(data)
+const timeline = useGalleryTimeline(data, collection)
+const partner = useGalleryPartner(data, collection)
+const sheet = useGallerySheet(data)
+```
+
+No export below reads a site name, a legacy project key, or a UUID: what a
+family's composables need beyond the data package itself is a `config`
+parameter (currently unused by either family — every DXA site so far
+shares the same entity list and catalogue shape; documented per function
+below for whichever future site needs its own).
+
+| Export (gallery / exhibition) | Reads | Returns |
+| --- | --- | --- |
+| `useGalleryData(config)` / `useExhibitionData(config)` | `config.eager` (entity names `loadEnglish` loads eagerly; default the family's own list, the exhibition's also carrying `themes`) | the family's whole data layer: `tr`/`md`/`mdInline`/`mdStrip`/`labelOf`/`loadEnglish`/`translations`, every entity and lookup map (`items`, `partners`, `countries`, `tags`, `dynasties`, `timelines`, `timelineEvents`, …), the routes (`itemRoute`, `partnerRoute`, `partnerObjectsRoute`), the legacy URL wrappers (`itemFromUidPath`, `partnerFromKey` — gallery only), `chromeImage`, `manifest`, `defaultLang`, plus family-specific fields (gallery: `siblingGalleries`/`pickSiblings`; exhibition: `isHiddenPartner`, `isInstitution`, `projectName`, `exhibitionTitle`/`exhibitionSubtitle`/`exhibitionHeadline`/`bannerCaption`, `siblingSites`) |
+| `useGalleryCollection(data, config)` / `useExhibitionCollection(data, config)` | the `data` object above; `config` unused today | `FACETS`, `tile(item, t)`, `collectionResults` (the `CatalogueResultsView` spec), plus the facet-value helpers (`countryIdForCode`, `tagLabelForLegacy`, gallery's own `tagIdForLegacy`, `hasEveryTag`) |
+| `useGalleryTimeline(data, collection, config)` / `useExhibitionTimeline(data, collection, config)` | `data`, the `collection` object above (for its `tile`); `config` unused today | the timeline specs (`timelineResults`/`timelineSpec`, `timelineGallery`/`timelineGallerySpec`) and their helpers (`countryLabel`/`countryIdForCode`, `timelineGalleryItems`; the exhibition shape adds `usesLocalTimeline`, `hasTimeline`, `timelineCountries`, `findEvents` for its own local-vs-country chronology switch) |
+| `useGalleryPartner(data, collection, config)` / `useExhibitionPartner(data, config)` | `data`, and (gallery only) `collection` for its `tile` | `partnerList`/`partnerListSpec`, `partnerSheet`/`partnerSheetSpec`, and (gallery only) `partnerObjects` — the exhibition shape's `partnerSpecs.js` never carried an objects-page spec |
+| `useGallerySheet(data, config)` / `useExhibitionSheet(data, config)` | `data`; `config` unused today | `{ itemSheet }`, the `RecordView` spec — the exhibition shape's `citation.project` reads `data.projectName`, absent from the gallery shape |
+| `PAGE_SIZE`, `DATE_MODE`, `FACET_CATEGORIES`, `FACET_LABEL_KEYS`, `useFacetLabels()` | — | the five THG catalogue facets, shared verbatim by both families (nine tiles a page, containment dates, `type`/`dynasty`/`subject`/`material`/`artist`) |
+
 ### The declaration outside a component
 
 | Export | Meaning |

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@museumwnf/viewer-core",
-  "version": "1.15.0",
+  "version": "1.16.0",
   "description": "Application engine for MWNF websites: turns a dataset.config.js into a mounted Vue application.",
   "type": "module",
   "license": "SEE LICENSE IN LICENSE.md",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/metanull/viewer-core.git"
+    "url": "git+https://github.com/museumwithnofrontiers/viewer-core.git"
   },
   "publishConfig": {
     "access": "public",
@@ -19,6 +19,7 @@
   "module": "./src/index.js",
   "exports": {
     ".": "./src/index.js",
+    "./dxa": "./src/dxa/index.js",
     "./i18n": "./src/i18n/index.js",
     "./legacy": "./src/legacy/index.js",
     "./testing": "./src/testing/index.js",

package/src/createStandardViewer.js

@@ -0,0 +1,61 @@
+import { createViewer } from './createViewer.js'
+import { mergeMessages } from './i18n/index.js'
+
+/**
+ * Build, wire up and mount a standard MWNF website in one call.
+ *
+ * Every website's `main.js` does the same three things after its own CSS
+ * and locale imports: merge the shared dictionary its family pulls in
+ * (`@museumwnf/viewer-i18n/{standalone|gallery|exhibition}`) under its own
+ * `locales/*.json` overloads (local wins), hand the result and the site's
+ * shell component to `createViewer()`, and mount the app. This helper does
+ * those three steps, so `main.js` is left with only what genuinely cannot
+ * move here:
+ *
+ * - its own CSS imports (`@museumwnf/viewer-layout/style.css`, the theme
+ *   and site stylesheets) — Vite needs a static, site-relative specifier
+ *   for each one, which only the site's own module can write;
+ * - the `import.meta.glob('../locales/*.json', { eager: true })` loop that
+ *   loads the site's own texts — a glob is resolved relative to the file
+ *   that calls it, so run from inside this package it would look for
+ *   `locales/` next to viewer-core, not next to the website.
+ *
+ * `viewer-core` does not depend on `@museumwnf/viewer-i18n`: that package's
+ * three family dictionaries are independent subpath entry points precisely
+ * so a website's bundle carries only the one it uses. Importing one of them
+ * from here — or choosing between them at runtime from a string in
+ * `config` — would either force every consumer to carry all three or
+ * replace a bundler-time choice with one a bundler cannot tree-shake. The
+ * website still imports its own family's `catalogues` and passes it as
+ * `dictionary`.
+ *
+ * @param {object} config - the site's `dataset.config.js` object, exactly
+ *   as passed to {@link createViewer} today
+ * @param {object} [siteClass] - the site's `SiteShell` component, used as
+ *   `config.shell` when `config` does not already set one (a config that
+ *   still declares its own `shell` keeps taking precedence, so existing
+ *   `dataset.config.js` files need no change)
+ * @param {object} [options]
+ * @param {object} [options.dictionary] - the family's shared catalogue,
+ *   i.e. `catalogues` imported from
+ *   `@museumwnf/viewer-i18n/{standalone|gallery|exhibition}`
+ * @param {object} [options.ownMessages] - the website's own catalogue,
+ *   already loaded (e.g. via the `import.meta.glob` loop above); merged
+ *   over `dictionary` with {@link mergeMessages} — local wins. Used on its
+ *   own, without a `dictionary`, when a website has no shared family text
+ * @param {string|Element} [options.el] - the mount target, defaults to
+ *   `'#app'`, exactly like every website's current `main.js`
+ * @returns {import('vue').App} the mounted Vue application (call
+ *   `.unmount()` on it, e.g. in a test)
+ */
+export function createStandardViewer(config, siteClass, options = {}) {
+  const { dictionary, ownMessages, el = '#app' } = options
+
+  const messages = dictionary
+    ? mergeMessages(dictionary, ownMessages ?? {})
+    : (config.messages ?? ownMessages ?? {})
+
+  const app = createViewer({ ...config, shell: config.shell ?? siteClass, messages })
+  app.mount(el)
+  return app
+}

package/src/dxa/exhibition/useExhibitionCollection.js

@@ -0,0 +1,176 @@
+import { DATE_MODE, FACET_CATEGORIES, PAGE_SIZE } from '../shared.js'
+
+export { DATE_MODE, FACET_CATEGORIES, FACET_LABEL_KEYS, PAGE_SIZE, useFacetLabels } from '../shared.js'
+
+// The catalogue spec: what a DXA exhibition's lists filter and search on.
+// The engine — query state, options, dates, pages, the boolean grammar — is
+// viewer-core's own; what is declared here is only what is an exhibition's:
+// the facet *predicates* over its own data, the haystack the search bar
+// reads, and the tile a record becomes.
+// `PAGE_SIZE`/`DATE_MODE`/`FACET_CATEGORIES`/`FACET_LABEL_KEYS`/
+// `useFacetLabels` are shared verbatim with the gallery family — see
+// `../shared.js`.
+//
+// Legacy asked the API for everything: `/items?ic[]=…&id[]=…&na=…&nz=…` for
+// the results, and `/items/countries`, `/items/tags`, `/items/years` *with
+// the same filters applied* for the dropdowns — which is what made the
+// facets dependent (pick a country, and the type list shrinks to the types
+// still reachable). The results page hands the engine the matching subset
+// for that reason; the entrance hands it everything.
+
+/**
+ * The exhibition's collection spec, over its own data layer's `data` (the
+ * return value of {@link import('./useExhibitionData.js').useExhibitionData}).
+ *
+ * Reads `data.countries`, `data.tags`, `data.countryById`, `data.tagById`,
+ * `data.itemById`, `data.labelOf`, `data.itemRoute`, `data.tr`,
+ * `data.defaultLang`, `data.mdInline`, `data.projectName`. `config` carries
+ * nothing today.
+ */
+export function useExhibitionCollection(data, config = {}) {
+  void config
+  const {
+    countries, tags, countryById, tagById, itemById, labelOf, itemRoute, tr, defaultLang, mdInline, projectName,
+  } = data
+
+  // ── What the URL carries ─────────────────────────────────────────────
+  //
+  // The legacy 2-letter country code for `country`, the legacy tag id for a
+  // facet: the values legacy's URLs carried, so a link shared then still
+  // resolves now.
+
+  function countryIdForCode(code) {
+    return code ? (countries.value ?? []).find((c) => c.code === code)?.id ?? null : null
+  }
+
+  function tagLabelForLegacy(legacyId) {
+    return (tags.value ?? []).find((t) => t.legacy_tag_id === legacyId)?.label ?? legacyId
+  }
+
+  /**
+   * The facet spec for viewer-core's `useFacets`: the country by code, each
+   * tag category by legacy id, labels upper-cased on the first letter as
+   * legacy printed them.
+   */
+  const FACETS = {
+    country: {
+      values: (item) => countryById.value.get(item.country_id)?.code ?? null,
+      label: (code) => labelOf('countries', countryIdForCode(code)),
+    },
+    ...Object.fromEntries(
+      FACET_CATEGORIES.map((category) => [
+        category,
+        {
+          values: (item) =>
+            (item.tag_ids ?? [])
+              .map((id) => tagById.value.get(id))
+              .filter((tag) => tag && tag.category === category)
+              .map((tag) => tag.legacy_tag_id),
+          label: tagLabelForLegacy,
+          capitalize: true,
+        },
+      ]),
+    ),
+  }
+
+  // ── The search bar ───────────────────────────────────────────────────
+  //
+  // Legacy ran MySQL boolean full-text search over the English sheet; the
+  // haystack is the same set of fields, and the grammar is viewer-core's.
+
+  function haystack(item, text) {
+    return [
+      text.name, text.description, text.short_description, text.type, text.holder, text.dates,
+      text.location, text.provenance, text.alternate_name, text.place_of_production,
+      ...(text.keywords ?? []), ...(text.materials ?? []),
+      item.internal_name, item.owner_reference, item.mwnf_reference,
+      labelOf('partners', item.partner_id), labelOf('countries', item.country_id),
+    ]
+  }
+
+  // ── The tile ──────────────────────────────────────────────────────────
+
+  /**
+   * A record as viewer-layout's grid contract: the thumbnail, the name, the
+   * lines legacy's hover card carried (date, holder, place, source
+   * project). The project name is the manifest's own, read in the same
+   * `defaultLang` every other line of this tile is — nothing for a record
+   * legacy left nameless (the Explore case), so the line is dropped, not
+   * printed with a hole in it.
+   */
+  function tile(item, t) {
+    const text = tr('items', item.id, defaultLang)
+    const project = projectName(item, defaultLang)
+    return {
+      id: item.id,
+      image: item.images?.[0]?.url ?? '',
+      imageAlt: labelOf('items', item.id),
+      name: mdInline(text.name ?? item.internal_name ?? ''),
+      meta: [
+        text.dates ?? '',
+        labelOf('partners', item.partner_id),
+        [text.location, labelOf('countries', item.country_id)].filter(Boolean).join(', '),
+        project ? `${t('catalogue.results.forProject')} ${project}` : '',
+      ].filter(Boolean),
+      to: itemRoute(item),
+    }
+  }
+
+  // ── The results page, as a spec ──────────────────────────────────────
+  //
+  // What viewer-layout's `CatalogueResultsView` renders on
+  // `/collection-results`: the facets over the *matching* records (the
+  // dependent dropdowns above), the containment date rule, undated first,
+  // nine tiles a page, legacy's "Collection | <selections>" summary line.
+  // The panel itself is composed by the view's wrapper, in the aside where
+  // legacy put it, so no controls are declared here. Every text is an
+  // entry name.
+
+  // `from`/`to`, not `start`/`end`: the entrance's `SearchFormView` spec
+  // (`mode: 'facets'`, `dates: 'buckets'`) writes the date bounds under
+  // those two fixed keys — the view's own, not something a spec can rename
+  // — so the results side has to read the same ones to stay linked to it.
+  const KEYS = ['country', ...FACET_CATEGORIES, 'from', 'to']
+
+  /** The filter summary line legacy printed as "Collection | <selections>". */
+  function filterSummary(filters, t) {
+    const parts = []
+    if (filters.country) parts.push(labelOf('countries', countryIdForCode(filters.country)))
+    for (const key of FACET_CATEGORIES) if (filters[key]) parts.push(tagLabelForLegacy(filters[key]))
+    if (filters.from) parts.push(`${t('catalogue.filter.from')} ${filters.from}`)
+    if (filters.to) parts.push(`${t('catalogue.filter.to')} ${filters.to}`)
+    return parts.filter(Boolean).join(' | ')
+  }
+
+  const collectionResults = {
+    entity: 'items',
+    keys: KEYS,
+    facets: FACETS,
+    facetScope: 'matching',
+    filterMode: 'immediate',
+    // The engine reads the raw `items` entity; a per-language build ships
+    // every member's `languages` array but not every member's text in this
+    // language, and legacy 404s such a record (`itemById`'s own rule, in
+    // useExhibitionData.js). The results page must not offer what the sheet
+    // would refuse to open, so it is filtered to the same renderable
+    // subset.
+    scope: (item) => itemById.value.has(item.id),
+    dates: { mode: DATE_MODE, begin: 'from', end: 'to' },
+    sort: { undated: 'first' },
+    pageSize: PAGE_SIZE,
+    variant: 'grid',
+    recordRoute: 'item',
+    actionLabel: 'exhibition.action.seeDatabaseEntry',
+    empty: 'catalogue.results.noResults',
+    pagination: { jump: true },
+
+    record: (item, { t }) => tile(item, t),
+
+    summary: ({ filters, pageInfo, t }) => [
+      { label: t('exhibition.section.collection'), value: filterSummary(filters, t) },
+      { count: pageInfo.total, value: `${t('catalogue.results.outOf')} ${itemById.value.size} ${t('catalogue.results.objects')}` },
+    ],
+  }
+
+  return { FACETS, haystack, tile, collectionResults, countryIdForCode, tagLabelForLegacy }
+}

package/src/dxa/exhibition/useExhibitionData.js

@@ -0,0 +1,246 @@
+import { computed } from 'vue'
+import { mediaUrl } from '../../siteConfig.js'
+import { useCatalogueData } from '../../composables/useCatalogueData.js'
+import { useDataPackage } from '../../composables/useDataPackage.js'
+import { byId, entityRef } from '../../composables/useEntities.js'
+import { projectLabel } from '../../conventions.js'
+
+// The data layer every DXA exhibition site (the-use-of-colours-in-art,
+// water-in-islam, …) wrote for itself: the entities an exhibition reads,
+// the lookup maps over them, its routes, its legacy key mappings and its
+// chrome. Promoted from the byte-identical copies the two live exhibitions
+// carried (epic #1730) — what a future exhibition needs that is genuinely
+// its own belongs in `config`, not in a fork of this file. The themes tree
+// stays in a site's own `composables/themes.js`, on top of viewer-core's
+// `useCollectionTree`.
+
+/** Every entity an exhibition page reads English labels or fallbacks for. */
+const DEFAULT_EAGER = ['items', 'partners', 'countries', 'glossary', 'dynasties', 'timeline_events', 'themes']
+
+/**
+ * The exhibition's data layer, bound to the installed data package. Each
+ * entity is a shared ref that stays `null` until a route declaring it in
+ * `meta.entities` brings its chunk in, so calling this loads nothing, and a
+ * page pays only for what it reads.
+ *
+ * `config.eager` overrides the entities `loadEnglish` loads eagerly
+ * (default: {@link DEFAULT_EAGER}).
+ */
+export function useExhibitionData(config = {}) {
+  const dataPackage = useDataPackage()
+  const manifest = dataPackage.manifest
+
+  // English is the base language of every catalogue in the platform: every
+  // list, label and fallback reads it. A record the visitor reads in
+  // another language is resolved on the sheet itself, by
+  // `useRecordLanguage`.
+  const defaultLang = 'en'
+
+  const exhibition = entityRef('exhibition')
+  const relatedContent = entityRef('related_content')
+  const tags = entityRef('tags')
+  const countries = entityRef('countries')
+  const languages = entityRef('languages')
+  const dynasties = entityRef('dynasties')
+  const glossary = entityRef('glossary')
+  const timelines = entityRef('timelines')
+  const timelineEvents = entityRef('timeline_events')
+
+  // E6: a hidden museum is exported but must not appear on any list or
+  // profile page. Its items still render — legacy hides the museum, not the
+  // object. Declared here as a `visible` predicate rather than coded into
+  // every page that lists partners; `isHiddenPartner` stays a named export
+  // because the item sheet's holder line is the one surface that needs the
+  // opposite of `visible` — the museum keeps its name and loses only the
+  // link, because it has no page to link to.
+  const hiddenPartnerIds = computed(() => new Set(exhibition.value?.hidden_partner_ids ?? []))
+  function isHiddenPartner(partner) {
+    return hiddenPartnerIds.value.has(partner?.id)
+  }
+
+  const catalogue = useCatalogueData({
+    eager: config.eager ?? DEFAULT_EAGER,
+    defaultLanguage: defaultLang,
+    visible: {
+      // An item's `languages` is what it has TRANSLATIONS in, so a
+      // non-empty array without this build's language means the text
+      // exists in some other language and not in this one — legacy's own
+      // instance 404s such a record, and this build drops it to match.
+      //
+      // An EMPTY array is a different case and must not be swept in with
+      // it: it means the package has no text in ANY language, which is a
+      // gap in the export rather than a fact about the record, and legacy
+      // serves those records regardless. They keep their legacy names
+      // through `labelOf`'s `internal_name` fallback and lose only their
+      // descriptions. Hence the `!i.languages?.length ||` guard, which
+      // reads like a redundant null-check and is not.
+      items: (i) => !i.languages?.length || i.languages.includes(defaultLang),
+      partners: (p) => !hiddenPartnerIds.value.has(p.id),
+    },
+  })
+
+  const items = catalogue.entity('items')
+  const itemById = catalogue.index('items')
+  const visiblePartners = catalogue.entity('partners')
+  const visiblePartnerIndex = catalogue.index('partners')
+  function visiblePartnerById(id) {
+    return visiblePartnerIndex.value.get(id) ?? null
+  }
+
+  const {
+    tr, md, mdInline, mdStrip, labelOf, loadEnglish, availableLanguages, loadTranslations, translations,
+  } = catalogue
+  loadEnglish()
+
+  /**
+   * Exhibition chrome images and the related-content PDFs.
+   * `banner_image_path`, `homepage_image_path` and `document_path` were
+   * never imported into inventory storage, so the package ships the legacy
+   * path and the address is built from the host the site's
+   * `dataset.config.js` declares under `media`. `size` ∈ zoom | hi_res |
+   * lo_res | small | full.
+   */
+  function chromeImage(path, size = 'hi_res') {
+    return mediaUrl(path, size)
+  }
+
+  // ── Lookup maps ────────────────────────────────────────────────────────
+  //
+  // Unfiltered, unlike `itemById`/`visiblePartnerById`: a holder line still
+  // needs to resolve a hidden museum's name (`isHiddenPartner` above is
+  // what suppresses the link), and every other lookup here has no
+  // visibility rule to begin with.
+  const partnerById = byId('partners')
+  const countryById = byId('countries')
+  const tagById = byId('tags')
+  const dynastyById = byId('dynasties')
+  const glossaryById = byId('glossary')
+  const languageByCode = byId('languages', 'code')
+
+  // countries.json is keyed by the inventory id (ISO 3166-1 alpha-3), but
+  // the legacy two-letter code is what related_content and the timeline
+  // keyspaces carry. `code` is the country's own backward_compatibility, so
+  // this is the bridge between the two — and the reason it is a lookup
+  // rather than a parse is that several legacy codes are not ISO (`uk`,
+  // `pa`, `qt`, `ua`, `sb`).
+  const countryByCode = computed(
+    () => new Map((countries.value ?? []).filter((c) => c.code).map((c) => [c.code, c])),
+  )
+
+  /** The same label from a legacy two-letter code (`uk` → United Kingdom). */
+  function countryLabelFromCode(code) {
+    if (!code) return ''
+    const country = countryByCode.value.get(code)
+    return country ? labelOf('countries', country.id) : code
+  }
+
+  /** The canonical item route: the package id, and no language in the path. */
+  function itemRoute(item) {
+    return { name: 'item', params: { id: item.id } }
+  }
+
+  // Institutions (monument owners) and museums both live in partners.json —
+  // the package ships the union of legacy's /partners and /institutions
+  // because a static package has no endpoints to split them across. The
+  // viewer routes by `type`, which is what legacy's two page templates
+  // keyed off.
+  function isInstitution(partner) {
+    return partner?.type === 'institution'
+  }
+
+  function partnerRoute(partner) {
+    return {
+      name: isInstitution(partner) ? 'institution' : 'partner',
+      params: { id: partner.id },
+    }
+  }
+
+  function partnerObjectsRoute(partner, page = 1) {
+    return {
+      name: isInstitution(partner) ? 'institution-monuments' : 'partner-objects',
+      params: { id: partner.id },
+      query: page > 1 ? { page } : {},
+    }
+  }
+
+  // ── Source projects ────────────────────────────────────────────────────
+  //
+  // A member is borrowed from the MWNF project that originally published
+  // it. The name is the data package's own `manifest.projects` entry
+  // (populated by the importer/exporter), keyed by this record's
+  // `project_id` (a UUID) — not viewer-core's deprecated, legacy-key-keyed
+  // `projectName()`/`projectFamily()`, and not an exhibition's own
+  // project-key comparisons either. The manifest already names an
+  // exhibition's own native project under its own uuid (the sibling
+  // `Collection` the importer creates alongside every `Project` carries the
+  // same title), so there is no special case here for a native member any
+  // more; the colour swatch is this exhibition's own editorial choice
+  // (`dataset.config.js`'s `projectColors`, read by the site's `ItemSheet`).
+
+  // Some members have no `project_id` at all: they come from the Explore
+  // monuments database rather than from a project, which is why provenance
+  // has to be read from the keyspace here instead of from a field. Legacy
+  // still coloured them and still printed an empty project name, so its
+  // citation read `"…" in , Museum With No Frontiers, …` with a hole in it.
+  // The colour is reproduced (the site's own `.mwnf-chip--Explore` rule);
+  // the empty name is not, because a label reading "for" with nothing after
+  // it is a rendering fault rather than a faithful copy. The line is
+  // dropped instead.
+  function isExploreRecord(item) {
+    return (item?.backward_compatibility ?? '').startsWith('mwnf3_explore:')
+  }
+
+  /** `null` for a record with no project (the Explore case) or whose
+   * project the manifest does not name in `lang`. */
+  function projectName(item, lang = defaultLang) {
+    return projectLabel(manifest, item?.project_id, lang)
+  }
+
+  /** The exhibition's own per-language chrome text. */
+  function exhibitionTitle(lang = defaultLang) {
+    return exhibition.value?.titles?.[lang] ?? exhibition.value?.titles?.en ?? ''
+  }
+
+  function exhibitionSubtitle(lang = defaultLang) {
+    return exhibition.value?.subtitles?.[lang] ?? exhibition.value?.subtitles?.en ?? ''
+  }
+
+  function exhibitionHeadline(lang = defaultLang) {
+    return exhibition.value?.headlines?.[lang] ?? exhibition.value?.headlines?.en ?? ''
+  }
+
+  function bannerCaption(lang = defaultLang) {
+    return exhibition.value?.banner_captions?.[lang] ?? exhibition.value?.banner_captions?.en ?? ''
+  }
+
+  // ── Sibling sites ──────────────────────────────────────────────────────
+  //
+  // Decision Q3: these are reference objects, not resolved links. The
+  // exporter records identity plus whatever the import carried; where a
+  // `legacy_host` came across we can link to it, and where it did not the
+  // entry still renders — it just does not become an anchor.
+
+  const siblingSites = computed(
+    () => (exhibition.value?.sibling_sites ?? []).filter((s) => !s.hidden),
+  )
+
+  function siblingUrl(sibling) {
+    return sibling?.legacy_host || null
+  }
+
+  return {
+    manifest,
+    defaultLang,
+    exhibition, relatedContent, tags, countries, languages, dynasties, glossary, timelines, timelineEvents,
+    isHiddenPartner,
+    items, itemById, visiblePartners, visiblePartnerById,
+    tr, md, mdInline, mdStrip, labelOf, loadEnglish, availableLanguages, loadTranslations, translations,
+    chromeImage,
+    partnerById, countryById, tagById, dynastyById, glossaryById, languageByCode,
+    countryByCode, countryLabelFromCode,
+    itemRoute, isInstitution, partnerRoute, partnerObjectsRoute,
+    isExploreRecord, projectName,
+    exhibitionTitle, exhibitionSubtitle, exhibitionHeadline, bannerCaption,
+    siblingSites, siblingUrl,
+  }
+}