@glossarist/concept-browser 0.7.44 → 0.7.45

package/src/__tests__/non-verbal-scroll-guard.test.ts

@@ -0,0 +1,116 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { createRouter, createMemoryHistory, type Router } from 'vue-router';
+import { defineComponent, h } from 'vue';
+
+vi.mock('../utils/non-verbal-highlight', () => ({
+  scrollToEntity: vi.fn(),
+  highlightEntity: vi.fn(),
+}));
+
+import { scrollToEntity, highlightEntity } from '../utils/non-verbal-highlight';
+import { installNonVerbalScroll } from '../router/non-verbal-scroll-guard';
+
+const Stub = defineComponent({ render: () => h('div') });
+
+function makeRouter(): Router {
+  return createRouter({
+    history: createMemoryHistory(),
+    routes: [
+      { path: '/', name: 'home', component: Stub },
+      { path: '/concept/:id', name: 'concept', component: Stub },
+    ],
+  });
+}
+
+describe('installNonVerbalScroll', () => {
+  let matchMediaSpy: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(() => {
+    vi.useFakeTimers();
+    vi.mocked(scrollToEntity).mockClear();
+    vi.mocked(highlightEntity).mockClear();
+    vi.mocked(scrollToEntity).mockImplementation(() => undefined);
+    vi.mocked(highlightEntity).mockImplementation(() => undefined);
+    matchMediaSpy = vi.spyOn(window, 'matchMedia').mockReturnValue({
+      matches: false,
+      addEventListener: () => undefined,
+      removeEventListener: () => undefined,
+      media: '',
+      addListener: () => undefined,
+      removeListener: () => undefined,
+      dispatchEvent: () => false,
+      onchange: null,
+    });
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+    vi.restoreAllMocks();
+  });
+
+  it('scrolls and highlights when navigating to an entity hash', async () => {
+    const router = makeRouter();
+    installNonVerbalScroll(router);
+
+    const target = document.createElement('figure');
+    target.id = 'figure-ds-foo';
+    document.body.appendChild(target);
+
+    await router.push('/concept/1');
+    await router.push({ path: '/concept/1', hash: '#figure-ds-foo' });
+    await vi.advanceTimersByTimeAsync(100);
+
+    expect(scrollToEntity).toHaveBeenCalledWith(target, true);
+    expect(highlightEntity).toHaveBeenCalledWith(target);
+
+    document.body.removeChild(target);
+  });
+
+  it('passes smooth=false when the user prefers reduced motion', async () => {
+    matchMediaSpy.mockReturnValue({
+      matches: true,
+      addEventListener: () => undefined,
+      removeEventListener: () => undefined,
+      media: '',
+      addListener: () => undefined,
+      removeListener: () => undefined,
+      dispatchEvent: () => false,
+      onchange: null,
+    });
+
+    const router = makeRouter();
+    installNonVerbalScroll(router);
+
+    const target = document.createElement('figure');
+    target.id = 'figure-ds-reduced';
+    document.body.appendChild(target);
+
+    await router.push({ path: '/concept/2', hash: '#figure-ds-reduced' });
+    await vi.advanceTimersByTimeAsync(100);
+
+    expect(scrollToEntity).toHaveBeenCalledWith(target, false);
+
+    document.body.removeChild(target);
+  });
+
+  it('ignores hashes that are not entity anchors', async () => {
+    const router = makeRouter();
+    installNonVerbalScroll(router);
+
+    await router.push({ path: '/concept/3', hash: '#some-other-hash' });
+    await vi.advanceTimersByTimeAsync(200);
+
+    expect(scrollToEntity).not.toHaveBeenCalled();
+  });
+
+  it('gives up after the polling timeout if the target never appears', async () => {
+    const router = makeRouter();
+    installNonVerbalScroll(router, { timeoutMs: 60 });
+
+    await router.push({ path: '/concept/4', hash: '#figure-ds-never' });
+    await vi.advanceTimersByTimeAsync(200);
+
+    expect(scrollToEntity).not.toHaveBeenCalled();
+    expect(highlightEntity).not.toHaveBeenCalled();
+  });
+});

package/src/__tests__/use-concept-entities.test.ts

