@museumwnf/viewer-core 1.14.0

package/src/record/recordSheet.js

@@ -0,0 +1,231 @@
+import { computed, ref, toValue, watch } from 'vue'
+import { useDataPackage } from '../composables/useDataPackage.js'
+import { entityRef } from '../composables/useEntities.js'
+import { useRecordLanguage } from '../composables/useRecordLanguage.js'
+import { glossaryIdsIn, renderBlock, renderInline, renderPlain } from '../i18n/markdown.js'
+
+const BASE_LANGUAGE = 'en'
+
+// A record page does the same things on every website before it shows a
+// single field: decide which language the record is read in, load that
+// language for the record's entity and for the entities its sheet names
+// (dynasties, glossary, partners), gather the glossary terms the record
+// reaches in that language for the renderer, and say when it is ready.
+// Seven pages wrote that choreography by hand. This is the one place it is
+// written, on top of `useRecordLanguage`, which decides the language.
+
+// A term's row in one language: its spellings and definition from
+// `rows`/`fallback` (English), its headword from `term` (the glossary
+// record itself, language-independent) — `null` when the term has neither,
+// which happens for a headword-only fixture row with no translation file at
+// all. Shared by `glossaryTermsFor` (walks a record's own `glossary_ids`)
+// and `glossaryTermsForText` (walks the whole glossary, filtered by what
+// the text contains), so the two agree on what a term row looks like.
+function termRow(id, term, rows, fallback) {
+  const t = rows[id] ?? fallback[id] ?? {}
+  const spellings = (t.spellings ?? []).map((s) => String(s).trim()).filter(Boolean)
+  const word = term?.word ?? spellings[0] ?? ''
+  if (!word && spellings.length === 0) return null
+  return { id, word, definition: t.definition ?? '', spellings: spellings.length ? spellings : [word] }
+}
+
+/**
+ * `{ id, word, definition, spellings }` for each glossary term of `record`
+ * (its `glossary_ids`), with the spellings and definition in `language`,
+ * falling back to English, then to the term's own headword.
+ */
+export function glossaryTermsFor(record, language, { entity = 'glossary', translations, byId } = {}) {
+  const ids = record?.glossary_ids ?? []
+  if (ids.length === 0) return []
+  const rows = translations(entity, language)
+  const fallback = translations(entity, BASE_LANGUAGE)
+  const out = []
+  for (const id of ids) {
+    const row = termRow(id, byId?.get(id), rows, fallback)
+    if (row) out.push(row)
+  }
+  return out
+}
+
+/**
+ * `glossaryTermsFor`'s counterpart for a text with no `glossary_ids` column
+ * to read — a dynasty history, a theme essay: every glossary term whose
+ * spelling occurs in `text`, matched the same word-bounded way `md`/
+ * `renderBlock` highlight it, so what this returns and what the text is
+ * rendered with agree. The candidate list — the whole glossary in
+ * `language`, English behind it — is the same for every text asked about
+ * in that language; `glossaryIdsIn` is what carries the caching (see
+ * `markdown.js`), so building it here costs one pass over the glossary,
+ * not a rebuilt regex.
+ */
+export function glossaryTermsForText(text, language, { entity = 'glossary' } = {}) {
+  const value = String(text ?? '')
+  if (!value) return []
+  const { translations } = useDataPackage()
+  const rows = translations(entity, language)
+  const fallback = translations(entity, BASE_LANGUAGE)
+  const byId = new Map()
+  const candidates = []
+  for (const term of entityRef(entity).value ?? []) {
+    const row = termRow(term.id, term, rows, fallback)
+    if (!row) continue
+    byId.set(term.id, row)
+    for (const spelling of row.spellings) candidates.push({ id: term.id, spelling })
+  }
+  return glossaryIdsIn(value, candidates).map((id) => byId.get(id))
+}
+
+/** The `[{ id, spelling }]` list the renderers highlight, one entry per spelling. */
+export function glossaryEntries(terms) {
+  const out = []
+  for (const term of terms ?? []) {
+    for (const spelling of term.spellings) out.push({ id: term.id, spelling, definition: term.definition, word: term.word })
+  }
+  return out
+}
+
+/**
+ * The record page's engine.
+ *
+ * `record` is a ref, computed or getter. `entity` is the record's entity;
+ * `translations` names the other entities the sheet reads in the record's
+ * language (`['dynasties', 'glossary', 'partners']`). Returns what
+ * `useRecordLanguage` returns — `language`, `languages`, `dir`, `select`,
+ * `reset` — plus `text` (the record's translation in the active language,
+ * falling back to English), `ready` (every named load done for this record
+ * and language), `terms` and `glossary` (the record's glossary terms, and
+ * the spelling list the renderers take), and `attribution` when asked for.
+ *
+ * `attribution: ['author', 'copy_editor']` names fields that are proper
+ * names rather than text: when the active language's row lacks them, the
+ * first other language of the record that has them supplies them. This is
+ * the one place a page reads across languages, and it exists because the
+ * importer files some records' credits on one language only.
+ */
+export function useRecordSheet(record, { entity, translations: related = [], attribution: attributionFields = [], languages } = {}) {
+  if (!entity) throw new Error('useRecordSheet: entity is required')
+  const pkg = useDataPackage()
+  const language = useRecordLanguage(record, { entity, languages })
+  const ready = ref(false)
+  const attribution = ref({})
+  const glossaryRecords = related.includes('glossary') ? entityRef('glossary') : null
+
+  const text = computed(() => {
+    const current = toValue(record)
+    return current ? pkg.tr(entity, current.id, language.language.value, BASE_LANGUAGE) : {}
+  })
+
+  async function resolveAttribution(current, lang) {
+    const own = pkg.tr(entity, current.id, lang, BASE_LANGUAGE)
+    if (attributionFields.some((field) => own[field])) return {}
+    for (const code of language.languages.value) {
+      if (code === lang) continue
+      await pkg.loadTranslations(entity, code)
+      const row = pkg.translations(entity, code)[current.id] ?? {}
+      if (attributionFields.some((field) => row[field])) {
+        const found = { from: code }
+        for (const field of attributionFields) if (row[field]) found[field] = row[field]
+        return found
+      }
+    }
+    return {}
+  }
+
+  let generation = 0
+  async function load() {
+    const current = toValue(record)
+    const lang = language.language.value
+    const mine = ++generation
+    ready.value = false
+    attribution.value = {}
+    if (!current) {
+      ready.value = true
+      return
+    }
+    // The record language and English both: `tr` falls back to English for a
+    // record or a term that has no row in the active language, and a fallback
+    // that has not been loaded is a blank, not a fallback.
+    const languages = lang === BASE_LANGUAGE ? [lang] : [lang, BASE_LANGUAGE]
+    await Promise.all(
+      [entity, ...related].flatMap((name) => languages.map((code) => pkg.loadTranslations(name, code))),
+    )
+    if (mine !== generation) return
+    if (attributionFields.length) {
+      const found = await resolveAttribution(current, lang)
+      if (mine !== generation) return
+      attribution.value = found
+    }
+    ready.value = true
+  }
+
+  watch(() => [toValue(record)?.id, language.language.value], load, { immediate: true })
+
+  const glossaryIndex = computed(() =>
+    glossaryRecords ? new Map((glossaryRecords.value ?? []).map((term) => [term.id, term])) : new Map(),
+  )
+  const terms = computed(() =>
+    glossaryTermsFor(toValue(record), language.language.value, {
+      translations: pkg.translations,
+      byId: glossaryIndex.value,
+    }),
+  )
+  const glossary = computed(() => glossaryEntries(terms.value))
+
+  return { ...language, text, ready, terms, glossary, attribution }
+}
+
+// ── The field engine ───────────────────────────────────────────────────────
+//
+// A sheet is a list of labelled values, in an order, with the empty ones
+// dropped. Which fields, in what order, under which labels, is the site's:
+// "Materials/techniques" on Islamic Art and "Type" on a gallery name the
+// same field and are both legacy facts. The spec is data; this turns it into
+// rows and renders every value through the one pipeline, with the glossary.
+
+const RENDER = {
+  inline: (value, ctx) => renderInline(value, { glossary: ctx.glossary }),
+  block: (value, ctx) => renderBlock(value, { breaks: true, glossary: ctx.glossary }),
+  plain: (value) => renderPlain(value),
+  link: (value) => String(value),
+  custom: (value) => value,
+}
+
+function present(value) {
+  if (value == null) return false
+  if (typeof value === 'string') return value.trim() !== ''
+  if (Array.isArray(value)) return value.length > 0
+  return true
+}
+
+/**
+ * `[{ key, label, render, value, html }]` from a spec and a context.
+ *
+ * A spec entry is `{ key, label, value, render = 'inline', when }`: `label`
+ * a text (already looked up) or `(ctx) => text`; `value` a function of the
+ * context returning the raw value, or the name of a field of `ctx.text`;
+ * `render` one of `inline`, `block`, `plain` (rendered through the pipeline
+ * with `ctx.glossary`), `link` (the value is an address) or `custom` (the
+ * value is handed back as it is, for a slot); `when(ctx)` gates the row.
+ * Rows whose value is empty are dropped. `ctx` is whatever the site passes —
+ * typically `{ record, text, glossary, ...helpers }`.
+ */
+export function sheetRows(spec, ctx = {}) {
+  const rows = []
+  for (const entry of spec ?? []) {
+    if (!entry || (entry.when && !entry.when(ctx))) continue
+    const raw = typeof entry.value === 'function' ? entry.value(ctx) : ctx.text?.[entry.value ?? entry.key]
+    if (!present(raw)) continue
+    const render = entry.render ?? 'inline'
+    const renderer = RENDER[render]
+    if (!renderer) throw new Error(`sheetRows: unknown render "${render}" on "${entry.key}"`)
+    const value = Array.isArray(raw) && render !== 'custom' ? raw.join(entry.join ?? ', ') : raw
+    rows.push({
+      key: entry.key,
+      label: typeof entry.label === 'function' ? entry.label(ctx) : (entry.label ?? entry.key),
+      render,
+      value,
+      html: render === 'custom' || render === 'link' ? null : renderer(value, ctx),
+    })
+  }
+  return rows
+}

