@glossarist/concept-browser 0.3.7 → 0.4.0

package/src/__tests__/test-helpers.ts

@@ -1,6 +1,7 @@
 import { createPinia, setActivePinia } from 'pinia';
 import { createRouter, createMemoryHistory } from 'vue-router';
-import type { Manifest, ConceptSummary, LocalizedConcept, SearchHit } from '../adapters/types';
+import { LocalizedConcept } from 'glossarist';
+import type { Manifest, ConceptSummary, SearchHit } from '../adapters/types';
 
 // ── Manifest Factory ──────────────────────────────────────────────────
 
@@ -43,6 +44,7 @@ export interface AdapterStubOptions {
   ensureChunksForRange?: () => Promise<void>;
   ensureAllChunksLoaded?: () => Promise<void>;
   extractEdges?: () => any[];
+  extractDomainEdges?: () => any[];
   getIndexEntry?: () => any;
 }
 
@@ -61,25 +63,26 @@ export function makeAdapterStub(options: AdapterStubOptions = {}): any {
     ensureChunksForRange: options.ensureChunksForRange ?? (() => Promise.resolve()),
     ensureAllChunksLoaded: options.ensureAllChunksLoaded ?? (() => Promise.resolve()),
     extractEdges: options.extractEdges ?? (() => []),
+    extractDomainEdges: options.extractDomainEdges ?? (() => []),
     getIndexEntry: options.getIndexEntry ?? (() => null),
   };
 }
 
 // ── Concept Data Factories ────────────────────────────────────────────
 
