@glossarist/concept-browser 0.7.112 → 0.7.114

package/README.md

@@ -293,6 +293,48 @@ The page appears in the sidebar navigation automatically.
 
 See [`site-config.example.yml`](site-config.example.yml) for all options including UI languages, fonts, features, and dataset groups.
 
+## Data/Deployment Boundary
+
+Concept-browser enforces a strict separation between **data** (authored by dataset authors) and **deployment** (configured by deployers):
+
+- **Dataset authors** write concepts, sources, bibliography, and inline mentions. They don't know where their dataset will be deployed or what other datasets will be co-deployed.
+- **Deployers** write `site-config.yml` to register datasets, declare URI patterns, and optionally add routing entries for external datasets. They never edit dataset content.
+- **Concept-browser** resolves every cross-reference at runtime via a fixed cascade, making multiple datasets behave as one coherent whole.
+
+### The resolution cascade
+
+Every `{{cite:...}}` and `{{urn:...}}` mention walks this cascade at render time:
+
+1. **`uriPatterns`** — is there a co-deployed dataset that matches? → internal link (case 1)
+2. **`routing[]`** — is there a routing entry for the URI? → external link (case 2)
+3. **`citation.link`** — does the source have a canonical link? → flat bib record (case 3)
+4. **Unresolved** — plain text
+
+The same YAML renders differently in different deployments. The data never changes.
+
+## Inline Content Syntax
+
+All inline references in concept text use the unified `{{kind:target}}` notation:
+
+| Kind | Example | What it does |
+|---|---|---|
+| `cite` | `{{cite:sourceId}}` | Cite a `ConceptSource` from this concept's `sources[]` — walks the full resolution cascade |
+| `urn` | `{{urn:iso:std:iso:704}}` | Reference a concept via URN routing |
+| `fig` | `{{fig:diagram_3}}` | Reference a figure entity in the same dataset |
+| `table` | `{{table:units}}` | Reference a table entity |
+| `formula` | `{{formula:ohm_law}}` | Reference a formula entity |
+| `bib` | `{{bib:ref_1}}` | Reference a bibliography entry (case-3-only, no underlying concept) |
+| `link` | `{{link:https://example.com}}` | External URL (canonical, deployment-independent) |
+| `image` | `{{image:src, alt}}` | Inline image embed |
+| *(none)* | `{{measurement unit}}` | Designation match in same dataset |
+| *(none)* | `{{112-01-10}}` | Numeric ID match in same dataset |
+
+Each kind accepts an optional label: `{{kind:target, label}}`.
+
+**Deprecated:** `<<ref,title>>` (AsciiDoc xref syntax) emits a deprecation warning. Migrate to `{{kind:target}}`.
+
+See `/learn/inline-content` on any deployed site for a full interactive reference.
+
 ## CLI Commands
 
 ```

package/package.json

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

package/src/__tests__/composables/cite-resolver.test.ts

@@ -0,0 +1,119 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { computed, ref } from 'vue';
+import { useConceptEdges } from '../../composables/use-concept-edges';
+import { useVocabularyStore } from '../../stores/vocabulary';
+import type { Manifest, GraphEdge } from '../../adapters/types';
+import { makeManifest, setupPinia } from '../test-helpers';
+import { getFactory, resetFactory } from '../../adapters/factory';
+import { useRenderOptions } from '../../composables/use-render-options';
+import type { Router } from 'vue-router';
+
+/**
+ * citeResolver contract — pins the {{cite:sourceId}} resolution cascade.
+ *
+ * The citeResolver must:
+ * 1. Look up the concept's own sources[] for a matching id
+ * 2. Delegate to ReferenceResolver.resolveCite() which walks the
+ *    deployment's cascade
+ * 3. Render based on classification (internal → navigable link,
+ *    self-contained → external link with origin.link, unresolved → span)
+ *
+ * Bug history: citeResolver was dead code (never wired). Every
+ * {{cite:foo}} mention fell through to a plain <span> with no resolution.
+ * This spec pins the wiring.
+ */
+
+describe('citeResolver — {{cite:sourceId}} resolution', () => {
+  const noopRouter = { push() {} } as unknown as Router;
+  let store: ReturnType<typeof useVocabularyStore>;
+  const manifest: Manifest = makeManifest({
+    id: 'test',
+    datasetUri: 'urn:test:dataset',
+    uriBase: 'https://example.org',
+  });
+
+  beforeEach(() => {
+    setupPinia();
+    resetFactory();
+    store = useVocabularyStore();
+    store.manifests.set(manifest.id, manifest);
+
+    const factory = getFactory();
+    factory.resolveRelatedRef = vi.fn((ref: { source: string | null; id: string | null } | null) =>
+      ref?.source === 'urn:test:dataset' && ref.id
+        ? { registerId: manifest.id, conceptId: ref.id }
+        : null,
+    );
+  });
+
+  it('returns cite-ref span when no sources are provided', () => {
+    const { citeResolver } = useRenderOptions(() => 'test', () => undefined);
+    const html = citeResolver('foo', null);
+    expect(html).toContain('cite-ref');
+    expect(html).toContain('foo');
+  });
+
+  it('returns cite-unresolved when source id not found in sources', () => {
+    const sources = [{ id: 'bar', origin: { ref: { source: 'Test', id: '42' } } }];
+    const { citeResolver } = useRenderOptions(() => 'test', () => sources);
+    const html = citeResolver('foo', null);
+    expect(html).toContain('cite-unresolved');
+    expect(html).toContain('foo');
+  });
+
+  it('renders the label when provided', () => {
+    const sources = [{ id: 'foo', origin: { ref: { source: 'Test', id: '42' } } }];
+    const { citeResolver } = useRenderOptions(() => 'test', () => sources);
+    const html = citeResolver('foo', 'custom label');
+    // The resolver runs the cascade. Without a registered sourceRef, it
+    // falls through to unresolved or self-contained. Either way, the label
+    // or the source info should be in the output.
+    expect(html).toMatch(/custom label|Test|42/);
+  });
+
+  it('renders origin.link as external link for self-contained citation', () => {
+    const link = 'https://example.org/external/page';
+    const sources = [{
+      id: 'foo',
+      origin: { ref: { source: 'External', id: 'X1' }, link },
+    }];
+    const { citeResolver } = useRenderOptions(() => 'test', () => sources);
+    const html = citeResolver('foo', null);
+    // Without a registered sourceRef matching "External", the cascade
+    // falls through to self-contained or external. The link should appear.
+    expect(html).toContain('href');
+    expect(html).toContain(link);
+  });
+
+  it('does NOT crash when source.origin is null', () => {
+    const sources = [{ id: 'foo', origin: null }];
+    const { citeResolver } = useRenderOptions(() => 'test', () => sources);
+    expect(() => citeResolver('foo', null)).not.toThrow();
+  });
+
+  it('does NOT crash when sources is empty array', () => {
+    const { citeResolver } = useRenderOptions(() => 'test', () => []);
+    expect(() => citeResolver('foo', null)).not.toThrow();
+  });
+
+  it('does NOT crash when registerId returns empty string', () => {
+    const sources = [{ id: 'foo', origin: { ref: { source: 'X', id: '1' } } }];
+    const { citeResolver } = useRenderOptions(() => '', () => sources);
+    expect(() => citeResolver('foo', null)).not.toThrow();
+  });
+});
+
+describe('RenderOptions — urnRefResolver removed', () => {
+  it('content-renderer no longer exports UrnRefResolver type', async () => {
+    // RenderOptions is a TypeScript interface (no runtime export).
+    // Verify the UrnRefResolver type is gone by checking the source.
+    const fs = await import('fs');
+    const path = await import('path');
+    const source = fs.readFileSync(
+      path.resolve(process.cwd(), 'src/utils/content-renderer.ts'),
+      'utf-8',
+    );
+    expect(source).not.toMatch(/UrnRefResolver/);
+    expect(source).not.toMatch(/urnRefResolver/);
+  });
+});

package/src/__tests__/utils/inline-content-kinds.test.ts

@@ -0,0 +1,139 @@
+import { describe, it, expect, vi, afterEach } from 'vitest';
+import { renderContent, cleanContent, type RenderOptions } from '../../utils/content-renderer';
+
+/**
+ * Unified mention syntax contract — {{kind:target[, label]}}.
+ *
+ * Pins the dispatch for every kind and the deprecation behavior for
+ * the legacy <<ref,title>> AsciiDoc xref syntax.
+ */
+
+describe('content-renderer — unified mention kinds', () => {
+
+  describe('{{link:URL}} — external link', () => {
+    it('renders bare URL as external anchor', () => {
+      const html = renderContent('{{link:https://example.com}}');
+      expect(html).toContain('<a href="https://example.com"');
+      expect(html).toContain('target="_blank"');
+      expect(html).toContain('rel="noopener"');
+      expect(html).toContain('https://example.com');
+    });
+
+    it('renders URL with label', () => {
+      const html = renderContent('{{link:https://example.com, click here}}');
+      expect(html).toContain('click here');
+      expect(html).toContain('href="https://example.com"');
+    });
+
+    it('delegates to linkResolver when provided', () => {
+      const opts: RenderOptions = { linkResolver: (url, label) => `<a href="${url}" class="custom">${label}</a>` };
+      const html = renderContent('{{link:https://example.com, test}}', opts);
+      expect(html).toContain('class="custom"');
+      expect(html).toContain('test');
+    });
+  });
+
+  describe('{{image:src}} — inline image embed', () => {
+    it('renders bare src as img tag', () => {
+      const html = renderContent('{{image:photo.png}}');
+      expect(html).toContain('<img');
+      expect(html).toContain('src="photo.png"');
+    });
+
+    it('renders src with alt text', () => {
+      const html = renderContent('{{image:photo.png, A photo of the setup}}');
+      expect(html).toContain('src="photo.png"');
+      expect(html).toContain('alt="A photo of the setup"');
+    });
+
+    it('delegates to imageResolver when provided', () => {
+      const opts: RenderOptions = { imageResolver: (src, alt) => `<img src="/base/${src}" alt="${alt}" class="custom-img" />` };
+      const html = renderContent('{{image:photo.png, test}}', opts);
+      expect(html).toContain('src="/base/photo.png"');
+      expect(html).toContain('class="custom-img"');
+    });
+  });
+
+  describe('{{bib:id}} — bibliography entry', () => {
+    it('renders id as bib-ref span when no resolver', () => {
+      const html = renderContent('{{bib:ref_1}}');
+      expect(html).toContain('bib-ref');
+      expect(html).toContain('ref_1');
+    });
+
+    it('renders label when provided', () => {
+      const html = renderContent('{{bib:ref_1, ISO 704}}');
+      expect(html).toContain('ISO 704');
+    });
+
+    it('delegates to bibResolver when provided', () => {
+      const opts: RenderOptions = { bibResolver: (id, title) => `<a href="/bib/${id}" class="bib-link">${title}</a>` };
+      const html = renderContent('{{bib:ref_1, ISO 704}}', opts);
+      expect(html).toContain('href="/bib/ref_1"');
+      expect(html).toContain('ISO 704');
+    });
+  });
+
+  describe('cleanContent — new kinds stripped correctly', () => {
+    it('strips {{link:URL}} to the URL', () => {
+      expect(cleanContent('{{link:https://example.com}}')).toBe('https://example.com');
+    });
+
+    it('strips {{link:URL, label}} to the label', () => {
+      expect(cleanContent('{{link:https://example.com, click here}}')).toBe('click here');
+    });
+
+    it('strips {{image:src}} to empty string', () => {
+      expect(cleanContent('{{image:photo.png}}')).toBe('');
+    });
+
+    it('strips {{image:src, alt}} to the alt text', () => {
+      expect(cleanContent('{{image:photo.png, A photo}}')).toBe('A photo');
+    });
+
+    it('strips {{bib:id}} to the id', () => {
+      expect(cleanContent('{{bib:ref_1}}')).toBe('ref_1');
+    });
+
+    it('strips {{bib:id, label}} to the label', () => {
+      expect(cleanContent('{{bib:ref_1, ISO 704}}')).toBe('ISO 704');
+    });
+  });
+});
+
+describe('content-renderer — legacy <<ref,title>> deprecation', () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it('emits a deprecation warning via console.warn', () => {
+    const spy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    renderContent('See <<845-01-01, 845-01-01>> for details.');
+    expect(spy).toHaveBeenCalledTimes(1);
+    expect(spy.mock.calls[0][0]).toContain('deprecated');
+    expect(spy.mock.calls[0][0]).toContain('<<845-01-01,845-01-01>>');
+  });
+
+  it('renders the title as plain text in a legacy-xref span', () => {
+    vi.spyOn(console, 'warn').mockImplementation(() => {});
+    const html = renderContent('See <<845-01-01, 845-01-01>> for details.');
+    expect(html).toContain('legacy-xref');
+    expect(html).toContain('845-01-01');
+    // Must NOT contain bib-ref or bib-link (the old wrong behavior)
+    expect(html).not.toContain('bib-ref');
+    expect(html).not.toContain('bib-link');
+  });
+
+  it('does NOT call bibResolver (cascade is not bypassed)', () => {
+    vi.spyOn(console, 'warn').mockImplementation(() => {});
+    const bibResolver = vi.fn(() => '<a class="bib-link">mock</a>');
+    const opts: RenderOptions = { bibResolver };
+    const html = renderContent('<<845-01-01, 845-01-01>>', opts);
+    expect(bibResolver).not.toHaveBeenCalled();
+    expect(html).not.toContain('bib-link');
+  });
+
+  it('cleanContent extracts the title from <<ref,title>>', () => {
+    expect(cleanContent('See <<845-01-01, 845-01-01>>')).toContain('845-01-01');
+  });
+});

package/src/components/ConceptDetail.vue

@@ -117,9 +117,14 @@ const conceptSources = computed(() => props.concept?.sources ?? []);
 const conceptTags = computed(() => props.concept?.tags ?? []);
 
 const factory = getFactory();
-const { ensureBibLoaded, bibResolver, nonVerbalRefResolver } = useRenderOptions(() => props.registerId);
+const { ready: bibReady, ensureBibLoaded, bibResolver, citeResolver, nonVerbalRefResolver } = useRenderOptions(
+  () => props.registerId,
+  () => props.concept?.sources,
+);
 
-const renderOpts = computed<RenderOptions>(() => ({
+const renderOpts = computed<RenderOptions>(() => {
+  bibReady.value;
+  return {
   xrefResolver: (uri, term) => {
     const resolution = factory.resolve(uri, props.registerId);
     if (resolution.type === 'internal') {
@@ -139,8 +144,10 @@ const renderOpts = computed<RenderOptions>(() => ({
     return `<a href="#" class="xref-link" data-register="${escapeAttr(props.registerId)}" data-concept="${escapeAttr(resolvedId)}">${escapeAttr(term)}</a>`;
   },
   bibResolver,
+  citeResolver,
   nonVerbalRefResolver,
-}));
+};
+});
 
 watch(() => props.registerId, () => { ensureBibLoaded(); }, { immediate: true });
 
@@ -152,7 +159,7 @@ const structuralEntityRefs = useConceptEntities(
 useNonVerbalCrossRef();
 
 function handleContentClick(e: MouseEvent) {
-  const target = (e.target as HTMLElement).closest('.xref-link') as HTMLElement | null;
+  const target = (e.target as HTMLElement).closest('.xref-link, .cite-link') as HTMLElement | null;
   if (!target) return;
   e.preventDefault();
   const registerId = target.dataset.register;

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

@@ -1,11 +1,34 @@
-import { ref } from 'vue';
-import type { RenderOptions, BibResolver, NonVerbalRefResolver } from '../utils/content-renderer';
+/**
+ * Render-options composable — builds resolvers for the content renderer.
+ *
+ * The citeResolver is the load-bearing addition: it connects inline
+ * {{cite:sourceId}} mentions to the existing ReferenceResolver cascade
+ * (factory.resolver.resolveCite). This closes the data/deployment
+ * boundary: the data author writes {{cite:iev_702-02-07}}, the resolver
+ * walks the deployment's sourceRefs → routing → link cascade, and the
+ * renderer emits the correct HTML based on classification.
+ */
+import { ref, type Ref } from 'vue';
+import type { RenderOptions, BibResolver, CiteResolver, 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';
+import { escapeAttr, escapeHtml } from '../utils/escape';
 
-export function useRenderOptions(registerId: () => string) {
+/** Minimal shape of a ConceptSource that citeResolver needs. */
+interface ConceptSourceLike {
+  id?: string | null;
+  origin?: {
+    ref?: { source?: string | null; id?: string | null; version?: string | null } | null;
+    locality?: { type?: string | null; reference_from?: string | null; referenceTo?: string | null; reference_to?: string | null; referenceFrom?: string | null } | null;
+    link?: string | null;
+  } | null;
+}
+
+export function useRenderOptions(
+  registerId: () => string,
+  getSources?: () => readonly ConceptSourceLike[] | undefined,
+) {
   const ready = ref(false);
 
   async function ensureBibLoaded() {
@@ -19,28 +42,80 @@ export function useRenderOptions(registerId: () => string) {
     const id = registerId();
     const entry = id ? getFactory().bibliography(id).findById(refId) : null;
     if (!entry) {
-      return `<span class="bib-ref">${escapeAttr(title)}</span>`;
+      return `<span class="bib-ref">${escapeHtml(title)}</span>`;
     }
     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.reference ?? '')}">${escapeHtml(display)}</a>`;