package/src/rights.js

@@ -0,0 +1,53 @@
+import { useRouter } from 'vue-router'
+import { mwnfLinks } from './conventions.js'
+import { useDataPackage } from './composables/useDataPackage.js'
+import { useSiteConfig } from './siteConfig.js'
+
+// A site's rights and the address of one of its pages — two facts a
+// citation needs that neither `citation()` nor the data package can know by
+// itself. The rights holder and terms come from the exporter's
+// `manifest.json` (inventory-app#1690 puts a `rights` block there); a
+// page's own address depends on where the site is deployed, which the
+// package cannot declare either. Both are read from one place a website
+// declares once — the manifest's `rights` block, and `site.origin` in
+// `dataset.config.js` — so a composed view asks here instead of assembling
+// its own guess.
+
+/**
+ * `{ holder, termsUrl, attribution }` from the loaded data package's
+ * `manifest.rights`. A package built before the block existed, or one that
+ * carries none, has no holder or attribution to offer, and its terms
+ * address falls back to the MWNF legal notice — the address every site
+ * pointed at before a package could declare its own.
+ */
+export function useSiteRights() {
+  const { manifest } = useDataPackage()
+  const rights = manifest.rights
+  return {
+    holder: rights?.rights_holder ?? null,
+    termsUrl: rights?.terms_url ?? mwnfLinks.legalNotice,
+    attribution: rights?.attribution ?? null,
+  }
+}
+
+const TRAILING_SLASHES = /\/+$/
+
+/**
+ * The address of `route` on this deployment: the declared `site.origin`
+ * plus the hash the router would put in the location bar for it. Null when
+ * the site declares no origin, so a page renders its citation without a
+ * source address instead of one that resolves nowhere once copied out of
+ * the app. `route` is either a route already resolved (its `fullPath` read
+ * directly, so asking for the current page's own address costs no second
+ * resolution) or a raw location, which the installed router resolves the
+ * same way a `<router-link>` would.
+ */
+export function sourceUrl(route) {
+  const origin = String(useSiteConfig().site?.origin ?? '').replace(TRAILING_SLASHES, '')
+  if (!origin) return null
+  const fullPath =
+    typeof route === 'object' && route !== null && typeof route.fullPath === 'string'
+      ? route.fullPath
+      : useRouter().resolve(route).fullPath
+  return `${origin}/#${fullPath}`
+}

