@glossarist/concept-browser 0.7.43 → 0.7.45

package/src/adapters/non-verbal/types.ts

@@ -0,0 +1,133 @@
+/**
+ * Non-verbal entity model — TypeScript projection of the authoritative
+ * glossarist-ruby model.
+ *
+ * The authoritative model lives in glossarist-ruby (Figure, Table, Formula
+ * inherit from NonVerbalEntity). This file mirrors that model in TypeScript
+ * for the consumer side. It does not redefine the model — every field here
+ * corresponds to a field in the authoritative source.
+ *
+ * See:
+ *   ../glossarist-ruby/lib/glossarist/non_verbal_entity.rb
+ *   ../glossarist-ruby/lib/glossarist/figure.rb
+ *   ../glossarist-ruby/lib/glossarist/table.rb
+ *   ../glossarist-ruby/lib/glossarist/formula.rb
+ *   ../glossarist-ruby/lib/glossarist/figure_image.rb
+ */
+
+export type LocalizedString = Record<string, string>;
+
+export type NonVerbalKind = 'figure' | 'table' | 'formula';
+
+export type FigureImageFormat = 'svg' | 'png' | 'jpg' | 'jpeg' | 'gif' | 'webp' | 'avif';
+
+export type FigureImageRole = 'vector' | 'raster' | 'dark' | 'light' | 'print';
+
+export interface FigureImage {
+  src: string;
+  format: FigureImageFormat;
+  role?: FigureImageRole;
+  width?: number;
+  height?: number;
+  scale?: number;
+}
+
+export interface NonVerbalSourceRef {
+  source?: string;
+  id?: string;
+  version?: string;
+  text?: string;
+}
+
+export interface NonVerbalSourceLocality {
+  type?: string;
+  referenceFrom?: string;
+  referenceTo?: string;
+}
+
+export interface NonVerbalSourceOrigin {
+  ref?: NonVerbalSourceRef;
+  locality?: NonVerbalSourceLocality;
+  link?: string;
+  id?: string;
+  version?: string;
+  source?: string;
+}
+
+export interface NonVerbalSource {
+  id?: string;
+  type?: string;
+  status?: string;
+  modification?: string;
+  origin?: NonVerbalSourceOrigin;
+}
+
+export interface NonVerbalEntityBase {
+  id: string;
+  identifier?: string;
+  caption?: LocalizedString;
+  description?: LocalizedString;
+  alt?: LocalizedString;
+  sources?: NonVerbalSource[];
+}
+
+export interface Figure extends NonVerbalEntityBase {
+  kind: 'figure';
+  images: FigureImage[];
+  subfigures?: Figure[];
+}
+
+export type TableFormat = 'html' | 'markdown' | 'asciidoc';
+
+export type TableContent =
+  | { kind: 'structured'; headers: LocalizedString[]; rows: LocalizedString[][] }
+  | { kind: 'markup'; markup: LocalizedString };
+
+export interface Table extends NonVerbalEntityBase {
+  kind: 'table';
+  content: TableContent;
+  format?: TableFormat;
+}
+
+export type FormulaNotation = 'latex' | 'mathml' | 'asciimath';
+
+export interface Formula extends NonVerbalEntityBase {
+  kind: 'formula';
+  expression: LocalizedString;
+  notation: FormulaNotation;
+}
+
+export type NonVerbalEntity = Figure | Table | Formula;
+
+/**
+ * V3 NonVerbRep runtime shape.
+ *
+ * glossarist-js's runtime `NonVerbRep` (post-V3 reshape) holds the same
+ * localized fields as `NonVerbalEntityBase` plus a `type` discriminator
+ * and an `images[]` array. The published `.d.ts` still describes the
+ * pre-V3 `ref`/`text` shape; this local interface lets consumer code
+ * type-check against reality. Remove when upstream ships a corrected
+ * `.d.ts` (TODO.figures/19).
+ */
+export interface NonVerbRepV3 extends NonVerbalEntityBase {
+  type: string | null;
+  images: FigureImage[];
+}
+
+export interface NonVerbalReference {
+  kind: NonVerbalKind;
+  entityId: string;
+  display?: string;
+}
+
+export function isFigure(entity: NonVerbalEntity): entity is Figure {
+  return entity.kind === 'figure';
+}
+
+export function isTable(entity: NonVerbalEntity): entity is Table {
+  return entity.kind === 'table';
+}
+
+export function isFormula(entity: NonVerbalEntity): entity is Formula {
+  return entity.kind === 'formula';
+}

