glossarist 0.3.8 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "glossarist",
-  "version": "0.3.8",
+  "version": "0.4.0",
   "description": "JavaScript SDK for Glossarist GCR packages — read, write, validate, and manage terminology concepts",
   "type": "module",
   "main": "src/index.js",

package/src/concept-parser.js

@@ -3,7 +3,7 @@ import { Concept } from './models/concept.js';
 import { RelatedConcept } from './models/related-concept.js';
 import { InvalidInputError, YamlParseError } from './errors.js';
 
-const STRUCTURAL_KEYS = new Set(['termid', 'term']);
+const STRUCTURAL_KEYS = new Set(['termid', 'term', 'figures', 'tables', 'formulas']);
 
 export class ConceptParser {
   parse(raw, context) {
@@ -51,6 +51,9 @@ export class ConceptParser {
       id: String(doc.termid),
       term: doc.term || null,
       localizations,
+      figures: doc.figures,
+      tables: doc.tables,
+      formulas: doc.formulas,
       raw: doc,
     });
   }
@@ -76,6 +79,9 @@ export class ConceptParser {
       groups: mc.data.groups,
       dates: mc.dates ?? mc.data?.dates,
       sources: mc.sources ?? mc.data?.sources,
+      figures: mc.data?.figures,
+      tables: mc.data?.tables,
+      formulas: mc.data?.formulas,
       status: mc.status,
       schemaVersion: mc.schema_version,
       raw: mc,

package/src/dataset-asset.js

@@ -12,6 +12,9 @@
 const DATASET_ASSETS = Object.freeze([
   { path: 'bibliography.yaml', type: 'file' },
   { path: 'images', type: 'directory' },
+  { path: 'figures', type: 'directory' },
+  { path: 'tables', type: 'directory' },
+  { path: 'formulas', type: 'directory' },
 ]);
 
 const FILE_ASSETS = Object.freeze(

package/src/entity-directory.js

@@ -0,0 +1,43 @@
+const ENTITY_DIRECTORIES = Object.freeze(new Map([
+  ['figure', 'figures'],
+  ['table', 'tables'],
+  ['formula', 'formulas'],
+]));
+
+const ENTITY_TYPES = Object.freeze([...ENTITY_DIRECTORIES.keys()]);
+
+function entityDir(type) {
+  const dir = ENTITY_DIRECTORIES.get(type);
+  if (!dir) throw new RangeError(`Unknown entity type: ${type}`);
+  return dir;
+}
+
+function entityPath(type, id) {
+  return `${entityDir(type)}/${id}.yaml`;
+}
+
+function isKnownEntityType(type) {
+  return ENTITY_DIRECTORIES.has(type);
+}
+
+function parseEntityPath(zipPath) {
+  for (const [type, dir] of ENTITY_DIRECTORIES) {
+    const prefix = `${dir}/`;
+    if (!zipPath.startsWith(prefix)) continue;
+    const filename = zipPath.slice(prefix.length);
+    if (!filename.endsWith('.yaml')) continue;
+    const id = filename.slice(0, -'.yaml'.length);
+    if (!id) continue;
+    return { type, id };
+  }
+  return null;
+}
+
+export {
+  ENTITY_DIRECTORIES,
+  ENTITY_TYPES,
+  entityDir,
+  entityPath,
+  isKnownEntityType,
+  parseEntityPath,
+};

package/src/gcr-reader.js

@@ -6,6 +6,9 @@ import { COMPILED_FORMATS, parseCompiledPath, compiledPath } from './compiled-fo
 import { DATASET_ASSETS, findFileAsset, findDirectoryAssetPath } from './dataset-asset.js';
 import { GcrMetadata } from './models/gcr-metadata.js';
 import { naturalSort } from './sort.js';
+import { NonVerbalEntity } from './models/non-verbal-entity.js';
+import { BibliographyData } from './models/bibliography-data.js';
+import { entityDir, entityPath, ENTITY_TYPES, parseEntityPath } from './entity-directory.js';
 
 export { naturalSort } from './sort.js';
 
@@ -283,12 +286,13 @@ export class GcrPackage {
   }
 
   /**
-   * Read bibliography.yaml from the package as a string (raw YAML).
-   * @returns {Promise<string | null>}
+   * Read and parse bibliography.yaml from the package as a BibliographyData instance.
+   * @returns {Promise<BibliographyData | null>}
    */
   async bibliography() {
-    const fileAsset = DATASET_ASSETS.find((a) => a.type === 'file' && a.path === 'bibliography.yaml');
-    return fileAsset ? this._readText(fileAsset.path) : null;
+    const raw = await this._readText('bibliography.yaml');
+    if (raw === null) return null;
+    return BibliographyData.fromYAML(raw);
   }
 
   /**
@@ -403,6 +407,50 @@ export class GcrPackage {
   async _readText(filePath) {
     return this.readText(filePath);
   }
+
+  // --- Non-verbal entity directories (figures/, tables/, formulas/) ---
+
+  async entityIds(type) {
+    const prefix = `${entityDir(type)}/`;
+    const ids = [];
+    this._zip.forEach((relativePath, entry) => {
+      if (!entry.dir && relativePath.startsWith(prefix) && relativePath.endsWith('.yaml')) {
+        ids.push(relativePath.slice(prefix.length, -'.yaml'.length));
+      }
+    });
+    return ids.sort(naturalSort);
+  }
+
+  async entity(type, id) {
+    const raw = await this.readText(entityPath(type, id));
+    if (raw === null) return null;
+    const yamlData = yaml.load(raw);
+    return NonVerbalEntity.fromData({ ...yamlData, type });
+  }
+
+  async eachEntity(type, callback) {
+    for (const id of await this.entityIds(type)) {
+      const entity = await this.entity(type, id);
+      if (entity) await callback(entity, id);
+    }
+  }
+
+  async allEntities(type) {
+    const entities = [];
+    await this.eachEntity(type, (e) => { entities.push(e); });
+    return entities;
+  }
+
+  async entityTypes() {
+    const seen = new Set();
+    this._zip.forEach((relativePath, entry) => {
+      if (!entry.dir) {
+        const parsed = parseEntityPath(relativePath);
+        if (parsed) seen.add(parsed.type);
+      }
+    });
+    return ENTITY_TYPES.filter((t) => seen.has(t));
+  }
 }
 
 // --- Concept YAML parsing ---

package/src/gcr-writer.js

@@ -38,7 +38,9 @@ export class GcrWriter {
     }
 
     if (options.bibliography) {
-      zip.file('bibliography.yaml', options.bibliography);
+      const bib = options.bibliography;
+      const yamlStr = bib.toYAML ? bib.toYAML() : String(bib);
+      zip.file('bibliography.yaml', yamlStr);
     }
 
     if (options.images) {

package/src/index.d.ts

@@ -1,12 +1,18 @@
 // Models
 export {
   GlossaristModel,
+  RegistrableModel,
   Concept, LocalizedConcept,
-  Designation, Expression, Abbreviation, Symbol, GraphicalSymbol,
-  Citation, ConceptRef, ConceptSource, RelatedConcept, ConceptDate,
-  DetailedDefinition, NonVerbRep,
+  Designation, Expression, Abbreviation, Symbol, LetterSymbol, GraphicalSymbol,
+  Citation, ConceptRef, ConceptSource, RelatedConcept,
+  DesignationRelationship, ConceptReference, ConceptDate,
+  DetailedDefinition, NonVerbRep, NON_VERBAL_TYPES,
+  NonVerbalEntity, SharedNonVerbalEntity,
+  Figure, FigureImage, Table, Formula,
+  NonVerbalReference, FigureReference, TableReference, FormulaReference,
+  BibliographyEntry, BibliographyData,
   GcrMetadata, GcrStatistics,
-  RELATIONSHIP_TYPES, DATE_TYPES,
+  RELATIONSHIP_TYPES, DESIGNATION_RELATIONSHIP_TYPES, DATE_TYPES,
 } from './models/index';
 
 // GCR reader
@@ -26,16 +32,27 @@ export { ConceptCollection } from './concept-collection';
 export { ManagedConceptCollection } from './managed-concept-collection';
 
 // Validators
-export { validateConcept, validateRegister, validateGcrPackage, createConceptValidator, ValidationError, ValidationRule, ValidationResult, RegisterValidator, GcrValidator } from './validators/index';
+export {
+  validateConcept, validateRegister, validateGcrPackage,
+  createConceptValidator,
+  ValidationError, ValidationRule, ValidationResult,
+  RegisterValidator, GcrValidator,
+  NonVerbalRefIntegrityRule, OrphanedImagesRule,
+} from './validators/index';
+export { AssetIndex } from './validators/asset-index';
 
 // UUID
 export { conceptUuid, localizedConceptUuid, uuidV5 } from './uuid';
 
 // Reference resolution
-export { ReferenceResolver, Reference, referenceResolver } from './reference-resolver';
+export {
+  ReferenceResolver, Reference, referenceResolver,
+  resolveBibliographyRecord, findNonVerbalEntity,
+} from './reference-resolver';
 
 export type MentionParseResult = {
-  kind: 'cite-ref' | 'urn-ref' | 'numeric' | 'designation' | 'unresolved';
+  kind: 'cite-ref' | 'urn-ref' | 'fig-ref' | 'table-ref' | 'formula-ref'
+      | 'numeric' | 'designation' | 'unresolved';
   key?: string;
   uri?: string;
   label?: string | null;
@@ -45,6 +62,14 @@ export type MentionParseResult = {
 
 export function parseMention(raw: string): MentionParseResult;
 
+export function fetchLocalizedString(
+  hash: Record<string, string> | null,
+  lang: string,
+  fallback?: string,
+): string | null;
+export function localizedStringIsEmpty(hash: Record<string, string> | null): boolean;
+export function localizedStringIsPresent(hash: Record<string, string> | null): boolean;
+
 // V1 support
 export { V1Reader, migrateV1ToV2 } from './v1-reader';
 
@@ -66,3 +91,11 @@ export const DIRECTORY_ASSETS: readonly { path: string; type: string }[];
 export function findFileAsset(path: string): { path: string; type: string } | undefined;
 export function findDirectoryAssetPath(zipPath: string): { path: string; type: string } | undefined;
 export function isDatasetAssetPath(zipPath: string): boolean;
+
+// Entity directory registry
+export const ENTITY_DIRECTORIES: ReadonlyMap<string, string>;
+export const ENTITY_TYPES: readonly string[];
+export function entityDir(type: string): string;
+export function entityPath(type: string, id: string): string;
+export function isKnownEntityType(type: string): boolean;
+export function parseEntityPath(zipPath: string): { type: string; id: string } | null;

package/src/index.js

@@ -7,7 +7,7 @@ export { ConceptCollection } from './concept-collection.js';
 export { ManagedConceptCollection } from './managed-concept-collection.js';
 export { validateConcept, validateRegister, validateGcrPackage, createConceptValidator, ValidationError, ValidationRule, ValidationResult, RegisterValidator, GcrValidator } from './validators/index.js';
 export { conceptUuid, localizedConceptUuid, uuidV5 } from './uuid.js';
-export { ReferenceResolver, Reference, referenceResolver, resolveBibliographyRecord } from './reference-resolver.js';
+export { ReferenceResolver, Reference, referenceResolver, resolveBibliographyRecord, findNonVerbalEntity } from './reference-resolver.js';
 export { parseMention } from './reference-mention.js';
 export { ReferenceClassifier } from './render-classification.js';
 export { V1Reader, migrateV1ToV2 } from './v1-reader.js';
@@ -30,12 +30,29 @@ export {
 
 export {
   GlossaristModel,
+  RegistrableModel,
   Register, Section,
   REGISTER_STATUSES, ORDERING_METHODS,
   Concept, LocalizedConcept,
   Designation, Expression, Abbreviation, Symbol, GraphicalSymbol,
   Citation, ConceptRef, ConceptSource, RelatedConcept, DesignationRelationship, ConceptReference, ConceptDate,
-  DetailedDefinition, NonVerbRep,
+  DetailedDefinition, NonVerbRep, NON_VERBAL_TYPES,
+  NonVerbalEntity, SharedNonVerbalEntity,
+  Figure, FigureImage, Table, Formula,
+  NonVerbalReference, FigureReference, TableReference, FormulaReference,
+  BibliographyEntry, BibliographyData,
+  fetchLocalizedString, localizedStringIsEmpty, localizedStringIsPresent,
   GcrMetadata, GcrStatistics,
   RELATIONSHIP_TYPES, DESIGNATION_RELATIONSHIP_TYPES, DATE_TYPES,
 } from './models/index.js';
+
+export { AssetIndex } from './validators/asset-index.js';
+
+export {
+  ENTITY_DIRECTORIES,
+  ENTITY_TYPES,
+  entityDir,
+  entityPath,
+  isKnownEntityType,
+  parseEntityPath,
+} from './entity-directory.js';

package/src/managed-concept-collection.js

@@ -3,6 +3,7 @@ import { readConcepts, readRegister } from './concept-reader.js';
 import { writeConcepts } from './concept-writer.js';
 import { loadGcr } from './gcr-reader.js';
 import { GcrWriter } from './gcr-writer.js';
+import { BibliographyData } from './models/bibliography-data.js';
 
 export class ManagedConceptCollection {
   constructor() {
@@ -73,8 +74,16 @@ export class ManagedConceptCollection {
     return this;
   }
 
-  setBibliography(yamlString) {
-    this._bibliography = yamlString;
+  setBibliography(bib) {
+    if (bib instanceof BibliographyData) {
+      this._bibliography = bib;
+    } else if (typeof bib === 'string') {
+      this._bibliography = BibliographyData.fromYAML(bib);
+    } else if (bib == null) {
+      this._bibliography = null;
+    } else {
+      this._bibliography = new BibliographyData(bib);
+    }
     return this;
   }
 

package/src/models/bibliography-data.js

@@ -0,0 +1,43 @@
+import yaml from 'js-yaml';
+import { GlossaristModel } from './base.js';
+import { BibliographyEntry } from './bibliography-entry.js';
+
+export class BibliographyData extends GlossaristModel {
+  constructor(data = {}) {
+    super();
+    const entriesData = data.bibliography ?? data.entries ?? [];
+    this._rawEntries = Array.isArray(entriesData) ? entriesData : [];
+    this._entries = null;
+  }
+
+  get entries() {
+    return this._lazy('_entries', '_rawEntries',
+      e => e instanceof BibliographyEntry ? e : new BibliographyEntry(e));
+  }
+
+  find(id) {
+    return this.entries.find(e => e.id === id) ?? null;
+  }
+
+  get keys() {
+    return this.entries.map(e => e.id);
+  }
+
+  toJSON() {
+    if (this.entries.length === 0) return { bibliography: [] };
+    return { bibliography: this.entries.map(e => e.toJSON()) };
+  }
+
+  toYAML() {
+    return yaml.dump(this.toJSON());
+  }
+
+  static fromYAML(yamlString) {
+    const parsed = yaml.load(yamlString);
+    return new BibliographyData(parsed ?? {});
+  }
+
+  static fromJSON(data) {
+    return new BibliographyData(data);
+  }
+}

package/src/models/bibliography-entry.js

@@ -0,0 +1,26 @@
+import { GlossaristModel } from './base.js';
+
+export class BibliographyEntry extends GlossaristModel {
+  constructor(data = {}) {
+    super();
+    this.id = data.id ?? null;
+    this.reference = data.reference ?? null;
+    this.title = data.title ?? null;
+    this.link = data.link ?? null;
+    this.type = data.type ?? null;
+  }
+
+  toJSON() {
+    const obj = {};
+    if (this.id != null) obj.id = this.id;
+    if (this.reference != null) obj.reference = this.reference;
+    if (this.title != null) obj.title = this.title;
+    if (this.link != null) obj.link = this.link;
+    if (this.type != null) obj.type = this.type;
+    return obj;
+  }
+
+  static fromJSON(data) {
+    return new BibliographyEntry(data);
+  }
+}

package/src/models/concept.js

@@ -4,6 +4,9 @@ import { RelatedConcept } from './related-concept.js';
 import { ConceptReference } from './concept-reference.js';
 import { ConceptDate } from './concept-date.js';
 import { ConceptSource } from './concept-source.js';
+import { FigureReference } from './non-verbal-references.js';
+import { TableReference } from './non-verbal-references.js';
+import { FormulaReference } from './non-verbal-references.js';
 
 export class Concept extends GlossaristModel {
   constructor(data = {}) {
@@ -19,6 +22,12 @@ export class Concept extends GlossaristModel {
     this.tags = Array.isArray(data.tags) ? [...data.tags] : [];
     this.dates = _mapInstances(data.dates ?? [], ConceptDate);
     this.sources = _mapInstances(data.sources ?? [], ConceptSource);
+    this._rawFigures = data.figures ?? [];
+    this._rawTables = data.tables ?? [];
+    this._rawFormulas = data.formulas ?? [];
+    this._figures = null;
+    this._tables = null;
+    this._formulas = null;
     this.status = data.status ?? null;
     this.schemaVersion = data.schemaVersion ?? data.schema_version ?? '3';
     this.raw = data.raw ?? null;
@@ -107,6 +116,21 @@ export class Concept extends GlossaristModel {
     return null;
   }
 
+  get figures() {
+    return this._lazy('_figures', '_rawFigures',
+      r => FigureReference.fromJSON(r));
+  }
+
+  get tables() {
+    return this._lazy('_tables', '_rawTables',
+      r => TableReference.fromJSON(r));
+  }
+
+  get formulas() {
+    return this._lazy('_formulas', '_rawFormulas',
+      r => FormulaReference.fromJSON(r));
+  }
+
   toJSON() {
     const obj = { id: this.id };
     if (this.term != null) obj.term = this.term;
@@ -141,6 +165,9 @@ export class Concept extends GlossaristModel {
     if (this.sources.length > 0) {
       obj.sources = this.sources.map(s => s.toJSON());
     }
+    this._serialize(obj, 'figures', '_figures', '_rawFigures');
+    this._serialize(obj, 'tables', '_tables', '_rawTables');
+    this._serialize(obj, 'formulas', '_formulas', '_rawFormulas');
     if (this.status != null) obj.status = this.status;
     obj.schema_version = this.schemaVersion;
     return obj;

package/src/models/designation.js

@@ -1,23 +1,11 @@
-import { GlossaristModel } from './base.js';
+import { RegistrableModel } from './registrable.js';
 import { ConceptSource } from './concept-source.js';
 import { Pronunciation } from './pronunciation.js';
 import { GrammarInfo } from './grammar-info.js';
 import { RelatedConcept } from './related-concept.js';
 import { DesignationRelationship, DESIGNATION_RELATIONSHIP_TYPES } from './designation-relationship.js';
 
-export class Designation extends GlossaristModel {
-  static _registry = new Map();
-
-  static register(type, cls) {
-    Designation._registry.set(type, cls);
-  }
-
-  static fromData(data) {
-    if (data instanceof Designation) return data;
-    const Cls = Designation._registry.get(data?.type) ?? Designation;
-    return new Cls(data);
-  }
-
+export class Designation extends RegistrableModel {
   constructor(data = {}) {
     super();
     this.designation = data.designation ?? '';

package/src/models/figure.js

@@ -0,0 +1,71 @@
+import { SharedNonVerbalEntity } from './shared-non-verbal-entity.js';
+import { NonVerbalEntity } from './non-verbal-entity.js';
+
+export class FigureImage {
+  constructor(data = {}) {
+    this.src = data.src ?? null;
+    this.format = data.format ?? null;
+    this.role = data.role ?? null;
+    this.width = data.width ?? null;
+    this.height = data.height ?? null;
+    this.scale = data.scale ?? null;
+  }
+
+  toJSON() {
+    const obj = {};
+    if (this.src != null) obj.src = this.src;
+    if (this.format != null) obj.format = this.format;
+    if (this.role != null) obj.role = this.role;
+    if (this.width != null) obj.width = this.width;
+    if (this.height != null) obj.height = this.height;
+    if (this.scale != null) obj.scale = this.scale;
+    return obj;
+  }
+
+  static fromJSON(data) { return new FigureImage(data); }
+}
+
+export class Figure extends SharedNonVerbalEntity {
+  constructor(data = {}) {
+    super(data);
+    this._rawImages = data.images ?? [];
+    this._rawSubfigures = data.subfigures ?? [];
+    this._images = null;
+    this._subfigures = null;
+  }
+
+  get images() {
+    return this._lazy('_images', '_rawImages',
+      i => i instanceof FigureImage ? i : new FigureImage(i));
+  }
+
+  get subfigures() {
+    return this._lazy('_subfigures', '_rawSubfigures',
+      s => s instanceof Figure ? s : new Figure(s));
+  }
+
+  findById(targetId) {
+    if (this.id === targetId) return this;
+    for (const sub of this.subfigures) {
+      const found = sub.findById(targetId);
+      if (found) return found;
+    }
+    return null;
+  }
+
+  allIds() {
+    const ids = this.id != null ? [this.id] : [];
+    return [...ids, ...this.subfigures.flatMap(s => s.allIds())];
+  }
+
+  toJSON() {
+    const obj = super.toJSON();
+    this._serialize(obj, 'images', '_images', '_rawImages');
+    this._serialize(obj, 'subfigures', '_subfigures', '_rawSubfigures');
+    return obj;
+  }
+
+  static fromJSON(data) { return new Figure(data); }
+}
+
+NonVerbalEntity.register('figure', Figure);

package/src/models/formula.js

@@ -0,0 +1,21 @@
+import { SharedNonVerbalEntity } from './shared-non-verbal-entity.js';
+import { NonVerbalEntity } from './non-verbal-entity.js';
+
+export class Formula extends SharedNonVerbalEntity {
+  constructor(data = {}) {
+    super(data);
+    this.expression = data.expression ?? null;
+    this.notation = data.notation ?? null;
+  }
+
+  toJSON() {
+    const obj = super.toJSON();
+    if (this.expression != null) obj.expression = this.expression;
+    if (this.notation != null) obj.notation = this.notation;
+    return obj;
+  }
+
+  static fromJSON(data) { return new Formula(data); }
+}
+
+NonVerbalEntity.register('formula', Formula);

package/src/models/index.js

@@ -12,9 +12,20 @@ export { DesignationRelationship, DESIGNATION_RELATIONSHIP_TYPES } from './desig
 export { ConceptReference } from './concept-reference.js';
 export { ConceptDate, DATE_TYPES } from './concept-date.js';
 export { DetailedDefinition } from './detailed-definition.js';
-export { NonVerbRep } from './non-verb-rep.js';
 export { Pronunciation } from './pronunciation.js';
 export { GrammarInfo, GRAMMAR_GENDERS, GRAMMAR_NUMBERS, GRAMMAR_PARTS_OF_SPEECH } from './grammar-info.js';
 export { Locality } from './locality.js';
 export { GcrMetadata } from './gcr-metadata.js';
 export { GcrStatistics } from './gcr-statistics.js';
+export { RegistrableModel } from './registrable.js';
+export { NonVerbalEntity } from './non-verbal-entity.js';
+export { SharedNonVerbalEntity } from './shared-non-verbal-entity.js';
+export { Figure, FigureImage } from './figure.js';
+export { Table } from './table.js';
+export { Formula } from './formula.js';
+export { NonVerbRep, NON_VERBAL_TYPES } from './non-verb-rep.js';
+export { NonVerbalReference } from './non-verbal-reference.js';
+export { FigureReference, TableReference, FormulaReference } from './non-verbal-references.js';
+export { BibliographyEntry } from './bibliography-entry.js';
+export { BibliographyData } from './bibliography-data.js';
+export { fetchLocalizedString, localizedStringIsEmpty, localizedStringIsPresent } from './localized-string.js';

package/src/models/localized-string.js

@@ -0,0 +1,19 @@
+const FALLBACK_LANG = 'eng';
+
+export function fetchLocalizedString(hash, lang, fallback = FALLBACK_LANG) {
+  if (hash == null || typeof hash !== 'object') return null;
+  const direct = hash[lang] ?? hash[String(lang)];
+  if (direct != null) return direct;
+  if (fallback != null && fallback !== lang) {
+    return hash[fallback] ?? hash[String(fallback)] ?? null;
+  }
+  return null;
+}
+
+export function localizedStringIsEmpty(hash) {
+  return hash == null || (typeof hash === 'object' && Object.keys(hash).length === 0);
+}
+
+export function localizedStringIsPresent(hash) {
+  return !localizedStringIsEmpty(hash);
+}

package/src/models/non-verb-rep.js

@@ -1,23 +1,25 @@
-import { GlossaristModel } from './base.js';
-import { ConceptSource } from './concept-source.js';
+import { NonVerbalEntity } from './non-verbal-entity.js';
+import { FigureImage } from './figure.js';
 
-export class NonVerbRep extends GlossaristModel {
+export const NON_VERBAL_TYPES = Object.freeze(['image', 'table', 'formula']);
+
+export class NonVerbRep extends NonVerbalEntity {
   constructor(data = {}) {
-    super();
+    super(data);
     this.type = data.type ?? null;
-    this.ref = data.ref ?? null;
-    this.text = data.text ?? null;
-    this.sources = (data.sources ?? []).map(
-      s => s instanceof ConceptSource ? s : new ConceptSource(s)
-    );
+    this._rawImages = data.images ?? [];
+    this._images = null;
+  }
+
+  get images() {
+    return this._lazy('_images', '_rawImages',
+      i => i instanceof FigureImage ? i : new FigureImage(i));
   }
 
   toJSON() {
-    const obj = {};
+    const obj = super.toJSON();
     if (this.type != null) obj.type = this.type;
-    if (this.ref != null) obj.ref = this.ref;
-    if (this.text != null) obj.text = this.text;
-    if (this.sources.length > 0) obj.sources = this.sources.map(s => s.toJSON());
+    this._serialize(obj, 'images', '_images', '_rawImages');
     return obj;
   }
 

package/src/models/non-verbal-entity.js

@@ -0,0 +1,39 @@
+import { RegistrableModel } from './registrable.js';
+import { ConceptSource } from './concept-source.js';
+
+export class NonVerbalEntity extends RegistrableModel {
+  constructor(data = {}) {
+    super();
+    this.caption = data.caption ?? null;
+    this.description = data.description ?? null;
+    this.alt = data.alt ?? null;
+    this._rawSources = data.sources ?? [];
+    this._sources = null;
+  }
+
+  get sources() {
+    return this._lazy('_sources', '_rawSources',
+      s => s instanceof ConceptSource ? s : new ConceptSource(s));
+  }
+
+  findById(_targetId) {
+    return null;
+  }
+
+  allIds() {
+    return [];
+  }
+
+  toJSON() {
+    const obj = {};
+    if (this.caption != null) obj.caption = this.caption;
+    if (this.description != null) obj.description = this.description;
+    if (this.alt != null) obj.alt = this.alt;
+    this._serialize(obj, 'sources', '_sources', '_rawSources');
+    return obj;
+  }
+
+  static fromJSON(data) {
+    return NonVerbalEntity.fromData(data);
+  }
+}

package/src/models/non-verbal-reference.js

@@ -0,0 +1,35 @@
+import { RegistrableModel } from './registrable.js';
+
+export class NonVerbalReference extends RegistrableModel {
+  constructor(data = {}) {
+    super();
+    this.entityId = data.entityId ?? data.entity_id ?? data.ref ?? data.id ?? null;
+    this.display = data.display ?? null;
+  }
+
+  get dedupKey() {
+    return [this.constructor.name, this.entityId];
+  }
+
+  toJSON() {
+    if (this.display != null) {
+      return { ref: this.entityId, display: this.display };
+    }
+    return this.entityId;
+  }
+
+  static fromJSON(data) {
+    if (data instanceof NonVerbalReference) return data;
+    if (typeof data === 'string') {
+      return new NonVerbalReference({ entityId: data });
+    }
+    const entityId = data.entityId ?? data.entity_id ?? data.ref ?? data.id ?? null;
+    const display = data.display ?? null;
+    const type = data.type;
+    if (type && this._registry().has(type)) {
+      const Cls = this._registry().get(type);
+      return new Cls({ entityId, display });
+    }
+    return new NonVerbalReference({ entityId, display });
+  }
+}

package/src/models/non-verbal-references.js

@@ -0,0 +1,16 @@
+import { NonVerbalReference } from './non-verbal-reference.js';
+
+export class FigureReference extends NonVerbalReference {
+  static fromJSON(data) { return NonVerbalReference.fromJSON(data); }
+}
+NonVerbalReference.register('figure', FigureReference);
+
+export class TableReference extends NonVerbalReference {
+  static fromJSON(data) { return NonVerbalReference.fromJSON(data); }
+}
+NonVerbalReference.register('table', TableReference);
+
+export class FormulaReference extends NonVerbalReference {
+  static fromJSON(data) { return NonVerbalReference.fromJSON(data); }
+}
+NonVerbalReference.register('formula', FormulaReference);

package/src/models/registrable.js

@@ -0,0 +1,25 @@
+import { GlossaristModel } from './base.js';
+
+const _registries = new WeakMap();
+
+export class RegistrableModel extends GlossaristModel {
+  static _registry() {
+    let map = _registries.get(this);
+    if (!map) {
+      map = new Map();
+      _registries.set(this, map);
+    }
+    return map;
+  }
+
+  static register(type, cls) {
+    this._registry().set(type, cls);
+  }
+
+  static fromData(data) {
+    if (data instanceof this) return data;
+    const type = data?.type;
+    const Cls = type ? this._registry().get(type) ?? this : this;
+    return new Cls(data);
+  }
+}

package/src/models/shared-non-verbal-entity.js

@@ -0,0 +1,28 @@
+import { NonVerbalEntity } from './non-verbal-entity.js';
+
+export class SharedNonVerbalEntity extends NonVerbalEntity {
+  constructor(data = {}) {
+    super(data);
+    this.id = data.id ?? null;
+    this.identifier = data.identifier ?? null;
+  }
+
+  findById(targetId) {
+    return this.id === targetId ? this : null;
+  }
+
+  allIds() {
+    return this.id != null ? [this.id] : [];
+  }
+
+  toJSON() {
+    const obj = super.toJSON();
+    if (this.id != null) obj.id = this.id;
+    if (this.identifier != null) obj.identifier = this.identifier;
+    return obj;
+  }
+
+  static fromJSON(data) {
+    return SharedNonVerbalEntity.fromData(data);
+  }
+}

package/src/models/table.js

@@ -0,0 +1,21 @@
+import { SharedNonVerbalEntity } from './shared-non-verbal-entity.js';
+import { NonVerbalEntity } from './non-verbal-entity.js';
+
+export class Table extends SharedNonVerbalEntity {
+  constructor(data = {}) {
+    super(data);
+    this.content = data.content ?? null;
+    this.format = data.format ?? null;
+  }
+
+  toJSON() {
+    const obj = super.toJSON();
+    if (this.content != null) obj.content = this.content;
+    if (this.format != null) obj.format = this.format;
+    return obj;
+  }
+
+  static fromJSON(data) { return new Table(data); }
+}
+
+NonVerbalEntity.register('table', Table);

package/src/reference-mention.js

@@ -27,6 +27,12 @@
 
 const NUMERIC_RE = /^\d+(?:[.-]\d+)+$/;
 
+const NVR_PREFIXES = Object.freeze([
+  { prefix: 'fig:', kind: 'fig-ref' },
+  { prefix: 'table:', kind: 'table-ref' },
+  { prefix: 'formula:', kind: 'formula-ref' },
+]);
+
 /**
  * Parse the body of a {{...}} mention (without the braces).
  *
@@ -63,7 +69,17 @@ export function parseMention(raw) {
     };
   }
 
-  // 3. Comma-separated form: {{id, render}}.
+  // 3. NVR prefixes (fig:/table:/formula:) — config-driven dispatch.
+  for (const { prefix, kind } of NVR_PREFIXES) {
+    const escPrefix = prefix.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const match = body.match(new RegExp(`^${escPrefix}([^,}]+)(?:,(.*))?$`));
+    if (match) {
+      const label = match[2] !== undefined ? unquoteLabel(match[2].trim()) : null;
+      return { kind, key: match[1].trim(), label, raw: body };
+    }
+  }
+
+  // 4. Comma-separated form: {{id, render}}.
   //    ID always comes first, render text always comes last.
   const commaIdx = body.indexOf(',');
   if (commaIdx !== -1) {
@@ -76,12 +92,12 @@ export function parseMention(raw) {
     return { kind: 'designation', id, label, raw: body };
   }
 
-  // 4. Bare numeric id.
+  // 5. Bare numeric id.
   if (NUMERIC_RE.test(body)) {
     return { kind: 'numeric', id: body, label: null, raw: body };
   }
 
-  // 5. Anything else is unresolved at the parse layer.
+  // 6. Anything else is unresolved at the parse layer.
   return { kind: 'unresolved', raw: body };
 }
 

package/src/reference-resolver.js

@@ -13,6 +13,21 @@ export class Reference {
     this.resolution = extras.resolution ?? null;
     this.lookupKey = extras.lookupKey ?? null;
   }
+
+  get dedupKey() {
+    if (this.type === 'bibliography') {
+      return ['bibliography',
+        this.sourceId ?? this.citation?.ref?.id ?? this.target];
+    }
+    if (this.type === 'figure' || this.type === 'table' || this.type === 'formula') {
+      return [this.type, this.lookupKey?.entityId ?? this.target];
+    }
+    if (this.type === 'concept') {
+      return ['concept',
+        this.lookupKey?.id ?? this.lookupKey?.designation ?? this.target];
+    }
+    return [this.type, this.target];
+  }
 }
 
 function refTarget(rc) {
@@ -33,6 +48,18 @@ export function resolveBibliographyRecord(citationRef, registry) {
   return bioColl.byId(citationRef.id);
 }
 
+export function findNonVerbalEntity(ref, registry) {
+  const { entityType, entityId } = ref.lookupKey ?? {};
+  if (!entityType || !entityId) return null;
+  const collection = registry[`nvr:${entityType}`];
+  if (!collection) return null;
+  for (const entity of collection) {
+    const found = entity.findById(entityId);
+    if (found) return found;
+  }
+  return null;
+}
+
 export class ReferenceResolver {
   extractReferences(concept) {
     const refs = [];
@@ -46,6 +73,22 @@ export class ReferenceResolver {
       }
     }
 
+    for (const ref of concept.figures) {
+      refs.push(new Reference('figure', ref.display ?? ref.entityId, 'structural', 'figures', {
+        lookupKey: { entityType: 'figure', entityId: ref.entityId },
+      }));
+    }
+    for (const ref of concept.tables) {
+      refs.push(new Reference('table', ref.display ?? ref.entityId, 'structural', 'tables', {
+        lookupKey: { entityType: 'table', entityId: ref.entityId },
+      }));
+    }
+    for (const ref of concept.formulas) {
+      refs.push(new Reference('formula', ref.display ?? ref.entityId, 'structural', 'formulas', {
+        lookupKey: { entityType: 'formula', entityId: ref.entityId },
+      }));
+    }
+
     for (const lang of concept.languages) {
       const lc = concept.localization(lang);
       if (!lc) continue;
@@ -66,7 +109,17 @@ export class ReferenceResolver {
       }
     }
 
-    return refs;
+    return this._dedup(refs);
+  }
+
+  _dedup(refs) {
+    const seen = new Set();
+    return refs.filter(ref => {
+      const key = JSON.stringify(ref.dedupKey);
+      if (seen.has(key)) return false;
+      seen.add(key);
+      return true;
+    });
   }
 
   _collectTexts(lc, lang) {
@@ -114,6 +167,21 @@ export class ReferenceResolver {
             resolution: null,
           }));
           break;
+        case 'fig-ref':
+          refs.push(new Reference('figure', parsed.label ?? parsed.key, 'embedded', source, {
+            lookupKey: { entityType: 'figure', entityId: parsed.key },
+          }));
+          break;
+        case 'table-ref':
+          refs.push(new Reference('table', parsed.label ?? parsed.key, 'embedded', source, {
+            lookupKey: { entityType: 'table', entityId: parsed.key },
+          }));
+          break;
+        case 'formula-ref':
+          refs.push(new Reference('formula', parsed.label ?? parsed.key, 'embedded', source, {
+            lookupKey: { entityType: 'formula', entityId: parsed.key },
+          }));
+          break;
         case 'numeric':
           refs.push(new Reference('concept', parsed.label ?? parsed.id, 'embedded', source, {
             lookupKey: { id: parsed.id },
@@ -168,6 +236,9 @@ export class ReferenceResolver {
     switch (ref.type) {
       case 'concept':      return this._resolveConcept(ref, registry);
       case 'bibliography': return this._resolveBibliography(ref, registry);
+      case 'figure':
+      case 'table':
+      case 'formula':      return this._resolveNonVerbal(ref, registry);
       case 'dataset':      return this._resolveDataset(ref, registry);
       case 'typed-ref':    return this._resolveTypedRef(ref, registry);
       case 'standard':     return this._resolveStandard(ref, registry);
@@ -175,6 +246,10 @@ export class ReferenceResolver {
     }
   }
 
+  _resolveNonVerbal(ref, registry) {
+    return findNonVerbalEntity(ref, registry);
+  }
+
   _resolveConcept(ref, registry) {
     if (ref.lookupKey?.id) {
       const dataset = ref.lookupKey.dataset;
@@ -218,7 +293,8 @@ export class ReferenceResolver {
   resolveAll(concept, registry) {
     const resolved = new Map();
     for (const ref of this.extractReferences(concept)) {
-      if (ref.type === 'concept' || ref.type === 'bibliography') {
+      if (ref.type === 'concept' || ref.type === 'bibliography'
+          || ref.type === 'figure' || ref.type === 'table' || ref.type === 'formula') {
         const target = this.resolveReference(ref, registry);
         if (target != null) {
           const key = ref.target ?? ref.uri ?? ref.sourceId;

package/src/render-classification.js

@@ -1,4 +1,4 @@
-import { resolveBibliographyRecord } from './reference-resolver.js';
+import { resolveBibliographyRecord, findNonVerbalEntity } from './reference-resolver.js';
 
 export class ReferenceClassifier {
   constructor(registry = {}, sourceDatasetId = null, options = {}) {
@@ -14,6 +14,9 @@ export class ReferenceClassifier {
       case 'concept':      return this._classifyConcept(ref);
       case 'dataset':      return this._classifyDataset(ref);
       case 'bibliography': return this._classifyBibliography(ref);
+      case 'figure':
+      case 'table':
+      case 'formula':      return this._classifyNonVerbal(ref);
       case 'typed-ref':    return this._classifyTypedRef(ref);
       case 'standard':     return 'legacy-standard';
       default:             return 'unknown';
@@ -63,4 +66,10 @@ export class ReferenceClassifier {
   _classifyTypedRef(_ref) {
     return 'typed-ref';
   }
+
+  _classifyNonVerbal(ref) {
+    return findNonVerbalEntity(ref, this.registry)
+      ? 'internal-citation'
+      : 'external-citation';
+  }
 }

package/src/validators/asset-index.js

@@ -0,0 +1,66 @@
+import { DATASET_ASSETS } from '../dataset-asset.js';
+
+export class AssetIndex {
+  constructor() {
+    this._paths = new Set();
+  }
+
+  get paths() {
+    return [...this._paths].sort();
+  }
+
+  get size() {
+    return this._paths.size;
+  }
+
+  register(path) {
+    if (path == null) return;
+    this._paths.add(this._normalize(path));
+  }
+
+  has(path) {
+    if (path == null) return false;
+    return this._paths.has(this._normalize(path));
+  }
+
+  [Symbol.iterator]() {
+    return this._paths[Symbol.iterator]();
+  }
+
+  _normalize(path) {
+    return String(path).replace(/^\//, '');
+  }
+
+  static async fromGcrPackage(pkg) {
+    const index = new AssetIndex();
+    const names = await pkg.imageFileNames();
+    for (const name of names) {
+      index.register(name);
+    }
+    return index;
+  }
+
+  static fromDirectory(datasetPath, fs) {
+    const index = new AssetIndex();
+    const imagesAsset = DATASET_ASSETS.find(
+      a => a.type === 'directory' && a.path === 'images');
+    if (!imagesAsset) return index;
+
+    const imagesDir = `${datasetPath}/${imagesAsset.path}`;
+    _walkDir(fs, imagesDir, imagesAsset.path, index);
+    return index;
+  }
+}
+
+function _walkDir(fs, dirPath, relativePrefix, index) {
+  if (!fs.existsSync(dirPath)) return;
+  for (const entry of fs.readdirSync(dirPath, { withFileTypes: true })) {
+    const fullPath = `${dirPath}/${entry.name}`;
+    const relPath = `${relativePrefix}/${entry.name}`;
+    if (entry.isDirectory()) {
+      _walkDir(fs, fullPath, relPath, index);
+    } else {
+      index.register(relPath);
+    }
+  }
+}

package/src/validators/index.js

@@ -14,6 +14,8 @@ export {
   UuidFormatRule,
   SourceUrnFormatRule,
   CiteRefIntegrityRule,
+  NonVerbalRefIntegrityRule,
+  OrphanedImagesRule,
 } from './v3-rules.js';
 
 import { ConceptValidator, LanguageCodeRule, DesignationTypeRule, EntryStatusRule } from './concept-validator.js';
@@ -29,6 +31,7 @@ import {
   UuidFormatRule,
   SourceUrnFormatRule,
   CiteRefIntegrityRule,
+  NonVerbalRefIntegrityRule,
 } from './v3-rules.js';
 
 const _default = new ConceptValidator()
@@ -43,7 +46,8 @@ const _default = new ConceptValidator()
   .addRule(new UuidFormatRule())
   .addRule(new SourceUrnFormatRule())
   .addRule(new RelationshipTypeRule())
-  .addRule(new CiteRefIntegrityRule());
+  .addRule(new CiteRefIntegrityRule())
+  .addRule(new NonVerbalRefIntegrityRule());
 
 export function validateConcept(concept) {
   return _default.validate(concept);

package/src/validators/v3-rules.js

@@ -1,4 +1,6 @@
 import { ValidationRule } from './validation-rule.js';
+import { parseMention } from '../reference-mention.js';
+import { GraphicalSymbol } from '../models/designation.js';
 
 const _eachLocalization = (concept, fn) => {
   for (const lang of concept.languages) {
@@ -267,3 +269,148 @@ export class CiteRefIntegrityRule extends ValidationRule {
     }
   }
 }
+
+
+// ── NonVerbalRefIntegrityRule ────────────────────────────────────────
+// Uses parseMention for classification (no regex duplication).
+
+
+const NVR_ARRAYS = Object.freeze([
+  { name: 'figures', entityType: 'figure' },
+  { name: 'tables', entityType: 'table' },
+  { name: 'formulas', entityType: 'formula' },
+]);
+
+function _findNvrMentions(concept) {
+  const mentions = [];
+  const walkText = (text, source) => {
+    if (typeof text !== 'string' || text.length === 0) return;
+    const re = /\{\{([^{}]*?)\}\}/g;
+    let m;
+    while ((m = re.exec(text)) !== null) {
+      const parsed = parseMention(m[1]);
+      if (parsed.kind === 'fig-ref' ||
+          parsed.kind === 'table-ref' ||
+          parsed.kind === 'formula-ref') {
+        mentions.push({ key: parsed.key, source });
+      }
+    }
+  };
+
+  for (const lang of concept.languages) {
+    const lc = concept.localization(lang);
+    if (!lc) continue;
+    for (let i = 0; i < lc.definitions.length; i++) {
+      walkText(lc.definitions[i]?.content,
+        `localizations.${lang}.definitions[${i}].content`);
+    }
+    for (let i = 0; i < lc.notes.length; i++) {
+      walkText(lc.notes[i]?.content,
+        `localizations.${lang}.notes[${i}].content`);
+    }
+    for (let i = 0; i < lc.examples.length; i++) {
+      walkText(lc.examples[i]?.content,
+        `localizations.${lang}.examples[${i}].content`);
+    }
+    for (let i = 0; i < lc.annotations.length; i++) {
+      walkText(lc.annotations[i]?.content,
+        `localizations.${lang}.annotations[${i}].content`);
+    }
+  }
+  return mentions;
+}
+
+export class NonVerbalRefIntegrityRule extends ValidationRule {
+  constructor() {
+    super('nvr-integrity', 'warning');
+  }
+
+  validate(concept, path, result) {
+    for (const { name } of NVR_ARRAYS) {
+      const counts = new Map();
+      for (const ref of concept[name]) {
+        if (ref.entityId == null) continue;
+        counts.set(ref.entityId, (counts.get(ref.entityId) ?? 0) + 1);
+      }
+      for (const [id, count] of counts) {
+        if (count > 1) {
+          this.addIssue(result, `${path}${name}`,
+            `duplicate ${name} reference id "${id}" appears ${count} times`);
+        }
+      }
+    }
+
+    const mentions = _findNvrMentions(concept);
+    if (mentions.length === 0) return;
+
+    const knownIds = new Set();
+    for (const { name } of NVR_ARRAYS) {
+      for (const ref of concept[name]) {
+        if (ref.entityId != null) knownIds.add(ref.entityId);
+      }
+    }
+
+    for (const { key, source } of mentions) {
+      if (!knownIds.has(key)) {
+        this.addIssue(result, source,
+          `inline NVR mention "${key}" does not resolve to any figures/tables/formulas entry`);
+      }
+    }
+  }
+}
+
+// ── OrphanedImagesRule ───────────────────────────────────────────────
+// Collection-scope rule: needs AssetIndex + all concepts. Called
+// directly by GcrValidator (not in concept validator chain).
+
+export class OrphanedImagesRule {
+  constructor() {
+    this.name = 'orphaned-images';
+    this.severity = 'warning';
+  }
+
+  check(context) {
+    const { assetIndex, concepts, resolver } = context;
+    if (!assetIndex || assetIndex.size === 0) return [];
+
+    const referenced = new Set();
+
+    for (const concept of concepts) {
+      if (resolver) {
+        for (const ref of resolver.extractReferences(concept)) {
+          if (ref.target && ref.target.includes('images/')) {
+            referenced.add(ref.target.replace(/^\//, ''));
+          }
+        }
+      }
+
+      for (const lang of concept.languages) {
+        const lc = concept.localization(lang);
+        if (!lc) continue;
+
+        for (const nvr of lc.nonVerbalRep) {
+          for (const img of nvr.images) {
+            if (img.src) referenced.add(img.src.replace(/^\//, ''));
+          }
+        }
+        for (const term of lc.terms) {
+          if (term instanceof GraphicalSymbol && term.image) {
+            referenced.add(term.image.replace(/^\//, ''));
+          }
+        }
+      }
+    }
+
+    const issues = [];
+    for (const imgPath of assetIndex.paths) {
+      if (!referenced.has(imgPath)) {
+        issues.push({
+          path: imgPath,
+          severity: 'warning',
+          message: `orphaned image: ${imgPath} (not referenced by any concept)`,
+        });
+      }
+    }
+    return issues;
+  }
+}