-export function makeLocalizedConcept(overrides: Partial<LocalizedConcept> = {}): LocalizedConcept {
-  return {
-    '@id': 'https://glossarist.org/test/concept/1/eng',
-    '@type': 'gl:LocalizedConcept',
-    'gl:languageCode': 'eng',
-    'gl:entryStatus': 'valid',
+export function makeLocalizedConcept(overrides: Record<string, unknown> = {}): LocalizedConcept {
+  return LocalizedConcept.fromJSON({
+    language_code: 'eng',
+    entry_status: 'valid',
+    terms: [{ type: 'expression', designation: 'test term' }],
     ...overrides,
-  };
+  });
 }
 
 export function makeConceptSummary(overrides: Partial<ConceptSummary> = {}): ConceptSummary {
   return {
     id: '1',
+    designations: { eng: 'test concept' },
     eng: 'test concept',
     status: 'valid',
     ...overrides,

package/src/adapters/DatasetAdapter.ts

@@ -3,12 +3,29 @@ import type {
   ConceptIndex,
   ConceptSummary,
   ConceptEntry,
-  ConceptDocument,
   SearchHit,
   GraphEdge,
+  GraphNode,
 } from './types';
+import type { Concept, LocalizedConcept, Designation } from 'glossarist';
+import { conceptFromJson, conceptUri } from './model-bridge';
 import { UriRouter } from './UriRouter';
 
+function slugify(text: string): string {
+  return text.toLowerCase().replace(/[^\w\s-]/g, '').replace(/[\s/]+/g, '-');
+}
+
+function resolveRefTarget(rc: any, uriBase: string, registerId: string): string {
+  if (!rc.ref) return '';
+  const ref = rc.ref;
+  if (ref.id) {
+    const reg = (ref.source && !ref.source.startsWith('http')) ? ref.source : registerId;
+    return `${uriBase}/${reg}/concept/${ref.id}`;
+  }
+  if (ref.source && ref.source.startsWith('http')) return ref.source;
+  return ref.source || '';
+}
+
 export class DatasetAdapter {
   private positionIndex = new Map<string, number>();
   readonly registerId: string;
@@ -16,7 +33,7 @@ export class DatasetAdapter {
   manifest: Manifest | null = null;
   index: ConceptIndex | null = null;
 
-  private conceptCache = new Map<string, ConceptDocument>();
+  private conceptCache = new Map<string, Concept>();
   private summaryMap = new Map<string, ConceptSummary>();
   private loadedChunks = new Set<number>();
   private indexMeta: { conceptCount: number; chunkSize: number; chunks: { file: string; count: number }[] } | null = null;
@@ -43,11 +60,43 @@ export class DatasetAdapter {
 
     const resp = await fetch(`${this.baseUrl}/index.json`);
     if (!resp.ok) throw new Error(`Failed to load index for ${this.registerId}: ${resp.status}`);
-    this.index = (await resp.json()) as ConceptIndex;
+    const data = await resp.json();
+
+    // Handle both old format (with eng/status fields) and new format (with designations map)
+    this.index = this.normalizeIndex(data);
     this.buildSummaryIndex();
     return this.index;
   }
 
+  private normalizeIndex(data: any): ConceptIndex {
+    const concepts: ConceptSummary[] = (data.concepts || []).map((c: any) => {
+      if (c.designations && typeof c.designations === 'object') {
+        return {
+          id: c.id,
+          designations: c.designations,
+          eng: c.eng || c.designations.eng || Object.values(c.designations)[0] || '',
+          status: c.status,
+        };
+      }
+      // Legacy format: c.eng is a string, no designations map
+      return {
+        id: c.id,
+        designations: c.eng ? { eng: c.eng } : {},
+        eng: c.eng || '',
+        status: c.status,
+      };
+    });
+
+    return {
+      registerId: data.registerId,
+      schemaVersion: data.schemaVersion,
+      conceptCount: data.conceptCount,
+      chunkSize: data.chunkSize,
+      chunks: data.chunks || [],
+      concepts,
+    };
+  }
+
   private buildSummaryIndex() {
     this.summaryMap.clear();
     this.positionIndex.clear();
@@ -68,7 +117,8 @@ export class DatasetAdapter {
     } else {
       const resp = await fetch(`${this.baseUrl}/index.json`);
       if (!resp.ok) throw new Error(`Failed to load index for ${this.registerId}`);
-      this.index = (await resp.json()) as ConceptIndex;
+      const data = await resp.json();
+      this.index = this.normalizeIndex(data);
       this.buildSummaryIndex();
       return this.index;
     }
@@ -79,7 +129,6 @@ export class DatasetAdapter {
       chunks: meta.chunks,
     };
 
-    // Pre-allocate array so positions match concept order — undefined = not loaded yet
     this.index = {
       registerId: meta.registerId,
       schemaVersion: meta.schemaVersion,
@@ -90,7 +139,6 @@ export class DatasetAdapter {
     };
 
     await this.loadChunkAsSummaries(0);
-
     return this.index;
   }
 
@@ -118,9 +166,11 @@ export class DatasetAdapter {
 
     for (let i = 0; i < entries.length; i++) {
       const entry = entries[i];
+      const designations = entry.designations || (entry.groups ? {} : { eng: '' });
       const summary: ConceptSummary = {
         id: entry.id,
-        eng: entry.designations?.eng || Object.values(entry.designations || {})[0] || '',
+        designations,
+        eng: designations.eng || Object.values(designations)[0] || '',
         status: entry.status,
       };
       this.index!.concepts[startPos + i] = summary;
@@ -146,7 +196,6 @@ export class DatasetAdapter {
     if (!this.indexMeta) return;
     const { chunks } = this.indexMeta;
     const toLoad = chunks.map((_, i) => i).filter(i => !this.loadedChunks.has(i));
-    // Load in parallel batches of 5 to avoid overwhelming the browser
     for (let i = 0; i < toLoad.length; i += 5) {
       const batch = toLoad.slice(i, i + 5);
       await Promise.all(batch.map(c => this.loadChunkAsSummaries(c)));
@@ -162,15 +211,16 @@ export class DatasetAdapter {
     return true;
   }
 
-  async fetchConcept(conceptId: string): Promise<ConceptDocument> {
+  async fetchConcept(conceptId: string): Promise<Concept> {
     const cached = this.conceptCache.get(conceptId);
     if (cached) return cached;
 
     const resp = await fetch(`${this.baseUrl}/concepts/${conceptId}.json`);
     if (!resp.ok) throw new Error(`Concept ${conceptId} not found in ${this.registerId}`);
-    const doc = (await resp.json()) as ConceptDocument;
-    this.conceptCache.set(conceptId, doc);
-    return doc;
+    const json = await resp.json();
+    const concept = conceptFromJson(json);
+    this.conceptCache.set(conceptId, concept);
+    return concept;
   }
 
   getIndexEntry(conceptId: string): ConceptSummary | undefined {
@@ -194,12 +244,10 @@ export class DatasetAdapter {
     if (!concepts) return { prev: null, next: null };
     const idx = this.getConceptPosition(conceptId);
     if (idx === -1) return { prev: null, next: null };
-    // Scan backward for prev (skip undefined)
     let prev: string | null = null;
     for (let i = idx - 1; i >= 0; i--) {
       if (concepts[i]) { prev = concepts[i]!.id; break; }
     }
-    // Scan forward for next (skip undefined)
     let next: string | null = null;
     for (let i = idx + 1; i < concepts.length; i++) {
       if (concepts[i]) { next = concepts[i]!.id; break; }
@@ -207,53 +255,92 @@ export class DatasetAdapter {
     return { prev, next };
   }
 
-  search(query: string, lang: string = 'eng'): SearchHit[] {
+  search(query: string): SearchHit[] {
     const q = query.toLowerCase();
-    const hits: SearchHit[] = [];
     const arr = this.index?.concepts;
-    if (!arr) return hits;
+    if (!arr) return [];
+
+    type ScoredHit = SearchHit & { _score: number };
+    const scored: ScoredHit[] = [];
 
     for (const entry of arr) {
       if (!entry) continue;
-      const term = entry.eng || '';
-      const termMatch = term.toLowerCase().includes(q);
-      const idMatch = entry.id.toLowerCase().includes(q);
-      if (termMatch || idMatch) {
-        const matchField = termMatch ? 'designation' as const : 'id' as const;
-        let snippet: string | undefined;
-        if (!termMatch && idMatch) {
-          snippet = `ID: ${entry.id}`;
-        }
-        hits.push({
+
+      // ID search — exact match highest, then starts with, then contains
+      const idLow = entry.id.toLowerCase();
+      if (idLow.includes(q)) {
+        const score = idLow === q ? 4 : idLow.startsWith(q) ? 3 : 2;
+        scored.push({
           conceptId: entry.id,
           registerId: this.registerId,
-          designation: term,
-          language: lang,
-          matchField,
-          snippet,
+          designation: entry.eng || '',
+          language: '',
+          matchField: 'id',
+          snippet: `ID: ${entry.id}`,
+          _score: score,
         });
+        continue;
+      }
+
+      // Multi-language designation search
+      for (const [language, term] of Object.entries(entry.designations)) {
+        if (!term) continue;
+        const tLow = term.toLowerCase();
+        if (tLow.includes(q)) {
+          const score = tLow === q ? 4 : tLow.startsWith(q) ? 3 : 1;
+          scored.push({
+            conceptId: entry.id,
+            registerId: this.registerId,
+            designation: term,
+            language,
+            matchField: 'designation',
+            _score: score,
+          });
+        }
       }
     }
-    return hits;
+
+    // Sort by score descending, then alphabetically
+    scored.sort((a, b) => b._score - a._score || a.designation.localeCompare(b.designation));
+    return scored;
   }
 
-  extractEdges(concept: ConceptDocument): GraphEdge[] {
+  extractEdges(concept: Concept): GraphEdge[] {
     const edges: GraphEdge[] = [];
-    const sourceUri = concept['@id'];
-
-    for (const [_lang, lc] of Object.entries(concept['gl:localizedConcept'] || {})) {
-      if (lc['gl:references']) {
-        for (const ref of lc['gl:references']) {
-          if (ref['@id'] && ref['@id'] !== sourceUri) {
-            const parsed = UriRouter.parseUri(ref['@id']);
-            edges.push({
-              source: sourceUri,
-              target: ref['@id'],
-              type: 'references',
-              label: ref['gl:term'],
-              register: parsed?.registerId ?? this.registerId,
-            });
-          }
+    const uriBase = this.manifest?.uriBase || 'https://glossarist.org';
+    const sourceUri = concept.uri || `${uriBase}/${this.registerId}/concept/${concept.id}`;
+
+    // Managed concept level relationships
+    for (const rc of concept.relatedConcepts) {
+      const target = resolveRefTarget(rc, uriBase, this.registerId);
+      if (target && target !== sourceUri) {
+        const parsed = UriRouter.parseUri(target);
+        edges.push({
+          source: sourceUri,
+          target,
+          type: rc.type || 'references',
+          label: rc.content || undefined,
+          register: parsed?.registerId ?? this.registerId,
+        });
+      }
+    }
+
+    // Per-localization references (from inline extraction in generate-data)
+    for (const lang of concept.languages) {
+      const lc = concept.localization(lang);
+      if (!lc) continue;
+      for (const rc of lc.related) {
+        const target = resolveRefTarget(rc, uriBase, this.registerId);
+        if (target && target !== sourceUri) {
+          const parsed = UriRouter.parseUri(target);
+          edges.push({
+            source: sourceUri,
+            target,
+            type: rc.type || 'references',
+            label: rc.content || undefined,
+            register: parsed?.registerId ?? this.registerId,
+            lang,
+          });
         }
       }
     }
@@ -261,6 +348,42 @@ export class DatasetAdapter {
     return edges;
   }
 
+  extractDomainEdges(concept: Concept): GraphEdge[] {
+    const edges: GraphEdge[] = [];
+    const uriBase = this.manifest?.uriBase || 'https://glossarist.org';
+    const sourceUri = concept.uri || `${uriBase}/${this.registerId}/concept/${concept.id}`;
+
+    for (const lang of concept.languages) {
+      const lc = concept.localization(lang);
+      if (lc?.domain) {
+        edges.push({
+          source: sourceUri,
+          target: `${uriBase}/${this.registerId}/domain/${slugify(lc.domain)}`,
+          type: 'domain',
+          label: lc.domain,
+          register: this.registerId,
+          lang,
+        });
+      }
+    }
+    return edges;
+  }
+
+  async loadDomainNodes(): Promise<GraphNode[]> {
+    const resp = await fetch(`${this.baseUrl}/domain-nodes.json`);
+    if (!resp.ok) return [];
+    const data = await resp.json();
+    return (data.domainNodes || []).map((dn: any) => ({
+      uri: dn.uri,
+      register: dn.registerId,
+      conceptId: dn.uri.split('/domain/')[1] || '',
+      designations: { eng: dn.label },
+      status: 'domain',
+      loaded: true,
+      nodeType: 'domain' as const,
+    }));
+  }
+
   async loadEdgeIndex(): Promise<GraphEdge[]> {
     const resp = await fetch(`${this.baseUrl}/edges.json`);
     if (!resp.ok) return [];

package/src/adapters/model-bridge.ts

@@ -0,0 +1,277 @@
+/**
+ * Model bridge: converts between wire-format JSON and glossarist-js model instances.
+ *
+ * Supports two input formats:
+ * 1. JSON-LD (gl:-prefixed) — legacy format from current generate-data.mjs
+ * 2. Glossarist native — snake_case format from glossarist-js Concept.toJSON()
+ *
+ * All downstream code works exclusively with Concept instances.
+ */
+import {
+  Concept,
+  LocalizedConcept,
+  Designation,
+  Expression,
+  Abbreviation,
+  Symbol as SymbolDesignation,
+  GraphicalSymbol,
+  Citation,
+  ConceptSource,
+  RelatedConcept,
+  ConceptDate,
+  DetailedDefinition,
+  NonVerbRep,
+  RELATIONSHIP_TYPES,
+  DATE_TYPES,
+} from 'glossarist';
+import {
+  LetterSymbol,
+  GrammarInfo,
+  Pronunciation,
+  ConceptReference,
+  Locality,
+  GRAMMAR_GENDERS,
+  GRAMMAR_NUMBERS,
+  GRAMMAR_PARTS_OF_SPEECH,
+} from 'glossarist/models';
+import type { ConceptSummary } from './types';
+
+// ── Detection ─────────────────────────────────────────────────────────────
+
+function isJsonLd(doc: Record<string, unknown>): boolean {
+  return '@type' in doc && 'gl:localizedConcept' in doc;
+}
+
+// ── JSON-LD → Glossarist native mapping ───────────────────────────────────
+
+function mapDesignationFromJsonLd(d: any): Record<string, unknown> {
+  const result: Record<string, unknown> = {};
+  const rawType = (d['@type'] as string) || '';
+
+  // Map type
+  if (rawType.includes('Abbreviation')) result.type = 'abbreviation';
+  else if (rawType.includes('LetterSymbol')) result.type = 'letter_symbol';
+  else if (rawType.includes('GraphicalSymbol')) result.type = 'graphical_symbol';
+  else if (rawType.includes('Symbol')) result.type = 'symbol';
+  else result.type = 'expression';
+
+  result.designation = d['gl:term'] ?? '';
+  result.normative_status = d['gl:normativeStatus'] ?? null;
+
+  if (d['gl:absent'] != null) result.absent = d['gl:absent'];
+  if (d['gl:fieldOfApplication']) result.field_of_application = d['gl:fieldOfApplication'];
+  if (d['gl:usageInfo']) result.usage_info = d['gl:usageInfo'];
+  if (d['gl:geographicalArea']) result.geographical_area = d['gl:geographicalArea'];
+  if (d['gl:language']) result.language = d['gl:language'];
+  if (d['gl:script']) result.script = d['gl:script'];
+  if (d['gl:system']) result.system = d['gl:system'];
+  if (d['gl:international'] != null) result.international = d['gl:international'];
+  if (d['gl:termType']) result.term_type = d['gl:termType'];
+
+  if (d['gl:pronunciation']?.length) {
+    result.pronunciation = d['gl:pronunciation'].map((p: any) => ({
+      content: p['gl:content'] ?? null,
+      language: p['gl:language'] ?? null,
+      script: p['gl:script'] ?? null,
+      system: p['gl:system'] ?? null,
+      country: p['gl:country'] ?? null,
+    }));
+  }
+
+  if (d['gl:source']?.length) {
+    result.sources = d['gl:source'].map(mapSourceFromJsonLd);
+  }
+
+  if (d['gl:related']?.length) {
+    result.related = d['gl:related'].map(mapRelatedFromJsonLd);
+  }
+
+  // Expression-specific
+  if (d['gl:prefix'] != null) result.prefix = d['gl:prefix'];
+  if (d['gl:gender']) {
+    result.grammar_info = [{ gender: d['gl:gender'] }];
+  }
+  if (d['gl:grammarInfo']?.length) {
+    result.grammar_info = d['gl:grammarInfo'].map((gi: any) => ({
+      gender: gi['gl:gender'] ?? null,
+      number: gi['gl:number'] ?? null,
+      part_of_speech: gi['gl:partOfSpeech'] ?? null,
+      noun: gi['gl:noun'] ?? false,
+      verb: gi['gl:verb'] ?? false,
+      adj: gi['gl:adj'] ?? false,
+      adverb: gi['gl:adverb'] ?? false,
+      preposition: gi['gl:preposition'] ?? false,
+      participle: gi['gl:participle'] ?? false,
+    }));
+  }
+
+  return result;
+}
+
+function mapSourceFromJsonLd(s: any): Record<string, unknown> {
+  const result: Record<string, unknown> = {};
+  if (s['gl:sourceType']) result.type = s['gl:sourceType'];
+  if (s['gl:sourceStatus']) result.status = s['gl:sourceStatus'];
+  if (s['gl:modification']) result.modification = s['gl:modification'];
+
+  if (s['gl:origin']) {
+    const origin: Record<string, unknown> = {};
+    const o = s['gl:origin'];
+    if (o['gl:ref']) {
+      const rawRef = o['gl:ref'];
+      const refObj: Record<string, unknown> = {};
+      // v3: ref is always an object { gl:source, gl:id, gl:version }
+      if (rawRef['gl:source']) refObj.source = rawRef['gl:source'];
+      if (rawRef['gl:id']) refObj.id = rawRef['gl:id'];
+      if (rawRef['gl:version']) refObj.version = rawRef['gl:version'];
+      if (rawRef['source']) refObj.source = rawRef['source'];
+      if (rawRef['id']) refObj.id = rawRef['id'];
+      if (rawRef['version']) refObj.version = rawRef['version'];
+      if (Object.keys(refObj).length > 0) origin.ref = refObj;
+    }
+    if (o['gl:locality']) {
+      const loc: Record<string, unknown> = {};
+      const rawLoc = o['gl:locality'];
+      if (rawLoc['gl:localityType']) loc.type = rawLoc['gl:localityType'];
+      if (rawLoc['gl:referenceFrom']) loc.reference_from = rawLoc['gl:referenceFrom'];
+      if (rawLoc['gl:referenceTo']) loc.reference_to = rawLoc['gl:referenceTo'];
+      if (rawLoc['type']) loc.type = rawLoc['type'];
+      if (rawLoc['reference_from']) loc.reference_from = rawLoc['reference_from'];
+      if (rawLoc['reference_to']) loc.reference_to = rawLoc['reference_to'];
+      origin.locality = loc;
+    }
+    if (o['gl:link']) origin.link = o['gl:link'];
+    if (o['gl:id']) origin.id = o['gl:id'];
+    if (o['gl:version']) origin.version = o['gl:version'];
+    if (o['gl:source']) origin.source = o['gl:source'];
+    result.origin = origin;
+  }
+
+  return result;
+}
+
+function mapRelatedFromJsonLd(r: any): Record<string, unknown> {
+  const result: Record<string, unknown> = { type: 'references' };
+  if (r['@id']) {
+    // Extract concept ID from URI: ".../concept/3.1.1.6" → source=register, id=3.1.1.6
+    const uri = r['@id'] as string;
+    const idMatch = uri.match(/\/concept\/([^/]+)$/);
+    result.ref = idMatch
+      ? { source: uri.split('/').slice(-3, -2)[0] || '', id: idMatch[1] }
+      : { source: uri, id: null };
+  }
+  if (r['gl:term']) result.content = r['gl:term'];
+  return result;
+}
+
+function mapLocalizedFromJsonLd(lc: any): Record<string, unknown> {
+  const data: Record<string, unknown> = {};
+
+  if (lc['gl:languageCode']) data.language_code = lc['gl:languageCode'];
+  if (lc['gl:entryStatus']) data.entry_status = lc['gl:entryStatus'];
+  if (lc['gl:classification']) data.classification = lc['gl:classification'];
+  if (lc['gl:reviewType']) data.review_type = lc['gl:reviewType'];
+  if (lc['gl:domain']) data.domain = lc['gl:domain'];
+  if (lc['gl:release']) data.release = lc['gl:release'];
+  if (lc['gl:lineageSourceSimilarity'] != null) data.lineage_source_similarity = lc['gl:lineageSourceSimilarity'];
+  if (lc['gl:script']) data.script = lc['gl:script'];
+  if (lc['gl:system']) data.system = lc['gl:system'];
+
+  if (lc['gl:designation']?.length) {
+    data.terms = lc['gl:designation'].map(mapDesignationFromJsonLd);
+  }
+
+  if (lc['gl:definition']?.length) {
+    data.definition = lc['gl:definition'].map((d: any) => {
+      const def: Record<string, unknown> = { content: d['gl:content'] ?? '' };
+      return def;
+    });
+  }
+
+  if (lc['gl:notes']?.length) {
+    data.notes = lc['gl:notes'].map((n: any) => ({ content: n['gl:content'] ?? '' }));
+  }
+
+  if (lc['gl:examples']?.length) {
+    data.examples = lc['gl:examples'].map((e: any) => ({ content: e['gl:content'] ?? '' }));
+  }
+
+  if (lc['gl:source']?.length) {
+    data.sources = lc['gl:source'].map(mapSourceFromJsonLd);
+  }
+
+  if (lc['gl:dates']?.length) {
+    data.dates = lc['gl:dates'].map((d: any) => ({
+      date: d['gl:date'] ?? null,
+      type: d['gl:dateType'] ?? null,
+    }));
+  }
+
+  if (lc['gl:references']?.length) {
+    data.related = lc['gl:references'].map(mapRelatedFromJsonLd);
+  }
+
+  // Review metadata — passed through to LocalizedConcept constructor
+  if (lc['gl:reviewDate']) data.review_date = lc['gl:reviewDate'];
+  if (lc['gl:reviewDecisionDate']) data.review_decision_date = lc['gl:reviewDecisionDate'];
+  if (lc['gl:reviewDecisionEvent']) data.review_decision_event = lc['gl:reviewDecisionEvent'];
+  if (lc['gl:reviewStatus']) data.review_status = lc['gl:reviewStatus'];
+  if (lc['gl:reviewDecision']) data.review_decision = lc['gl:reviewDecision'];
+  if (lc['gl:reviewDecisionNotes']) data.review_decision_notes = lc['gl:reviewDecisionNotes'];
+
+  return data;
+}
+
+function conceptFromJsonLd(doc: Record<string, any>): Concept {
+  const id = String(doc['gl:identifier'] ?? doc['@id']?.split('/').pop() ?? '');
+  const localizations: Record<string, any> = {};
+
+  const rawLc = doc['gl:localizedConcept'] ?? {};
+  for (const [lang, lc] of Object.entries(rawLc)) {
+    if (lc && typeof lc === 'object') {
+      localizations[lang] = mapLocalizedFromJsonLd(lc);
+    }
+  }
+
+  const related = (doc['gl:references'] ?? []).map(mapRelatedFromJsonLd);
+
+  return Concept.fromJSON({
+    id,
+    term: doc['gl:term'] ?? null,
+    uri: doc['@id'] ?? null,
+    localizations,
+    related,
+    status: null,
+  });
+}
+
+// ── Public API ────────────────────────────────────────────────────────────
+
+export function conceptFromJson(doc: Record<string, any>): Concept {
+  if (isJsonLd(doc)) {
+    return conceptFromJsonLd(doc);
+  }
+  // glossarist native format — use fromJSON directly
+  return Concept.fromJSON(doc as Record<string, unknown>);
+}
+
+export function conceptToSummary(concept: Concept): ConceptSummary {
+  const designations: Record<string, string> = {};
+  for (const lang of concept.languages) {
+    const lc = concept.localization(lang);
+    if (lc?.primaryDesignation) {
+      designations[lang] = lc.primaryDesignation;
+    }
+  }
+  return {
+    id: concept.id,
+    designations,
+    eng: designations.eng || Object.values(designations)[0] || '',
+    status: concept.status ?? 'valid',
+  };
+}
+
+export function conceptUri(concept: Concept, registerId: string, uriBase: string): string {
+  if (concept.uri) return concept.uri;
+  return `${uriBase}/${registerId}/concept/${concept.id}`;
+}