package/src/adapters/non-verbal-resolver.ts

@@ -0,0 +1,101 @@
+/**
+ * NonVerbalEntityResolver — the single runtime access point for non-verbal
+ * entities.
+ *
+ * Responsibilities:
+ *   - Fetch entity JSON-LD from `public/data/{ds}/{kind-dir}/{id}.json`.
+ *   - Bridge to the TS model via `KIND_TO_BRIDGE`.
+ *   - Cache per `(kind, datasetId, id)` with Promise dedup for concurrent
+ *     callers.
+ *   - Compute image URLs (basePath-aware for GitHub Pages).
+ *   - Compute stable anchor IDs via the anchor SSOT.
+ *
+ * Components and the content-renderer go through this resolver; they never
+ * call `fetch()` directly. The resolver is owned by `AdapterFactory` —
+ * exactly one instance per app.
+ */
+
+import type { NonVerbalEntity, NonVerbalKind } from './non-verbal/types';
+import { KIND_TO_DIR, KIND_TO_BRIDGE } from './non-verbal/kind';
+import { anchorId } from '../utils/non-verbal-anchor';
+
+export type { NonVerbalEntity, NonVerbalKind } from './non-verbal/types';
+
+export interface NonVerbalEntityResolverOptions {
+  basePath?: string;
+  fetcher?: (url: string) => Promise<Response>;
+}
+
+interface CacheEntry {
+  promise: Promise<NonVerbalEntity | null>;
+  resolved: NonVerbalEntity | null | undefined;
+}
+
+export class NonVerbalEntityResolver {
+  private readonly cache = new Map<string, CacheEntry>();
+  private readonly basePath: string;
+  private readonly fetcher: (url: string) => Promise<Response>;
+
+  constructor(opts: NonVerbalEntityResolverOptions = {}) {
+    this.basePath = opts.basePath ?? import.meta.env.BASE_URL ?? '/';
+    this.fetcher = opts.fetcher ?? ((url: string) => fetch(url));
+  }
+
+  resolve(kind: NonVerbalKind, datasetId: string, entityId: string): Promise<NonVerbalEntity | null> {
+    const key = `${kind}|${datasetId}|${entityId}`;
+    const existing = this.cache.get(key);
+    if (existing) return existing.promise;
+
+    const promise = (async () => {
+      const dir = KIND_TO_DIR[kind];
+      const url = `${this.basePath}data/${datasetId}/${dir}/${entityId}.json`;
+      const resp = await this.fetcher(url);
+      if (resp.status === 404) return null;
+      if (!resp.ok) {
+        throw new Error(`Failed to load ${kind} ${entityId} from ${datasetId}: ${resp.status}`);
+      }
+      const doc = (await resp.json()) as Record<string, unknown>;
+      const entity = KIND_TO_BRIDGE[kind](doc);
+      return entity;
+    })();
+
+    const entry: CacheEntry = { promise, resolved: undefined };
+    promise.then(
+      v => { entry.resolved = v; return v; },
+      () => { this.cache.delete(key); return null; },
+    );
+    this.cache.set(key, entry);
+    return promise;
+  }
+
+  /**
+   * Synchronous peek at the cache. Returns the entity if the previous
+   * `resolve` already completed, otherwise `undefined`. Useful for SSR or
+   * pre-hydration checks where the cache is warm.
+   */
+  peek(kind: NonVerbalKind, datasetId: string, entityId: string): NonVerbalEntity | null | undefined {
+    return this.cache.get(`${kind}|${datasetId}|${entityId}`)?.resolved;
+  }
+
+  resolveImageUrl(datasetId: string, src: string): string {
+    const cleanSrc = src.startsWith('images/') ? src.slice('images/'.length) : src;
+    return `${this.basePath}data/${datasetId}/images/${cleanSrc}`;
+  }
+
+  anchor(kind: NonVerbalKind, datasetId: string, entityId: string): string {
+    return anchorId(kind, datasetId, entityId);
+  }
+
+  /**
+   * Drop the cached entry for one entity. Locale switching does NOT need
+   * this — the cached entity is the raw JSON-LD, and localization happens
+   * at render time via the locale SSOT.
+   */
+  invalidate(kind: NonVerbalKind, datasetId: string, entityId: string): void {
+    this.cache.delete(`${kind}|${datasetId}|${entityId}`);
+  }
+
+  clear(): void {
+    this.cache.clear();
+  }
+}

