@glossarist/concept-browser 0.7.98 → 0.7.100

package/package.json

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

package/src/__tests__/components/hyperedge-diagram.test.ts

@@ -0,0 +1,55 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { mount } from '@vue/test-utils';
+import { createPinia, setActivePinia } from 'pinia';
+import HyperedgeDiagram from '../../components/HyperedgeDiagram.vue';
+
+/**
+ * HyperedgeDiagram mounts a small SVG and calls the actual sphere
+ * renderer (drawRakeBundles or drawGenericPipes) on mount. These
+ * tests pin the contract: each kind produces the right kind of SVG
+ * child elements, matching what the sphere itself renders.
+ */
+describe('HyperedgeDiagram', () => {
+  beforeEach(() => {
+    setActivePinia(createPinia());
+  });
+
+  it('renders an SVG element', () => {
+    const w = mount(HyperedgeDiagram, { props: { kind: 'partitive' } });
+    expect(w.find('svg.hyperedge-diagram').exists()).toBe(true);
+  });
+
+  it('partitive kind calls drawRakeBundles (emits line.rake-seg + circle.rake-junction)', () => {
+    const w = mount(HyperedgeDiagram, { props: { kind: 'partitive' } });
+    const svg = w.element as SVGSVGElement;
+    /* The sample fixture has 3 members with mixed multiplicity, so the
+       rake emits ≥1 segment + exactly 1 junction circle + 1 diamond. */
+    expect(svg.querySelectorAll('line.rake-seg').length).toBeGreaterThan(0);
+    expect(svg.querySelectorAll('circle.rake-junction').length).toBe(1);
+    expect(svg.querySelectorAll('path').length).toBe(1);
+  });
+
+  it('generic kind calls drawGenericPipes (emits line.pipe-seg + rect.pipe-junction)', () => {
+    const w = mount(HyperedgeDiagram, { props: { kind: 'generic' } });
+    const svg = w.element as SVGSVGElement;
+    /* The sample fixture has 3 members → 1 thick pipe + 3 thin threads = 4 segments,
+       plus 1 square junction and 1 diamond. */
+    expect(svg.querySelectorAll('line.pipe-seg').length).toBe(4);
+    expect(svg.querySelectorAll('rect.pipe-junction').length).toBe(1);
+    expect(svg.querySelectorAll('path').length).toBe(1);
+  });
+
+  it('partitive kind does not leak pipe-and-thread artifacts', () => {
+    const w = mount(HyperedgeDiagram, { props: { kind: 'partitive' } });
+    const svg = w.element as SVGSVGElement;
+    expect(svg.querySelectorAll('line.pipe-seg').length).toBe(0);
+    expect(svg.querySelectorAll('rect.pipe-junction').length).toBe(0);
+  });
+
+  it('generic kind does not leak rake artifacts', () => {
+    const w = mount(HyperedgeDiagram, { props: { kind: 'generic' } });
+    const svg = w.element as SVGSVGElement;
+    expect(svg.querySelectorAll('line.rake-seg').length).toBe(0);
+    expect(svg.querySelectorAll('circle.rake-junction').length).toBe(0);
+  });
+});

package/src/__tests__/components/pipe-bundles.test.ts

@@ -99,7 +99,7 @@ describe('drawGenericPipes — pipe-and-thread contract', () => {
     expect(svg.querySelectorAll('rect.pipe-junction').length).toBe(1);
   });
 
