@glossarist/concept-browser 0.7.48 → 0.7.51

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glossarist/concept-browser",
-  "version": "0.7.48",
+  "version": "0.7.51",
   "description": "Vue SPA for browsing Glossarist terminology datasets with cross-reference resolution, graph visualization, and multi-language support",
   "type": "module",
   "bin": {

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,126 @@
+// 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;
+  }
+
+  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,34 +1,35 @@
 /**
  * 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 { isFigure, isTable, isFormula } from './types';
+export type {
+  Figure,
+  FigureImage,
+  Table,
+  Formula,
+  NonVerbalEntity,
+  SharedNonVerbalEntity,
+} from 'glossarist';
 
 export { figureFromJsonLd } from './figure-bridge';
 export { tableFromJsonLd } from './table-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
- * and an `images[]` array. The published `.d.ts` still describes the
- * pre-V3 `ref`/`text` shape; this local interface lets consumer code
- * type-check against reality. Remove when upstream ships a corrected
- * `.d.ts` (TODO.figures/19).
+ * 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` (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 {
@@ -119,15 +101,3 @@ export interface NonVerbalReference {
   entityId: string;
   display?: string;
 }
-
-export function isFigure(entity: NonVerbalEntity): entity is Figure {
-  return entity.kind === 'figure';
-}
-
-export function isTable(entity: NonVerbalEntity): entity is Table {
-  return entity.kind === 'table';
-}
-
-export function isFormula(entity: NonVerbalEntity): entity is Formula {
-  return entity.kind === 'formula';
-}

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

@@ -15,11 +15,13 @@
  * exactly one instance per app.
  */
 
-import type { NonVerbalEntity, NonVerbalKind } from './non-verbal/types';
+import type { NonVerbalKind } from './non-verbal/types';
+import type { NonVerbalEntity } from 'glossarist';
 import { KIND_TO_DIR, KIND_TO_BRIDGE } from './non-verbal/kind';
 import { anchorId } from '../utils/non-verbal-anchor';
 
