@glossarist/concept-browser 0.7.50 → 0.7.52

package/src/adapters/DatasetAdapter.ts

@@ -12,6 +12,12 @@ import type {
 import type { Concept } from 'glossarist';
 import { conceptFromJson } from './model-bridge';
 import { GraphDataSource } from './GraphDataSource';
+import {
+  ChunkLoadError,
+  ConceptNotFoundError,
+  IndexLoadError,
+  ManifestLoadError,
+} from '../errors';
 
 // ── Wire-format types for JSON responses ────────────────────────────────────
 
@@ -82,7 +88,7 @@ export class DatasetAdapter {
   async loadManifest(): Promise<Manifest> {
     if (this.manifestComplete && this.manifest) return this.manifest;
     const resp = await fetch(`${this.baseUrl}/manifest.json`);
-    if (!resp.ok) throw new Error(`Failed to load manifest for ${this.registerId}: ${resp.status}`);
+    if (!resp.ok) throw ManifestLoadError.make(this.registerId, resp.status);
     this.manifest = (await resp.json()) as Manifest;
     this.manifestComplete = true;
     return this.manifest;
@@ -97,7 +103,7 @@ 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}`);
+    if (!resp.ok) throw IndexLoadError.make(this.registerId, resp.status);
     const data = await resp.json();
 
     // Handle both old format (with eng/status fields) and new format (with designations map)
@@ -150,7 +156,7 @@ export class DatasetAdapter {
       meta = await metaResp.json();
     } else {
       const resp = await fetch(`${this.baseUrl}/index.json`);
-      if (!resp.ok) throw new Error(`Failed to load index for ${this.registerId}`);
+      if (!resp.ok) throw IndexLoadError.make(this.registerId, resp.status);
       const data = await resp.json();
       this.index = this.normalizeIndex(data as IndexJson);
       this.buildSummaryIndex();
@@ -180,7 +186,7 @@ export class DatasetAdapter {
     if (this.loadedChunks.has(chunkIndex)) return [];
     const chunkFile = `index-${String(chunkIndex).padStart(4, '0')}.json`;
     const resp = await fetch(`${this.baseUrl}/chunks/${chunkFile}`);
-    if (!resp.ok) throw new Error(`Failed to load chunk ${chunkIndex} for ${this.registerId}`);
+    if (!resp.ok) throw ChunkLoadError.make(this.registerId, chunkIndex, resp.status);
     const data = await resp.json();
     this.loadedChunks.add(chunkIndex);
     return data.concepts as ConceptEntry[];
@@ -255,7 +261,7 @@ export class DatasetAdapter {
     }
 
     const resp = await fetch(`${this.baseUrl}/concepts/${conceptId}.json`);
-    if (!resp.ok) throw new Error(`Concept ${conceptId} not found in ${this.registerId}`);
+    if (!resp.ok) throw ConceptNotFoundError.make(this.registerId, conceptId);
     const json = await resp.json();
     const concept = conceptFromJson(json);
     this.conceptCache.set(conceptId, concept);

package/src/adapters/GraphDataSource.ts

@@ -4,6 +4,7 @@ import type { DatasetAdapter } from './DatasetAdapter';
 import { UriRouter } from './UriRouter';
 import { slugify } from '../utils/slugify';
 import { toSectionNode, toSectionTree } from '../utils/section-tree';
+import { ConceptIdentity } from './concept-identity';
 
 interface DomainNodeJson {
   uri?: string;
@@ -23,7 +24,7 @@ function resolveRefTarget(rc: RelatedConcept, uriBase: string, registerId: strin
     if (ref.source && !ref.source.startsWith('http')) {
       reg = urnMap?.get(ref.source) ?? ref.source;
     }
-    return `${uriBase}/${reg}/concept/${ref.id}`;
+    return new ConceptIdentity(ref.id, reg, uriBase).uri;
   }
   if (ref.source && ref.source.startsWith('http')) return ref.source;
   return ref.source || '';

package/src/adapters/UriRouter.ts

@@ -1,4 +1,5 @@
 import type { Manifest } from './types';
+import { ConceptIdentity } from './concept-identity';
 
 // ── URI pattern matching ────────────────────────────────────────────────────
 
@@ -104,7 +105,7 @@ export class UriRouter {
   buildUri(registerId: string, conceptId: string): string {
     const info = this.registerMap.get(registerId);
     const uriBase = info?.uriBase ?? '';
-    return `${uriBase}/${registerId}/concept/${conceptId}`;
+    return new ConceptIdentity(conceptId, registerId, uriBase).uri;
   }
 
   getRegisteredIds(): string[] {

package/src/adapters/concept-identity.ts

@@ -0,0 +1,69 @@
+import { InvalidConceptIdentityError, InvalidConceptUriError } from '../errors';
+
+export interface ConceptIdentityParts {
+  readonly localId: string;
+  readonly registerId: string;
+  readonly uriBase: string;
+}
+
+const CONCEPT_URI_RE = /^(.+)\/([^/]+)\/concept\/(.+)$/;
+
+export class ConceptIdentity implements ConceptIdentityParts {
+  private readonly _uri: string;
+  private readonly _slug: string;
+  private readonly _path: string;
+
+  constructor(
+    public readonly localId: string,
+    public readonly registerId: string,
+    public readonly uriBase: string,
+  ) {
+    if (!localId || !registerId || !uriBase) {
+      throw new InvalidConceptIdentityError(
+        'ConceptIdentity requires non-empty localId, registerId, and uriBase',
+        { localId, registerId, uriBase },
+      );
+    }
+    this._uri = `${uriBase}/${registerId}/concept/${localId}`;
+    this._slug = localId;
+    this._path = `${registerId}/concepts/${localId}`;
+  }
+
+  get uri(): string { return this._uri; }
+  get slug(): string { return this._slug; }
+  get path(): string { return this._path; }
+
+  equals(other: ConceptIdentity): boolean {
+    return this._uri === other._uri;
+  }
+
+  toString(): string { return this._uri; }
+
+  toJSON(): ConceptIdentityParts {
+    return { localId: this.localId, registerId: this.registerId, uriBase: this.uriBase };
+  }
+
+  localizationUri(lang: string): string {
+    return `${this._uri}/${lang}`;
+  }
+
+  designationUri(lang: string, slug: string): string {
+    return `${this._uri}/${lang}/desig/${slug}`;
+  }
+
+  domainUri(domainSlug: string): string {
+    return `${this.uriBase}/${this.registerId}/domain/${domainSlug}`;
+  }
+
+  static fromUri(uri: string): ConceptIdentity {
+    const m = uri.match(CONCEPT_URI_RE);
+    if (!m) {
+      throw InvalidConceptUriError.make(uri);
+    }
+    return new ConceptIdentity(m[3], m[2], m[1]);
+  }
+
+  static isConceptUri(uri: string): boolean {
+    return CONCEPT_URI_RE.test(uri);
+  }
+}

package/src/adapters/factory.ts

@@ -5,6 +5,7 @@ import { ReferenceResolver } from './ReferenceResolver';
 import { UriRouter } from './UriRouter';
 import { NonVerbalEntityResolver } from './non-verbal-resolver';
 import { BibliographyAdapter } from './bibliography-adapter';
+import { DatasetRegistryLoadError, UnknownDatasetError } from '../errors';
 
 export class AdapterFactory {
   private adapters = new Map<string, DatasetAdapter>();
@@ -36,7 +37,7 @@ export class AdapterFactory {
       registry = JSON.parse(inline.textContent) as DatasetRegistry[];
     } else {
       const resp = await fetch(datasetsUrl);
-      if (!resp.ok) throw new Error(`Failed to load dataset registry: ${resp.status}`);
+      if (!resp.ok) throw DatasetRegistryLoadError.make(resp.status, datasetsUrl);
       registry = await resp.json() as DatasetRegistry[];
     }
 
@@ -132,7 +133,7 @@ export class AdapterFactory {
 
   async loadDataset(registerId: string): Promise<DatasetAdapter> {
     const adapter = this.adapters.get(registerId);
-    if (!adapter) throw new Error(`Unknown dataset: ${registerId}`);
+    if (!adapter) throw UnknownDatasetError.make(registerId);
 
     const manifest = await adapter.loadManifest();
     await adapter.loadIndex();

package/src/adapters/model-bridge.ts

@@ -36,6 +36,7 @@ import {
   GRAMMAR_PARTS_OF_SPEECH,
 } from 'glossarist/models';
 import type { ConceptSummary } from './types';
+import { ConceptIdentity } from './concept-identity';
 
 // ── JSON-LD wire-format types ─────────────────────────────────────────────
 
@@ -634,5 +635,5 @@ export function conceptToSummary(concept: Concept): ConceptSummary {
 
 export function conceptUri(concept: Concept, registerId: string, uriBase: string): string {
   if (concept.uri) return concept.uri;
-  return `${uriBase}/${registerId}/concept/${concept.id}`;
+  return new ConceptIdentity(concept.id, registerId, uriBase).uri;
 }

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

@@ -23,8 +23,8 @@
  * ambiguity with the HTML `<img alt>` attribute.
  */
 
-import type { Figure, FigureImage, FigureImageFormat, FigureImageRole } from './types';
-import { isType, pickField, pickFieldArray, pickFieldRecord, localized } from './prefix';
+import { Figure, FigureImage } from 'glossarist';
+import { isType, pickField, pickFieldArray, localized } from './prefix';
 import { sourcesFromJsonLd } from './source-bridge';
 
 const FORMAT_SET: ReadonlySet<string> = new Set(['svg', 'png', 'jpg', 'jpeg', 'gif', 'webp', 'avif']);
@@ -35,18 +35,20 @@ function imageFromJsonLd(raw: Record<string, unknown>): FigureImage | null {
   const src = pickField<string>(raw, 'src');
   if (!src) return null;
   const formatRaw = (pickField<string>(raw, 'format') ?? '').toLowerCase();
-  const format = (FORMAT_SET.has(formatRaw) ? formatRaw : 'svg') as FigureImageFormat;
+  const format = FORMAT_SET.has(formatRaw) ? formatRaw : 'svg';
   const roleRaw = pickField<string>(raw, 'role');
-  const role = roleRaw && ROLE_SET.has(roleRaw) ? (roleRaw as FigureImageRole) : undefined;
+  const role = roleRaw && ROLE_SET.has(roleRaw) ? roleRaw : undefined;
   const width = pickField<number>(raw, 'width');
   const height = pickField<number>(raw, 'height');
   const scale = pickField<number>(raw, 'scale');
-  const img: FigureImage = { src, format };
-  if (role) img.role = role;
-  if (typeof width === 'number') img.width = width;
-  if (typeof height === 'number') img.height = height;
-  if (typeof scale === 'number') img.scale = scale;
-  return img;
+  return new FigureImage({
+    src,
+    format,
+    ...(role !== undefined && { role }),
+    ...(typeof width === 'number' && { width }),
+    ...(typeof height === 'number' && { height }),
+    ...(typeof scale === 'number' && { scale }),
+  });
 }
 
 function imagesFromJsonLd(raw: unknown): FigureImage[] {
@@ -85,17 +87,14 @@ export function figureFromJsonLd(doc: Record<string, unknown>): Figure | null {
   const subfigures = subfiguresFromJsonLd(pickField(doc, 'subfigure'));
   const sources = sourcesFromJsonLd(pickField(doc, 'source'));
 
-  const fig: Figure = { kind: 'figure', id, images };
-  if (identifier) fig.identifier = identifier;
-  if (caption) fig.caption = caption;
-  if (alt) fig.alt = alt;
-  if (description) fig.description = description;
-  if (subfigures) fig.subfigures = subfigures;
-  if (sources.length) fig.sources = sources;
-
-  // pickFieldRecord is unused for figures; keep the import meaningful by
-  // ensuring no stray image fields leak through (silent no-op).
-  void pickFieldRecord;
-
-  return fig;
+  return new Figure({
+    id,
+    images,
+    ...(identifier && { identifier }),
+    ...(caption && { caption }),
+    ...(alt && { alt }),
+    ...(description && { description }),
+    ...(subfigures && { subfigures }),
+    ...(sources.length && { sources }),
+  });
 }

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

@@ -15,7 +15,7 @@
  *   }
  */
 
-import type { Formula, FormulaNotation } from './types';
+import { Formula } from 'glossarist';
 import { isType, pickField, localized } from './prefix';
 import { sourcesFromJsonLd } from './source-bridge';
 
@@ -31,18 +31,20 @@ export function formulaFromJsonLd(doc: Record<string, unknown>): Formula | null
   if (!expression) return null;
 
   const notationRaw = (pickField<string>(doc, 'notation') ?? '').toLowerCase();
-  const notation = NOTATION_SET.has(notationRaw) ? (notationRaw as FormulaNotation) : 'latex';
+  const notation = NOTATION_SET.has(notationRaw) ? notationRaw : 'latex';
 
   const identifier = pickField<string>(doc, 'identifier');
   const caption = localized(doc, 'caption');
   const description = localized(doc, 'description');
   const sources = sourcesFromJsonLd(pickField(doc, 'source'));
 
-  const f: Formula = { kind: 'formula', id, expression, notation };
-  if (identifier) f.identifier = identifier;
-  if (caption) f.caption = caption;
-  if (description) f.description = description;
-  if (sources.length) f.sources = sources;
-
-  return f;
+  return new Formula({
+    id,
+    expression,
+    notation,
+    ...(identifier && { identifier }),
+    ...(caption && { caption }),
+    ...(description && { description }),
+    ...(sources.length && { sources }),
+  });
 }

package/src/adapters/non-verbal/glossarist-augment.d.ts

@@ -0,0 +1,133 @@
+// Local module augmentation for glossarist 0.4.2.
+//
+// Upstream's published src/models/index.d.ts declares ZERO classes for the
+// non-verbal hierarchy (Figure, Table, Formula, FigureImage, NonVerbalEntity,
+// SharedNonVerbalEntity, NonVerbalReference + subclasses, BibliographyEntry,
+// BibliographyData) plus the localized-string helpers. The top-level
+// index.d.ts re-exports the names, so TypeScript silently resolves every
+// consumer import to `any`.
+//
+// This file declares the runtime shape so consumer code can be type-checked.
+// DELETE this file when upstream ships proper declarations — tracked by
+// PR glossarist/glossarist-js#31 (targets v0.4.3+).
+
+import type { ConceptSource, GlossaristModel } from 'glossarist';
+
+declare module 'glossarist' {
+  class RegistrableModel extends GlossaristModel {
+    static register(type: string, cls: typeof RegistrableModel): void;
+    static fromData(data: Record<string, unknown>): RegistrableModel;
+  }
+
+  class FigureImage extends GlossaristModel {
+    constructor(data?: {
+      src?: string | null;
+      format?: string | null;
+      role?: string | null;
+      width?: number | null;
+      height?: number | null;
+      scale?: number | null;
+    });
+    readonly src: string | null;
+    readonly format: string | null;
+    readonly role: string | null;
+    readonly width: number | null;
+    readonly height: number | null;
+    readonly scale: number | null;
+    static fromJSON(data: Record<string, unknown>): FigureImage;
+  }
+
+  class NonVerbalEntity extends RegistrableModel {
+    constructor(data?: Record<string, unknown>);
+    readonly caption: Record<string, string> | null;
+    readonly description: Record<string, string> | null;
+    readonly alt: Record<string, string> | null;
+    readonly sources: ConceptSource[];
+    findById(targetId: string): NonVerbalEntity | null;
+    allIds(): string[];
+    static fromJSON(data: Record<string, unknown>): NonVerbalEntity;
+  }
+
+  class SharedNonVerbalEntity extends NonVerbalEntity {
+    constructor(data?: Record<string, unknown>);
+    readonly id: string | null;
+    readonly identifier: string | null;
+    findById(targetId: string): SharedNonVerbalEntity | null;
+    allIds(): string[];
+    static fromJSON(data: Record<string, unknown>): SharedNonVerbalEntity;
+  }
+
+  class Figure extends SharedNonVerbalEntity {
+    constructor(data?: Record<string, unknown>);
+    readonly images: FigureImage[];
+    readonly subfigures: Figure[];
+    findById(targetId: string): Figure | null;
+    allIds(): string[];
+    static fromJSON(data: Record<string, unknown>): Figure;
+  }
+
+  class Table extends SharedNonVerbalEntity {
+    constructor(data?: Record<string, unknown>);
+    readonly content: Record<string, unknown> | null;
+    readonly format: string | null;
+    static fromJSON(data: Record<string, unknown>): Table;
+  }
+
+  class Formula extends SharedNonVerbalEntity {
+    constructor(data?: Record<string, unknown>);
+    readonly expression: Record<string, string> | null;
+    readonly notation: string | null;
+    static fromJSON(data: Record<string, unknown>): Formula;
+  }
+
+  const NON_VERBAL_TYPES: readonly string[];
+
+  class NonVerbalReference extends RegistrableModel {
+    constructor(data?: Record<string, unknown>);
+    readonly entityId: string | null;
+    readonly display: string | null;
+    readonly dedupKey: readonly [string, string | null];
+    static fromJSON(data: Record<string, unknown> | string): NonVerbalReference;
+    static register(type: string, cls: typeof NonVerbalReference): void;
+  }
+
+  interface NonVerbRep {
+    readonly caption: string | null;
+    readonly description: string | null;
+    readonly alt: string | null;
+    readonly images: FigureImage[];
+  }
+
+  class FigureReference extends NonVerbalReference {
+    static fromJSON(data: Record<string, unknown> | string): FigureReference;
+  }
+
+  class TableReference extends NonVerbalReference {
+    static fromJSON(data: Record<string, unknown> | string): TableReference;
+  }
+
+  class FormulaReference extends NonVerbalReference {
+    static fromJSON(data: Record<string, unknown> | string): FormulaReference;
+  }
+
+  class BibliographyEntry extends GlossaristModel {
+    constructor(data?: Record<string, unknown>);
+    readonly id: string | null;
+    readonly reference: string | null;
+    readonly title: string | null;
+    readonly link: string | null;
+    readonly type: string | null;
+    static fromJSON(data: Record<string, unknown>): BibliographyEntry;
+  }
+
+  class BibliographyData extends GlossaristModel {
+    constructor(data?: Record<string, unknown>);
+    readonly entries: BibliographyEntry[];
+    find(id: string): BibliographyEntry | null;
+    readonly keys: string[];
+    toYAML(): string;
+    toJSON(): { bibliography: BibliographyEntry[] };
+    static fromYAML(yamlString: string): BibliographyData;
+    static fromJSON(data: Record<string, unknown>): BibliographyData;
+  }
+}

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

@@ -1,33 +1,36 @@
 /**
  * Public API for the non-verbal entity model layer.
  *
- * Re-exports the types, bridges, and dispatch table. Components and
- * composables import from here — never from individual files — so the
- * internal layout can evolve without breaking the public surface.
+ * Model classes (Figure, Table, Formula, FigureImage, NonVerbalEntity) are
+ * re-exported from `glossarist` — upstream is the SSOT for the model.
+ * Consumer-owned types live in `./types`.
  */
 
 export type {
   LocalizedString,
   NonVerbalKind,
-  FigureImage,
   FigureImageFormat,
   FigureImageRole,
   NonVerbalSource,
   NonVerbalSourceOrigin,
   NonVerbalSourceRef,
   NonVerbalSourceLocality,
-  NonVerbalEntityBase,
-  Figure,
-  Table,
   TableContent,
   TableFormat,
-  Formula,
   FormulaNotation,
-  NonVerbalEntity,
   NonVerbRepV3,
   NonVerbalReference,
 } from './types';
 
+export type {
+  Figure,
+  FigureImage,
+  Table,
+  Formula,
+  NonVerbalEntity,
+  SharedNonVerbalEntity,
+} from 'glossarist';
+
 export { figureFromJsonLd } from './figure-bridge';
 export { tableFromJsonLd } from './table-bridge';
 export { formulaFromJsonLd } from './formula-bridge';

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

@@ -1,4 +1,5 @@
-import type { NonVerbalEntity, NonVerbalKind } from './types';
+import type { NonVerbalKind } from './types';
+import type { NonVerbalEntity } from 'glossarist';
 import {
   ENTITY_DIRECTORIES,
   ENTITY_TYPES,

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

@@ -20,7 +20,8 @@
  *   }
  */
 
-import type { Table, TableContent, TableFormat } from './types';
+import { Table } from 'glossarist';
+import type { TableContent } from './types';
 import { isType, pickField, localized } from './prefix';
 import { sourcesFromJsonLd } from './source-bridge';
 
@@ -83,16 +84,17 @@ export function tableFromJsonLd(doc: Record<string, unknown>): Table | null {
   if (!content) return null;
 
   const formatRaw = (pickField<string>(doc, 'format') ?? '').toLowerCase();
-  const format = FORMAT_SET.has(formatRaw) ? (formatRaw as TableFormat) : undefined;
+  const format = FORMAT_SET.has(formatRaw) ? formatRaw : undefined;
 
   const sources = sourcesFromJsonLd(pickField(doc, 'source'));
 
-  const t: Table = { kind: 'table', id, content };
-  if (identifier) t.identifier = identifier;
-  if (caption) t.caption = caption;
-  if (description) t.description = description;
-  if (format) t.format = format;
-  if (sources.length) t.sources = sources;
-
-  return t;
+  return new Table({
+    id,
+    content: content as Record<string, unknown>,
+    ...(identifier && { identifier }),
+    ...(caption && { caption }),
+    ...(description && { description }),
+    ...(format && { format }),
+    ...(sources.length && { sources }),
+  });
 }

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

@@ -1,18 +1,23 @@
 /**
- * Non-verbal entity model — TypeScript projection of the authoritative
- * glossarist-ruby model.
+ * Consumer-side types for non-verbal entities.
  *
- * The authoritative model lives in glossarist-ruby (Figure, Table, Formula
- * inherit from NonVerbalEntity). This file mirrors that model in TypeScript
- * for the consumer side. It does not redefine the model — every field here
- * corresponds to a field in the authoritative source.
+ * Model classes (Figure, Table, Formula, FigureImage, NonVerbalEntity) are
+ * imported from `glossarist` — the upstream library is the SSOT for the
+ * model. This file holds only what is genuinely consumer-owned:
  *
- * See:
- *   ../glossarist-ruby/lib/glossarist/non_verbal_entity.rb
- *   ../glossarist-ruby/lib/glossarist/figure.rb
- *   ../glossarist-ruby/lib/glossarist/table.rb
- *   ../glossarist-ruby/lib/glossarist/formula.rb
- *   ../glossarist-ruby/lib/glossarist/figure_image.rb
+ *   - `NonVerbalKind`: routing discriminator used by the resolver, the
+ *     anchor scheme, the mention dispatcher, and the section router.
+ *   - `NonVerbRepV3`: local view of NonVerbRep's V3 shape. Upstream's
+ *     published .d.ts still describes the pre-V3 `ref`/`text` shape; this
+ *     interface lets the consumer type-check against runtime reality.
+ *     Delete when upstream ships a corrected declaration.
+ *   - `NonVerbalReference`: consumer-side view of inline mentions like
+ *     `{{fig:foo}}`. Carries a `kind` for UI routing.
+ *   - `LocalizedString`, `FigureImageFormat`, `FigureImageRole`,
+ *     `TableFormat`, `TableContent`, `FormulaNotation`: string-union
+ *     refinements the consumer validates at bridge time.
+ *   - `NonVerbalSource*`: wire shape for JSON-LD source entries. Stays
+ *     consumer-side until upstream ships a V3 NonVerbalSource model.
  */
 
 export type LocalizedString = Record<string, string>;
@@ -23,15 +28,6 @@ export type FigureImageFormat = 'svg' | 'png' | 'jpg' | 'jpeg' | 'gif' | 'webp'
 
 export type FigureImageRole = 'vector' | 'raster' | 'dark' | 'light' | 'print';
 
-export interface FigureImage {
-  src: string;
-  format: FigureImageFormat;
-  role?: FigureImageRole;
-  width?: number;
-  height?: number;
-  scale?: number;
-}
-
 export interface NonVerbalSourceRef {
   source?: string;
   id?: string;
@@ -62,56 +58,42 @@ export interface NonVerbalSource {
   origin?: NonVerbalSourceOrigin;
 }
 
-export interface NonVerbalEntityBase {
-  id: string;
-  identifier?: string;
-  caption?: LocalizedString;
-  description?: LocalizedString;
-  alt?: LocalizedString;
-  sources?: NonVerbalSource[];
-}
-
-export interface Figure extends NonVerbalEntityBase {
-  kind: 'figure';
-  images: FigureImage[];
-  subfigures?: Figure[];
-}
-
 export type TableFormat = 'html' | 'markdown' | 'asciidoc';
 
 export type TableContent =
   | { kind: 'structured'; headers: LocalizedString[]; rows: LocalizedString[][] }
   | { kind: 'markup'; markup: LocalizedString };
 
-export interface Table extends NonVerbalEntityBase {
-  kind: 'table';
-  content: TableContent;
-  format?: TableFormat;
-}
-
 export type FormulaNotation = 'latex' | 'mathml' | 'asciimath';
 
-export interface Formula extends NonVerbalEntityBase {
-  kind: 'formula';
-  expression: LocalizedString;
-  notation: FormulaNotation;
-}
-
-export type NonVerbalEntity = Figure | Table | Formula;
-
 /**
  * V3 NonVerbRep runtime shape.
  *
  * glossarist-js's runtime `NonVerbRep` (post-V3 reshape) holds the same
- * localized fields as `NonVerbalEntityBase` plus a `type` discriminator
+ * localized fields as the base NonVerbalEntity plus a `type` discriminator
  * and an `images[]` array. The published `.d.ts` (still stale at v0.4.2)
  * describes the pre-V3 `ref`/`text` shape; this local interface lets
  * consumer code type-check against reality. Drop when upstream ships a
- * corrected `.d.ts`.
+ * corrected `.d.ts` (glossarist/glossarist-js#31).
  */
-export interface NonVerbRepV3 extends NonVerbalEntityBase {
+export interface NonVerbRepV3 {
+  id: string;
+  identifier?: string | null;
   type: string | null;
-  images: FigureImage[];
+  caption?: LocalizedString | null;
+  description?: LocalizedString | null;
+  alt?: LocalizedString | null;
+  images: NonVerbRepImage[];
+  sources?: NonVerbalSource[];
+}
+
+export interface NonVerbRepImage {
+  src: string;
+  format?: string | null;
+  role?: string | null;
+  width?: number | null;
+  height?: number | null;
+  scale?: number | null;
 }
 
 export interface NonVerbalReference {