package/src/router/index.js

@@ -0,0 +1,138 @@
+import { createRouter, createWebHashHistory } from 'vue-router'
+import { loadEntities } from '../composables/useEntities.js'
+import DetailView from '../views/DetailView.vue'
+import HomeView from '../views/HomeView.vue'
+import ListView from '../views/ListView.vue'
+import NotFoundView from '../views/NotFoundView.vue'
+
+// The routing convention, applied to every website by the one router they
+// share: hash history; every route named; `/<section>` and `/<section>/:id`
+// with the package id; language, page and filters in the query; the shapes
+// of legacy URLs kept as redirect-only entries; a catch-all to one not-found
+// view; scroll restoration owned here, not by a shell or a view.
+
+/**
+ * Where the page is after a navigation: where it was when the visitor comes
+ * back through history; at the anchor when the URL names one; where it is
+ * when only a filter of the same page changed; at the top otherwise —
+ * including a change of `page`, which is a new page of results and is read
+ * from the beginning, and including the language, which re-renders
+ * everything.
+ */
+export function defaultScrollBehavior(to, from, savedPosition) {
+  if (savedPosition) return savedPosition
+  if (to.hash) return { el: to.hash, behavior: 'smooth' }
+  if (
+    from.name !== undefined &&
+    to.name === from.name &&
+    sameParams(to.params, from.params) &&
+    String(to.query.page ?? '') === String(from.query.page ?? '')
+  ) {
+    return false
+  }
+  return { top: 0 }
+}
+
+function sameParams(a, b) {
+  const keys = new Set([...Object.keys(a ?? {}), ...Object.keys(b ?? {})])
+  for (const key of keys) {
+    if (String(a?.[key] ?? '') !== String(b?.[key] ?? '')) return false
+  }
+  return true
+}
+
+/**
+ * A legacy URL shape becomes a route that only ever redirects: `resolve`
+ * receives the matched params (and the route) and answers the canonical
+ * location — a name with params, or a path — or nothing, which is the
+ * not-found page. It may be async, so a website can load the entity it maps
+ * a legacy key through.
+ */
+function legacyRoute({ path, resolve, name }, index) {
+  return {
+    path,
+    name: name ?? `legacy-${index}`,
+    component: NotFoundView,
+    meta: { legacy: true },
+    async beforeEnter(to) {
+      const target = await resolve(to.params, to)
+      if (!target) {
+        return { name: 'not-found', params: { pathMatch: to.path.slice(1).split('/') }, replace: true }
+      }
+      const location = typeof target === 'string' ? { path: target } : { ...target }
+      return { ...location, replace: true }
+    },
+  }
+}
+
+/**
+ * The three slots every website has — the home page, a list page, a record
+ * page — and what renders them. The generic views are the defaults: a plain
+ * list of entity names, a paginated list of records, a record's fields,
+ * enough to look at a new dataset. A website names the real pages in
+ * `config.views` (`{ home, list, detail }`), typically the composed views of
+ * `@museumwnf/viewer-layout/views`, and the same route names then render
+ * them: `home` for `/`, `<entity>-list` and `<entity>-detail` for every
+ * entity `features.entities` publishes. A component a site registers on the
+ * `home` name in `extraViews` still wins — the escape hatch stays open.
+ */
+export function resolveViews(config = {}) {
+  return {
+    home: HomeView,
+    list: ListView,
+    detail: DetailView,
+    ...Object.fromEntries(Object.entries(config.views ?? {}).filter(([, view]) => view)),
+  }
+}
+
+export function createViewerRouter(config = {}) {
+  const views = resolveViews(config)
+  const routes = [{ path: '/', name: 'home', component: views.home }]
+
+  for (const entity of config.features?.entities ?? []) {
+    routes.push({
+      path: `/${entity}`,
+      name: `${entity}-list`,
+      component: views.list,
+      props: { entity },
+    })
+    routes.push({
+      path: `/${entity}/:id`,
+      name: `${entity}-detail`,
+      component: views.detail,
+      props: (route) => ({ entity, id: route.params.id }),
+    })
+  }
+
+  for (const record of config.extraViews ?? []) {
+    routes.push(record)
+  }
+  for (const record of config.routes ?? []) {
+    routes.push(record)
+  }
+  for (const [index, entry] of (config.legacyRoutes ?? []).entries()) {
+    routes.push(legacyRoute(entry, index))
+  }
+  if (config.notFound !== false) {
+    routes.push({
+      path: '/:pathMatch(.*)*',
+      name: 'not-found',
+      component: config.notFound ?? NotFoundView,
+    })
+  }
+
+  const router = createRouter({
+    history: createWebHashHistory(),
+    routes,
+    scrollBehavior: config.scrollBehavior ?? defaultScrollBehavior,
+  })
+
+  // A route that names the entities it reads has them loaded before its view
+  // exists, so the view never renders against records that are not there yet.
+  router.beforeResolve(async (to) => {
+    const names = [...new Set(to.matched.flatMap((record) => record.meta?.entities ?? []))]
+    if (names.length > 0) await loadEntities(names)
+  })
+
+  return router
+}