-  it('renders a delimiting-characteristic label per thread', () => {
+  it('renders ONE characteristic label (the criterion) — no per-thread labels', () => {
     const svg = makeSvg();
     drawGenericPipes(svg, pos, {
       isDark: false,
@@ -109,11 +109,26 @@ describe('drawGenericPipes — pipe-and-thread contract', () => {
       locale: 'eng',
     });
     const labels = Array.from(svg.querySelectorAll('text.pipe-label')).map(t => t.textContent);
-    /* 3 per-member characteristics + 1 group-level criterion = 4 labels */
-    expect(labels).toContain('multiple of a unit');
-    expect(labels).toContain('submultiple of a unit');
-    expect(labels).toContain('coherent derived unit');
-    expect(labels).toContain('by magnitude relationship');
+    /* Exactly one label — the hyperedge-level criterion. Per-member
+       delimitingCharacteristic values are NOT rendered. */
+    expect(labels).toEqual(['by magnitude relationship']);
+  });
+
+  it('renders NO label when the criterion is absent', () => {
+    const svg = makeSvg();
+    const rel = makeRelation();
+    delete rel.criterion;
+    drawGenericPipes(svg, pos, {
+      isDark: false,
+      color: '#b45309',
+      isMuted: false,
+      relations: [rel],
+      locale: 'eng',
+    });
+    /* Pipe + threads + junction + diamond still render, but zero labels. */
+    expect(svg.querySelectorAll('text.pipe-label').length).toBe(0);
+    expect(svg.querySelectorAll('line.pipe-seg').length).toBe(4);
+    expect(svg.querySelectorAll('rect.pipe-junction').length).toBe(1);
   });
 
   it('renders a diamond at the comprehensive end (origin marker)', () => {

package/src/__tests__/components/rake-bundles.test.ts

@@ -0,0 +1,318 @@
+import { describe, it, expect } from 'vitest';
+import { drawRakeBundles } from '../../components/relation-sphere/rake-bundles';
+import type { PartitiveRelationWire, PartitiveMemberWire } from '../../adapters/types';
+import {
+  NORMAL_STROKE_WIDTH,
+  DELIMITING_STROKE_WIDTH,
+} from '../../utils/partitive-multiplicity';
+
+/**
+ * Renderer tests for the partitive-relation rake bundle.
+ *
+ * Mirrors `pipe-bundles.test.ts` — pins the visual contract so a
+ * regression in stem/spine/teeth geometry, multiplicity stroke style,
+ * or partial-completeness spine extension cannot ship silently.
+ *
+ * Layout reference (ISO 704 rake notation):
+ *
+ *     comprehensive
+ *         │           ← stem (FRAME_STROKE_WIDTH, single solid)
+ *         ●─────────  ← spine (FRAME_STROKE_WIDTH, single solid)
+ *         │     │
+ *         ▼     ▼    ← teeth (per-member multiplicity + delimiting style)
+ *       p1     p2
+ */
+function makeSvg(): SVGSVGElement {
+  return document.createElementNS('http://www.w3.org/2000/svg', 'svg') as unknown as SVGSVGElement;
+}
+
+function member(uri: string, fields: Partial<PartitiveMemberWire> = {}): PartitiveMemberWire {
+  return {
+    uri,
+    presence: fields.presence ?? 'required',
+    count: fields.count ?? 'exactly_one',
+    isDelimiting: fields.isDelimiting ?? false,
+  };
+}
+
+function makeRelation(overrides: Partial<PartitiveRelationWire> = {}): PartitiveRelationWire {
+  return {
+    source: 'https://example.org/vim-2012/concept/1.3',
+    comprehensive: 'https://example.org/vim-2012/concept/1.3',
+    completeness: 'complete',
+    register: 'vim-2012',
+    partitives: [
+      member('https://example.org/vim-2012/concept/1.4'),
+      member('https://example.org/vim-2012/concept/1.5'),
+      member('https://example.org/vim-2012/concept/1.22'),
+    ],
+    ...overrides,
+  };
+}
+
+/* Fixed position map: comp at top-center, 3 members fanned across the bottom.
+   The rake renderer projects members onto a perpendicular spine; absolute
+   coordinates don't matter for the contract assertions, only that each
+   member has a distinct position so the spine has non-zero length. */
+const pos = new Map<string, { x: number; y: number }>([
+  ['vim-2012/1.3', { x: 120, y: 20 }],
+  ['vim-2012/1.4', { x: 30, y: 140 }],
+  ['vim-2012/1.5', { x: 120, y: 140 }],
+  ['vim-2012/1.22', { x: 210, y: 140 }],
+]);
+
+describe('drawRakeBundles — rake contract', () => {
+  it('renders nothing when muted', () => {
+    const svg = makeSvg();
+    drawRakeBundles(svg, pos, {
+      isDark: false,
+      color: '#0d9488',
+      isMuted: true,
+      relations: [makeRelation()],
+    });
+    expect(svg.querySelectorAll('line.rake-seg').length).toBe(0);
+    expect(svg.querySelectorAll('circle.rake-junction').length).toBe(0);
+    expect(svg.querySelectorAll('path').length).toBe(0);
+  });
+
+  it('renders a diamond at the comprehensive end (origin marker)', () => {
+    const svg = makeSvg();
+    drawRakeBundles(svg, pos, {
+      isDark: false,
+      color: '#0d9488',
+      isMuted: false,
+      relations: [makeRelation()],
+    });
+    /* Diamond is the only <path> element the rake emits. */
+    const paths = svg.querySelectorAll('path');
+    expect(paths.length).toBe(1);
+    /* Diamond path is centered on the comp position (120, 20).
+       The first coordinate of the diamond "M cx (cy-half)" pattern. */
+    const d = paths[0].getAttribute('d') ?? '';
+    expect(d.startsWith('M 120 ')).toBe(true);
+  });
+
+  it('renders exactly one circular junction at the spine center', () => {
+    const svg = makeSvg();
+    drawRakeBundles(svg, pos, {
+      isDark: false,
+      color: '#0d9488',
+      isMuted: false,
+      relations: [makeRelation()],
+    });
+    expect(svg.querySelectorAll('circle.rake-junction').length).toBe(1);
+  });
+
+  it('does NOT emit pipe-and-thread artifacts (no shape leak)', () => {
+    const svg = makeSvg();
+    drawRakeBundles(svg, pos, {
+      isDark: false,
+      color: '#0d9488',
+      isMuted: false,
+      relations: [makeRelation()],
+    });
+    expect(svg.querySelectorAll('line.pipe-seg').length).toBe(0);
+    expect(svg.querySelectorAll('rect.pipe-junction').length).toBe(0);
+  });
+
+  it('renders frame-width stem + spine at FRAME_STROKE_WIDTH (1.4)', () => {
+    const svg = makeSvg();
+    drawRakeBundles(svg, pos, {
+      isDark: false,
+      color: '#0d9488',
+      isMuted: false,
+      relations: [makeRelation()],
+    });
+    const segs = Array.from(svg.querySelectorAll('line.rake-seg'));
+    const frameSegs = segs.filter(s => Math.abs(parseFloat(s.getAttribute('stroke-width')!) - 1.4) < 0.01);
+    /* Stem + spine = 2 frame-width segments. */
+    expect(frameSegs.length).toBe(2);
+  });
+
+  it('tooth stroke width reflects isDelimiting (NORMAL vs 3× DELIMITING)', () => {
+    const svg = makeSvg();
+    /* All members required/exactly_one, but only the second is delimiting.
+       Expected tooth widths: NORMAL, DELIMITING (3×), NORMAL. */
+    const rel = makeRelation({
+      partitives: [
+        member('https://example.org/vim-2012/concept/1.4'),
+        member('https://example.org/vim-2012/concept/1.5', { isDelimiting: true }),
+        member('https://example.org/vim-2012/concept/1.22'),
+      ],
+    });
+    drawRakeBundles(svg, pos, {
+      isDark: false,
+      color: '#0d9488',
+      isMuted: false,
+      relations: [rel],
+    });
+    const segs = Array.from(svg.querySelectorAll('line.rake-seg'));
+    const widths = segs.map(s => parseFloat(s.getAttribute('stroke-width')!));
+    /* Stem + spine are 1.4; non-delimiting teeth are NORMAL (1.5);
+       delimiting teeth are DELIMITING (4.5). */
+    expect(widths.filter(w => Math.abs(w - NORMAL_STROKE_WIDTH) < 0.01).length).toBe(2);
+    expect(widths.filter(w => Math.abs(w - DELIMITING_STROKE_WIDTH) < 0.01).length).toBe(1);
+  });
+
+  it('count=multiple renders 2 parallel tooth lines (lineCount=2)', () => {
+    const svg = makeSvg();
+    /* One member with count=multiple. Counting segments:
+       - 1 stem (FRAME)
+       - 1 spine (FRAME) — only if spine extents > 1px; with a single
+         member the spine is degenerate (zero length). The renderer
+         guards with `if (Math.abs(maxAlong - minAlong) > 1)`, so spine
+         is skipped for single-member input.
+       - 2 tooth lines (lineCount=2 for count=multiple).
+       Total: 1 stem + 2 teeth = 3 segments. */
+    const rel = makeRelation({
+      partitives: [
+        member('https://example.org/vim-2012/concept/1.4', { count: 'multiple' }),
+        member('https://example.org/vim-2012/concept/1.5', { count: 'multiple' }),
+      ],
+    });
+    drawRakeBundles(svg, pos, {
+      isDark: false,
+      color: '#0d9488',
+      isMuted: false,
+      relations: [rel],
+    });
+    const segs = svg.querySelectorAll('line.rake-seg');
+    /* 2 members × 2 lines each = 4 teeth, + 1 stem + 1 spine = 6. */
+    expect(segs.length).toBe(6);
+  });
+
+  it('presence=optional makes the tooth dashed', () => {
+    const svg = makeSvg();
+    const rel = makeRelation({
+      partitives: [
+        member('https://example.org/vim-2012/concept/1.4', { presence: 'optional' }),
+        member('https://example.org/vim-2012/concept/1.5', { presence: 'required' }),
+      ],
+    });
+    drawRakeBundles(svg, pos, {
+      isDark: false,
+      color: '#0d9488',
+      isMuted: false,
+      relations: [rel],
+    });
+    const segs = Array.from(svg.querySelectorAll('line.rake-seg'));
+    /* Teeth are the segments at NORMAL_STROKE_WIDTH (1.5) — frame
+       segments are at 1.4. Filter to teeth, then check dash pattern. */
+    const teeth = segs.filter(s => Math.abs(parseFloat(s.getAttribute('stroke-width')!) - NORMAL_STROKE_WIDTH) < 0.01);
+    expect(teeth.length).toBeGreaterThanOrEqual(2);
+    /* presence=optional tooth is dashed; presence=required is solid.
+       At least one dashed, at least one solid. */
+    const dashed = teeth.filter(t => t.getAttribute('stroke-dasharray'));
+    const solid = teeth.filter(t => !t.getAttribute('stroke-dasharray'));
+    expect(dashed.length).toBeGreaterThanOrEqual(1);
+    expect(solid.length).toBeGreaterThanOrEqual(1);
+  });
+
+  it('partial completeness extends the spine beyond the member bounding box', () => {
+    /* Members at x = {30, 120, 210}; their bbox X is [30, 210].
+       With completeness='partial', PARTIAL_TAIL (28px) is appended to
+       the spine extent — so the spine endpoint must land OUTSIDE [30, 210].
+       With completeness='complete' the spine stays inside the bbox. */
+    const members = [
+      member('https://example.org/vim-2012/concept/1.4'),
+      member('https://example.org/vim-2012/concept/1.5'),
+      member('https://example.org/vim-2012/concept/1.22'),
+    ];
+    const completeSvg = makeSvg();
+    const partialSvg = makeSvg();
+    drawRakeBundles(completeSvg, pos, {
+      isDark: false, color: '#0d9488', isMuted: false,
+      relations: [makeRelation({ completeness: 'complete', partitives: members })],
+    });
+    drawRakeBundles(partialSvg, pos, {
+      isDark: false, color: '#0d9488', isMuted: false,
+      relations: [makeRelation({ completeness: 'partial', partitives: members })],
+    });
+    /* Frame-width (1.4) segments are stem + spine. For complete, all
+       spine frame-segment endpoints lie within the member X bbox [30,210].
+       For partial, at least one endpoint lies outside. */
+    const isFrame = (s: Element) => Math.abs(parseFloat(s.getAttribute('stroke-width')!) - 1.4) < 0.01;
+    const endpointsOutsideBbox = (svg: SVGSVGElement) => {
+      return Array.from(svg.querySelectorAll('line.rake-seg'))
+        .filter(isFrame)
+        .some(s => {
+          const x1 = parseFloat(s.getAttribute('x1')!);
+          const x2 = parseFloat(s.getAttribute('x2')!);
+          return x1 < 30 || x1 > 210 || x2 < 30 || x2 > 210;
+        });
+    };
+    expect(endpointsOutsideBbox(completeSvg)).toBe(false);
+    expect(endpointsOutsideBbox(partialSvg)).toBe(true);
+  });
+
+  it('renders a degenerate rake (stem + 1 tooth, no spine) when only 1 member has a position', () => {
+    /* The renderer does not enforce ≥2 members — the model layer does.
+       Given 1 member, the rake produces a stem and a single tooth, no
+       spine (maxAlong - minAlong = 0, so the spine is skipped). */
+    const svg = makeSvg();
+    const sparsePos = new Map<string, { x: number; y: number }>([
+      ['vim-2012/1.3', { x: 120, y: 20 }],
+      ['vim-2012/1.4', { x: 30, y: 140 }],
+      /* 1.5 and 1.22 missing — only 1 member with a position */
+    ]);
+    drawRakeBundles(svg, sparsePos, {
+      isDark: false, color: '#0d9488', isMuted: false,
+      relations: [makeRelation()],
+    });
+    /* 1 stem (frame) + 1 tooth (normal) = 2 segments. */
+    expect(svg.querySelectorAll('line.rake-seg').length).toBe(2);
+    expect(svg.querySelectorAll('circle.rake-junction').length).toBe(1);
+  });
+
+  it('skips the relation entirely when the comprehensive is missing from pos', () => {
+    const svg = makeSvg();
+    const sparsePos = new Map<string, { x: number; y: number }>([
+      ['vim-2012/1.4', { x: 30, y: 140 }],
+      ['vim-2012/1.5', { x: 120, y: 140 }],
+      /* comprehensive 1.3 missing — compPos lookup fails, relation skipped */
+    ]);
+    drawRakeBundles(svg, sparsePos, {
+      isDark: false, color: '#0d9488', isMuted: false,
+      relations: [makeRelation()],
+    });
+    expect(svg.querySelectorAll('line.rake-seg').length).toBe(0);
+    expect(svg.querySelectorAll('circle.rake-junction').length).toBe(0);
+    expect(svg.querySelectorAll('path').length).toBe(0);
+  });
+
+  it('renders a separate junction + diamond per relation when multiple are present', () => {
+    const svg = makeSvg();
+    /* Two distinct comprehensives → two rake bundles. */
+    const multiPos = new Map<string, { x: number; y: number }>([
+      ['vim-2012/1.3', { x: 60, y: 20 }],
+      ['vim-2012/1.4', { x: 30, y: 140 }],
+      ['vim-2012/1.5', { x: 90, y: 140 }],
+      ['vim-2012/2.9', { x: 180, y: 20 }],
+      ['vim-2012/2.10', { x: 150, y: 140 }],
+      ['vim-2012/2.26', { x: 210, y: 140 }],
+    ]);
+    drawRakeBundles(svg, multiPos, {
+      isDark: false, color: '#0d9488', isMuted: false,
+      relations: [
+        makeRelation({
+          comprehensive: 'https://example.org/vim-2012/concept/1.3',
+          source: 'https://example.org/vim-2012/concept/1.3',
+          partitives: [
+            member('https://example.org/vim-2012/concept/1.4'),
+            member('https://example.org/vim-2012/concept/1.5'),
+          ],
+        }),
+        makeRelation({
+          comprehensive: 'https://example.org/vim-2012/concept/2.9',
+          source: 'https://example.org/vim-2012/concept/2.9',
+          partitives: [
+            member('https://example.org/vim-2012/concept/2.10'),
+            member('https://example.org/vim-2012/concept/2.26'),
+          ],
+        }),
+      ],
+    });
+    expect(svg.querySelectorAll('circle.rake-junction').length).toBe(2);
+    expect(svg.querySelectorAll('path').length).toBe(2);
+  });
+});

package/src/__tests__/views/relation-types-view.test.ts

@@ -0,0 +1,85 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { mount } from '@vue/test-utils';
+import { createPinia, setActivePinia } from 'pinia';
+import { createRouter, createMemoryHistory } from 'vue-router';
+import RelationTypesView from '../../views/RelationTypesView.vue';
+
+/**
+ * Smoke + structure tests for the Relation Types teaching page.
+ *
+ * Hyperedge section: 2 cards (partitive + general) with anchors.
+ * Bilateral section: at least one category with type rows.
+ */
+async function makeRouter() {
+  const router = createRouter({
+    history: createMemoryHistory(),
+    routes: [
+      { path: '/', name: 'home', component: { template: '<div/>' } },
+      { path: '/relation-types', name: 'relation-types', component: RelationTypesView },
+    ],
+  });
+  await router.push('/relation-types');
+  await router.isReady();
+  return router;
+}
+
+describe('RelationTypesView', () => {
+  beforeEach(() => {
+    setActivePinia(createPinia());
+  });
+
+  it('renders the page header with translated title', async () => {
+    const router = await makeRouter();
+    const w = mount(RelationTypesView, { global: { plugins: [router] } });
+    expect(w.find('h1').text()).toContain('Relation Types');
+  });
+
+  it('renders both hyperedge cards with the expected anchors', async () => {
+    const router = await makeRouter();
+    const w = mount(RelationTypesView, { global: { plugins: [router] } });
+    const cards = w.findAll('.hyperedge-card');
+    expect(cards.length).toBe(2);
+    const ids = cards.map(c => c.attributes('id'));
+    expect(ids).toContain('__partitive__');
+    expect(ids).toContain('__generic__');
+  });
+
+  it('renders a HyperedgeDiagram child for each card', async () => {
+    const router = await makeRouter();
+    const w = mount(RelationTypesView, { global: { plugins: [router] } });
+    /* The HyperedgeDiagram component renders an <svg class="hyperedge-diagram"> */
+    expect(w.findAll('svg.hyperedge-diagram').length).toBe(2);
+  });
+
+  it('renders the bilateral section grouped by category', async () => {
+    const router = await makeRouter();
+    const w = mount(RelationTypesView, { global: { plugins: [router] } });
+    const bilateralArticles = w.findAll('section[aria-label="Bilateral relations (one-to-one)"] article');
+    /* The taxonomy has ≥5 categories (hierarchical, associative, lifecycle, …). */
+    expect(bilateralArticles.length).toBeGreaterThanOrEqual(5);
+  });
+
+  it('every bilateral type row has an id anchor matching the type key', async () => {
+    const router = await makeRouter();
+    const w = mount(RelationTypesView, { global: { plugins: [router] } });
+    const rows = w.findAll('.bilateral-row');
+    expect(rows.length).toBeGreaterThan(10); /* taxonomy has ~40 types */
+    for (const row of rows) {
+      const id = row.attributes('id');
+      expect(id).toBeTruthy();
+      expect(id).toMatch(/^[a-z_]+$/);
+    }
+  });
+
+  it('renders label + ISO standard + definition for each hyperedge card', async () => {
+    const router = await makeRouter();
+    const w = mount(RelationTypesView, { global: { plugins: [router] } });
+    const cards = w.findAll('.hyperedge-card');
+    for (const card of cards) {
+      /* Label is the h3 heading; ISO reference is a mono span; definition is a paragraph. */
+      expect(card.find('h3').text()).toBeTruthy();
+      expect(card.find('span.font-mono').text()).toMatch(/ISO 704/);
+      expect(card.find('p').text().length).toBeGreaterThan(20);
+    }
+  });
+});

package/src/components/HyperedgeDiagram.vue

@@ -0,0 +1,115 @@
+<script setup lang="ts">
+/**
+ * HyperedgeDiagram — small inline SVG that calls the actual sphere
+ * renderers (drawRakeBundles / drawGenericPipes) on hand-picked
+ * sample data. Used on the Relation Types teaching page.
+ *
+ * The diagrams stay in sync with the real sphere rendering by
+ * construction — no static SVG to drift out of date.
+ */
+import { onMounted, ref } from 'vue';
+import { drawRakeBundles } from './relation-sphere/rake-bundles';
+import { drawGenericPipes } from './relation-sphere/pipe-bundles';
+import type {
+  PartitiveRelationWire,
+  PartitiveMemberWire,
+  GenericRelationWire,
+} from '../adapters/types';
+import { useUiStore } from '../stores/ui';
+
+const props = defineProps<{
+  kind: 'partitive' | 'generic';
+}>();
+
+const svgRef = ref<SVGSVGElement | null>(null);
+const uiStore = useUiStore();
+
+/* Synthetic positions: comp at top-center, members fanned across the
+   bottom. Mirrors the layout the sphere produces for a 3-member
+   hyperedge with the focus at the center. */
+const POS = new Map<string, { x: number; y: number }>([
+  ['vim-2012/1.3', { x: 120, y: 24 }],
+  ['vim-2012/1.4', { x: 36, y: 132 }],
+  ['vim-2012/1.5', { x: 120, y: 144 }],
+  ['vim-2012/1.22', { x: 204, y: 132 }],
+]);
+
+const PARTITIVE: PartitiveRelationWire = {
+  source: 'https://example.org/vim-2012/concept/1.3',
+  comprehensive: 'https://example.org/vim-2012/concept/1.3',
+  completeness: 'partial',
+  register: 'vim-2012',
+  partitives: [
+    /* required + multiple → solid double-line */
+    { uri: 'https://example.org/vim-2012/concept/1.4', presence: 'required', count: 'multiple', isDelimiting: false },
+    /* required + exactly_one + delimiting → 3× width single solid */
+    { uri: 'https://example.org/vim-2012/concept/1.5', presence: 'required', count: 'exactly_one', isDelimiting: true },
+    /* optional + at_least_one → dashed double-line */
+    { uri: 'https://example.org/vim-2012/concept/1.22', presence: 'optional', count: 'at_least_one', isDelimiting: false },
+  ] satisfies PartitiveMemberWire[],
+};
+
+const GENERIC: GenericRelationWire = {
+  source: 'https://example.org/vim-2012/concept/1.9',
+  comprehensive: 'https://example.org/vim-2012/concept/1.9',
+  completeness: 'partial',
+  register: 'vim-2012',
+  criterion: { eng: 'by magnitude relationship', fra: 'selon la relation de grandeur' },
+  members: [
+    { uri: 'https://example.org/vim-2012/concept/1.17', presence: 'required', count: 'at_least_one',
+      delimitingCharacteristic: { eng: 'multiple of a unit', fra: "multiple d'une unité" } },
+    { uri: 'https://example.org/vim-2012/concept/1.18', presence: 'required', count: 'at_least_one',
+      delimitingCharacteristic: { eng: 'submultiple of a unit', fra: "sous-multiple d'une unité" } },
+    { uri: 'https://example.org/vim-2012/concept/1.12', presence: 'required', count: 'at_least_one',
+      delimitingCharacteristic: { eng: 'coherent derived unit', fra: 'unité dérivée cohérente' } },
+  ],
+};
+
+/* Override positions for the generic sample (comp is 1.9, members are 1.17/1.18/1.12). */
+const GENERIC_POS = new Map<string, { x: number; y: number }>([
+  ['vim-2012/1.9', { x: 120, y: 24 }],
+  ['vim-2012/1.17', { x: 36, y: 132 }],
+  ['vim-2012/1.18', { x: 120, y: 144 }],
+  ['vim-2012/1.12', { x: 204, y: 132 }],
+]);
+
+onMounted(() => {
+  const svg = svgRef.value;
+  if (!svg) return;
+  if (props.kind === 'partitive') {
+    drawRakeBundles(svg, POS, {
+      isDark: uiStore.isDark,
+      color: uiStore.isDark ? '#2dd4bf' : '#0d9488',
+      isMuted: false,
+      relations: [PARTITIVE],
+    });
+  } else {
+    drawGenericPipes(svg, GENERIC_POS, {
+      isDark: uiStore.isDark,
+      color: uiStore.isDark ? '#fbbf24' : '#b45309',
+      isMuted: false,
+      relations: [GENERIC],
+      locale: 'eng',
+    });
+  }
+});
+</script>
+
+<template>
+  <svg
+    ref="svgRef"
+    class="hyperedge-diagram"
+    viewBox="0 0 240 168"
+    xmlns="http://www.w3.org/2000/svg"
+    aria-hidden="true"
+  />
+</template>
+
+<style scoped>
+.hyperedge-diagram {
+  width: 100%;
+  max-width: 240px;
+  height: auto;
+  display: block;
+}
+</style>

package/src/components/RelationSphere.vue

@@ -1068,7 +1068,7 @@ const legendItems = computed(() => {
   if (partitiveCount > 0) {
     typeMap.set('__partitive__', {
       type: '__partitive__',
-      label: 'Partitive Relation',
+      label: 'partitive relation',
       color: uiStore.isDark ? '#2dd4bf' : '#0d9488',
       count: partitiveCount,
     });
@@ -1078,7 +1078,7 @@ const legendItems = computed(() => {
   if (genericCount > 0) {
     typeMap.set('__generic__', {
       type: '__generic__',
-      label: 'General Relation',
+      label: 'general relation',
       color: uiStore.isDark ? '#fbbf24' : '#b45309',
       count: genericCount,
     });
@@ -1405,16 +1405,23 @@ defineExpose({ navigate });
         <div v-if="legendItems.length" class="sp-section">
           <div class="sp-section-label">{{ t('sphere.relationTypes') }}</div>
           <div class="sp-legend-grid">
-            <button v-for="item in legendItems" :key="item.type" class="sp-legend-item"
+            <div v-for="item in legendItems" :key="item.type"
+              class="sp-legend-item"
               :class="{ muted: isTypeMuted(item.type), 'is-partitive': item.type === '__partitive__' }"
-              @click="toggleType(item.type)"
-              :title="item.type">
-              <span v-if="item.type === '__partitive__'" class="sp-swatch sp-swatch-rake"
-                :style="{ '--rake-color': isTypeMuted(item.type) ? '#b8b9cc' : item.color }"></span>
-              <span v-else class="sp-swatch" :style="{ background: isTypeMuted(item.type) ? '#b8b9cc' : item.color }"></span>
-              <span>{{ item.label }}</span>
-              <span class="sp-count">{{ item.count }}</span>
-            </button>
+            >
+              <button class="sp-legend-toggle"
+                @click="toggleType(item.type)"
+                :title="item.type"
+                :aria-label="`${t('sphere.toggleMute')}: ${item.label}`">
+                <span v-if="item.type === '__partitive__'" class="sp-swatch sp-swatch-rake"
+                  :style="{ '--rake-color': isTypeMuted(item.type) ? '#b8b9cc' : item.color }"></span>
+                <span v-else class="sp-swatch" :style="{ background: isTypeMuted(item.type) ? '#b8b9cc' : item.color }"></span>
+                <span class="sp-count">{{ item.count }}</span>
+              </button>
+              <router-link class="sp-legend-label"
+                :to="{ name: 'relation-types', hash: '#' + item.type }"
+                :title="t('sphere.learnAbout') + ': ' + item.label">{{ item.label }}</router-link>
+            </div>
           </div>
         </div>
 
@@ -1653,12 +1660,22 @@ defineExpose({ navigate });
 /* Type legend */
 .sp-legend-grid { display: flex; flex-direction: column; gap: 2px; }
 .sp-legend-item {
-  display: flex; align-items: center; gap: 8px; padding: 3px 6px; border-radius: 3px;
-  cursor: pointer; border: 1px solid transparent; background: transparent; text-align: left;
+  display: flex; align-items: center; gap: 6px; padding: 3px 6px; border-radius: 3px;
+  border: 1px solid transparent; background: transparent; text-align: left;
   width: 100%; font-family: inherit; font-size: 11px; color: var(--ink-mute);
 }
 .sp-legend-item:hover { background: var(--rule); }
 .sp-legend-item.muted { opacity: 0.35; }
+.sp-legend-toggle {
+  display: inline-flex; align-items: center; gap: 6px; flex-shrink: 0;
+  cursor: pointer; border: none; background: transparent; padding: 0;
+  font: inherit; color: inherit;
+}
+.sp-legend-label {
+  color: inherit; text-decoration: none; flex: 1; min-width: 0;
+  overflow: hidden; text-overflow: ellipsis; white-space: nowrap;
+}
+.sp-legend-label:hover { text-decoration: underline; }
 .sp-swatch { width: 18px; height: 2px; flex-shrink: 0; border-radius: 1px; }
 /* Rake swatch — small bracket icon signaling a PartitiveRelation hyperedge
    (not a single binary edge). Two parallel solid lines (close-set double)

package/src/components/relation-sphere/pipe-bundles.ts

@@ -20,10 +20,13 @@
  *      the rake code with isDelimiting=true on all members, which made
  *      the children THICKER than the parent — backwards.)
  *
- *   3. Per-member delimiting characteristic text is rendered along each
- *      thread (ISO 704 §5.5.4.2.1 — the intension difference that
- *      distinguishes each coordinate concept). The optional group-level
- *      `criterion` is shown at the middle node.
+ *   3. Characteristic label — the criterion is a single hyperedge-level
+ *      field shared by all members (the dimension along which they
+ *      differ), rendered once on the pipe body. Optional: when the
+ *      criterion is absent, no label is shown at all. Per-member
+ *      delimitingCharacteristic is NOT labeled here — those values
+ *      distinguish each member but are not "the characteristic of
+ *      the hyperedge".
  *
  * Pure DOM/geometry — no Vue reactivity, no d3 state. The caller passes
  * the generic relations, position map, and rendering context.
@@ -58,8 +61,8 @@ interface NodePos { x: number; y: number }
  *
  * Each relation produces: 1 thick pipe (comp → middle), N thin threads
  * (middle → each member), 1 junction square at the middle node, 1
- * diamond at the comp end, optional criterion label at the middle,
- * optional delimiting-characteristic label per thread.
+ * diamond at the comp end, and — only when the hyperedge has a
+ * criterion — 1 characteristic label on the pipe body.
  */
 export function drawGenericPipes(
   svg: SVGSVGElement,
@@ -89,23 +92,15 @@ export function drawGenericPipes(
     const layout = computePipeLayout(compPos, memberPositions);
     if (!layout) continue;
 
-    /* 1. Thick parent pipe: comp → middle node */
+    /* 1. Thick parent pipe: comp → middle node. The characteristic
+          label (criterion) sits on the pipe body — see step 4. */
     drawSegment(svg, opts.color, layout.pipeStart, layout.pipeEnd, PIPE_WIDTH);
 
-    /* 2. Thin threads: middle → each member, with characteristic label */
+    /* 2. Thin threads: middle → each member. No per-thread labels —
+          the characteristic is a single hyperedge-level field shared
+          by all members, rendered once on the pipe body. */
     for (const thread of layout.threads) {
       drawSegment(svg, opts.color, thread.start, thread.end, THREAD_WIDTH);
-      const dcText = pickLocalized(thread.member.delimitingCharacteristic, opts.locale);
-      if (dcText) {
-        const midX = (thread.start.x + thread.end.x) / 2;
-        const midY = (thread.start.y + thread.end.y) / 2;
-        drawLabel(svg, midX, midY, dcText, opts.color, {
-          fontSize: 8.5,
-          italic: true,
-          bg: true,
-          isDark: opts.isDark,
-        });
-      }
     }
 
     /* 3. Square junction at the middle node (distinct from the rake's
@@ -113,7 +108,9 @@ export function drawGenericPipes(
           circle = partitive). */
     drawSquare(svg, layout.middleNode.x, layout.middleNode.y, JUNCTION_RADIUS, opts.color, contrastStroke);
 
-    /* 4. Group-level criterion label, if present */
+    /* 4. Characteristic label — single, hyperedge-level, optional.
+          Drawn on the pipe body (midpoint between comp and middle node).
+          When criterion is absent, no label is rendered at all. */
     const critText = pickLocalized(rel.criterion, opts.locale);
     if (critText) {
       const midX = (layout.pipeStart.x + layout.pipeEnd.x) / 2;

package/src/config/page-types.ts

@@ -35,6 +35,7 @@ export const PAGE_TYPES: readonly PageTypeDefinition[] = [
   { type: 'stats',      route: 'stats',   title: 'Statistics',   icon: 'chart',      scope: 'dataset', featureFlag: '!stats',     autoSynthesize: true },
   { type: 'sources',    route: 'sources', title: 'Sources',      icon: 'database',   scope: 'dataset', autoSynthesize: true },
   { type: 'about',      route: 'about',   title: 'About',        icon: 'info',       scope: 'dataset', featureFlag: '!about',     autoSynthesize: true },
+  { type: 'relation-types', route: 'relation-types', title: 'Relation Types', icon: 'schema', scope: 'global', autoSynthesize: true },
 ] as const;
 
 export type BuiltinPageType = typeof PAGE_TYPES[number]['type'];

package/src/i18n/locales/eng.yml

@@ -12,6 +12,17 @@ nav.about: About
 nav.sources: Sources
 nav.navigation: Navigation
 nav.datasets: Datasets
+nav.relationTypes: Relation Types
+
+# Relation Types teaching page
+relationTypes.intro: What each line shape and label means in this site. Diagrams use the same renderers as the Relation Sphere, so what you see here is what you'll see in the wild.
+relationTypes.hyperedgeSection: Hyperedge relations (one-to-many)
+relationTypes.bilateralSection: Bilateral relations (one-to-one)
+relationTypes.isoStandard: ISO standard
+relationTypes.example: Example
+relationTypes.category: Category
+relationTypes.diagram: Diagram
+relationTypes.notInDataset: Not used in the current dataset
 
 # Home page
 home.search: Search
@@ -213,6 +224,8 @@ sphere.tight: tight
 sphere.loose: loose
 sphere.redraw: Redraw
 sphere.focus: FOCUS
+sphere.toggleMute: Toggle visibility
+sphere.learnAbout: Learn about this relation type
 concept.detailView: Detail
 concept.relationSphere: Relation Sphere
 concept.permalink: Permalink

package/src/i18n/locales/fra.yml

@@ -11,6 +11,17 @@ nav.stats: Statistiques
 nav.about: À propos
 nav.navigation: Navigation
 nav.datasets: Jeux de données
+nav.relationTypes: Types de relations
+
+# Page enseignante « Types de relations »
+relationTypes.intro: Ce que chaque forme de ligne et étiquette signifie sur ce site. Les diagrammes utilisent les mêmes rendus que la Sphère de relations — ce que vous voyez ici correspond à ce que vous verrez en navigation.
+relationTypes.hyperedgeSection: Relations hyper-arêtes (un-plusieurs)
+relationTypes.bilateralSection: Relations bilatérales (un-un)
+relationTypes.isoStandard: Norme ISO
+relationTypes.example: Exemple
+relationTypes.category: Catégorie
+relationTypes.diagram: Diagramme
+relationTypes.notInDataset: Non utilisé dans le jeu de données courant
 
 # Home page
 home.search: Rechercher
@@ -204,6 +215,8 @@ sphere.tight: serré
 sphere.loose: étendu
 sphere.redraw: Redessiner
 sphere.focus: FOCUS
+sphere.toggleMute: Basculer la visibilité
+sphere.learnAbout: En savoir plus sur ce type de relation
 concept.detailView: Détail
 concept.relationSphere: Sphère de relations
 concept.permalink: Permalien

package/src/router/index.ts

@@ -94,6 +94,11 @@ export const routes: RouteRecordRaw[] = [
     name: 'contributors',
     component: () => import('../views/ContributorsView.vue'),
   },
+  {
+    path: '/relation-types',
+    name: 'relation-types',
+    component: () => import('../views/RelationTypesView.vue'),
+  },
   {
     path: '/about',
     name: 'about-global',

package/src/views/RelationTypesView.vue

@@ -0,0 +1,159 @@
+<script setup lang="ts">
+/**
+ * RelationTypesView — teaching page explaining every relation type
+ * the app renders, grouped into:
+ *
+ *   1. Hyperedge relations (one-to-many decompositions)
+ *      - partitive (rake diagram) — ISO 704:2022 §5.5.3
+ *      - general  (pipe-and-thread diagram) — ISO 704:2022 §5.5.4
+ *
+ *   2. Bilateral relations (one-to-one) — grouped by category, labels
+ *      and definitions pulled from the live ontology taxonomy. Adding
+ *      a new type to src/data/taxonomies.json automatically flows
+ *      through to this page (no code change).
+ *
+ * Sphere legend labels deep-link here via `#<type>` anchors
+ * (e.g. `#__generic__`, `#__partitive__`, `#broader_generic`).
+ */
+import { computed } from 'vue';
+import { useI18n } from '../i18n';
+import {
+  RELATIONSHIP_CATEGORIES,
+  relationshipLabel,
+  relationshipDefinition,
+} from '../utils/relationship-categories';
+import HyperedgeDiagram from '../components/HyperedgeDiagram.vue';
+
+const { t } = useI18n();
+
+interface HyperedgeCard {
+  readonly anchor: string;
+  readonly kind: 'partitive' | 'generic';
+  readonly label: string;
+  readonly iso: string;
+  readonly definition: string;
+  readonly example: { conceptId: string; description: string };
+}
+
+const HYPEREDGE_CARDS: readonly HyperedgeCard[] = [
+  {
+    anchor: '__partitive__',
+    kind: 'partitive',
+    label: 'partitive relation',
+    iso: 'ISO 704:2022 §5.5.3',
+    definition:
+      'A whole/part decomposition. The comprehensive concept is the whole; each member is a part. Per-member multiplicity (presence × count) is encoded in the tooth stroke style — solid for required, dashed for optional, double-line for multiple or at-least-one, 3× width for delimiting members.',
+    example: { conceptId: '1.3', description: 'system of quantities' },
+  },
+  {
+    anchor: '__generic__',
+    kind: 'generic',
+    label: 'general relation',
+    iso: 'ISO 704:2022 §5.5.4',
+    definition:
+      'A genus/species decomposition. The comprehensive concept is the genus; each member is a species (coordinate concept) differing along a shared dimension. The thick parent pipe carries the shared criterion (the dimension); thin direct threads radiate from a middle node to each member.',
+    example: { conceptId: '1.9', description: 'measurement unit' },
+  },
+];
+
+const bilateralCategories = computed(() =>
+  RELATIONSHIP_CATEGORIES.map(cat => ({
+    id: cat.id,
+    label: cat.label,
+    color: cat.color,
+    types: cat.types.map(type => ({
+      type,
+      label: relationshipLabel(type),
+      definition: relationshipDefinition(type),
+    })),
+  })),
+);
+</script>
+
+<template>
+  <div class="relation-types-view max-w-5xl mx-auto px-4 py-8">
+    <header class="mb-8">
+      <h1 class="text-3xl font-serif text-ink-800 dark:text-ink-50 mb-2">
+        {{ t('nav.relationTypes') }}
+      </h1>
+      <p class="text-ink-500 dark:text-ink-300">{{ t('relationTypes.intro') }}</p>
+    </header>
+
+    <!-- ── Hyperedge relations ─────────────────────────────────────── -->
+    <section class="mb-12" :aria-label="t('relationTypes.hyperedgeSection')">
+      <h2 class="text-xl font-semibold text-ink-700 dark:text-ink-100 mb-4 border-b border-ink-100 dark:border-ink-700 pb-2">
+        {{ t('relationTypes.hyperedgeSection') }}
+      </h2>
+      <div class="grid grid-cols-1 lg:grid-cols-2 gap-6">
+        <article
+          v-for="card in HYPEREDGE_CARDS"
+          :key="card.anchor"
+          :id="card.anchor"
+          class="hyperedge-card card p-5 scroll-mt-20"
+        >
+          <div class="flex items-baseline justify-between mb-3 gap-3">
+            <h3 class="text-lg font-semibold text-ink-800 dark:text-ink-50">{{ card.label }}</h3>
+            <span class="text-xs font-mono text-ink-400 dark:text-ink-500">{{ card.iso }}</span>
+          </div>
+          <div class="grid grid-cols-[auto_1fr] gap-4 items-start">
+            <div class="diagram-frame bg-surface-alt dark:bg-ink-800 rounded-md p-2 border border-ink-100 dark:border-ink-700">
+              <HyperedgeDiagram :kind="card.kind" />
+            </div>
+            <div>
+              <p class="text-sm text-ink-600 dark:text-ink-200 mb-3">{{ card.definition }}</p>
+              <p class="text-xs text-ink-400 dark:text-ink-400">
+                {{ t('relationTypes.example') }}: VIM {{ card.example.conceptId }} — {{ card.example.description }}
+              </p>
+            </div>
+          </div>
+        </article>
+      </div>
+    </section>
+
+    <!-- ── Bilateral relations ─────────────────────────────────────── -->
+    <section :aria-label="t('relationTypes.bilateralSection')">
+      <h2 class="text-xl font-semibold text-ink-700 dark:text-ink-100 mb-4 border-b border-ink-100 dark:border-ink-700 pb-2">
+        {{ t('relationTypes.bilateralSection') }}
+      </h2>
+      <div class="space-y-6">
+        <article
+          v-for="cat in bilateralCategories"
+          :key="cat.id"
+          class="card p-4"
+        >
+          <header class="flex items-center gap-2 mb-3">
+            <span :class="['text-xs font-semibold uppercase tracking-wide px-2 py-0.5 rounded', cat.color]">
+              {{ cat.label }}
+            </span>
+            <span class="text-xs text-ink-400">{{ cat.types.length }}</span>
+          </header>
+          <ul class="space-y-2">
+            <li
+              v-for="item in cat.types"
+              :key="item.type"
+              :id="item.type"
+              class="bilateral-row scroll-mt-20"
+            >
+              <div class="flex items-baseline gap-2 flex-wrap">
+                <span class="font-medium text-ink-800 dark:text-ink-100">{{ item.label }}</span>
+                <code class="text-xs text-ink-400 dark:text-ink-500 font-mono">{{ item.type }}</code>
+              </div>
+              <p v-if="item.definition" class="text-sm text-ink-600 dark:text-ink-300 mt-0.5">
+                {{ item.definition }}
+              </p>
+            </li>
+          </ul>
+        </article>
+      </div>
+    </section>
+  </div>
+</template>
+
+<style scoped>
+.hyperedge-card {
+  scroll-margin-top: 5rem;
+}
+.bilateral-row {
+  scroll-margin-top: 5rem;
+}
+</style>