@glossarist/concept-browser 0.7.44 → 0.7.45

package/src/composables/use-render-options.ts

@@ -1,55 +1,52 @@
-import { ref, watch } from 'vue';
-import type { RenderOptions, BibResolver, FigResolver } from '../utils/content-renderer';
+import { ref } from 'vue';
+import type { RenderOptions, BibResolver, NonVerbalRefResolver } from '../utils/content-renderer';
+import type { NonVerbalKind } from '../adapters/non-verbal/types';
 import { getFactory } from '../adapters/factory';
+import { anchorId } from '../utils/non-verbal-anchor';
 import { escapeAttr } from '../utils/escape';
 
-interface BibEntry {
-  reference: string;
-  title?: string;
-  link?: string;
-}
-
-const bibCache = new Map<string, Record<string, BibEntry>>();
-
-async function loadBibliography(registerId: string): Promise<Record<string, BibEntry> | null> {
-  if (bibCache.has(registerId)) return bibCache.get(registerId)!;
-  try {
-    const resp = await fetch(`${import.meta.env.BASE_URL}data/${registerId}/bibliography.json`);
-    if (!resp.ok) return null;
-    const data = await resp.json();
-    bibCache.set(registerId, data);
-    return data;
-  } catch {
-    return null;
-  }
-}
-
 export function useRenderOptions(registerId: () => string) {
-  const bibData = ref<Record<string, BibEntry> | null>(null);
+  const ready = ref(false);
 
   async function ensureBibLoaded() {
     const id = registerId();
     if (!id) return;
-    bibData.value = await loadBibliography(id);
+    await getFactory().bibliography(id).load();
+    ready.value = true;
   }
 
   const bibResolver: BibResolver = (refId, title) => {
-    const entry = bibData.value?.[refId];
+    const id = registerId();
+    const entry = id ? getFactory().bibliography(id).findById(refId) : null;
     if (!entry) {
       return `<span class="bib-ref">${escapeAttr(title)}</span>`;
     }
-    const display = title || entry.reference;
+    const display = title || entry.reference || refId;
     if (entry.link) {
-      return `<a href="${escapeAttr(entry.link)}" target="_blank" rel="noopener" class="bib-link" title="${escapeAttr(entry.title || '')}">${escapeAttr(display)}</a>`;
+      return `<a href="${escapeAttr(entry.link)}" target="_blank" rel="noopener" class="bib-link" title="${escapeAttr(entry.title ?? '')}">${escapeAttr(display)}</a>`;
     }
-    return `<span class="bib-ref" title="${escapeAttr(entry.title || '')}">${escapeAttr(display)}</span>`;
+    return `<span class="bib-ref" title="${escapeAttr(entry.title ?? '')}">${escapeAttr(display)}</span>`;
   };
 
-  const figResolver: FigResolver = (figId) => {
+  const nonVerbalRefResolver: NonVerbalRefResolver = (kind: NonVerbalKind, entityId, display) => {
     const id = registerId();
-    const imgSrc = `${import.meta.env.BASE_URL}data/${id}/images/${figId}.png`;
-    return `<span class="fig-ref"><a href="${escapeAttr(imgSrc)}" target="_blank" rel="noopener">${escapeAttr(figId)}</a></span>`;
+    if (!id) {
+      const label = display ?? entityId;
+      return `<span class="nv-ref nv-ref--${kind}">${escapeAttr(label)}</span>`;
+    }
+    const href = `#${anchorId(kind, id, entityId)}`;
+    const label = display ?? defaultLabelForKind(kind, entityId);
+    const cls = `nv-ref nv-ref--${kind}`;
+    return `<a href="${href}" class="${cls}" data-nv-kind="${escapeAttr(kind)}" data-nv-dataset="${escapeAttr(id)}" data-nv-entity="${escapeAttr(entityId)}">${escapeAttr(label)}</a>`;
   };
 
-  return { bibData, ensureBibLoaded, bibResolver, figResolver };
+  return { ready, ensureBibLoaded, bibResolver, nonVerbalRefResolver };
+}
+
+function defaultLabelForKind(kind: NonVerbalKind, entityId: string): string {
+  switch (kind) {
+    case 'figure': return `Figure ${entityId}`;
+    case 'table': return `Table ${entityId}`;
+    case 'formula': return `Formula ${entityId}`;
+  }
 }

package/src/router/index.ts

@@ -1,4 +1,5 @@
 import { createRouter, createWebHistory, type RouteRecordRaw } from 'vue-router';
+import { installNonVerbalScroll } from './non-verbal-scroll-guard';
 
 export const routes: RouteRecordRaw[] = [
   {
@@ -109,4 +110,6 @@ const router = createRouter({
   routes,
 });
 
+installNonVerbalScroll(router);
+
 export default router;

package/src/router/non-verbal-scroll-guard.ts

@@ -0,0 +1,56 @@
+/**
+ * installNonVerbalScroll — router hook that turns entity-hash deep-links
+ * (`/concept/X#figure-{ds}-{id}`) into scroll + highlight on arrival.
+ *
+ * Why polling instead of an event? Entity components fetch their
+ * JSON-LD asynchronously via the resolver; the target `<figure>` does
+ * not exist in the DOM until that fetch resolves. Polling for up to
+ * `timeoutMs` covers the slow-network worst case without coupling the
+ * router to the resolver.
+ *
+ * The anchor id format is owned by `utils/non-verbal-anchor.ts`; this
+ * guard only matches the hash prefix and hands off to the same
+ * highlight utility used by click-driven navigation, so the user sees
+ * identical behavior whether they arrived by click or by URL.
+ */
+import type { Router } from 'vue-router';
+import { highlightEntity, scrollToEntity } from '../utils/non-verbal-highlight';
+
+const DEFAULT_TIMEOUT_MS = 5000;
+const POLL_INTERVAL_MS = 50;
+
+const ENTITY_HASH_RE = /^#(?:figure|table|formula)-/;
+
+export function installNonVerbalScroll(
+  router: Router,
+  options: { timeoutMs?: number } = {},
+): void {
+  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+
+  router.afterEach((to) => {
+    if (!to.hash || !ENTITY_HASH_RE.test(to.hash)) return;
+    const anchorId = to.hash.slice(1);
+    const prefersReducedMotion = typeof window !== 'undefined'
+      && window.matchMedia?.('(prefers-reduced-motion: reduce)').matches;
+
+    void waitForElement(anchorId, timeoutMs).then((el) => {
+      if (!el) return;
+      scrollToEntity(el, !prefersReducedMotion);
+      highlightEntity(el);
+    });
+  });
+}
+
+function waitForElement(id: string, timeoutMs: number): Promise<HTMLElement | null> {
+  return new Promise((resolve) => {
+    if (typeof document === 'undefined') return resolve(null);
+    const start = Date.now();
+    const tick = () => {
+      const el = document.getElementById(id);
+      if (el) return resolve(el);
+      if (Date.now() - start > timeoutMs) return resolve(null);
+      setTimeout(tick, POLL_INTERVAL_MS);
+    };
+    tick();
+  });
+}

package/src/style.css

@@ -133,6 +133,23 @@
     @apply text-ink-600 hover:text-ink-800 underline-offset-2 hover:underline transition-colors;
   }
 
+  /* Non-verbal entity highlight — single source of truth for the
+     cross-ref "you landed here" affordance. Toggled by
+     utils/non-verbal-highlight.ts; applies to figure/table/formula
+     root elements uniformly. */
+  .nv-entity--highlighted {
+    outline: 2px solid var(--brand-primary, #2563eb);
+    outline-offset: 4px;
+    animation: nv-entity-pulse 1.6s ease-out;
+  }
+  @keyframes nv-entity-pulse {
+    0%, 100% { box-shadow: 0 0 0 0 rgba(37, 99, 235, 0); }
+    20%      { box-shadow: 0 0 0 6px rgba(37, 99, 235, 0.25); }
+  }
+  @media (prefers-reduced-motion: reduce) {
+    .nv-entity--highlighted { animation: none; }
+  }
+
   /* Concept definition lists */
   .concept-list {
     list-style: disc;

package/src/utils/content-renderer.ts

@@ -5,28 +5,39 @@
  * math placeholders, tables, lists, and text formatting. This is the single
  * source of truth for content rendering in the browser.
  *
+ * Mention kinds routed here (all dispatched by glossarist's `parseMention`):
+ *   - {{fig:id}} / {{fig:id, display}}  → nonVerbalRefResolver (figure)
+ *   - {{table:id}} / {{table:id, display}}  → nonVerbalRefResolver (table)
+ *   - {{formula:id}} / {{formula:id, display}}  → nonVerbalRefResolver (formula)
+ *   - {{cite:key[, render term]}}  → citeResolver
+ *   - {{urn:...[, render term]}}  → urnRefResolver / xrefResolver
+ *   - {{concept_id[, render term]}}  → conceptRefResolver
+ *   - {{designation[, render term]}}  → conceptRefResolver
+ *
  * Math-specific helpers (replaceBracketed, mathPlaceholder) are internal.
- * The v-math directive upgrades the placeholders to KaTeX at runtime.
+ * The v-math directive upgrades the placeholders to Plurimath at runtime.
  */
 import { escapeHtml, escapeAttr } from './escape';
 import { parseMention } from 'glossarist';
+import type { NonVerbalKind } from '../adapters/non-verbal/types';
+import { entityKindFromMentionKind } from '../adapters/non-verbal/kind';
 
 // ── Resolver types ────────────────────────────────────────────────────────
 
 export type XrefResolver = (uri: string, term: string) => string;
 export type BibResolver = (refId: string, title: string) => string;
-export type FigResolver = (figId: string) => string;
 export type CiteResolver = (key: string, label: string | null) => string;
 export type ConceptRefResolver = (conceptId: string, term: string) => string;
 export type UrnRefResolver = (uri: string, term: string) => string;
+export type NonVerbalRefResolver = (kind: NonVerbalKind, entityId: string, display?: string) => string;
 
 export interface RenderOptions {
   xrefResolver?: XrefResolver;
   bibResolver?: BibResolver;
-  figResolver?: FigResolver;
   conceptRefResolver?: ConceptRefResolver;
   citeResolver?: CiteResolver;
   urnRefResolver?: UrnRefResolver;
+  nonVerbalRefResolver?: NonVerbalRefResolver;
 }
 
 // ── Math placeholders ────────────────────────────────────────────────────
@@ -144,19 +155,11 @@ function resolveBibRefs(text: string, opts: RenderOptions): string {
   });
 }
 
-function resolveFigRefs(text: string, opts: RenderOptions): string {
-  return text.replace(/<<(fig_[^>]+)>>/g, (_, figId) => {
-    if (opts.figResolver) {
-      return opts.figResolver(figId.trim());
-    }
-    return `<span class="fig-ref">${escapeHtml(figId.trim())}</span>`;
-  });
-}
-
 function resolveUrnRefs(text: string, opts: RenderOptions): string {
   // Double-brace URN refs: {{urn:...,term}} or {{urn:...,term,display}}
-  // Note: glossarist ≥ 0.3.7 parseMention handles these as 'urn-ref', but we
-  // keep this handler for when parseMention returns 'unresolved' (glossarist < 0.3.7)
+  // These bypass parseMention because the three-arg form has different
+  // semantics in the renderer (display shown, not term) vs. cleanContent
+  // (term shown for search indexing).
   let result = text.replace(/\{\{(urn:[^,}]+),([^,}]+)(?:,([^}]+))?\}\}/g, (_, uri, term, display) => {
     const t = (display || term).trim();
     if (opts.xrefResolver) {
@@ -178,60 +181,68 @@ function resolveUrnRefs(text: string, opts: RenderOptions): string {
 }
 
 function resolveMentions(text: string, opts: RenderOptions): string {
-  // Single-pass {{...}} mention dispatcher via parseMention (SSOT)
   return text.replace(/\{\{([^{}]+?)\}\}/g, (_orig, body) => {
     const parsed = parseMention(body);
+    const p = parsed as Record<string, unknown>;
+
+    switch (p.kind) {
+      case 'fig-ref':
+      case 'table-ref':
+      case 'formula-ref': {
+        const nvKind = entityKindFromMentionKind(p.kind as string) as NonVerbalKind;
+        const entityId = p.key as string;
+        const display = (p.label as string) ?? undefined;
+        if (opts.nonVerbalRefResolver) {
+          return opts.nonVerbalRefResolver(nvKind, entityId, display);
+        }
+        const label = display ?? entityId;
+        return `<span class="nv-ref nv-ref--${nvKind}">${escapeHtml(label)}</span>`;
+      }
 
-    // cite:key[,render term] — bibliography citation
-    if (parsed.kind === 'cite-ref') {
-      const key = parsed.key!;
-      const label = parsed.label ?? null;
-      if (opts.citeResolver) return opts.citeResolver(key, label);
-      return `<span class="bib-ref">${escapeHtml(label ?? key)}</span>`;
-    }
+      case 'cite-ref': {
+        const key = p.key as string;
+        const label = (p.label as string) ?? null;
+        if (opts.citeResolver) return opts.citeResolver(key, label);
+        return `<span class="bib-ref">${escapeHtml(label ?? key)}</span>`;
+      }
 
-    // urn:...[,render term] — URN cross-reference (glossarist ≥ 0.3.7)
-    const anyParsed = parsed as Record<string, unknown>;
-    if ((anyParsed.kind as string) === 'urn-ref') {
-      const uri = anyParsed.uri as string;
-      const label = (anyParsed.label as string) ?? uri;
-      if (opts.urnRefResolver) return opts.urnRefResolver(uri, label);
-      if (opts.xrefResolver) return opts.xrefResolver(uri, label);
-      return escapeHtml(label);
-    }
+      case 'urn-ref': {
+        const uri = p.uri as string;
+        const label = (p.label as string) ?? uri;
+        if (opts.urnRefResolver) return opts.urnRefResolver(uri, label);
+        if (opts.xrefResolver) return opts.xrefResolver(uri, label);
+        return escapeHtml(label);
+      }
 
-    // numeric_id[,render term] — local concept ID
-    if (parsed.kind === 'numeric') {
-      const id = parsed.id!;
-      const label = parsed.label;
-      if (label && opts.conceptRefResolver) {
-        return opts.conceptRefResolver(id, label);
+      case 'numeric': {
+        const id = p.id as string;
+        const label = p.label as string | null;
+        if (label && opts.conceptRefResolver) {
+          return opts.conceptRefResolver(id, label);
+        }
+        return `<span class="gl-mention">${escapeHtml(id)}</span>`;
       }
-      return `<span class="gl-mention">${escapeHtml(id)}</span>`;
-    }
 
-    // designation[,render term] — designation matching (glossarist ≥ 0.3.7)
-    if ((anyParsed.kind as string) === 'designation') {
-      const designation = anyParsed.id as string;
-      const label = (anyParsed.label as string) ?? designation;
-      if (opts.conceptRefResolver) {
-        return opts.conceptRefResolver(designation, label);
+      case 'designation': {
+        const designation = p.id as string;
+        const label = (p.label as string) ?? designation;
+        if (opts.conceptRefResolver) {
+          return opts.conceptRefResolver(designation, label);
+        }
+        return escapeHtml(label);
       }
-      return escapeHtml(label);
-    }
 
-    // Fallback for unresolved: handle two-arg form or render as plain text
-    // This handles cases where parseMention doesn't recognize the kind
-    // (e.g. glossarist < 0.3.7 before urn-ref/designation kinds were added)
-    const commaIdx = body.indexOf(',');
-    if (commaIdx > 0) {
-      const id = body.slice(0, commaIdx).trim();
-      const display = body.slice(commaIdx + 1).trim();
-      if (opts.conceptRefResolver) return opts.conceptRefResolver(id, display);
-      return escapeHtml(display);
+      default: {
+        const commaIdx = body.indexOf(',');
+        if (commaIdx > 0) {
+          const id = body.slice(0, commaIdx).trim();
+          const display = body.slice(commaIdx + 1).trim();
+          if (opts.conceptRefResolver) return opts.conceptRefResolver(id, display);
+          return escapeHtml(display);
+        }
+        return `<span class="gl-mention">${escapeHtml(body.trim())}</span>`;
+      }
     }
-
-    return `<span class="gl-mention">${escapeHtml(body.trim())}</span>`;
   });
 }
 
@@ -246,9 +257,9 @@ function resolveMentions(text: string, opts: RenderOptions): string {
  * 3. Bullet and numbered lists
  * 4. Text formatting (bold, italic, subscript)
  * 5. Bibliography cross-references (<<ref,title>>)
- * 6. Figure references (<<fig_...>>)
- * 7. Single-brace URN inline references ({urn:...})
- * 8. Mention dispatcher via parseMention (cite-ref, urn-ref, numeric, designation)
+ * 6. Single-brace URN inline references ({urn:...})
+ * 7. Mention dispatcher — non-verbal (fig/table/formula), then parseMention
+ *    (cite-ref, urn-ref, numeric, designation)
  */
 export function renderContent(text: string, xrefResolverOrOpts?: XrefResolver | RenderOptions): string {
   if (!text) return '';
@@ -273,10 +284,9 @@ export function renderContent(text: string, xrefResolverOrOpts?: XrefResolver |
 
   // Stage 4: Reference resolution
   result = resolveBibRefs(result, opts);
-  result = resolveFigRefs(result, opts);
   result = resolveUrnRefs(result, opts);
 
-  // Stage 5: Mention dispatcher (parseMention SSOT)
+  // Stage 5: Mention dispatcher (non-verbal first, then parseMention SSOT)
   result = resolveMentions(result, opts);
 
   return result;
@@ -295,7 +305,9 @@ export function cleanContent(text: string): string {
     .replace(/~([^~]+)~/g, '_$1')
     .replace(/\n[ \t]*\* /g, '; ')
     .replace(/<<([^,>]+),([^>]+)>>/g, '$2')
-    .replace(/<<(fig_[^>]+)>>/g, '$1')
+    // Non-verbal mentions: {{fig:id, display}} → display; {{fig:id}} → id
+    .replace(/\{\{(?:fig|figure|table|tbl|formula|eq):([^,}]+),\s*([^}]+)\}\}/g, '$2')
+    .replace(/\{\{(?:fig|figure|table|tbl|formula|eq):([^}]+)\}\}/g, '$1')
     // URN refs — show render term (second part for two-arg, third part for three-arg)
     .replace(/\{\{urn:[^,}]+,([^,}]+),([^}]+)\}\}/g, '$1')  // three-arg: {{urn:...,term,display}} → term
     .replace(/\{\{urn:[^,}]+(?:,([^}]+))?\}\}/g, (_, label) => label ? label.trim() : '')  // two-arg or bare

package/src/utils/locale.ts

@@ -0,0 +1,92 @@
+/**
+ * Locale fallback SSOT.
+ *
+ * Single source of truth for localized text resolution across the runtime.
+ * Both the non-verbal entity resolver and any other localized content
+ * resolution should call `pickLocaleText` / `pickLocaleMap` rather than
+ * implement their own fallback chain.
+ */
+
+import { fetchLocalizedString } from 'glossarist';
+
+const DEFAULT_FALLBACK_CHAIN: readonly string[] = ['eng'] as const;
+
+const RTL_LOCALES: ReadonlySet<string> = new Set(['ara', 'heb', 'fas', 'urd', 'arb']);
+
+const ISO_639_2_TO_BCP47: Record<string, string> = {
+  eng: 'en', fra: 'fr', deu: 'de', zho: 'zh', ara: 'ar', jpn: 'ja', rus: 'ru',
+  kor: 'ko', spa: 'es', ita: 'it', por: 'pt', nld: 'nl', swe: 'sv', fin: 'fi',
+  dan: 'da', nob: 'nb', nno: 'nn', nor: 'no', pol: 'pl', tur: 'tr', ces: 'cs', ell: 'el',
+  heb: 'he', hin: 'hi', ind: 'id', fas: 'fa', ukr: 'uk', hun: 'hu', ron: 'ro',
+  slk: 'sk', slv: 'sl', hrv: 'hr', srp: 'sr', bul: 'bg', msa: 'ms', tha: 'th',
+  vie: 'vi', urd: 'ur', ben: 'bn', tam: 'ta', tel: 'te', mar: 'mr', guj: 'gu',
+  pan: 'pa', mal: 'ml', kan: 'kn', ori: 'or', asm: 'as', sin: 'si', nep: 'ne',
+  lit: 'lt', lav: 'lv', est: 'et', gle: 'ga', cym: 'cy', eus: 'eu', cat: 'ca',
+  glg: 'gl', afr: 'af', sqi: 'sq', mkd: 'mk', bel: 'be', kaz: 'kk', uzb: 'uz',
+  aze: 'az', hye: 'hy', kat: 'ka', mon: 'mn', tuk: 'tk', uig: 'ug', tgl: 'tl',
+};
+
+export type LocalizedText = Record<string, string>;
+
+export interface ResolvedLocaleText {
+  locale: string;
+  text: string;
+}
+
+export function pickLocaleText(
+  map: LocalizedText | undefined,
+  locale: string,
+  fallbackChain: readonly string[] = DEFAULT_FALLBACK_CHAIN,
+): string {
+  const r = pickLocaleMap(map, locale, fallbackChain);
+  return r?.text ?? '';
+}
+
+export function pickLocaleMap(
+  map: LocalizedText | undefined,
+  locale: string,
+  fallbackChain: readonly string[] = DEFAULT_FALLBACK_CHAIN,
+): ResolvedLocaleText | null {
+  if (!map) return null;
+
+  // Disable fetchLocalizedString's built-in 'eng' default by passing null —
+  // at runtime `null` defeats the default param and the `!= null` guard
+  // inside the lib skips its own fallback. The published .d.ts types the
+  // parameter as `string | undefined`, so cast through `unknown`. The chain
+  // is owned by THIS module: callers see one predictable resolution order.
+  const noFallback = null as unknown as undefined;
+  const direct = fetchLocalizedString(map, locale, noFallback);
+  if (direct != null) return { locale, text: direct };
+
+  for (const l of fallbackChain) {
+    const fb = fetchLocalizedString(map, l, noFallback);
+    if (fb != null) return { locale: l, text: fb };
+  }
+
+  const entries = Object.entries(map);
+  if (entries.length === 0) return null;
+  return { locale: entries[0][0], text: entries[0][1] };
+}
+
+export function hasLocale(map: LocalizedText | undefined, locale: string): boolean {
+  return !!map && Object.prototype.hasOwnProperty.call(map, locale);
+}
+
+export function isRtl(locale: string): boolean {
+  return RTL_LOCALES.has(locale);
+}
+
+export function localeToBcp47(locale: string): string {
+  return ISO_639_2_TO_BCP47[locale] ?? locale;
+}
+
+export function resolveFallbackChain(datasetLocales?: readonly string[]): readonly string[] {
+  if (!datasetLocales || datasetLocales.length === 0) {
+    return DEFAULT_FALLBACK_CHAIN;
+  }
+  const chain = [...datasetLocales];
+  for (const l of DEFAULT_FALLBACK_CHAIN) {
+    if (!chain.includes(l)) chain.push(l);
+  }
+  return chain;
+}

package/src/utils/non-verbal-anchor.ts

@@ -0,0 +1,51 @@
+/**
+ * Anchor scheme SSOT for non-verbal entities.
+ *
+ * The anchor id format is `{kind}-{datasetId}-{entityId}` (e.g.
+ * `figure-iala-2023-mixed-reflection`). Components, cross-ref click
+ * handlers, router guards, and prose mentions all use this module to
+ * compute or match anchor ids — keeping the scheme in one place means
+ * changing it later is a one-file edit.
+ *
+ * The kind prefix is the kind itself (e.g. `figure`), not a shortened
+ * alias. This matches the wire format and the anchor selector prefix
+ * used by the cross-ref composable.
+ */
+
+import type { NonVerbalKind } from '../adapters/non-verbal/types';
+
+const ANCHOR_KIND_PREFIX: Record<NonVerbalKind, string> = {
+  figure: 'figure',
+  table: 'table',
+  formula: 'formula',
+};
+
+export const ANCHOR_KIND_SELECTORS: readonly string[] = Object
+  .values(ANCHOR_KIND_PREFIX)
+  .map(k => `a[href^="#${k}-"]`);
+
+export function anchorId(kind: NonVerbalKind, datasetId: string, entityId: string): string {
+  return `${ANCHOR_KIND_PREFIX[kind]}-${datasetId}-${entityId}`;
+}
+
+export function anchorSelector(kind: NonVerbalKind, datasetId: string, entityId: string): string {
+  return `#${CSS.escape(anchorId(kind, datasetId, entityId))}`;
+}
+
+export interface ParsedAnchor {
+  kind: NonVerbalKind;
+  datasetId: string;
+  entityId: string;
+}
+
+const PARSER_RE = /^(figure|table|formula)-(.+)-(.+)$/;
+
+export function parseAnchorId(id: string): ParsedAnchor | null {
+  const m = id.match(PARSER_RE);
+  if (!m) return null;
+  return { kind: m[1] as NonVerbalKind, datasetId: m[2], entityId: m[3] };
+}
+
+export function hrefFromAnchor(id: string): string {
+  return `#${id}`;
+}

package/src/utils/non-verbal-highlight.ts

@@ -0,0 +1,27 @@
+/**
+ * Cross-reference highlight utility — shared by the click handler and the
+ * router scroll guard. Both call `highlightEntity()` after scrolling into
+ * view; the user sees a brief, accessible focus ring.
+ *
+ * Honors prefers-reduced-motion: the highlight class is added either way
+ * (it's a state indicator), but the smooth-scroll behavior is gated
+ * upstream by `useReducedMotion`.
+ */
+
+const HIGHLIGHT_CLASS = 'nv-entity--highlighted';
+const HIGHLIGHT_DURATION_MS = 1600;
+
+export function highlightEntity(el: HTMLElement | null): void {
+  if (!el) return;
+  el.classList.add(HIGHLIGHT_CLASS);
+  el.setAttribute('tabindex', '-1');
+  el.focus({ preventScroll: true });
+  window.setTimeout(() => {
+    el.classList.remove(HIGHLIGHT_CLASS);
+  }, HIGHLIGHT_DURATION_MS);
+}
+
+export function scrollToEntity(el: HTMLElement | null, smooth: boolean): void {
+  if (!el) return;
+  el.scrollIntoView({ behavior: smooth ? 'smooth' : 'auto', block: 'start' });
+}