package/src/siteConfig.js

@@ -0,0 +1,37 @@
+import { getCurrentInstance, inject } from 'vue'
+import { VIEWER_CONFIG } from './injectionKeys.js'
+
+// `dataset.config.js` is the whole declaration of a website. What a site
+// needs outside a component — a composable building an image address, a
+// route helper — reads it from here; a component may inject it as well.
+
+let current = {}
+
+export function setSiteConfig(config) {
+  current = config ?? {}
+}
+
+/** The website's configuration, as `createViewer` received it. */
+export function useSiteConfig() {
+  if (getCurrentInstance()) {
+    const injected = inject(VIEWER_CONFIG, null)
+    if (injected) return injected
+  }
+  return current
+}
+
+const ABSOLUTE = /^(?:[a-z][a-z0-9+.-]*:|\/\/)/i
+
+/**
+ * The address of a legacy media file, from the path the data package carries
+ * and the host `config.media.legacyHost` declares. `size` is one of the
+ * legacy server's size names (`zoom`, `hi_res`, `lo_res`, `small`). A path
+ * that is already an address is returned as it is.
+ */
+export function mediaUrl(path, size = 'hi_res') {
+  if (!path) return null
+  if (ABSOLUTE.test(path)) return path
+  const host = String(useSiteConfig().media?.legacyHost ?? '').replace(/\/+$/, '')
+  if (!host) return null
+  return `${host}/${size}/${String(path).replace(/^\/+/, '')}`
+}

