glossarist 0.1.6 → 0.2.0

package/README.md

@@ -118,6 +118,51 @@ COMPILED_EXTENSIONS.get('turtle');           // 'ttl'
 isKnownFormat('csv');                        // false
 ```
 
+### Bibliography and images in GCR
+
+GCR packages can contain a `bibliography.yaml` file and an `images/` directory, making the archive fully self-contained. This mirrors the Ruby glossarist gem's `DATASET_ASSETS` convention.
+
+```js
+import { loadGcr } from 'glossarist';
+
+const pkg = await loadGcr(fs.readFileSync('dataset.gcr'));
+
+// Bibliography (raw YAML string)
+const bib = await pkg.bibliography();         // 'ISO_19111_2019:\n  ...' or null
+
+// Images
+await pkg.hasImages();                        // true
+const names = await pkg.imageFileNames();     // ['images/fig1.png', ...]
+const img = await pkg.imageFile('fig1.png');  // Uint8Array or null
+const allImages = await pkg.allImageFiles();  // Map<string, Uint8Array>
+```
+
+#### Write bibliography and images into a GCR package
+
+```js
+import { GcrWriter } from 'glossarist';
+
+const buf = await GcrWriter.createBuffer({
+  concepts: [...],
+  metadata: { shortname: 'my-dataset' },
+  bibliography: 'ISO_19111_2019:\n  title: Geographic information',
+  images: {
+    'figure1.png': pngBuffer,
+    'diagrams/schema.svg': svgString,
+  },
+});
+```
+
+#### Dataset asset registry
+
+```js
+import { DATASET_ASSETS, FILE_ASSETS, DIRECTORY_ASSETS } from 'glossarist';
+
+DATASET_ASSETS;   // [{ path: 'bibliography.yaml', type: 'file' }, { path: 'images', type: 'directory' }]
+FILE_ASSETS;      // [{ path: 'bibliography.yaml', type: 'file' }]
+DIRECTORY_ASSETS; // [{ path: 'images', type: 'directory' }]
+```
+
 ### Domain model
 
 Every domain entity is a class instance with `toJSON()`, `fromJSON()`, `equals()`, and `clone()`:
@@ -269,6 +314,7 @@ Public API (index.js)
 ├── Serialization     → ConceptSerializer (canonical + managed YAML output)
 ├── I/O               → loadGcr, readConcepts, createGcr, writeConcepts
 ├── Compiled formats  → CompiledFormatRegistry (TBX, JSON-LD, Turtle, JSONL in GCR)
+├── Dataset assets    → DATASET_ASSETS registry (bibliography.yaml, images/ in GCR)
 ├── Collections       → ConceptCollection (Proxy-based, queryable), ManagedConceptCollection
 ├── Validation        → ConceptValidator, RegisterValidator, ValidationRule (pluggable)
 ├── Utilities         → conceptUuid, referenceResolver, V1Reader

package/package.json

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

package/src/concept-collection.js

@@ -1,4 +1,4 @@
-import { naturalSort } from './gcr-reader.js';
+import { naturalSort } from './sort.js';
 
 const _items = Symbol('items');
 

package/src/concept-reader.d.ts

@@ -1,4 +1,4 @@
-import type { Concept } from './gcr-reader';
+import type { Concept } from './models/index';
 
 /** Read all concept YAML files from a directory. */
 export function readConcepts(dir: string): Concept[];

package/src/concept-reader.js

@@ -2,7 +2,7 @@ import fs from 'fs';
 import path from 'path';
 import yaml from 'js-yaml';
 import { conceptParser } from './concept-parser.js';
-import { naturalSort } from './gcr-reader.js';
+import { naturalSort } from './sort.js';
 import { InvalidInputError } from './errors.js';
 
 function assertDir(dir, fnName) {

package/src/dataset-asset.js

@@ -0,0 +1,65 @@
+/**
+ * Registry of dataset assets that can be bundled inside a GCR package.
+ *
+ * Mirrors the Ruby glossarist gem's GcrPackage::DATASET_ASSETS.
+ * Asset types:
+ *   - file: a single named file at the GCR root (e.g. bibliography.yaml)
+ *   - directory: a named directory with arbitrary nested files (e.g. images/)
+ *
+ * New asset types can be added by appending to DATASET_ASSETS (open/closed).
+ */
+
+const DATASET_ASSETS = Object.freeze([
+  { path: 'bibliography.yaml', type: 'file' },
+  { path: 'images', type: 'directory' },
+]);
+
+const FILE_ASSETS = Object.freeze(
+  DATASET_ASSETS.filter((a) => a.type === 'file'),
+);
+
+const DIRECTORY_ASSETS = Object.freeze(
+  DATASET_ASSETS.filter((a) => a.type === 'directory'),
+);
+
+/**
+ * Find a file asset descriptor by its ZIP path.
+ * @param {string} path
+ * @returns {{ path: string, type: string } | undefined}
+ */
+function findFileAsset(path) {
+  return FILE_ASSETS.find((a) => a.path === path);
+}
+
+/**
+ * Check whether a ZIP path belongs to a directory asset.
+ * Returns the asset descriptor if so, undefined otherwise.
+ * @param {string} zipPath
+ * @returns {{ path: string, type: string } | undefined}
+ */
+function findDirectoryAssetPath(zipPath) {
+  for (const asset of DIRECTORY_ASSETS) {
+    if (zipPath === asset.path || zipPath.startsWith(`${asset.path}/`)) {
+      return asset;
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Check if a ZIP path is a dataset asset entry.
+ * @param {string} zipPath
+ * @returns {boolean}
+ */
+function isDatasetAssetPath(zipPath) {
+  return findFileAsset(zipPath) !== undefined || findDirectoryAssetPath(zipPath) !== undefined;
+}
+
+export {
+  DATASET_ASSETS,
+  FILE_ASSETS,
+  DIRECTORY_ASSETS,
+  findFileAsset,
+  findDirectoryAssetPath,
+  isDatasetAssetPath,
+};

package/src/gcr-reader.d.ts

@@ -1,52 +1,4 @@
-/** A single term designation. */
-export interface Term {
-  type: string;
-  designation: string;
-  normative_status?: string;
-}
-
-/** A definition content block. */
-export interface Definition {
-  content: string;
-}
-
-/** A bibliographic source reference. */
-export interface Source {
-  type: string;
-  origin?: { ref: string };
-}
-
-/** Localized concept data for a single language. */
-export interface Localization {
-  terms: Term[];
-  definition?: Definition[];
-  notes?: { content: string }[];
-  examples?: { content: string }[];
-  sources?: Source[];
-  entry_status?: string;
-  normative_status?: string;
-}
-
-/** A normalized glossarist concept. */
-export interface Concept {
-  termid: string;
-  term: string | null;
-  localizations: Record<string, Localization>;
-  raw: Record<string, unknown>;
-}
-
-/** GCR package metadata from metadata.yaml. */
-export interface GcrMetadata {
-  shortname: string;
-  version?: string;
-  title?: string;
-  concept_count?: number;
-  languages?: string[];
-  schema_version?: string;
-  glossarist_version?: string;
-  created_at?: string;
-  statistics?: Record<string, unknown>;
-}
+import { Concept, GcrMetadata } from './models/index';
 
 /**
  * Load a GCR package from a ZIP archive.
@@ -56,7 +8,7 @@ export function loadGcr(input: Buffer | ArrayBuffer | Uint8Array | Blob | string
 
 /** A loaded GCR package (ZIP archive of glossarist concept data). */
 export class GcrPackage {
-  /** Read and parse metadata.yaml. */
+  /** Read and parse metadata.yaml as a GcrMetadata instance. */
   metadata(): Promise<GcrMetadata | null>;
   /** Read and parse optional register.yaml. */
   register(): Promise<Record<string, unknown> | null>;
@@ -85,9 +37,28 @@ export class GcrPackage {
   eachCompiledFile(format: string, callback: (id: string, content: string) => void | Promise<void>): Promise<void>;
   /** Load all entries for a compiled format into a Map. */
   allCompiledFiles(format: string): Promise<Map<string, string>>;
+
+  // Dataset assets (bibliography, images)
+
+  /** List all dataset asset entries found in this package. */
+  datasetAssetEntries(): Promise<Array<{ path: string; type: 'file' | 'directory'; asset: { path: string; type: string } }>>;
+  /** Read a file-type dataset asset by its registered path. */
+  readDatasetFileAsset(assetPath: string): Promise<string | null>;
+  /** Read bibliography.yaml from the package as raw YAML string. */
+  bibliography(): Promise<string | null>;
+  /** Check whether the images/ directory is present and non-empty. */
+  hasImages(): Promise<boolean>;
+  /** List all image file paths (relative to ZIP root). */
+  imageFileNames(): Promise<string[]>;
+  /** Read a single image file as Uint8Array. */
+  imageFile(path: string): Promise<Uint8Array | null>;
+  /** Iterate all image files. */
+  eachImageFile(callback: (path: string, content: Uint8Array) => void | Promise<void>): Promise<void>;
+  /** Load all image files into a Map (path → Uint8Array). */
+  allImageFiles(): Promise<Map<string, Uint8Array>>;
 }
 
-/** Parse raw concept YAML (canonical or managed format) into a normalized Concept. */
+/** Parse raw concept YAML (canonical or managed format) into a Concept. */
 export function parseConceptYaml(raw: string, context?: string): Concept;
 
 /** Natural sort comparator for concept IDs like "3.1.1.1", "551-12-39". */

package/src/gcr-reader.js

@@ -2,12 +2,14 @@ import JSZip from 'jszip';
 import yaml from 'js-yaml';
 import { conceptParser } from './concept-parser.js';
 import { InvalidInputError } from './errors.js';
-import { COMPILED_EXTENSIONS, parseCompiledPath, compiledPath } from './compiled-format.js';
+import { COMPILED_FORMATS, parseCompiledPath, compiledPath } from './compiled-format.js';
+import { DATASET_ASSETS, findFileAsset, findDirectoryAssetPath } from './dataset-asset.js';
+import { GcrMetadata } from './models/gcr-metadata.js';
+import { naturalSort } from './sort.js';
 
-const BASE64_RE = /^[A-Za-z0-9+/]{100,}={0,2}$/;
+export { naturalSort } from './sort.js';
 
-const NATURAL_SORT_RE = /(\d+|\D+)/g;
-const DIGIT_RE = /^\d+$/;
+const BASE64_RE = /^[A-Za-z0-9+/]{100,}={0,2}$/;
 
 /**
  * @typedef {Object} Term
@@ -81,12 +83,12 @@ export class GcrPackage {
   }
 
   /**
-   * Read and parse metadata.yaml from the package.
+   * Read and parse metadata.yaml from the package as a GcrMetadata instance.
    * @returns {Promise<GcrMetadata | null>}
    */
   async metadata() {
     const raw = await this._readText('metadata.yaml');
-    return raw ? yaml.load(raw) : null;
+    return raw ? GcrMetadata.fromYaml(raw) : null;
   }
 
   /**
@@ -154,7 +156,6 @@ export class GcrPackage {
 
   /**
    * List compiled format directories present in this package.
-   * Only returns formats whose `compiled/{format}/` directory contains at least one file.
    * @returns {Promise<string[]>}
    */
   async compiledFormats() {
@@ -165,9 +166,7 @@ export class GcrPackage {
         if (parsed) seen.add(parsed.format);
       }
     });
-    return COMPILED_EXTENSIONS.keys
-      ? [...COMPILED_EXTENSIONS.keys()].filter((f) => seen.has(f))
-      : [...seen];
+    return COMPILED_FORMATS.filter((f) => seen.has(f));
   }
 
   /**
@@ -250,6 +249,124 @@ export class GcrPackage {
     return map;
   }
 
+  // --- Dataset assets (bibliography, images, etc.) ---
+
+  /**
+   * List all dataset asset entries found in this package.
+   * Each entry has { path, type, asset } where asset is the registry descriptor.
+   * @returns {Promise<Array<{ path: string, type: 'file' | 'directory', asset: { path: string, type: string } }>>}
+   */
+  async datasetAssetEntries() {
+    const entries = [];
+    this._zip.forEach((relativePath, zipEntry) => {
+      if (zipEntry.dir) return;
+      const fileAsset = findFileAsset(relativePath);
+      if (fileAsset) {
+        entries.push({ path: relativePath, type: 'file', asset: fileAsset });
+        return;
+      }
+      const dirAsset = findDirectoryAssetPath(relativePath);
+      if (dirAsset) {
+        entries.push({ path: relativePath, type: 'directory', asset: dirAsset });
+      }
+    });
+    return entries;
+  }
+
+  /**
+   * Read a file-type dataset asset by its registered path (e.g. 'bibliography.yaml').
+   * @param {string} assetPath - registered file asset path
+   * @returns {Promise<string | null>}
+   */
+  async readDatasetFileAsset(assetPath) {
+    return this._readText(assetPath);
+  }
+
+  /**
+   * Read bibliography.yaml from the package as a string (raw YAML).
+   * @returns {Promise<string | null>}
+   */
+  async bibliography() {
+    const fileAsset = DATASET_ASSETS.find((a) => a.type === 'file' && a.path === 'bibliography.yaml');
+    return fileAsset ? this._readText(fileAsset.path) : null;
+  }
+
+  /**
+   * Check whether the images/ directory is present and non-empty.
+   * Uses the dataset-asset registry to find the images directory.
+   * @returns {Promise<boolean>}
+   */
+  async hasImages() {
+    const asset = DATASET_ASSETS.find((a) => a.type === 'directory' && a.path === 'images');
+    if (!asset) return false;
+    const prefix = `${asset.path}/`;
+    let found = false;
+    this._zip.forEach((relativePath, entry) => {
+      if (!found && !entry.dir && relativePath.startsWith(prefix)) {
+        found = true;
+      }
+    });
+    return found;
+  }
+
+  /**
+   * List all image file paths (relative to ZIP root).
+   * Uses the dataset-asset registry to find the images directory.
+   * @returns {Promise<string[]>}
+   */
+  async imageFileNames() {
+    const asset = DATASET_ASSETS.find((a) => a.type === 'directory' && a.path === 'images');
+    if (!asset) return [];
+    const prefix = `${asset.path}/`;
+    const names = [];
+    this._zip.forEach((relativePath, entry) => {
+      if (!entry.dir && relativePath.startsWith(prefix)) {
+        names.push(relativePath);
+      }
+    });
+    return names.sort();
+  }
+
+  /**
+   * Read a single image file as a Uint8Array.
+   * @param {string} path - relative path starting with 'images/' or just the filename
+   * @returns {Promise<Uint8Array | null>}
+   */
+  async imageFile(path) {
+    const asset = DATASET_ASSETS.find((a) => a.type === 'directory' && a.path === 'images');
+    if (!asset) return null;
+    const fullPath = path.startsWith(`${asset.path}/`) ? path : `${asset.path}/${path}`;
+    const entry = this._zip.file(fullPath);
+    if (!entry) return null;
+    return entry.async('uint8array');
+  }
+
+  /**
+   * Iterate all image files.
+   * @param {(path: string, content: Uint8Array) => void | Promise<void>} callback
+   * @returns {Promise<void>}
+   */
+  async eachImageFile(callback) {
+    const names = await this.imageFileNames();
+    for (const name of names) {
+      const entry = this._zip.file(name);
+      if (entry) {
+        const content = await entry.async('uint8array');
+        await callback(name, content);
+      }
+    }
+  }
+
+  /**
+   * Load all image files into a Map (path → Uint8Array).
+   * @returns {Promise<Map<string, Uint8Array>>}
+   */
+  async allImageFiles() {
+    const map = new Map();
+    await this.eachImageFile((path, content) => { map.set(path, content); });
+    return map;
+  }
+
   /** @private @param {string} filePath @returns {Promise<string | null>} */
   async _readText(filePath) {
     const entry = this._zip.file(filePath);
@@ -277,34 +394,6 @@ export function parseConceptYaml(raw, context) {
   return conceptParser.parse(raw, context);
 }
 
-// --- Helpers ---
-
-/**
- * Natural sort comparator for concept IDs like "3.1.1.1", "551-12-39".
- * @param {string} a
- * @param {string} b
- * @returns {number}
- *
- * @example
- * ['3.1.10', '3.1.2', '3.1.1'].sort(naturalSort); // ['3.1.1', '3.1.2', '3.1.10']
- */
-export function naturalSort(a, b) {
-  const pa = a.match(NATURAL_SORT_RE) || [];
-  const pb = b.match(NATURAL_SORT_RE) || [];
-  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
-    const na = pa[i] || '';
-    const nb = pb[i] || '';
-    if (DIGIT_RE.test(na) && DIGIT_RE.test(nb)) {
-      const diff = parseInt(na, 10) - parseInt(nb, 10);
-      if (diff !== 0) return diff;
-    } else {
-      const cmp = na.localeCompare(nb);
-      if (cmp !== 0) return cmp;
-    }
-  }
-  return 0;
-}
-
 /**
  * @typedef {Object} GcrMetadata
  * @property {string} shortname - dataset short name

package/src/gcr-writer.d.ts

@@ -1,16 +1,21 @@
-import { Concept } from './models/index';
+import { Concept, GcrMetadata } from './models/index';
 
 /** Compiled formats map: format name → id → content string. */
 export type CompiledFormatsMap = Record<string, Record<string, string> | Map<string, string>>;
 
+/** Images map: relative path → binary content. */
+export type ImagesMap = Record<string, Uint8Array | string | ArrayBuffer> | Map<string, Uint8Array | string | ArrayBuffer>;
+
 export class GcrWriter {
   static createBuffer(options: {
     concepts: Concept[];
-    metadata?: Record<string, unknown>;
+    metadata?: GcrMetadata | Record<string, unknown>;
     register?: Record<string, unknown>;
     uuidFn?: () => string;
     format?: 'canonical' | 'managed' | 'auto';
     compiledFormats?: CompiledFormatsMap;
+    bibliography?: string;
+    images?: ImagesMap;
   }): Promise<Uint8Array>;
 }
 

package/src/gcr-writer.js

@@ -2,6 +2,8 @@ import JSZip from 'jszip';
 import { conceptSerializer } from './concept-serializer.js';
 import { InvalidInputError } from './errors.js';
 import { compiledPath, isKnownFormat } from './compiled-format.js';
+import { GcrMetadata } from './models/gcr-metadata.js';
+import { GcrStatistics } from './models/gcr-statistics.js';
 
 export class GcrWriter {
   static async createBuffer(options) {
@@ -15,7 +17,8 @@ export class GcrWriter {
     const zip = new JSZip();
 
     if (options.metadata) {
-      zip.file('metadata.yaml', conceptSerializer.toRegisterYaml(options.metadata));
+      const meta = GcrWriter._normalizeMetadata(options.metadata, options.concepts);
+      zip.file('metadata.yaml', conceptSerializer.toRegisterYaml(meta));
     }
     if (options.register) {
       zip.file('register.yaml', conceptSerializer.toRegisterYaml(options.register));
@@ -34,9 +37,37 @@ export class GcrWriter {
       GcrWriter._writeCompiledFormats(zip, options.compiledFormats);
     }
 
+    if (options.bibliography) {
+      zip.file('bibliography.yaml', options.bibliography);
+    }
+
+    if (options.images) {
+      GcrWriter._writeImages(zip, options.images);
+    }
+
     return zip.generateAsync({ type: 'uint8array' });
   }
 
+  static _normalizeMetadata(metadata, concepts) {
+    if (metadata instanceof GcrMetadata) {
+      const meta = metadata.clone();
+      if (!meta.statistics && concepts.length > 0) {
+        meta.statistics = GcrStatistics.fromConcepts(concepts);
+      }
+      if (!meta.conceptCount) meta.conceptCount = concepts.length;
+      return meta.toJSON();
+    }
+
+    const data = { ...metadata };
+    if (!data.statistics && concepts.length > 0) {
+      data.statistics = GcrStatistics.fromConcepts(concepts).toJSON();
+    }
+    if (!data.concept_count && concepts.length > 0) {
+      data.concept_count = concepts.length;
+    }
+    return data;
+  }
+
   static _writeCompiledFormats(zip, compiledFormats) {
     for (const [format, entries] of Object.entries(compiledFormats)) {
       if (!isKnownFormat(format)) {
@@ -48,6 +79,14 @@ export class GcrWriter {
       }
     }
   }
+
+  static _writeImages(zip, images) {
+    const map = images instanceof Map ? images : new Map(Object.entries(images));
+    for (const [path, content] of map) {
+      const fullPath = path.startsWith('images/') ? path : `images/${path}`;
+      zip.file(fullPath, content);
+    }
+  }
 }
 
 export async function createGcr(concepts, metadata) {

package/src/index.d.ts

@@ -5,12 +5,12 @@ export {
   Designation, Expression, Abbreviation, Symbol, GraphicalSymbol,
   Citation, ConceptSource, RelatedConcept, ConceptDate,
   DetailedDefinition, NonVerbRep,
+  GcrMetadata, GcrStatistics,
   RELATIONSHIP_TYPES, DATE_TYPES,
 } from './models/index';
 
 // GCR reader
 export { loadGcr, GcrPackage, parseConceptYaml, naturalSort } from './gcr-reader';
-export type { GcrMetadata } from './gcr-reader';
 
 // GCR writer
 export { createGcr, GcrWriter } from './gcr-writer';
@@ -47,3 +47,11 @@ export function isKnownFormat(format: string): boolean;
 export function compiledFilename(format: string, id: string): string;
 export function compiledPath(format: string, id: string): string;
 export function parseCompiledPath(zipPath: string): { format: string; id: string } | null;
+
+// Dataset asset registry
+export const DATASET_ASSETS: readonly { path: string; type: string }[];
+export const FILE_ASSETS: readonly { path: string; type: string }[];
+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;

package/src/index.js

@@ -1,4 +1,5 @@
-export { loadGcr, GcrPackage, parseConceptYaml, naturalSort } from './gcr-reader.js';
+export { naturalSort } from './sort.js';
+export { loadGcr, GcrPackage, parseConceptYaml } from './gcr-reader.js';
 export { readConcepts, readConcept, listConceptIds, readRegister } from './concept-reader.js';
 export { writeConcept, writeConcepts } from './concept-writer.js';
 export { createGcr, GcrWriter } from './gcr-writer.js';
@@ -19,11 +20,18 @@ export {
   parseCompiledPath,
 } from './compiled-format.js';
 
+export {
+  DATASET_ASSETS,
+  FILE_ASSETS,
+  DIRECTORY_ASSETS,
+} from './dataset-asset.js';
+
 export {
   GlossaristModel,
   Concept, LocalizedConcept,
   Designation, Expression, Abbreviation, Symbol, GraphicalSymbol,
   Citation, ConceptSource, RelatedConcept, ConceptDate,
   DetailedDefinition, NonVerbRep,
+  GcrMetadata, GcrStatistics,
   RELATIONSHIP_TYPES, DATE_TYPES,
 } from './models/index.js';

package/src/managed-concept-collection.js

@@ -2,16 +2,20 @@ import { ConceptCollection } from './concept-collection.js';
 import { readConcepts, readRegister } from './concept-reader.js';
 import { writeConcepts } from './concept-writer.js';
 import { loadGcr } from './gcr-reader.js';
-import { createGcr } from './gcr-writer.js';
+import { GcrWriter } from './gcr-writer.js';
 
 export class ManagedConceptCollection {
   constructor() {
     this._concepts = new ConceptCollection();
     this._register = null;
+    this._bibliography = null;
+    this._images = null;
   }
 
   get concepts() { return this._concepts; }
   get register() { return this._register; }
+  get bibliography() { return this._bibliography; }
+  get images() { return this._images; }
 
   loadFromDirectory(dir) {
     this._concepts = new ConceptCollection(readConcepts(dir));
@@ -23,6 +27,8 @@ export class ManagedConceptCollection {
     const pkg = await loadGcr(input);
     this._concepts = new ConceptCollection(await pkg.allConcepts());
     this._register = await pkg.register();
+    this._bibliography = await pkg.bibliography();
+    this._images = await pkg.allImageFiles();
     return this;
   }
 
@@ -34,7 +40,15 @@ export class ManagedConceptCollection {
   }
 
   async saveToGcr(options = {}) {
-    return createGcr(this._concepts, options.metadata);
+    return GcrWriter.createBuffer({
+      concepts: this._concepts,
+      metadata: options.metadata,
+      register: this._register,
+      format: options.format,
+      compiledFormats: options.compiledFormats,
+      bibliography: this._bibliography,
+      images: this._images,
+    });
   }
 
   add(concept) {
@@ -58,4 +72,14 @@ export class ManagedConceptCollection {
     this._register = data;
     return this;
   }
+
+  setBibliography(yamlString) {
+    this._bibliography = yamlString;
+    return this;
+  }
+
+  setImages(images) {
+    this._images = images instanceof Map ? images : new Map(Object.entries(images));
+    return this;
+  }
 }

package/src/models/gcr-metadata.js

@@ -0,0 +1,68 @@
+import yaml from 'js-yaml';
+import { GlossaristModel } from './base.js';
+import { GcrStatistics } from './gcr-statistics.js';
+
+export class GcrMetadata extends GlossaristModel {
+  constructor(data = {}) {
+    super();
+    this.shortname = data.shortname ?? null;
+    this.version = data.version ?? null;
+    this.title = data.title ?? null;
+    this.description = data.description ?? null;
+    this.owner = data.owner ?? null;
+    this.tags = data.tags ?? [];
+    this.conceptCount = data.concept_count ?? data.conceptCount ?? 0;
+    this.languages = data.languages ?? [];
+    this.createdAt = data.created_at ?? data.createdAt ?? null;
+    this.glossaristVersion = data.glossarist_version ?? data.glossaristVersion ?? null;
+    this.schemaVersion = data.schema_version ?? data.schemaVersion ?? '1';
+    this.homepage = data.homepage ?? null;
+    this.repository = data.repository ?? null;
+    this.license = data.license ?? null;
+    this.uriPrefix = data.uri_prefix ?? data.uriPrefix ?? null;
+    this.conceptUriTemplate = data.concept_uri_template ?? data.conceptUriTemplate ?? null;
+    this.compiledFormats = data.compiled_formats ?? data.compiledFormats ?? [];
+    this.statistics = data.statistics
+      ? (data.statistics instanceof GcrStatistics ? data.statistics : new GcrStatistics(data.statistics))
+      : null;
+  }
+
+  get concept_count() { return this.conceptCount; }
+  get created_at() { return this.createdAt; }
+  get glossarist_version() { return this.glossaristVersion; }
+  get schema_version() { return this.schemaVersion; }
+  get uri_prefix() { return this.uriPrefix; }
+  get concept_uri_template() { return this.conceptUriTemplate; }
+  get compiled_formats() { return this.compiledFormats; }
+
+  toJSON() {
+    const obj = {};
+    if (this.shortname != null) obj.shortname = this.shortname;
+    if (this.version != null) obj.version = this.version;
+    if (this.title != null) obj.title = this.title;
+    if (this.description != null) obj.description = this.description;
+    if (this.owner != null) obj.owner = this.owner;
+    if (this.tags.length > 0) obj.tags = this.tags;
+    if (this.conceptCount > 0) obj.concept_count = this.conceptCount;
+    if (this.languages.length > 0) obj.languages = this.languages;
+    if (this.createdAt != null) obj.created_at = this.createdAt;
+    if (this.glossaristVersion != null) obj.glossarist_version = this.glossaristVersion;
+    if (this.schemaVersion != null) obj.schema_version = this.schemaVersion;
+    if (this.homepage != null) obj.homepage = this.homepage;
+    if (this.repository != null) obj.repository = this.repository;
+    if (this.license != null) obj.license = this.license;
+    if (this.uriPrefix != null) obj.uri_prefix = this.uriPrefix;
+    if (this.conceptUriTemplate != null) obj.concept_uri_template = this.conceptUriTemplate;
+    if (this.compiledFormats.length > 0) obj.compiled_formats = this.compiledFormats;
+    if (this.statistics != null) obj.statistics = this.statistics.toJSON();
+    return obj;
+  }
+
+  static fromJSON(data) {
+    return new GcrMetadata(data);
+  }
+
+  static fromYaml(yamlString) {
+    return new GcrMetadata(yaml.load(yamlString));
+  }
+}

package/src/models/gcr-statistics.js

@@ -0,0 +1,51 @@
+import { GlossaristModel } from './base.js';
+
+export class GcrStatistics extends GlossaristModel {
+  constructor(data = {}) {
+    super();
+    this.totalConcepts = data.total_concepts ?? data.totalConcepts ?? 0;
+    this.conceptsWithDefinitions = data.concepts_with_definitions ?? data.conceptsWithDefinitions ?? 0;
+    this.conceptsByStatus = data.concepts_by_status ?? data.conceptsByStatus ?? {};
+  }
+
+  get total_concepts() { return this.totalConcepts; }
+  get concepts_with_definitions() { return this.conceptsWithDefinitions; }
+  get concepts_by_status() { return this.conceptsByStatus; }
+
+  toJSON() {
+    const obj = { total_concepts: this.totalConcepts };
+    if (this.conceptsWithDefinitions > 0) {
+      obj.concepts_with_definitions = this.conceptsWithDefinitions;
+    }
+    if (Object.keys(this.conceptsByStatus).length > 0) {
+      obj.concepts_by_status = this.conceptsByStatus;
+    }
+    return obj;
+  }
+
+  static fromJSON(data) {
+    return new GcrStatistics(data);
+  }
+
+  static fromConcepts(concepts) {
+    const langs = new Set();
+    let withDefs = 0;
+    const byStatus = {};
+
+    for (const concept of concepts) {
+      for (const lang of concept.languages) {
+        langs.add(lang);
+        const lc = concept.localization(lang);
+        if (lc && lc.definitions.length > 0) withDefs++;
+        const status = lc?.entryStatus ?? 'unknown';
+        byStatus[status] = (byStatus[status] ?? 0) + 1;
+      }
+    }
+
+    return new GcrStatistics({
+      total_concepts: concepts.length,
+      concepts_with_definitions: withDefs,
+      concepts_by_status: byStatus,
+    });
+  }
+}

package/src/models/index.d.ts

@@ -106,3 +106,42 @@ export class NonVerbRep extends GlossaristModel {
   readonly formula: string | null;
   readonly sources: Citation[];
 }
+
+export class GcrStatistics extends GlossaristModel {
+  readonly totalConcepts: number;
+  readonly conceptsWithDefinitions: number;
+  readonly conceptsByStatus: Record<string, number>;
+  readonly total_concepts: number;
+  readonly concepts_with_definitions: number;
+  readonly concepts_by_status: Record<string, number>;
+  static fromConcepts(concepts: Concept[]): GcrStatistics;
+  static fromJSON(data: Record<string, unknown>): GcrStatistics;
+}
+
+export class GcrMetadata extends GlossaristModel {
+  readonly shortname: string | null;
+  readonly version: string | null;
+  readonly title: string | null;
+  readonly description: string | null;
+  readonly owner: string | null;
+  readonly tags: string[];
+  readonly conceptCount: number;
+  readonly languages: string[];
+  readonly createdAt: string | null;
+  readonly glossaristVersion: string | null;
+  readonly schemaVersion: string;
+  readonly homepage: string | null;
+  readonly repository: string | null;
+  readonly license: string | null;
+  readonly uriPrefix: string | null;
+  readonly conceptUriTemplate: string | null;
+  readonly compiledFormats: string[];
+  readonly statistics: GcrStatistics | null;
+  readonly concept_count: number;
+  readonly created_at: string | null;
+  readonly glossarist_version: string | null;
+  readonly schema_version: string;
+  readonly compiled_formats: string[];
+  static fromYaml(yamlString: string): GcrMetadata;
+  static fromJSON(data: Record<string, unknown>): GcrMetadata;
+}

package/src/models/index.js

@@ -8,3 +8,5 @@ export { RelatedConcept, RELATIONSHIP_TYPES } from './related-concept.js';
 export { ConceptDate, DATE_TYPES } from './concept-date.js';
 export { DetailedDefinition } from './detailed-definition.js';
 export { NonVerbRep } from './non-verb-rep.js';
+export { GcrMetadata } from './gcr-metadata.js';
+export { GcrStatistics } from './gcr-statistics.js';;

package/src/sort.js

@@ -0,0 +1,25 @@
+const NATURAL_SORT_RE = /(\d+|\D+)/g;
+const DIGIT_RE = /^\d+$/;
+
+/**
+ * Natural sort comparator for concept IDs like "3.1.1.1", "551-12-39".
+ * @param {string} a
+ * @param {string} b
+ * @returns {number}
+ */
+export function naturalSort(a, b) {
+  const pa = a.match(NATURAL_SORT_RE) || [];
+  const pb = b.match(NATURAL_SORT_RE) || [];
+  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+    const na = pa[i] || '';
+    const nb = pb[i] || '';
+    if (DIGIT_RE.test(na) && DIGIT_RE.test(nb)) {
+      const diff = parseInt(na, 10) - parseInt(nb, 10);
+      if (diff !== 0) return diff;
+    } else {
+      const cmp = na.localeCompare(nb);
+      if (cmp !== 0) return cmp;
+    }
+  }
+  return 0;
+}