-export type { NonVerbalEntity, NonVerbalKind } from './non-verbal/types';
+export type { NonVerbalKind } from './non-verbal/types';
+export type { NonVerbalEntity } from 'glossarist';
 
 export interface NonVerbalEntityResolverOptions {
   basePath?: string;

package/src/components/NonVerbalRepDisplay.vue

@@ -1,7 +1,7 @@
 <script setup lang="ts">
 import { computed } from 'vue';
 import type { NonVerbRep, Citation } from 'glossarist';
-import type { FigureImage, LocalizedString, NonVerbRepV3, NonVerbalSource } from '../adapters/non-verbal/types';
+import type { LocalizedString, NonVerbRepV3, NonVerbRepImage, NonVerbalSource } from '../adapters/non-verbal/types';
 import { resolveFallbackChain } from '../utils/locale';
 import FigureImages from './figure/FigureImages.vue';
 import NonVerbalCaption from './non-verbal/NonVerbalCaption.vue';
@@ -21,7 +21,7 @@ const fallbackChain = computed(() => resolveFallbackChain(props.datasetLocales))
 // (images/alt/caption/description/sources). See TODO.figures/19.
 const v3Reps = computed<NonVerbRepV3[]>(() => props.reps as unknown as NonVerbRepV3[]);
 
-function imagesOf(rep: NonVerbRepV3): FigureImage[] {
+function imagesOf(rep: NonVerbRepV3): NonVerbRepImage[] {
   return rep.images ?? [];
 }
 

package/src/components/figure/FigureDisplay.vue

@@ -10,7 +10,7 @@
  * so `{{fig:id}}` mentions can scroll to it via the cross-ref composable.
  */
 import { computed, ref } from 'vue';
-import type { Figure } from '../../adapters/non-verbal/types';
+import type { Figure } from 'glossarist';
 import { useNonVerbalEntity } from '../../composables/use-non-verbal-entity';
 import { resolveFallbackChain } from '../../utils/locale';
 import { anchorId } from '../../utils/non-verbal-anchor';
@@ -34,39 +34,40 @@ const id = () => props.entityId;
 const { entity, state, error } = useNonVerbalEntity(k, ds, id);
 
 const fallbackChain = computed(() => resolveFallbackChain(props.datasetLocales));
-const layout = computed(() => entity.value ? deriveLayout(entity.value as Figure) : 'single');
+const fig = computed(() => entity.value as Figure | null);
+const layout = computed(() => fig.value ? deriveLayout(fig.value) : 'single');
 const anchor = computed(() => anchorId('figure', props.datasetId, props.entityId));
 const descriptionId = computed(() => `${anchor.value}-desc`);
 
-const topLevelImages = computed(() => (entity.value as Figure | null)?.images ?? []);
+const topLevelImages = computed(() => fig.value?.images ?? []);
 </script>
 
 <template>
   <figure
-    v-if="entity && state === 'loaded'"
+    v-if="fig && state === 'loaded'"
     :id="anchor"
     :class="`figure figure--${layout}`"
   >
     <div v-if="topLevelImages.length" :class="`figure__media figure__media--${layout}`">
       <FigureImages
         :images="topLevelImages"
-        :alt="(entity as Figure).alt"
+        :alt="fig.alt"
         :dataset-id="datasetId"
         :locale="locale"
         :fallback-chain="fallbackChain"
-        :hasDescription="!!(entity as Figure).description && Object.keys((entity as Figure).description ?? {}).length > 0"
+        :hasDescription="!!fig.description && Object.keys(fig.description ?? {}).length > 0"
         :description-id="descriptionId"
         entity-label="Figure"
       />
     </div>
 
-    <template v-if="(entity as Figure).subfigures?.length">
+    <template v-if="fig.subfigures?.length">
       <div :class="`figure__subfigures figure__subfigures--${layout}`">
         <FigureDisplay
-          v-for="sub in (entity as Figure).subfigures"
-          :key="sub.id"
+          v-for="sub in fig.subfigures"
+          :key="sub.id ?? ''"
           :dataset-id="datasetId"
-          :entity-id="sub.id"
+          :entity-id="sub.id ?? ''"
           :locale="locale"
           :dataset-locales="datasetLocales"
         />
@@ -74,17 +75,17 @@ const topLevelImages = computed(() => (entity.value as Figure | null)?.images ??
     </template>
 
     <NonVerbalCaption
-      :identifier="(entity as Figure).identifier"
-      :caption="(entity as Figure).caption"
-      :description="(entity as Figure).description"
+      :identifier="fig.identifier"
+      :caption="fig.caption"
+      :description="fig.description"
       :locale="locale"
       :fallback-chain="fallbackChain"
       :description-id="descriptionId"
     />
 
     <NonVerbalSources
-      v-if="(entity as Figure).sources?.length"
-      :sources="(entity as Figure).sources!"
+      v-if="fig.sources?.length"
+      :sources="fig.sources"
     />
   </figure>
 

package/src/components/figure/FigureImages.vue

@@ -1,12 +1,15 @@
 <script setup lang="ts">
 import { computed } from 'vue';
-import type { FigureImage, LocalizedString } from '../../adapters/non-verbal/types';
+import type { FigureImage } from 'glossarist';
+import type { LocalizedString, NonVerbRepImage } from '../../adapters/non-verbal/types';
 import { pickLocaleText, hasLocale } from '../../utils/locale';
 import { getFactory } from '../../adapters/factory';
 
+type ImageLike = FigureImage | NonVerbRepImage;
+
 const props = withDefaults(defineProps<{
-  images: FigureImage[];
-  alt?: LocalizedString;
+  images: ImageLike[];
+  alt?: LocalizedString | null;
   datasetId: string;
   locale: string;
   fallbackChain?: readonly string[];
@@ -19,7 +22,19 @@ const props = withDefaults(defineProps<{
 
 const resolver = getFactory().nonVerbalResolver;
 
-const altText = computed(() => pickLocaleText(props.alt, props.locale, props.fallbackChain));
+function imgSrc(img: ImageLike): string {
+  return typeof img.src === 'string' ? img.src : '';
+}
+function imgFormat(img: ImageLike): string {
+  const f = img.format;
+  return typeof f === 'string' ? f : 'svg';
+}
+function imgRole(img: ImageLike): string | null {
+  const r = img.role;
+  return typeof r === 'string' ? r : null;
+}
+
+const altText = computed(() => pickLocaleText(props.alt ?? undefined, props.locale, props.fallbackChain));
 const altMissing = computed(() => !props.alt || Object.keys(props.alt).length === 0);
 const altEmpty = computed(() =>
   !!props.alt && hasLocale(props.alt, props.locale) && props.alt[props.locale] === '',
@@ -30,26 +45,33 @@ interface SourceVariant { src: string; type: string; media?: string; }
 const sourceVariants = computed<SourceVariant[]>(() => {
   const out: SourceVariant[] = [];
   for (const img of props.images) {
-    if (!img.role || img.role === 'vector' || img.role === 'raster') continue;
-    const src = resolver.resolveImageUrl(props.datasetId, img.src);
-    const type = img.format === 'svg' ? 'image/svg+xml' : `image/${img.format === 'jpg' ? 'jpeg' : img.format}`;
+    const role = imgRole(img);
+    if (!role || role === 'vector' || role === 'raster') continue;
+    const src = imgSrc(img);
+    const format = imgFormat(img);
+    if (!src) continue;
+    const type = format === 'svg' ? 'image/svg+xml' : `image/${format === 'jpg' ? 'jpeg' : format}`;
     let media: string | undefined;
-    if (img.role === 'dark') media = '(prefers-color-scheme: dark)';
-    else if (img.role === 'light') media = '(prefers-color-scheme: light)';
-    else if (img.role === 'print') media = 'print';
-    out.push({ src, type, media });
+    if (role === 'dark') media = '(prefers-color-scheme: dark)';
+    else if (role === 'light') media = '(prefers-color-scheme: light)';
+    else if (role === 'print') media = 'print';
+    out.push({ src: resolver.resolveImageUrl(props.datasetId, src), type, media });
   }
   return out;
 });
 
 const defaultImg = computed(() => {
-  const nonRole = props.images.find(i => !i.role || i.role === 'vector' || i.role === 'raster');
+  const nonRole = props.images.find(i => {
+    const r = imgRole(i);
+    return !r || r === 'vector' || r === 'raster';
+  });
   const chosen = nonRole ?? props.images[0];
-  if (!chosen) return null;
+  const src = chosen ? imgSrc(chosen) : '';
+  if (!src) return null;
   return {
-    src: resolver.resolveImageUrl(props.datasetId, chosen.src),
-    width: chosen.width,
-    height: chosen.height,
+    src: resolver.resolveImageUrl(props.datasetId, src),
+    width: chosen?.width ?? undefined,
+    height: chosen?.height ?? undefined,
   };
 });
 </script>

package/src/components/figure/figure-image-pick.ts

@@ -11,7 +11,7 @@
  * The `print` role is reserved for print stylesheets (selected via CSS
  * @media print in FigureImages.vue), not picked here.
  */
-import type { FigureImage } from '../../adapters/non-verbal/types';
+import type { FigureImage } from 'glossarist';
 
 export interface PickOptions {
   prefersDark?: boolean;

package/src/components/figure/figure-layout.ts

@@ -12,7 +12,7 @@
  * Authors who want different behavior can split a composite figure into
  * multiple top-level figures. V1 does not expose a `layout` field.
  */
-import type { Figure } from '../../adapters/non-verbal/types';
+import type { Figure } from 'glossarist';
 
 export type FigureLayout = 'single' | 'row' | 'column' | 'grid';
 

package/src/components/formula/FormulaDisplay.vue

@@ -7,7 +7,8 @@
  * `<figure>` receives the anchor ID for `{{formula:id}}` mentions.
  */
 import { computed } from 'vue';
-import type { Formula } from '../../adapters/non-verbal/types';
+import type { Formula } from 'glossarist';
+import type { FormulaNotation } from '../../adapters/non-verbal/types';
 import { useNonVerbalEntity } from '../../composables/use-non-verbal-entity';
 import { resolveFallbackChain } from '../../utils/locale';
 import { anchorId } from '../../utils/non-verbal-anchor';
@@ -27,37 +28,38 @@ const k = () => 'formula' as const;
 const { entity, state, error } = useNonVerbalEntity(k, () => props.datasetId, () => props.entityId);
 
 const fallbackChain = computed(() => resolveFallbackChain(props.datasetLocales));
+const form = computed(() => entity.value as Formula | null);
 const anchor = computed(() => anchorId('formula', props.datasetId, props.entityId));
 const descriptionId = computed(() => `${anchor.value}-desc`);
 </script>
 
 <template>
   <figure
-    v-if="entity && state === 'loaded'"
+    v-if="form && state === 'loaded'"
     :id="anchor"
     class="formula-entity"
   >
     <div class="formula__expr-line">
       <FormulaExpression
-        :expression="(entity as Formula).expression"
-        :notation="(entity as Formula).notation"
+        :expression="form.expression"
+        :notation="(form.notation as FormulaNotation | null)"
         :locale="locale"
         :fallback-chain="fallbackChain"
       />
     </div>
 
     <NonVerbalCaption
-      :identifier="(entity as Formula).identifier"
-      :caption="(entity as Formula).caption"
-      :description="(entity as Formula).description"
+      :identifier="form.identifier"
+      :caption="form.caption"
+      :description="form.description"
       :locale="locale"
       :fallback-chain="fallbackChain"
       :description-id="descriptionId"
     />
 
     <NonVerbalSources
-      v-if="(entity as Formula).sources?.length"
-      :sources="(entity as Formula).sources!"
+      v-if="form.sources?.length"
+      :sources="form.sources"
     />
   </figure>
 

package/src/components/formula/FormulaExpression.vue

@@ -16,13 +16,13 @@ import { pickLocaleMap, localeToBcp47 } from '../../utils/locale';
 import { loadPlurimath } from '../../utils/plurimath';
 
 const props = defineProps<{
-  expression: LocalizedString;
-  notation: FormulaNotation;
+  expression: LocalizedString | null;
+  notation: FormulaNotation | null;
   locale: string;
   fallbackChain?: readonly string[];
 }>();
 
-const resolved = computed(() => pickLocaleMap(props.expression, props.locale, props.fallbackChain));
+const resolved = computed(() => pickLocaleMap(props.expression ?? undefined, props.locale, props.fallbackChain));
 const html = ref<string>('');
 const lang = computed(() => resolved.value ? localeToBcp47(resolved.value.locale) : undefined);
 
@@ -34,7 +34,7 @@ const PLURIMATH_FORMAT: Record<FormulaNotation, string> = {
 
 async function render() {
   const r = resolved.value;
-  if (!r) { html.value = ''; return; }
+  if (!r || !props.notation) { html.value = ''; return; }
   try {
     const Plurimath = await loadPlurimath();
     const p = new Plurimath(r.text, PLURIMATH_FORMAT[props.notation]);

package/src/components/non-verbal/NonVerbalCaption.vue

@@ -22,20 +22,20 @@ import type { LocalizedString } from '../../adapters/non-verbal/types';
 import { pickLocaleMap, localeToBcp47 } from '../../utils/locale';
 
 const props = defineProps<{
-  identifier?: string;
-  caption?: LocalizedString;
-  description?: LocalizedString;
+  identifier?: string | null;
+  caption?: LocalizedString | null;
+  description?: LocalizedString | null;
   locale: string;
   fallbackChain?: readonly string[];
   descriptionId?: string;
 }>();
 
 const captionResolved = computed(() =>
-  pickLocaleMap(props.caption, props.locale, props.fallbackChain),
+  pickLocaleMap(props.caption ?? undefined, props.locale, props.fallbackChain),
 );
 
 const descriptionResolved = computed(() =>
-  pickLocaleMap(props.description, props.locale, props.fallbackChain),
+  pickLocaleMap(props.description ?? undefined, props.locale, props.fallbackChain),
 );
 
 const captionLang = computed(() =>

package/src/components/non-verbal/NonVerbalSources.vue

@@ -6,20 +6,12 @@
  * so the rendering matches the rest of the app. Each source may carry a
  * modification note (e.g. "Adapted.") which is rendered alongside.
  */
-import type { Citation } from 'glossarist';
-import type { NonVerbalSource } from '../../adapters/non-verbal/types';
+import type { ConceptSource } from 'glossarist';
 import CitationDisplay from '../CitationDisplay.vue';
 
 defineProps<{
-  sources: NonVerbalSource[];
+  sources: ConceptSource[];
 }>();
-
-// CitationDisplay expects glossarist's Citation class. NonVerbalSource.origin
-// is wire-compatible at runtime but typed differently on the consumer side;
-// cast once at this boundary.
-function asCitation(origin: NonVerbalSource['origin']): Citation | null {
-  return (origin as unknown as Citation) ?? null;
-}
 </script>
 
 <template>
@@ -27,7 +19,7 @@ function asCitation(origin: NonVerbalSource['origin']): Citation | null {
     <div class="nv-sources__label">Sources</div>
     <ol class="nv-sources__list">
       <li v-for="(src, i) in sources" :key="i" class="nv-source">
-        <CitationDisplay v-if="asCitation(src.origin)" :citation="asCitation(src.origin)!" />
+        <CitationDisplay v-if="src.origin" :citation="src.origin" />
         <span v-if="src.modification" class="nv-source__modification">
           — {{ src.modification }}
         </span>

package/src/components/table/TableDisplay.vue

@@ -6,7 +6,8 @@
  * TableMarkup (HTML / Markdown / AsciiDoc) based on `content.kind`.
  */
 import { computed } from 'vue';
-import type { Table } from '../../adapters/non-verbal/types';
+import type { Table } from 'glossarist';
+import type { TableContent, TableFormat } from '../../adapters/non-verbal/types';
 import { useNonVerbalEntity } from '../../composables/use-non-verbal-entity';
 import { resolveFallbackChain } from '../../utils/locale';
 import { anchorId } from '../../utils/non-verbal-anchor';
@@ -31,12 +32,13 @@ const anchor = computed(() => anchorId('table', props.datasetId, props.entityId)
 const descriptionId = computed(() => `${anchor.value}-desc`);
 
 const table = computed<Table | null>(() => entity.value as Table | null);
+const content = computed<TableContent | null>(() => (table.value?.content ?? null) as TableContent | null);
 const structuredContent = computed(() => {
-  const c = table.value?.content;
+  const c = content.value;
   return c && c.kind === 'structured' ? c : null;
 });
 const markup = computed(() => {
-  const c = table.value?.content;
+  const c = content.value;
   return c && c.kind === 'markup' ? c.markup : null;
 });
 </script>
@@ -56,7 +58,7 @@ const markup = computed(() => {
     <TableMarkup
       v-else-if="markup"
       :content="markup"
-      :format="table.format"
+      :format="(table.format as TableFormat | null)"
       :locale="locale"
       :fallback-chain="fallbackChain"
     />

package/src/components/table/TableMarkup.vue

@@ -18,7 +18,7 @@ import { renderAsciiDocLite } from '../../utils/asciidoc-lite';
 
 const props = defineProps<{
   content: LocalizedString;
-  format?: TableFormat;
+  format?: TableFormat | null;
   locale: string;
   fallbackChain?: readonly string[];
 }>();

package/src/composables/use-non-verbal-entity.ts

@@ -8,7 +8,8 @@
  */
 import { ref, watch, shallowRef } from 'vue';
 import { getFactory } from '../adapters/factory';
-import type { NonVerbalEntity, NonVerbalKind } from '../adapters/non-verbal/types';
+import type { NonVerbalKind } from '../adapters/non-verbal/types';
+import type { NonVerbalEntity } from 'glossarist';
 
 export type LoadState = 'loading' | 'loaded' | 'not-found' | 'error';