package/src/styles/base.css

@@ -0,0 +1,49 @@
+/* Structural rules only. Colors, fonts and brand values come from CSS custom
+   properties defined by the website (or by @museumwnf/viewer-layout). */
+
+*,
+*::before,
+*::after {
+  box-sizing: border-box;
+}
+
+body {
+  margin: 0;
+  font-family: var(--vc-font-body, system-ui, sans-serif);
+  line-height: var(--vc-line-height, 1.5);
+  background: var(--vc-color-background, transparent);
+  color: var(--vc-color-text, inherit);
+}
+
+img {
+  max-width: 100%;
+  height: auto;
+}
+
+.vc-home,
+.vc-list,
+.vc-detail {
+  max-width: var(--vc-content-width, 60rem);
+  margin-inline: auto;
+  padding: var(--vc-content-padding, 1.5rem);
+}
+
+.vc-detail dl {
+  display: grid;
+  grid-template-columns: max-content 1fr;
+  gap: 0.25rem 1rem;
+}
+
+.vc-detail dt {
+  font-weight: var(--vc-weight-label, 600);
+}
+
+.vc-detail dd {
+  margin: 0;
+}
+
+.vc-pagination {
+  display: flex;
+  gap: 1rem;
+  align-items: baseline;
+}

package/src/testing/checkOfferedLanguages.js