@@ -0,0 +1,76 @@
+import { describe, it, expect } from 'vitest';
+import { Concept } from 'glossarist';
+import { computed } from 'vue';
+import { useConceptEntities } from '../composables/use-concept-entities';
+
+function makeConcept(args: {
+  figures?: unknown[];
+  tables?: unknown[];
+  formulas?: unknown[];
+}): Concept {
+  return Concept.fromJSON({
+    id: '2-1-145',
+    localizations: { eng: { language_code: 'eng' } },
+    figures: args.figures ?? [],
+    tables: args.tables ?? [],
+    formulas: args.formulas ?? [],
+  });
+}
+
+describe('useConceptEntities', () => {
+  it('returns an empty list when the concept has no structural refs', () => {
+    const concept = computed(() => makeConcept({}));
+    const datasetId = computed(() => 'iala-2023');
+    const refs = useConceptEntities(concept, datasetId);
+    expect(refs.value).toEqual([]);
+  });
+
+  it('pulls figure refs from concept.figures', () => {
+    const concept = computed(() => makeConcept({
+      figures: [{ ref: 'mixed-reflection' }],
+    }));
+    const refs = useConceptEntities(concept, computed(() => 'iala-2023'));
+    expect(refs.value).toHaveLength(1);
+    expect(refs.value[0]).toMatchObject({
+      kind: 'figure',
+      entityId: 'mixed-reflection',
+      anchor: 'figure-iala-2023-mixed-reflection',
+    });
+  });
+
+  it('pulls table and formula refs alongside figures', () => {
+    const concept = computed(() => makeConcept({
+      figures: [{ ref: 'fig-1' }],
+      tables: [{ ref: 'tbl-1' }],
+      formulas: [{ ref: 'fml-1' }],
+    }));
+    const refs = useConceptEntities(concept, computed(() => 'ds'));
+    const kinds = refs.value.map(r => r.kind);
+    expect(kinds).toEqual(expect.arrayContaining(['figure', 'table', 'formula']));
+  });
+
+  it('preserves display override', () => {
+    const concept = computed(() => makeConcept({
+      figures: [{ ref: 'dispersion-prism', display: 'Figure 3' }],
+    }));
+    const refs = useConceptEntities(concept, computed(() => 'ds'));
+    expect(refs.value[0].display).toBe('Figure 3');
+  });
+
+  it('sets display to null when no override is provided', () => {
+    const concept = computed(() => makeConcept({
+      figures: [{ ref: 'foo' }],
+    }));
+    const refs = useConceptEntities(concept, computed(() => 'ds'));
+    expect(refs.value[0].display).toBeNull();
+  });
+
+  it('recomputes when datasetId changes', () => {
+    const concept = computed(() => makeConcept({
+      figures: [{ ref: 'foo' }],
+    }));
+    const datasetId = computed(() => 'first');
+    const refs = useConceptEntities(concept, datasetId);
+    expect(refs.value[0].anchor).toBe('figure-first-foo');
+  });
+});

package/src/adapters/bibliography-adapter.ts

@@ -0,0 +1,49 @@
+import { BibliographyData, type BibliographyEntry } from 'glossarist';
+
+export interface BibliographyAdapterOptions {
+  basePath?: string;
+  fetcher?: (url: string) => Promise<Response>;
+}
+
+export class BibliographyAdapter {
+  private data: BibliographyData | null = null;
+  private loaded = false;
+  private readonly basePath: string;
+  private readonly fetcher: (url: string) => Promise<Response>;
+
+  constructor(
+    private readonly datasetId: string,
+    opts: BibliographyAdapterOptions = {},
+  ) {
+    this.basePath = opts.basePath ?? import.meta.env.BASE_URL ?? '/';
+    this.fetcher = opts.fetcher ?? ((url: string) => fetch(url));
+  }
+
+  async load(): Promise<void> {
+    if (this.loaded) return;
+    try {
+      const resp = await this.fetcher(`${this.basePath}data/${this.datasetId}/bibliography.json`);
+      if (resp.ok) {
+        const json = await resp.json();
+        this.data = BibliographyData.fromJSON(json);
+      }
+    } catch {
+      // Honest failure: loaded=true prevents retry storms; findById returns null.
+    } finally {
+      this.loaded = true;
+    }
+  }
+
+  findById(id: string): BibliographyEntry | null {
+    return this.data?.find(id) ?? null;
+  }
+
+  all(): BibliographyEntry[] {
+    return this.data?.entries ?? [];
+  }
+
+  clear(): void {
+    this.data = null;
+    this.loaded = false;
+  }
+}

package/src/adapters/factory.ts