package/src/components/ConceptDetail.vue

@@ -16,6 +16,8 @@ import { getFactory } from '../adapters/factory';
 import { useRenderOptions } from '../composables/use-render-options';
 import { useConceptEdges } from '../composables/use-concept-edges';
 import { useConceptContent } from '../composables/use-concept-content';
+import { useConceptEntities } from '../composables/use-concept-entities';
+import { useNonVerbalCrossRef } from '../composables/use-non-verbal-cross-ref';
 import { relationshipLabel, INVERSE_RELATIONSHIPS } from '../utils/relationship-categories';
 import { slugify } from '../utils/slugify';
 import { useSiteConfig } from '../config/use-site-config';
@@ -23,6 +25,7 @@ import ConceptTimeline from './ConceptTimeline.vue';
 import ConceptRdfView from './ConceptRdfView.vue';
 import FormatDownloads from './FormatDownloads.vue';
 import NonVerbalRepDisplay from './NonVerbalRepDisplay.vue';
+import NonVerbalList from './non-verbal/NonVerbalList.vue';
 import CitationDisplay from './CitationDisplay.vue';
 import DesignationList from './DesignationList.vue';
 import { useI18n } from '../i18n';
@@ -103,7 +106,7 @@ const conceptSources = computed(() => props.concept.sources);
 const conceptTags = computed(() => props.concept.tags ?? []);
 
 const factory = getFactory();