@@ -0,0 +1,67 @@
+import { useDataPackage } from '../composables/useDataPackage.js'
+import { declaredSiteLanguages, offeredLanguages } from '../languages.js'
+
+// One check of a website's language declaration, shared by every website so
+// that the rule is tested once rather than rewritten seven times. It returns
+// the problems it finds, as sentences; a website's test asserts the list is
+// empty.
+
+/**
+ * Checks `config.languages` and `config.navigation.languages` against the
+ * data package: only languages with item content are offered; the order is
+ * the package's declared order; every offered language has a label, and the
+ * switcher lists exactly the offered languages.
+ *
+ * A website that narrows the package's declaration passes the same `declared`
+ * list it gave `offeredLanguages()`, so the check expects the narrowed set —
+ * the two helpers apply one rule, and a website that narrows in the config
+ * but not in the test would otherwise be told its own list is wrong.
+ */
+export function checkOfferedLanguages(
+  config,
+  { declared, entity = 'items', manifest, availableLanguages } = {},
+) {
+  const pkg = useDataPackage()
+  const withContent = (availableLanguages ?? pkg.availableLanguages)(entity)
+  const fromPackage = declaredSiteLanguages(manifest ?? pkg.manifest)
+  const offered = config?.languages ?? []
+  const problems = []
+
+  if (offered.length === 0) {
+    problems.push('The website offers no language.')
+  }
+  for (const code of offered) {
+    if (!withContent.includes(code)) {
+      problems.push(`"${code}" is offered but no ${entity} carry it.`)
+    }
+  }
+  if (declared || fromPackage) {
+    const expected = offeredLanguages({ declared, entity, manifest, availableLanguages })
+    if (offered.join(',') !== expected.join(',')) {
+      const source = declared ? 'the website narrows the package to' : 'the package declares'
+      problems.push(
+        `The offered languages are [${offered.join(', ')}] where ${source} [${expected.join(', ')}].`,
+      )
+    }
+  } else {
+    const sorted = [...offered].sort()
+    if (offered.join(',') !== sorted.join(',')) {
+      problems.push('The package declares no site languages, so the offered list has to be alphabetical.')
+    }
+  }
+
+  const switcher = config?.navigation?.languages
+  if (switcher !== undefined) {
+    const codes = (switcher ?? []).map((entry) => (typeof entry === 'string' ? entry : entry?.code))
+    if (codes.join(',') !== offered.join(',')) {
+      problems.push(`The switcher lists [${codes.join(', ')}] where the website offers [${offered.join(', ')}].`)
+    }
+    for (const entry of switcher ?? []) {
+      if (typeof entry === 'object' && !(typeof entry.label === 'string' && entry.label.trim())) {
+        problems.push(`"${entry.code}" has no label in the switcher.`)
+      }
+    }
+  }
+
+  return problems
+}