@@ -3,16 +3,30 @@ import type { RoutingEntry as ConfigRoutingEntry } from '../config/types';
 import { DatasetAdapter } from './DatasetAdapter';
 import { ReferenceResolver } from './ReferenceResolver';
 import { UriRouter } from './UriRouter';
+import { NonVerbalEntityResolver } from './non-verbal-resolver';
+import { BibliographyAdapter } from './bibliography-adapter';
 
 export class AdapterFactory {
   private adapters = new Map<string, DatasetAdapter>();
+  private bibliographyAdapters = new Map<string, BibliographyAdapter>();
   private crossRefIndex: Record<string, string[]> | null = null;
   readonly uriRouter: UriRouter;
   readonly resolver: ReferenceResolver;
+  readonly nonVerbalResolver: NonVerbalEntityResolver;
 
   constructor() {
     this.uriRouter = new UriRouter();
     this.resolver = new ReferenceResolver(this.uriRouter);
+    this.nonVerbalResolver = new NonVerbalEntityResolver();
+  }
+
+  bibliography(datasetId: string): BibliographyAdapter {
+    let a = this.bibliographyAdapters.get(datasetId);
+    if (!a) {
+      a = new BibliographyAdapter(datasetId);
+      this.bibliographyAdapters.set(datasetId, a);
+    }
+    return a;
   }
 
   async discoverDatasets(datasetsUrl: string): Promise<DatasetAdapter[]> {

package/src/adapters/model-bridge.ts

@@ -169,6 +169,9 @@ interface JsonLdConcept {
   'gl:localizedConcept'?: Record<string, JsonLdLocalizedConcept>;
   'gl:related'?: JsonLdRelated[];
   'gl:tags'?: string[];
+  'gl:figureRef'?: unknown[];
+  'gl:tableRef'?: unknown[];
+  'gl:formulaRef'?: unknown[];
 }
 
 // ── Bridges for fields not yet in glossarist-js ────────────────────────────
@@ -540,6 +543,9 @@ function conceptFromJsonLd(doc: JsonLdConcept): Concept {
     localizations,
     related,
     tags,
+    figures: normalizeEntityRefs(doc['gl:figureRef']),
+    tables: normalizeEntityRefs(doc['gl:tableRef']),
+    formulas: normalizeEntityRefs(doc['gl:formulaRef']),
     status: null,
   });
 
@@ -547,6 +553,51 @@ function conceptFromJsonLd(doc: JsonLdConcept): Concept {
   return concept;
 }
 
+/**
+ * Normalize JSON-LD structural entity refs (`gl:figureRef` / `gl:tableRef`
+ * / `gl:formulaRef`) into the shape `NonVerbalReference.fromJSON` expects.
+ *
+ * Accepts three wire forms — bare string ID, `{ "@id": "../kind/foo" }`,
+ * or `{ "@id": "../kind/foo", "gl:display": "Figure 3" }` — and emits the
+ * canonical `{ ref, display? }` shape. The path's last segment is the
+ * entity id; the field name (`figureRef` vs `tableRef` vs `formulaRef`)
+ * is the kind discriminator upstream.
+ */
+function normalizeEntityRefs(raw: unknown): unknown[] {
+  if (!Array.isArray(raw)) return [];
+  return raw.map(normalizeOneEntityRef).filter((v): v is Record<string, string> => v !== null);
+}
+
+function normalizeOneEntityRef(entry: unknown): Record<string, string> | null {
+  if (typeof entry === 'string') {
+    const trimmed = entry.trim();
+    return trimmed ? { ref: trimmed } : null;
+  }
+  if (!entry || typeof entry !== 'object') return null;
+  const obj = entry as Record<string, unknown>;
+  const atId = typeof obj['@id'] === 'string' ? (obj['@id'] as string) : null;
+  const explicitRef = typeof obj.ref === 'string' ? obj.ref
+    : typeof obj.entityId === 'string' ? obj.entityId
+    : typeof obj.entity_id === 'string' ? obj.entity_id
+    : null;
+  const entityId = (atId ? lastPathSegment(atId) : null) ?? explicitRef;
+  if (!entityId) return null;
+  const out: Record<string, string> = { ref: entityId };
+  const display = typeof obj['gl:display'] === 'string' ? obj['gl:display']
+    : typeof obj['gloss:display'] === 'string' ? obj['gloss:display']
+    : typeof obj.display === 'string' ? obj.display
+    : null;
+  if (display) out.display = display;
+  return out;
+}
+
+function lastPathSegment(p: string): string | null {
+  const cleaned = p.replace(/[?#].*$/, '').replace(/\/+$/, '');
+  const segments = cleaned.split('/');
+  const last = segments[segments.length - 1];
+  return last ? decodeURIComponent(last) : null;
+}
+
 // ── Public API ────────────────────────────────────────────────────────────
 
 export function conceptFromJson(doc: Record<string, unknown>): Concept {

package/src/adapters/non-verbal/figure-bridge.ts

@@ -0,0 +1,101 @@
+/**
+ * Figure bridge — JSON-LD → Figure (TS model).
+ *
+ * Wire format (per task 11 + glossarist-ruby's planned export):
+ *
+ *   {
+ *     "@id": "https://glossarist.org/{ds}/figure/{id}",
+ *     "@type": "gl:Figure" | "gloss:Figure",
+ *     "gl:id": "{id}",
+ *     "gl:identifier": "Figure 7c",            // plain string
+ *     "gl:caption": { "eng": "...", "fra": "..." },
+ *     "gl:altText": { "eng": "..." },           // mapped to model.alt
+ *     "gl:description": { "eng": "..." },
+ *     "gl:image": [
+ *       { "gl:src": "x.png", "gl:format": "png", "gl:role": "raster",
+ *         "gl:width": 1600, "gl:height": 1200, "gl:scale": 1 }
+ *     ],
+ *     "gl:subfigure": [ ... recursive Figure docs ... ],
+ *     "gl:source": [ ... NonVerbalSource docs ... ]
+ *   }
+ *
+ * The wire field `gl:altText` is mapped to the model field `alt` to avoid
+ * ambiguity with the HTML `<img alt>` attribute.
+ */
+
+import type { Figure, FigureImage, FigureImageFormat, FigureImageRole } from './types';
+import { isType, pickField, pickFieldArray, pickFieldRecord, localized } from './prefix';
+import { sourcesFromJsonLd } from './source-bridge';
+
+const FORMAT_SET: ReadonlySet<string> = new Set(['svg', 'png', 'jpg', 'jpeg', 'gif', 'webp', 'avif']);
+
+const ROLE_SET: ReadonlySet<string> = new Set(['vector', 'raster', 'dark', 'light', 'print']);
+
+function imageFromJsonLd(raw: Record<string, unknown>): FigureImage | null {
+  const src = pickField<string>(raw, 'src');
+  if (!src) return null;
+  const formatRaw = (pickField<string>(raw, 'format') ?? '').toLowerCase();
+  const format = (FORMAT_SET.has(formatRaw) ? formatRaw : 'svg') as FigureImageFormat;
+  const roleRaw = pickField<string>(raw, 'role');
+  const role = roleRaw && ROLE_SET.has(roleRaw) ? (roleRaw as FigureImageRole) : undefined;
+  const width = pickField<number>(raw, 'width');
+  const height = pickField<number>(raw, 'height');
+  const scale = pickField<number>(raw, 'scale');
+  const img: FigureImage = { src, format };
+  if (role) img.role = role;
+  if (typeof width === 'number') img.width = width;
+  if (typeof height === 'number') img.height = height;
+  if (typeof scale === 'number') img.scale = scale;
+  return img;
+}
+
+function imagesFromJsonLd(raw: unknown): FigureImage[] {
+  if (!Array.isArray(raw)) return [];
+  const out: FigureImage[] = [];
+  for (const entry of raw) {
+    if (!entry || typeof entry !== 'object') continue;
+    const img = imageFromJsonLd(entry as Record<string, unknown>);
+    if (img) out.push(img);
+  }
+  return out;
+}
+
+function subfiguresFromJsonLd(raw: unknown): Figure[] | undefined {
+  if (!Array.isArray(raw)) return undefined;
+  const out: Figure[] = [];
+  for (const entry of raw) {
+    if (!entry || typeof entry !== 'object') continue;
+    const sub = figureFromJsonLd(entry as Record<string, unknown>);
+    if (sub) out.push(sub);
+  }
+  return out.length ? out : undefined;
+}
+
+export function figureFromJsonLd(doc: Record<string, unknown>): Figure | null {
+  if (!isType(doc, 'Figure')) return null;
+
+  const id = pickField<string>(doc, 'id') ?? '';
+  if (!id) return null;
+
+  const identifier = pickField<string>(doc, 'identifier');
+  const caption = localized(doc, 'caption');
+  const alt = localized(doc, 'altText');
+  const description = localized(doc, 'description');
+  const images = imagesFromJsonLd(pickFieldArray(doc, 'image'));
+  const subfigures = subfiguresFromJsonLd(pickField(doc, 'subfigure'));
+  const sources = sourcesFromJsonLd(pickField(doc, 'source'));
+
+  const fig: Figure = { kind: 'figure', id, images };
+  if (identifier) fig.identifier = identifier;
+  if (caption) fig.caption = caption;
+  if (alt) fig.alt = alt;
+  if (description) fig.description = description;
+  if (subfigures) fig.subfigures = subfigures;
+  if (sources.length) fig.sources = sources;
+
+  // pickFieldRecord is unused for figures; keep the import meaningful by
+  // ensuring no stray image fields leak through (silent no-op).
+  void pickFieldRecord;
+
+  return fig;
+}

package/src/adapters/non-verbal/formula-bridge.ts

@@ -0,0 +1,48 @@
+/**
+ * Formula bridge — JSON-LD → Formula (TS model).
+ *
+ * Wire format:
+ *
+ *   {
+ *     "@type": "gl:Formula",
+ *     "gl:id": "{id}",
+ *     "gl:identifier": "Formula 5",
+ *     "gl:caption": { ... },
+ *     "gl:description": { ... },
+ *     "gl:expression": { "eng": "E = mc^2", "fra": "E = mc^2" },
+ *     "gl:notation": "latex" | "mathml" | "asciimath",
+ *     "gl:source": [ ... ]
+ *   }
+ */
+
+import type { Formula, FormulaNotation } from './types';
+import { isType, pickField, localized } from './prefix';
+import { sourcesFromJsonLd } from './source-bridge';
+
+const NOTATION_SET: ReadonlySet<string> = new Set(['latex', 'mathml', 'asciimath']);
+
+export function formulaFromJsonLd(doc: Record<string, unknown>): Formula | null {
+  if (!isType(doc, 'Formula')) return null;
+
+  const id = pickField<string>(doc, 'id') ?? '';
+  if (!id) return null;
+
+  const expression = localized(doc, 'expression');
+  if (!expression) return null;
+
+  const notationRaw = (pickField<string>(doc, 'notation') ?? '').toLowerCase();
+  const notation = NOTATION_SET.has(notationRaw) ? (notationRaw as FormulaNotation) : 'latex';
+
+  const identifier = pickField<string>(doc, 'identifier');
+  const caption = localized(doc, 'caption');
+  const description = localized(doc, 'description');
+  const sources = sourcesFromJsonLd(pickField(doc, 'source'));
+
+  const f: Formula = { kind: 'formula', id, expression, notation };
+  if (identifier) f.identifier = identifier;
+  if (caption) f.caption = caption;
+  if (description) f.description = description;
+  if (sources.length) f.sources = sources;
+
+  return f;
+}

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

@@ -0,0 +1,55 @@
+/**
+ * Public API for the non-verbal entity model layer.
+ *
+ * Re-exports the types, bridges, and dispatch table. Components and
+ * composables import from here — never from individual files — so the
+ * internal layout can evolve without breaking the public surface.
+ */
+
+export type {
+  LocalizedString,
+  NonVerbalKind,
+  FigureImage,
+  FigureImageFormat,
+  FigureImageRole,
+  NonVerbalSource,
+  NonVerbalSourceOrigin,
+  NonVerbalSourceRef,
+  NonVerbalSourceLocality,
+  NonVerbalEntityBase,
+  Figure,
+  Table,
+  TableContent,
+  TableFormat,
+  Formula,
+  FormulaNotation,
+  NonVerbalEntity,
+  NonVerbRepV3,
+  NonVerbalReference,
+} from './types';
+
+export { isFigure, isTable, isFormula } from './types';
+
+export { figureFromJsonLd } from './figure-bridge';
+export { tableFromJsonLd } from './table-bridge';
+export { formulaFromJsonLd } from './formula-bridge';
+
+export {
+  KIND_TO_DIR,
+  KIND_TO_TYPE_FIELD,
+  KIND_TO_BRIDGE,
+  ALL_KINDS,
+  MENTION_KIND_TO_ENTITY_KIND,
+  kindFromType,
+  entityKindFromMentionKind,
+} from './kind';
+
+export type { BridgeFn } from './kind';
+
+export {
+  pickField,
+  pickFieldArray,
+  pickFieldRecord,
+  isType,
+  localized,
+} from './prefix';

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

@@ -0,0 +1,46 @@
+import type { NonVerbalEntity, NonVerbalKind } from './types';
+import {
+  ENTITY_DIRECTORIES,
+  ENTITY_TYPES,
+} from 'glossarist';
+import { figureFromJsonLd } from './figure-bridge';
+import { tableFromJsonLd } from './table-bridge';
+import { formulaFromJsonLd } from './formula-bridge';
+
+export type BridgeFn = (doc: Record<string, unknown>) => NonVerbalEntity | null;
+
+export const KIND_TO_DIR: Readonly<Record<NonVerbalKind, string>> = Object.freeze(
+  Object.fromEntries(ENTITY_DIRECTORIES),
+) as Readonly<Record<NonVerbalKind, string>>;
+
+export const KIND_TO_TYPE_FIELD: Readonly<Record<NonVerbalKind, string>> = {
+  figure: 'Figure',
+  table: 'Table',
+  formula: 'Formula',
+};
+
+export const KIND_TO_BRIDGE: Readonly<Record<NonVerbalKind, BridgeFn>> = {
+  figure: figureFromJsonLd,
+  table: tableFromJsonLd,
+  formula: formulaFromJsonLd,
+};
+
+export const ALL_KINDS: readonly NonVerbalKind[] = ENTITY_TYPES as readonly NonVerbalKind[];
+
+export const MENTION_KIND_TO_ENTITY_KIND: Readonly<Record<string, NonVerbalKind>> = {
+  'fig-ref': 'figure',
+  'table-ref': 'table',
+  'formula-ref': 'formula',
+};
+
+export function kindFromType(typeField: string): NonVerbalKind | null {
+  const bare = typeField.replace(/^(gl|gloss):/, '');
+  for (const k of ALL_KINDS) {
+    if (bare === KIND_TO_TYPE_FIELD[k]) return k;
+  }
+  return null;
+}
+
+export function entityKindFromMentionKind(mentionKind: string): NonVerbalKind | null {
+  return MENTION_KIND_TO_ENTITY_KIND[mentionKind] ?? null;
+}

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

@@ -0,0 +1,67 @@
+/**
+ * Vocabulary prefix helper.
+ *
+ * The concept-browser JSON-LD corpus uses the `gl:` prefix. glossarist-ruby's
+ * `glossarist export` is planned to emit `gloss:` prefix. Until the
+ * cross-repo vocabulary issue is resolved (see AUDIT.figures.md §"Open
+ * issue: vocabulary prefix"), bridges must accept both prefixes.
+ *
+ * `pickField` is the single accessor every bridge uses — centralizing the
+ * dual-prefix handling here means removing the legacy prefix later is a
+ * one-file change.
+ */
+
+const PREFIXES = ['gl', 'gloss'] as const;
+
+export function pickField<T = unknown>(
+  doc: Record<string, unknown>,
+  field: string,
+): T | undefined {
+  for (const p of PREFIXES) {
+    const k = `${p}:${field}`;
+    if (doc[k] !== undefined) return doc[k] as T;
+  }
+  return undefined;
+}
+
+export function pickFieldArray<T = unknown>(
+  doc: Record<string, unknown>,
+  field: string,
+): T[] {
+  const v = pickField<T[]>(doc, field);
+  return Array.isArray(v) ? v : [];
+}
+
+export function pickFieldRecord<V = unknown>(
+  doc: Record<string, unknown>,
+  field: string,
+): Record<string, V> | undefined {
+  const v = pickField<unknown>(doc, field);
+  if (v && typeof v === 'object' && !Array.isArray(v)) {
+    return v as Record<string, V>;
+  }
+  return undefined;
+}
+
+export function isType(doc: Record<string, unknown>, typeShort: string): boolean {
+  const t = doc['@type'];
+  if (typeof t !== 'string') return false;
+  for (const p of PREFIXES) {
+    if (t === `${p}:${typeShort}`) return true;
+  }
+  return false;
+}
+
+export function localized(doc: Record<string, unknown>, field: string): Record<string, string> | undefined {
+  const v = pickField<unknown>(doc, field);
+  if (!v) return undefined;
+  if (typeof v === 'string') return { eng: v };
+  if (typeof v === 'object' && !Array.isArray(v)) {
+    const out: Record<string, string> = {};
+    for (const [k, val] of Object.entries(v)) {
+      if (typeof val === 'string') out[k] = val;
+    }
+    return Object.keys(out).length ? out : undefined;
+  }
+  return undefined;
+}