+    }
+    return `<span class="bib-ref" title="${escapeAttr(entry.reference ?? '')}">${escapeHtml(display)}</span>`;
+  };
+
+  /**
+   * citeResolver — the canonical path for {{cite:sourceId}} mentions.
+   *
+   * Looks up the concept's own sources[] for a matching id, then
+   * delegates to ReferenceResolver.resolveCite() which walks the
+   * deployment's cascade (sourceRefs → routing → link → unresolved).
+   */
+  const citeResolver: CiteResolver = (key, label) => {
+    const rid = registerId();
+    const sources = getSources?.();
+    if (!sources || !rid) {
+      return `<span class="cite-ref">${escapeHtml(label ?? key)}</span>`;
+    }
+
+    const source = sources.find(s => s.id === key);
+    if (!source?.origin) {
+      return `<span class="cite-unresolved">${escapeHtml(label ?? key)}</span>`;
+    }
+
+    const factory = getFactory();
+    const resolution = factory.resolver.resolveCite(source.origin, rid);
+    const refId = source.origin.ref?.id ?? key;
+    const refSource = source.origin.ref?.source ?? '';
+    const display = label ?? refId;
+
+    switch (resolution.classification) {
+      case 'internal-citation': {
+        if (!resolution.resolved) break;
+        const { registerId: targetReg, conceptId } = resolution.resolved;
+        const isCross = targetReg !== rid;
+        const crossBadge = isCross ? '<span class="text-[9px] opacity-60">↗</span>' : '';
+        return `<a href="#" class="cite-link" data-register="${escapeAttr(targetReg)}" data-concept="${escapeAttr(conceptId)}">${escapeHtml(display)} ${crossBadge}</a>`;
+      }
+      case 'self-contained-citation': {
+        const link = source.origin.link;
+        if (link) {
+          return `<a href="${escapeAttr(link)}" target="_blank" rel="noopener" class="cite-link cite-external">${escapeHtml(refSource || display)} <span class="text-[9px] opacity-60">↗</span></a>`;
+        }
+        return `<span class="cite-ref">${escapeHtml(refSource || display)}</span>`;
+      }
+      case 'external-citation': {
+        const link = source.origin.link;
+        if (link) {
+          return `<a href="${escapeAttr(link)}" target="_blank" rel="noopener" class="cite-link cite-external">${escapeHtml(refSource || display)} <span class="text-[9px] opacity-60">↗</span></a>`;
+        }
+        return `<span class="cite-ref">${escapeHtml(refSource || display)}</span>`;
+      }
     }
-    return `<span class="bib-ref" title="${escapeAttr(entry.title ?? '')}">${escapeAttr(display)}</span>`;
+
+    return `<span class="cite-unresolved">${escapeHtml(display)}</span>`;
   };
 
   const nonVerbalRefResolver: NonVerbalRefResolver = (kind: NonVerbalKind, entityId, display) => {
     const id = registerId();
     if (!id) {
       const label = display ?? entityId;
-      return `<span class="nv-ref nv-ref--${kind}">${escapeAttr(label)}</span>`;
+      return `<span class="nv-ref nv-ref--${kind}">${escapeHtml(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 `<a href="${href}" class="${cls}" data-nv-kind="${escapeAttr(kind)}" data-nv-dataset="${escapeAttr(id)}" data-nv-entity="${escapeAttr(entityId)}">${escapeHtml(label)}</a>`;
   };
 
-  return { ready, ensureBibLoaded, bibResolver, nonVerbalRefResolver };
+  return { ready, ensureBibLoaded, bibResolver, citeResolver, nonVerbalRefResolver };
 }
 
 function defaultLabelForKind(kind: NonVerbalKind, entityId: string): string {
@@ -50,3 +125,6 @@ function defaultLabelForKind(kind: NonVerbalKind, entityId: string): string {
     case 'formula': return `Formula ${entityId}`;
   }
 }
+
+/** Ensure `ready` is tracked as a Ref for consumers that read `.value`. */
+export type RenderOptionsReady = Ref<boolean>;

package/src/pages/[...path].astro

@@ -17,6 +17,7 @@ export async function getStaticPaths() {
     { params: { path: 'learn/relationships' } },
     { params: { path: 'learn/designations' } },
     { params: { path: 'learn/statuses' } },
+    { params: { path: 'learn/inline-content' } },
   ];
   for (const ds of datasets) {
     paths.push({ params: { path: `dataset/${ds.data.id}/about` } });

package/src/router/index.ts

@@ -118,6 +118,11 @@ export const routes: RouteRecordRaw[] = [
     name: 'learn-statuses',
     component: () => import('../views/learn/LearnStatusesView.vue'),
   },
+  {
+    path: '/learn/inline-content',
+    name: 'learn-inline-content',
+    component: () => import('../views/learn/LearnInlineContentView.vue'),
+  },
   {
     path: '/about',
     name: 'about-global',

package/src/utils/content-renderer.ts

@@ -5,14 +5,22 @@
  * 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
+ * Unified mention syntax: {{kind:target[, label]}}
+ * Every inline reference is a typed mention with a kind prefix:
+ *
+ *   - {{cite:key[, label]}}    → citeResolver (concept source citation)
+ *   - {{urn:...[, label]}}     → xrefResolver (URN routing)
+ *   - {{fig:id[, label]}}      → nonVerbalRefResolver (figure)
+ *   - {{table:id[, label]}}    → nonVerbalRefResolver (table)
+ *   - {{formula:id[, label]}}  → nonVerbalRefResolver (formula)
+ *   - {{bib:id[, label]}}      → bibResolver (bibliography entry, case-3-only)
+ *   - {{link:URL[, label]}}    → linkResolver (external URL)
+ *   - {{image:src[, alt]}}     → imageResolver (inline image embed)
+ *   - {{designation[, label]}} → conceptRefResolver (designation match)
+ *   - {{numeric_id[, label]}}  → conceptRefResolver (numeric ID match)
+ *
+ * Legacy `<<ref,title>>` (AsciiDoc xref) is deprecated; emits a console
+ * warning and renders as plain text. Migrate to {{kind:target}} syntax.
  *
  * Math-specific helpers (replaceBracketed, mathPlaceholder) are internal.
  * The v-math directive upgrades the placeholders to Plurimath at runtime.
@@ -28,16 +36,18 @@ export type XrefResolver = (uri: string, term: string) => string;
 export type BibResolver = (refId: string, title: 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 type LinkResolver = (url: string, label: string) => string;
+export type ImageResolver = (src: string, alt: string) => string;
 
 export interface RenderOptions {
   xrefResolver?: XrefResolver;
   bibResolver?: BibResolver;
   conceptRefResolver?: ConceptRefResolver;
   citeResolver?: CiteResolver;
-  urnRefResolver?: UrnRefResolver;
   nonVerbalRefResolver?: NonVerbalRefResolver;
+  linkResolver?: LinkResolver;
+  imageResolver?: ImageResolver;
 }
 
 // ── Math placeholders ────────────────────────────────────────────────────
@@ -146,12 +156,30 @@ function convertLists(text: string): string {
 
 // ── Inline reference resolution ──────────────────────────────────────────
 
-function resolveBibRefs(text: string, opts: RenderOptions): string {
+/**
+ * Deprecated AsciiDoc xref syntax: <<refId, title>>
+ *
+ * This was historically overloaded for:
+ *   1. Non-concept entity xrefs (should use {{fig/table/formula:id, label}})
+ *   2. Bibliography lookups (should use {{bib:id}} or {{cite:id}})
+ *   3. Concept citations (should use {{cite:id}})
+ *
+ * All three uses are wrong. This function emits a deprecation warning and
+ * renders the title as plain text. Datasets should migrate to the unified
+ * {{kind:target}} syntax.
+ */
+function resolveLegacyXref(text: string): string {
   return text.replace(/<<([^,>]+),([^>]+)>>/g, (_, refId, title) => {
-    if (opts.bibResolver) {
-      return opts.bibResolver(refId.trim(), title.trim());
+    const rid = refId.trim();
+    const lbl = title.trim();
+    if (typeof console !== 'undefined') {
+      console.warn(
+        `[glossarist] <<${rid},${lbl}>> is deprecated. ` +
+        `Use {{fig/table/formula:${rid}, ${lbl}}} for non-concept entities, ` +
+        `{{cite:${rid}}} for concept citations, or {{bib:${rid}}} for bibliography.`,
+      );
     }
-    return `<span class="bib-ref">${escapeHtml(title.trim())}</span>`;
+    return `<span class="legacy-xref" title="Deprecated: use {{kind:target}} syntax">${escapeHtml(lbl)}</span>`;
   });
 }
 
@@ -182,6 +210,45 @@ function resolveUrnRefs(text: string, opts: RenderOptions): string {
 
 function resolveMentions(text: string, opts: RenderOptions): string {
   return text.replace(/\{\{([^{}]+?)\}\}/g, (_orig, body) => {
+
+    // ── New kinds: link, image, bib (pre-parsed before parseMention) ──
+    // These follow the same {{kind:target[, label]}} convention as
+    // fig/table/formula but are handled here because glossarist's
+    // parseMention doesn't recognize them yet. When glossarist-js adds
+    // support (per PROMPT-NOW.md), these pre-parse cases can be removed
+    // and the switch below will handle them natively.
+
+    const linkMatch = body.match(/^link:(.+)$/i);
+    if (linkMatch) {
+      const rest = linkMatch[1];
+      const commaIdx = rest.indexOf(',');
+      const url = (commaIdx > 0 ? rest.slice(0, commaIdx).trim() : rest.trim());
+      const label = commaIdx > 0 ? rest.slice(commaIdx + 1).trim() : url;
+      if (opts.linkResolver) return opts.linkResolver(url, label);
+      return `<a href="${escapeAttr(url)}" target="_blank" rel="noopener" class="ext-link">${escapeHtml(label)}</a>`;
+    }
+
+    const imageMatch = body.match(/^image:(.+)$/i);
+    if (imageMatch) {
+      const rest = imageMatch[1];
+      const commaIdx = rest.indexOf(',');
+      const src = (commaIdx > 0 ? rest.slice(0, commaIdx).trim() : rest.trim());
+      const alt = commaIdx > 0 ? rest.slice(commaIdx + 1).trim() : '';
+      if (opts.imageResolver) return opts.imageResolver(src, alt);
+      return `<img src="${escapeAttr(src)}" alt="${escapeAttr(alt)}" class="inline-image" />`;
+    }
+
+    const bibMatch = body.match(/^bib:(.+)$/i);
+    if (bibMatch) {
+      const rest = bibMatch[1];
+      const commaIdx = rest.indexOf(',');
+      const id = (commaIdx > 0 ? rest.slice(0, commaIdx).trim() : rest.trim());
+      const label = commaIdx > 0 ? rest.slice(commaIdx + 1).trim() : id;
+      if (opts.bibResolver) return opts.bibResolver(id, label);
+      return `<span class="bib-ref">${escapeHtml(label)}</span>`;
+    }
+
+    // ── Existing kinds: handled by glossarist's parseMention ──
     const parsed = parseMention(body);
     const p = parsed as unknown as Record<string, unknown>;
 
@@ -209,7 +276,6 @@ function resolveMentions(text: string, opts: RenderOptions): string {
       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);
       }
@@ -256,10 +322,10 @@ function resolveMentions(text: string, opts: RenderOptions): string {
  * 2. AsciiDoc tables
  * 3. Bullet and numbered lists
  * 4. Text formatting (bold, italic, subscript)
- * 5. Bibliography cross-references (<<ref,title>>)
- * 6. Single-brace URN inline references ({urn:...})
- * 7. Mention dispatcher — non-verbal (fig/table/formula), then parseMention
- *    (cite-ref, urn-ref, numeric, designation)
+ * 5. Legacy AsciiDoc xrefs (<<ref,title>> → deprecated, renders as plain text)
+ * 6. URN inline references ({urn:...})
+ * 7. Mention dispatcher — link/image/bib (pre-parsed), then parseMention
+ *    (fig/table/formula, cite-ref, urn-ref, numeric, designation)
  */
 export function renderContent(text: string, xrefResolverOrOpts?: XrefResolver | RenderOptions): string {
   if (!text) return '';
@@ -283,7 +349,7 @@ export function renderContent(text: string, xrefResolverOrOpts?: XrefResolver |
   result = result.replace(/~([^~]+)~/g, '<sub>$1</sub>');
 
   // Stage 4: Reference resolution
-  result = resolveBibRefs(result, opts);
+  result = resolveLegacyXref(result);
   result = resolveUrnRefs(result, opts);
 
   // Stage 5: Mention dispatcher (non-verbal first, then parseMention SSOT)
@@ -299,18 +365,28 @@ export function renderContent(text: string, xrefResolverOrOpts?: XrefResolver |
 export function cleanContent(text: string): string {
   if (!text) return '';
   let result = text
+    // Legacy xrefs first (before HTML tag stripping eats <<)
+    .replace(/<<([^,>]+),([^>]+)>>/g, '$2')
     .replace(/<[^>]+>/g, '')
     .replace(/\*\*([^*]+)\*\*/g, '$1')
     .replace(/(?<!\*)\*([^*]+)\*(?!\*)/g, '$1')
     .replace(/~([^~]+)~/g, '_$1')
     .replace(/\n[ \t]*\* /g, '; ')
-    .replace(/<<([^,>]+),([^>]+)>>/g, '$2')
-    // Non-verbal mentions: {{fig:id, display}} → display; {{fig:id}} → id
+    // Entity 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')
+    // Link mentions: {{link:URL, label}} → label; {{link:URL}} → URL
+    .replace(/\{\{link:([^,}]+),\s*([^}]+)\}\}/gi, '$2')
+    .replace(/\{\{link:([^}]+)\}\}/gi, '$1')
+    // Image mentions: {{image:src, alt}} → alt; {{image:src}} → empty
+    .replace(/\{\{image:[^,}]+,\s*([^}]+)\}\}/gi, '$1')
+    .replace(/\{\{image:([^}]+)\}\}/gi, '')
+    // Bib mentions: {{bib:id, label}} → label; {{bib:id}} → id
+    .replace(/\{\{bib:([^,}]+),\s*([^}]+)\}\}/gi, '$2')
+    .replace(/\{\{bib:([^}]+)\}\}/gi, '$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
+    .replace(/\{\{urn:[^,}]+,([^,}]+),([^}]+)\}\}/g, '$1')
+    .replace(/\{\{urn:[^,}]+(?:,([^}]+))?\}\}/g, (_, label) => label ? label.trim() : '')
     .replace(/\{urn:[^,}]+,([^,}]+)(?:,[^}]+)?\}/g, '$1')
     // Cite refs — show render term (or empty if bare)
     .replace(/\{\{cite:[^,}]+(?:,([^}]+))?\}\}/g, (_, label) => label ? label.trim() : '')

package/src/views/learn/LearnInlineContentView.vue

@@ -0,0 +1,128 @@
+<script setup lang="ts">
+/**
+ * LearnInlineContentView — unified inline content syntax reference.
+ *
+ * Documents every {{kind:target}} mention kind with examples,
+ * explains the data/deployment boundary for citations, and shows
+ * the resolution cascade.
+ */
+import { computed } from 'vue';
+import { useI18n } from '../../i18n';
+import LearnCard from '../../components/learn/LearnCard.vue';
+
+const { t } = useI18n();
+
+const introText = computed(() =>
+  t('learn.inlineContent.intro') ||
+  'Every inline reference in concept text uses the unified mustache-kind:target notation. The first word (before the colon) tells you what kind of reference it is.',
+);
+
+const mentionKinds = [
+  { kind: 'cite', syntax: '{{cite:sourceId}}', example: '{{cite:iso7301}}', desc: 'Cite a ConceptSource from this concept\'s sources[] list. Walks the full resolution cascade (co-deployed → routed → bib).' },
+  { kind: 'cite + label', syntax: '{{cite:sourceId, label}}', example: '{{cite:iso7301, rice}}', desc: 'Same as cite, with an explicit display label.' },
+  { kind: 'urn', syntax: '{{urn:URN}}', example: '{{urn:iso:std:iso:704}}', desc: 'Reference a concept via URN routing. The deployment decides which dataset (if any) handles this URN.' },
+  { kind: 'fig', syntax: '{{fig:id}}', example: '{{fig:diagram_3}}', desc: 'Reference a figure entity in the same dataset.' },
+  { kind: 'table', syntax: '{{table:id}}', example: '{{table:unit_list}}', desc: 'Reference a table entity.' },
+  { kind: 'formula', syntax: '{{formula:id}}', example: '{{formula:ohm_law}}', desc: 'Reference a formula entity.' },
+  { kind: 'bib', syntax: '{{bib:id}}', example: '{{bib:ref_1}}', desc: 'Bibliography entry (case-3-only — no underlying concept). Renders as a flat reference.' },
+  { kind: 'link', syntax: '{{link:URL}}', example: '{{link:https://example.com}}', desc: 'External URL. The URL is canonical; the deployment has no say.' },
+  { kind: 'link + label', syntax: '{{link:URL, label}}', example: '{{link:https://example.com, click here}}', desc: 'External URL with display label.' },
+  { kind: 'image', syntax: '{{image:src}}', example: '{{image:diagram.png}}', desc: 'Inline image embed. Local images get basePath-prefixed.' },
+  { kind: 'image + alt', syntax: '{{image:src, alt}}', example: '{{image:diagram.png, The diagram}}', desc: 'Image with accessibility alt text.' },
+  { kind: 'designation', syntax: '{{designation}}', example: '{{measurement unit}}', desc: 'Reference a concept by matching its designation text (same dataset).' },
+  { kind: 'numeric', syntax: '{{numeric_id}}', example: '{{112-01-10}}', desc: 'Reference a concept by numeric ID (same dataset).' },
+];
+
+const cascade = [
+  { step: 1, name: 'uriPatterns', desc: 'Is there a co-deployed dataset that matches this URI?', result: 'Internal link (case 1)' },
+  { step: 2, name: 'routing[]', desc: 'Is there a routing entry for this URI in site-config.yml?', result: 'External link (case 2)' },
+  { step: 3, name: 'citation.link', desc: 'Does the source have a canonical link?', result: 'Flat bib record (case 3)' },
+  { step: 4, name: 'unresolved', desc: 'No match anywhere', result: 'Plain text' },
+];
+</script>
+
+<template>
+  <div class="max-w-4xl mx-auto px-4 sm:px-6 lg:px-8 py-8 space-y-6">
+    <h1 class="font-title text-3xl text-ink-800 dark:text-ink-50 mb-2">
+      {{ t('learn.inlineContent.title') || 'Inline Content Syntax' }}
+    </h1>
+    <p class="text-ink-500 dark:text-ink-400">
+      {{ introText }}
+    </p>
+
+    <LearnCard title="Mention Kinds">
+      <template #body>
+        <div class="overflow-x-auto">
+          <table class="w-full text-sm">
+            <thead>
+              <tr class="border-b border-ink-100 dark:border-ink-700 text-left">
+                <th class="py-2 pr-4">Kind</th>
+                <th class="py-2 pr-4">Syntax</th>
+                <th class="py-2 pr-4">Example</th>
+                <th class="py-2">Description</th>
+              </tr>
+            </thead>
+            <tbody>
+              <tr v-for="row in mentionKinds" :key="row.syntax" class="border-b border-ink-50 dark:border-ink-800">
+                <td class="py-2 pr-4 font-mono text-xs text-ink-600 dark:text-ink-300">{{ row.kind }}</td>
+                <td class="py-2 pr-4 font-mono text-xs text-ink-700 dark:text-ink-200">{{ row.syntax }}</td>
+                <td class="py-2 pr-4 font-mono text-xs text-emerald-700 dark:text-emerald-300">{{ row.example }}</td>
+                <td class="py-2 text-xs text-ink-500 dark:text-ink-400">{{ row.desc }}</td>
+              </tr>
+            </tbody>
+          </table>
+        </div>
+      </template>
+    </LearnCard>
+
+    <LearnCard title="Data / Deployment Boundary">
+      <template #body>
+        <div class="space-y-3 text-sm text-ink-600 dark:text-ink-300">
+          <p>
+            <strong>Dataset authors</strong> write citations in a deployment-agnostic way.
+            They don't know where their dataset will be deployed or what other datasets will be co-deployed.
+          </p>
+          <p>
+            <strong>Deployers</strong> write <code class="text-xs bg-ink-50 dark:bg-ink-800 px-1 rounded">site-config.yml</code>
+            to register datasets and declare URI patterns. They never edit dataset content.
+          </p>
+          <p>
+            <strong>Concept-browser</strong> resolves every citation at runtime. The same YAML works in any deployment.
+          </p>
+        </div>
+      </template>
+    </LearnCard>
+
+    <LearnCard title="Resolution Cascade">
+      <template #body>
+        <div class="space-y-2">
+          <div v-for="step in cascade" :key="step.step" class="flex items-start gap-3 py-2">
+            <span class="flex-shrink-0 w-6 h-6 rounded-full bg-ink-100 dark:bg-ink-700 text-ink-600 dark:text-ink-300 text-xs font-mono flex items-center justify-center">{{ step.step }}</span>
+            <div class="flex-1">
+              <div class="font-mono text-xs text-ink-700 dark:text-ink-200">{{ step.name }}</div>
+              <div class="text-xs text-ink-500 dark:text-ink-400">{{ step.desc }}</div>
+              <div class="text-xs text-emerald-700 dark:text-emerald-300 mt-0.5">{{ step.result }}</div>
+            </div>
+          </div>
+        </div>
+      </template>
+    </LearnCard>
+
+    <LearnCard title="Deprecated: <<ref,title>>">
+      <template #body>
+        <div class="text-sm text-ink-600 dark:text-ink-300 space-y-2">
+          <p>
+            The AsciiDoc xref syntax <code class="text-xs bg-amber-50 dark:bg-amber-900/20 px-1 rounded">&lt;&lt;ref,title&gt;&gt;</code>
+            is deprecated. It emits a console warning and renders as plain text.
+          </p>
+          <p>Migrate to the unified syntax:</p>
+          <ul class="list-disc list-inside text-xs space-y-1">
+            <li><code>&lt;&lt;fig_3,Figure 3&gt;&gt;</code> → <code class="text-emerald-700 dark:text-emerald-300" v-text="'{{fig:fig_3, Figure 3}}'"></code></li>
+            <li><code>&lt;&lt;845-01-01, 845-01-01&gt;&gt;</code> → <code class="text-emerald-700 dark:text-emerald-300" v-text="'{{cite:iev_845-01-01}}'"></code></li>
+            <li><code>&lt;&lt;ref_1, ISO 704&gt;&gt;</code> → <code class="text-emerald-700 dark:text-emerald-300" v-text="'{{bib:ref_1, ISO 704}}'"></code></li>
+          </ul>
+        </div>
+      </template>
+    </LearnCard>
+  </div>
+</template>