package/src/testing/index.js

@@ -0,0 +1,3 @@
+export { checkOfferedLanguages } from './checkOfferedLanguages.js'
+export { checkRoutes, checkSectionMeta, checkTextsRendered, mountSite } from './smoke.js'
+export { defineViewerConfig } from './viteConfig.js'

package/src/testing/smoke.js

@@ -0,0 +1,103 @@
+import { createViewer } from '../createViewer.js'
+
+/**
+ * Mount a website to a detached DOM node on a given hash, returning the app,
+ * host, and router for test assertions. The router is ready and the app is
+ * mounted before the promise resolves.
+ *
+ * `config` and `messages` are the same objects a website's main.js assembles.
+ * `hash` defaults to the home page.
+ */
+export async function mountSite(config, messages, hash = '#/') {
+  window.location.hash = hash
+  const app = createViewer({ ...config, messages })
+  const host = document.createElement('div')
+  document.body.appendChild(host)
+  app.mount(host)
+  const router = app.config.globalProperties.$router
+  await router.isReady()
+  return { app, host, router }
+}
+
+/**
+ * Check that a configuration's routes are properly declared: every route has
+ * a name, no route is a catch-all, and every legacy route is listed in
+ * `legacyPaths`.
+ *
+ * Returns the list of problems found (empty if all is well). Routes without
+ * names appear by index in the message.
+ */
+export function checkRoutes(config, { names = [], legacyPaths = [] } = {}) {
+  const problems = []
+  const declaredNames = (config.extraViews ?? []).map((r) => r.name)
+  const declaredLegacy = (config.legacyRoutes ?? []).map((r) => r.path)
+
+  // Check every route has a name.
+  for (let i = 0; i < (config.extraViews ?? []).length; i++) {
+    if (!config.extraViews[i].name) {
+      problems.push(`Route ${i} has no name.`)
+    }
+  }
+
+  // Check no route is a catch-all.
+  if ((config.extraViews ?? []).some((r) => r.path?.includes('pathMatch'))) {
+    problems.push('A route is a catch-all (contains pathMatch); the catch-all belongs to the router.')
+  }
+
+  // Check expected names are present.
+  for (const name of names) {
+    if (!declaredNames.includes(name)) {
+      problems.push(`Expected route "${name}" not found.`)
+    }
+  }
+
+  // Check expected legacy paths are present.
+  for (const path of legacyPaths) {
+    if (!declaredLegacy.includes(path)) {
+      problems.push(`Expected legacy path "${path}" not found.`)
+    }
+  }
+
+  return problems
+}
+
+/**
+ * Check that every route has a `meta.section` string. A route without one
+ * leaves the menu unaware of what section the visitor is in.
+ *
+ * Returns the list of problems found (empty if all is well).
+ */
+export function checkSectionMeta(config) {
+  const problems = []
+
+  for (const route of config.extraViews ?? []) {
+    if (typeof route.meta?.section !== 'string' || !route.meta.section.trim()) {
+      problems.push(`Route "${route.name}" has no section metadata.`)
+    }
+  }
+
+  return problems
+}
+
+/**
+ * Check that the texts in a mounted host include entries from the given
+ * namespaces. Matches each namespace against the rendered text with a
+ * case-insensitive regex like `/\b(ns1|ns2)\.[a-z]/i`.
+ *
+ * Returns the list of text keys matched (empty if none found). A missing
+ * key renders as its bare name, e.g. `"catalogue.era.ad"`, which the regex
+ * would match.
+ */
+export function checkTextsRendered(host, { namespaces = [] } = {}) {
+  if (!namespaces.length) return []
+
+  const text = host.textContent
+  const pattern = new RegExp(`\\b(${namespaces.join('|')})\\.[a-z]`, 'gi')
+  const found = new Set()
+
+  for (const match of text.matchAll(pattern)) {
+    found.add(match[1])
+  }
+
+  return Array.from(found)
+}