-const { ensureBibLoaded, bibResolver, figResolver } = useRenderOptions(() => props.registerId);
+const { ensureBibLoaded, bibResolver, nonVerbalRefResolver } = useRenderOptions(() => props.registerId);
 
 const renderOpts = computed<RenderOptions>(() => ({
   xrefResolver: (uri, term) => {
@@ -125,11 +128,18 @@ const renderOpts = computed<RenderOptions>(() => ({
     return `<a href="#" class="xref-link" data-register="${escapeAttr(props.registerId)}" data-concept="${escapeAttr(resolvedId)}">${escapeAttr(term)}</a>`;
   },
   bibResolver,
-  figResolver,
+  nonVerbalRefResolver,
 }));
 
 watch(() => props.registerId, () => { ensureBibLoaded(); }, { immediate: true });
 
+const structuralEntityRefs = useConceptEntities(
+  computed(() => props.concept),
+  computed(() => props.registerId),
+);
+
+useNonVerbalCrossRef();
+
 function handleContentClick(e: MouseEvent) {
   const target = (e.target as HTMLElement).closest('.xref-link') as HTMLElement | null;
   if (!target) return;
@@ -416,7 +426,7 @@ const nonVerbalReps = computed(() => {
               </div>
 
               <!-- Non-verbal representations -->
-              <NonVerbalRepDisplay v-if="lc.lc.nonVerbalRep?.length" :reps="lc.lc.nonVerbalRep" />
+              <NonVerbalRepDisplay v-if="lc.lc.nonVerbalRep?.length" :reps="lc.lc.nonVerbalRep" :locale="lc.lang" :register-id="registerId" :dataset-locales="languages" />
 
               <!-- Sources -->
               <div v-if="lc.sources.length" class="space-y-2">
@@ -467,7 +477,10 @@ const nonVerbalReps = computed(() => {
           </div>
 
           <!-- Non-verbal reps (concept-level) -->
-          <NonVerbalRepDisplay v-if="nonVerbalReps.length" :reps="nonVerbalReps" />
+          <NonVerbalRepDisplay v-if="nonVerbalReps.length" :reps="nonVerbalReps" :locale="languages[0] ?? 'eng'" :register-id="registerId" :dataset-locales="languages" />
+
+          <!-- Structural entity refs (concept-level figures/tables/formulas) -->
+          <NonVerbalList v-if="structuralEntityRefs.length" :refs="structuralEntityRefs" />
         </div>
 
         <!-- Right sidebar -->

package/src/components/LanguageDetail.vue

@@ -63,9 +63,6 @@ const renderOpts: RenderOptions = {
   bibResolver: (refId, title) => {
     return `<span class="bib-ref">${escapeAttr(title)}</span>`;
   },
-  figResolver: (figId) => {
-    return `<span class="fig-ref">${escapeAttr(figId)}</span>`;
-  },
 };
 
 function handleContentClick(e: MouseEvent) {

package/src/components/NonVerbalRepDisplay.vue

@@ -1,38 +1,96 @@
 <script setup lang="ts">
-import type { NonVerbRep, ConceptSource } from 'glossarist';
-import { sourceStatusInfo, sourceTypeInfo } from '../utils/designation-registry';
+import { computed } from 'vue';
+import type { NonVerbRep, Citation } from 'glossarist';
+import type { FigureImage, LocalizedString, NonVerbRepV3, NonVerbalSource } from '../adapters/non-verbal/types';
+import { resolveFallbackChain } from '../utils/locale';
+import FigureImages from './figure/FigureImages.vue';
+import NonVerbalCaption from './non-verbal/NonVerbalCaption.vue';
+import CitationDisplay from './CitationDisplay.vue';
 
-defineProps<{
+const props = defineProps<{
   reps: NonVerbRep[];
+  locale: string;
+  registerId: string;
+  datasetLocales?: readonly string[];
 }>();
+
+const fallbackChain = computed(() => resolveFallbackChain(props.datasetLocales));
+
+// Cast once at the boundary: glossarist-js's published `.d.ts` still
+// describes pre-V3 NonVerbRep, but the runtime exposes the V3 shape
+// (images/alt/caption/description/sources). See TODO.figures/19.
+const v3Reps = computed<NonVerbRepV3[]>(() => props.reps as unknown as NonVerbRepV3[]);
+
+function imagesOf(rep: NonVerbRepV3): FigureImage[] {
+  return rep.images ?? [];
+}
+
+function hasImages(rep: NonVerbRepV3): boolean {
+  return imagesOf(rep).length > 0;
+}
+
+function asCitation(origin: NonVerbalSource['origin']): Citation | null {
+  return (origin as unknown as Citation) ?? null;
+}
 </script>
 
 <template>
-  <div v-if="reps.length" class="space-y-3">
+  <div v-if="v3Reps.length" class="space-y-3">
     <div class="section-label">Non-verbal representations</div>
-    <div v-for="(rep, i) in reps" :key="i" class="card p-4 space-y-2">
-      <div class="flex items-center gap-2">
-        <span class="badge text-[10px] bg-violet-50 text-violet-700">{{ rep.type ?? 'representation' }}</span>
-        <span v-if="rep.text" class="text-sm text-ink-700">{{ rep.text }}</span>
-      </div>
+    <figure v-for="(rep, i) in v3Reps" :key="i" class="card p-4 space-y-2">
+      <span class="badge text-[10px] bg-violet-50 text-violet-700">{{ rep.type ?? 'representation' }}</span>
 
-      <!-- Image -->
-      <div v-if="rep.type === 'image' && rep.ref">
-        <img :src="rep.ref" :alt="rep.text || 'Non-verbal representation'" class="max-h-64 rounded border border-ink-100" loading="lazy" />
-      </div>
+      <FigureImages
+        v-if="hasImages(rep)"
+        :images="imagesOf(rep)"
+        :alt="(rep.alt as LocalizedString | undefined) ?? undefined"
+        :dataset-id="registerId"
+        :locale="locale"
+        :fallback-chain="fallbackChain"
+        :has-description="!!rep.description && Object.keys(rep.description).length > 0"
+        :entity-label="rep.type ?? 'representation'"
+      />
 
-      <!-- Table / Formula reference -->
-      <div v-if="(rep.type === 'table' || rep.type === 'formula') && rep.ref">
-        <a :href="rep.ref" target="_blank" rel="noopener" class="text-sm concept-link break-all">{{ rep.ref }}</a>
-      </div>
+      <NonVerbalCaption
+        :caption="(rep.caption as LocalizedString | undefined) ?? undefined"
+        :description="(rep.description as LocalizedString | undefined) ?? undefined"
+        :locale="locale"
+        :fallback-chain="fallbackChain"
+      />
 
-      <!-- Sources for this representation -->
-      <div v-if="rep.sources?.length" class="flex flex-wrap gap-1.5">
-        <div v-for="(src, si) in rep.sources" :key="si" class="text-xs text-ink-400">
-          <span v-if="src.type" class="badge text-[9px]" :class="sourceTypeInfo(src.type).color">{{ sourceTypeInfo(src.type).label }}</span>
-          <span v-if="src.origin?.ref" class="ml-1">{{ src.origin.ref.source }}{{ src.origin.ref.id ? ' ' + src.origin.ref.id : '' }}</span>
-        </div>
+      <div v-if="rep.sources?.length" class="nv-rep__sources">
+        <div class="nv-rep__sources-label">Sources</div>
+        <ol class="nv-rep__sources-list">
+          <li v-for="(src, si) in rep.sources" :key="si" class="nv-rep__source">
+            <CitationDisplay v-if="asCitation(src.origin)" :citation="asCitation(src.origin)!" :register-id="registerId" />
+            <span v-if="src.modification" class="nv-rep__source-modification">— {{ src.modification }}</span>
+          </li>
+        </ol>
       </div>
-    </div>
+    </figure>
   </div>
 </template>
+
+<style scoped>
+.nv-rep__sources {
+  font-size: 0.75rem;
+  color: var(--ink-500, #666);
+  margin-top: 0.5rem;
+}
+.nv-rep__sources-label {
+  font-weight: 600;
+  text-transform: uppercase;
+  letter-spacing: 0.04em;
+  margin-bottom: 0.25rem;
+}
+.nv-rep__sources-list {
+  list-style: decimal inside;
+  display: flex;
+  flex-direction: column;
+  gap: 0.25rem;
+}
+.nv-rep__source-modification {
+  color: var(--ink-400, #888);
+  font-style: italic;
+}
+</style>

package/src/components/figure/FigureDisplay.vue

@@ -0,0 +1,132 @@
+<script setup lang="ts">
+/**
+ * FigureDisplay — main component for rendering a dataset-level Figure.
+ *
+ * Fetches the entity via the resolver, renders the image(s), caption,
+ * description, and sources. Composite figures (with subfigures) render
+ * recursively — each subfigure is itself a FigureDisplay.
+ *
+ * Self-anchoring: the outer `<figure>` element receives the anchor ID
+ * so `{{fig:id}}` mentions can scroll to it via the cross-ref composable.
+ */
+import { computed, ref } from 'vue';
+import type { Figure } from '../../adapters/non-verbal/types';
+import { useNonVerbalEntity } from '../../composables/use-non-verbal-entity';
+import { resolveFallbackChain } from '../../utils/locale';
+import { anchorId } from '../../utils/non-verbal-anchor';
+import { deriveLayout } from './figure-layout';
+import NonVerbalCaption from '../non-verbal/NonVerbalCaption.vue';
+import NonVerbalSources from '../non-verbal/NonVerbalSources.vue';
+import NonVerbalFallback from '../non-verbal/NonVerbalFallback.vue';
+import FigureImages from './FigureImages.vue';
+
+const props = defineProps<{
+  datasetId: string;
+  entityId: string;
+  locale: string;
+  /** Languages configured on the dataset — drives fallback chain. */
+  datasetLocales?: readonly string[];
+}>();
+
+const k = () => 'figure' as const;
+const ds = () => props.datasetId;
+const id = () => props.entityId;
+const { entity, state, error } = useNonVerbalEntity(k, ds, id);
+
+const fallbackChain = computed(() => resolveFallbackChain(props.datasetLocales));
+const layout = computed(() => entity.value ? deriveLayout(entity.value as Figure) : 'single');
+const anchor = computed(() => anchorId('figure', props.datasetId, props.entityId));
+const descriptionId = computed(() => `${anchor.value}-desc`);
+
+const topLevelImages = computed(() => (entity.value as Figure | null)?.images ?? []);
+</script>
+
+<template>
+  <figure
+    v-if="entity && state === 'loaded'"
+    :id="anchor"
+    :class="`figure figure--${layout}`"
+  >
+    <div v-if="topLevelImages.length" :class="`figure__media figure__media--${layout}`">
+      <FigureImages
+        :images="topLevelImages"
+        :alt="(entity as Figure).alt"
+        :dataset-id="datasetId"
+        :locale="locale"
+        :fallback-chain="fallbackChain"
+        :hasDescription="!!(entity as Figure).description && Object.keys((entity as Figure).description ?? {}).length > 0"
+        :description-id="descriptionId"
+        entity-label="Figure"
+      />
+    </div>
+
+    <template v-if="(entity as Figure).subfigures?.length">
+      <div :class="`figure__subfigures figure__subfigures--${layout}`">
+        <FigureDisplay
+          v-for="sub in (entity as Figure).subfigures"
+          :key="sub.id"
+          :dataset-id="datasetId"
+          :entity-id="sub.id"
+          :locale="locale"
+          :dataset-locales="datasetLocales"
+        />
+      </div>
+    </template>
+
+    <NonVerbalCaption
+      :identifier="(entity as Figure).identifier"
+      :caption="(entity as Figure).caption"
+      :description="(entity as Figure).description"
+      :locale="locale"
+      :fallback-chain="fallbackChain"
+      :description-id="descriptionId"
+    />
+
+    <NonVerbalSources
+      v-if="(entity as Figure).sources?.length"
+      :sources="(entity as Figure).sources!"
+    />
+  </figure>
+
+  <NonVerbalFallback
+    v-else-if="state === 'loading' || state === 'not-found' || state === 'error'"
+    :state="state"
+    kind="figure"
+    :entity-id="entityId"
+    :message="error ?? undefined"
+  />
+</template>
+
+<style scoped>
+.figure {
+  margin: 1rem 0;
+  display: flex;
+  flex-direction: column;
+  gap: 0.5rem;
+}
+.figure__media--row,
+.figure__media--grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(160px, 1fr));
+  gap: 0.75rem;
+}
+.figure__media--column {
+  display: flex;
+  flex-direction: column;
+  gap: 0.75rem;
+}
+.figure__subfigures--row { flex-direction: row; flex-wrap: wrap; gap: 0.75rem; }
+.figure__subfigures--column { flex-direction: column; gap: 0.75rem; }
+.figure__subfigures--grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(160px, 1fr));
+  gap: 0.75rem;
+}
+
+[dir='rtl'] .figure__subfigures--row { flex-direction: row-reverse; }
+
+.figure:focus-visible {
+  outline: 2px solid var(--blue-500, #3b82f6);
+  outline-offset: 4px;
+}
+</style>

package/src/components/figure/FigureImages.vue

@@ -0,0 +1,111 @@
+<script setup lang="ts">
+import { computed } from 'vue';
+import type { FigureImage, LocalizedString } from '../../adapters/non-verbal/types';
+import { pickLocaleText, hasLocale } from '../../utils/locale';
+import { getFactory } from '../../adapters/factory';
+
+const props = withDefaults(defineProps<{
+  images: FigureImage[];
+  alt?: LocalizedString;
+  datasetId: string;
+  locale: string;
+  fallbackChain?: readonly string[];
+  descriptionId?: string;
+  hasDescription?: boolean;
+  entityLabel?: string;
+}>(), {
+  entityLabel: 'Figure',
+});
+
+const resolver = getFactory().nonVerbalResolver;
+
+const altText = computed(() => pickLocaleText(props.alt, props.locale, props.fallbackChain));
+const altMissing = computed(() => !props.alt || Object.keys(props.alt).length === 0);
+const altEmpty = computed(() =>
+  !!props.alt && hasLocale(props.alt, props.locale) && props.alt[props.locale] === '',
+);
+
+interface SourceVariant { src: string; type: string; media?: string; }
+
+const sourceVariants = computed<SourceVariant[]>(() => {
+  const out: SourceVariant[] = [];
+  for (const img of props.images) {
+    if (!img.role || img.role === 'vector' || img.role === 'raster') continue;
+    const src = resolver.resolveImageUrl(props.datasetId, img.src);
+    const type = img.format === 'svg' ? 'image/svg+xml' : `image/${img.format === 'jpg' ? 'jpeg' : img.format}`;
+    let media: string | undefined;
+    if (img.role === 'dark') media = '(prefers-color-scheme: dark)';
+    else if (img.role === 'light') media = '(prefers-color-scheme: light)';
+    else if (img.role === 'print') media = 'print';
+    out.push({ src, type, media });
+  }
+  return out;
+});
+
+const defaultImg = computed(() => {
+  const nonRole = props.images.find(i => !i.role || i.role === 'vector' || i.role === 'raster');
+  const chosen = nonRole ?? props.images[0];
+  if (!chosen) return null;
+  return {
+    src: resolver.resolveImageUrl(props.datasetId, chosen.src),
+    width: chosen.width,
+    height: chosen.height,
+  };
+});
+</script>
+
+<template>
+  <div class="figure__images">
+    <picture v-if="!altMissing">
+      <source
+        v-for="(v, i) in sourceVariants"
+        :key="i"
+        :type="v.type"
+        :srcset="v.src"
+        :media="v.media"
+      />
+      <img
+        v-if="defaultImg"
+        :src="defaultImg.src"
+        :alt="altEmpty ? '' : altText"
+        :width="defaultImg.width"
+        :height="defaultImg.height"
+        loading="lazy"
+        :aria-describedby="hasDescription && descriptionId ? descriptionId : undefined"
+        class="figure__img"
+      >
+    </picture>
+    <div
+      v-else
+      class="figure__alt-missing"
+      role="img"
+      :aria-label="`${entityLabel} is missing alt text`"
+    >
+      <p>{{ entityLabel }}: alt text missing</p>
+    </div>
+  </div>
+</template>
+
+<style scoped>
+.figure__images {
+  margin: 0;
+}
+.figure__img {
+  max-width: 100%;
+  height: auto;
+  display: block;
+  border-radius: 0.375rem;
+}
+.figure__alt-missing {
+  padding: 1rem;
+  background: #fef3c7;
+  border: 1px dashed #d97706;
+  border-radius: 0.375rem;
+  color: #92400e;
+  font-size: 0.8125rem;
+}
+
+@media (prefers-color-scheme: dark) {
+  .figure__img { background: var(--surface-alt, #222); }
+}
+</style>