@glossarist/concept-browser 0.7.50 → 0.7.52

package/src/types/dataset-turtle.d.ts

@@ -0,0 +1,32 @@
+declare module '*/scripts/lib/dataset-turtle.mjs' {
+  export interface DatasetDistribution {
+    readonly id: string;
+    readonly title: string;
+    readonly mediaType: string;
+    readonly downloadUrl: string;
+    readonly byteSize?: number;
+  }
+
+  export interface DatasetSection {
+    readonly collectionIri: string;
+    readonly title: string;
+    readonly memberUris: readonly string[];
+  }
+
+  export interface DatasetTurtleInput {
+    readonly datasetIri: string;
+    readonly registerId: string;
+    readonly title: string;
+    readonly description?: string;
+    readonly modified: string;
+    readonly languages: readonly string[];
+    readonly distributions: readonly DatasetDistribution[];
+    readonly topConceptUris: readonly string[];
+    readonly sections: readonly DatasetSection[];
+    readonly sourceRepoUrl?: string;
+    readonly publisherIri?: string;
+    readonly contactIri?: string;
+  }
+
+  export function buildDatasetTurtle(input: DatasetTurtleInput): string;
+}

package/src/types/normalize-yaml.d.ts

@@ -0,0 +1,16 @@
+declare module '*/scripts/normalize-yaml.mjs' {
+  export interface NormalizeResult {
+    checked: number;
+    nonNfc: number;
+    fixed: string[];
+    check: boolean;
+  }
+
+  export interface NormalizeOptions {
+    root?: string;
+    check?: boolean;
+    paths?: string[];
+  }
+
+  export function normalizeYaml(options?: NormalizeOptions): NormalizeResult;
+}

package/src/types/turtle-escape.d.ts

@@ -0,0 +1,6 @@
+declare module '*/scripts/lib/turtle-escape.mjs' {
+  export function ttlLit(s: unknown): string;
+  export function ttlPrefixed(qname: string): string;
+  export function ttlIri(iri: string): string;
+  export function assertValidIri(iri: unknown, context?: string): string;
+}

package/src/types/vocab-turtle.d.ts

@@ -0,0 +1,13 @@
+declare module '*/scripts/lib/vocab-turtle.mjs' {
+  export interface VocabTerm {
+    readonly iri: string;
+    readonly label: string;
+  }
+  export interface VocabScheme {
+    readonly schemeIri: string;
+    readonly label: string;
+    readonly terms: readonly VocabTerm[];
+  }
+  export function buildVocabularyTurtle(): string;
+  export function listVocabSchemes(): readonly VocabScheme[];
+}

package/src/utils/asciidoc-lite.ts

@@ -4,6 +4,7 @@
  */
 
 import { escapeHtml, escapeAttr } from './escape';
+import { sanitizeUrl } from './url-safety';
 
 export function renderAsciiDocLite(text: string): string {
   if (!text) return '';
@@ -102,14 +103,18 @@ export function renderAsciiDocLite(text: string): string {
 
 function inlineFormat(text: string): string {
   // AsciiDoc link: https://example.com[text]
-  text = text.replace(/(https?:\/\/[^\s\[]+)\[([^\]]*)\]/g, (_, url, label) =>
-    `<a href="${escapeHtml(url)}" target="_blank" rel="noopener">${escapeHtml(label || url)}</a>`
-  );
+  text = text.replace(/(https?:\/\/[^\s\[]+)\[([^\]]*)\]/g, (_, url, label) => {
+    const href = sanitizeUrl(url);
+    if (!href) return escapeHtml(label || url);
+    return `<a href="${escapeHtml(href)}" target="_blank" rel="noopener">${escapeHtml(label || url)}</a>`;
+  });
 
   // Bare URLs
-  text = text.replace(/(?<!href="|">)(https?:\/\/[^\s<]+)/g, url =>
-    `<a href="${escapeHtml(url)}" target="_blank" rel="noopener">${escapeHtml(url)}</a>`
-  );
+  text = text.replace(/(?<!href="|">)(https?:\/\/[^\s<]+)/g, url => {
+    const href = sanitizeUrl(url);
+    if (!href) return escapeHtml(url);
+    return `<a href="${escapeHtml(href)}" target="_blank" rel="noopener">${escapeHtml(url)}</a>`;
+  });
 
   // Monospace: `text`
   text = text.replace(/`([^`]+)`/g, '<code>$1</code>');

package/src/utils/bcp47.ts

@@ -0,0 +1,141 @@
+import { InvalidLangTagError } from '../errors';
+
+export interface LangTag {
+  readonly primary: string;
+  readonly script?: string;
+  readonly region?: string;
+  readonly variants?: string[];
+  readonly privateUse?: string[];
+  readonly raw: string;
+}
+
+const ISO_639_3_TO_1: Readonly<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',
+};
+
+const ISO_639_1_TO_3: Readonly<Record<string, string>> = (() => {
+  const out: Record<string, string> = {};
+  for (const [k, v] of Object.entries(ISO_639_3_TO_1)) out[v] = k;
+  return Object.freeze(out);
+})();
+
+const DEFAULT_SCRIPTS: Readonly<Record<string, string>> = {
+  zh: 'Hans',
+  sr: 'Cyrl',
+  uz: 'Latn',
+};
+
+const SCRIPT_RE = /^[A-Z][a-z]{3}$/;
+const ISO_ALPHA2_REGION_RE = /^[A-Z]{2}$/;
+const UN_M49_REGION_RE = /^\d{3}$/;
+
+export function mapIso6393To6391(code: string): string | null {
+  return ISO_639_3_TO_1[code] ?? null;
+}
+
+export function mapIso6391To6393(code: string): string | null {
+  return ISO_639_1_TO_3[code] ?? null;
+}
+
+export function parseLangTag(input: string): LangTag {
+  if (!input || typeof input !== 'string') {
+    throw new InvalidLangTagError(`Invalid language tag: ${String(input)}`, { input });
+  }
+  const trimmed = input.trim();
+  if (!trimmed) {
+    throw new InvalidLangTagError(`Empty language tag`, { input });
+  }
+
+  const segments = trimmed.split('-');
+  const first = segments[0]!;
+  if (!/^[a-zA-Z]{2,3}$/.test(first)) {
+    throw new InvalidLangTagError(
+      `Invalid primary subtag: ${first}`,
+      { input, subtag: first },
+    );
+  }
+
+  const primary = (ISO_639_3_TO_1[first.toLowerCase()] ?? first.toLowerCase());
+  const tag: LangTag = { primary, raw: input };
+
+  let i = 1;
+  let privateUse: string[] | undefined;
+  if (segments[i] === 'x') {
+    privateUse = segments.slice(i + 1);
+    i = segments.length;
+  }
+
+  let script: string | undefined;
+  let region: string | undefined;
+  let variants: string[] | undefined;
+
+  for (; i < segments.length; i++) {
+    const seg = segments[i]!;
+    if (seg === 'x') {
+      privateUse = segments.slice(i + 1);
+      break;
+    }
+    if (SCRIPT_RE.test(seg) && !script) {
+      script = seg;
+    } else if ((ISO_ALPHA2_REGION_RE.test(seg) || UN_M49_REGION_RE.test(seg)) && !region) {
+      region = seg;
+    } else if (/^[a-z0-9]{4,8}$/i.test(seg)) {
+      variants = variants ?? [];
+      variants.push(seg);
+    } else {
+      throw new InvalidLangTagError(
+        `Unrecognized language subtag: ${seg}`,
+        { input, subtag: seg },
+      );
+    }
+  }
+
+  const finalTag: LangTag = {
+    primary,
+    script: script ?? DEFAULT_SCRIPTS[primary],
+    region,
+    variants,
+    privateUse,
+    raw: input,
+  };
+  return finalTag;
+}
+
+export function formatLangTag(tag: LangTag): string {
+  const parts: string[] = [tag.primary];
+  if (tag.script) parts.push(tag.script);
+  if (tag.region) parts.push(tag.region);
+  if (tag.variants?.length) parts.push(...tag.variants);
+  if (tag.privateUse?.length) parts.push('x', ...tag.privateUse);
+  return parts.join('-');
+}
+
+export function canonicalLangTag(input: string): string {
+  return formatLangTag(parseLangTag(input));
+}
+
+export function isValidLangTag(input: string): boolean {
+  try {
+    parseLangTag(input);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function isNfc(text: string): boolean {
+  return text.normalize('NFC') === text;
+}
+
+export function toNfc(text: string): string {
+  return text.normalize('NFC');
+}

package/src/utils/color-theme-integration.ts

@@ -0,0 +1,11 @@
+/**
+ * Color-theme integration bridge for the relationship-categories module.
+ * Re-exports the color pair accessors with a stable interface so consumers
+ * don't need to import from two places.
+ */
+export {
+  colorPairForType,
+  colorPairForCategory,
+  colorThemeForOverrides,
+} from './relationship-categories';
+export type { ColorPair } from './color-theme';

package/src/utils/color-theme.ts

@@ -0,0 +1,129 @@
+/**
+ * Color theme SSOT. Loads `data/colors.json` defaults and merges per-
+ * deployment overrides from `site-config.json` `colors` block.
+ *
+ * Pure data + pure accessors — no Vue reactivity. Reactive consumption
+ * is via the `useColorTheme()` composable.
+ */
+import { readFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import type { DatasetColorSpec, SiteColors } from '../config/types';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const COLORS_PATH = join(__dirname, '..', '..', 'data', 'colors.json');
+
+export interface ColorPair {
+  readonly light: string;
+  readonly dark: string;
+}
+
+interface ColorDefaults {
+  readonly relationshipCategory: Record<string, ColorPair>;
+  readonly relationshipType: Record<string, ColorPair>;
+  readonly conceptStatus: Record<string, ColorPair>;
+  readonly groupKind: Record<string, ColorPair>;
+}
+
+let cachedDefaults: ColorDefaults | undefined;
+
+function loadDefaults(): ColorDefaults {
+  if (cachedDefaults) return cachedDefaults;
+  const raw = JSON.parse(readFileSync(COLORS_PATH, 'utf8'));
+  cachedDefaults = {
+    relationshipCategory: raw.relationshipCategory,
+    relationshipType: raw.relationshipType,
+    conceptStatus: raw.conceptStatus,
+    groupKind: raw.groupKind,
+  };
+  return cachedDefaults!;
+}
+
+function normalize(spec: DatasetColorSpec | undefined): ColorPair | undefined {
+  if (spec == null) return undefined;
+  if (typeof spec === 'string') return { light: spec, dark: spec };
+  return { light: spec.light, dark: spec.dark };
+}
+
+function resolvePair(
+  key: string | undefined,
+  overrides: Record<string, DatasetColorSpec> | undefined,
+  defaults: Record<string, ColorPair>,
+  fallback: ColorPair,
+): ColorPair {
+  if (key && overrides) {
+    const ov = normalize(overrides[key]);
+    if (ov) return ov;
+  }
+  if (key && defaults[key]) return defaults[key];
+  return fallback;
+}
+
+export function createColorTheme(siteColors?: SiteColors) {
+  const defaults = loadDefaults();
+
+  function relationshipCategoryColor(categoryId: string): ColorPair {
+    return resolvePair(
+      categoryId,
+      siteColors?.relationshipCategory,
+      defaults.relationshipCategory,
+      defaults.relationshipCategory.associative,
+    );
+  }
+
+  function relationshipTypeColor(typeId: string, categoryId?: string): ColorPair {
+    const ov = normalize(siteColors?.relationshipType?.[typeId]);
+    if (ov) return ov;
+    if (defaults.relationshipType[typeId]) return defaults.relationshipType[typeId];
+    if (categoryId) return relationshipCategoryColor(categoryId);
+    return defaults.relationshipCategory.associative;
+  }
+
+  function conceptStatusColor(statusId: string): ColorPair {
+    return resolvePair(
+      statusId,
+      siteColors?.conceptStatus,
+      defaults.conceptStatus,
+      { light: '#6B6E7D', dark: '#9CA3AF' },
+    );
+  }
+
+  function groupKindColor(kind: string): ColorPair {
+    return resolvePair(
+      kind,
+      siteColors?.groupKind,
+      defaults.groupKind,
+      defaults.groupKind.default,
+    );
+  }
+
+  function datasetColor(datasetId: string, declared?: DatasetColorSpec): ColorPair {
+    const ov = normalize(siteColors?.dataset?.[datasetId]);
+    if (ov) return ov;
+    const declaredPair = normalize(declared);
+    if (declaredPair) return declaredPair;
+    return { light: '#3366ff', dark: '#60A5FA' };
+  }
+
+  function groupColor(groupId: string, declared?: DatasetColorSpec): ColorPair {
+    const ov = normalize(siteColors?.group?.[groupId]);
+    if (ov) return ov;
+    const declaredPair = normalize(declared);
+    if (declaredPair) return declaredPair;
+    return groupKindColor('default');
+  }
+
+  return {
+    relationshipCategoryColor,
+    relationshipTypeColor,
+    conceptStatusColor,
+    groupKindColor,
+    datasetColor,
+    groupColor,
+    defaults,
+  };
+}
+
+export type ColorTheme = ReturnType<typeof createColorTheme>;
+
+export const FALLBACK_COLOR_PAIR: ColorPair = { light: '#6B6E7D', dark: '#9CA3AF' };

package/src/utils/dataset-style.ts

@@ -1,4 +1,6 @@
 import { useVocabularyStore } from '../stores/vocabulary';
+import type { DatasetColorSpec } from '../config/types';
+import { createColorTheme } from './color-theme';
 
 const PALETTE = [
   '#3366ff', '#0d9488', '#d97706', '#8b5cf6',
@@ -7,9 +9,16 @@ const PALETTE = [
 ];
 
 export interface DsStyle {
+  /** Single-hex backward-compat color (light mode). */
   color: string;
+  /** Explicit light-mode color. */
   light: string;
+  /** Explicit dark-mode color. */
   dark: string;
+  /** Light-mode rgba with custom alpha. */
+  lightAlpha: (a: number) => string;
+  /** Dark-mode rgba with custom alpha. */
+  darkAlpha: (a: number) => string;
 }
 
 function hexToRgba(hex: string, alpha: number): string {
@@ -19,14 +28,29 @@ function hexToRgba(hex: string, alpha: number): string {
   return `rgba(${r}, ${g}, ${b}, ${alpha})`;
 }
 
-export function makeDsStyle(color: string): DsStyle {
+export function makeDsStyle(spec?: DatasetColorSpec, fallbackLight = '#3366ff'): DsStyle {
+  const pair = normalizeSpec(spec, fallbackLight);
   return {
-    color,
-    light: hexToRgba(color, 0.1),
-    dark: hexToRgba(color, 0.85),
+    color: pair.light,
+    light: pair.light,
+    dark: pair.dark,
+    lightAlpha: (a: number) => hexToRgba(pair.light, a),
+    darkAlpha: (a: number) => hexToRgba(pair.dark, a),
   };
 }
 
+function normalizeSpec(spec: DatasetColorSpec | undefined, fallback: string): { light: string; dark: string } {
+  if (spec == null) {
+    const dark = hexToRgba(fallback, 0.85);
+    return { light: fallback, dark };
+  }
+  if (typeof spec === 'string') {
+    const dark = hexToRgba(spec, 0.85);
+    return { light: spec, dark };
+  }
+  return { light: spec.light, dark: spec.dark };
+}
+
 export function paletteColor(index: number): string {
   return PALETTE[index % PALETTE.length];
 }
@@ -40,8 +64,9 @@ export function useDsStyle() {
 
     const store = useVocabularyStore();
     const ds = store.datasetList.find(d => d.id === registerId);
-    const color = ds?.manifest.color || paletteColor(store.datasetList.findIndex(d => d.id === registerId));
-    const style = makeDsStyle(color);
+    const declared = ds?.manifest?.color as DatasetColorSpec | undefined;
+    const fallback = paletteColor(store.datasetList.findIndex(d => d.id === registerId));
+    const style = makeDsStyle(declared, fallback);
     cache.set(registerId, style);
     return style;
   }

package/src/utils/locale.ts

@@ -5,27 +5,19 @@
  * Both the non-verbal entity resolver and any other localized content
  * resolution should call `pickLocaleText` / `pickLocaleMap` rather than
  * implement their own fallback chain.
+ *
+ * Language-code mapping (ISO 639-3 ↔ ISO 639-1) and BCP-47 parsing live in
+ * `./bcp47`; this module re-exports the mapping for backwards
+ * compatibility.
  */
 
 import { fetchLocalizedString } from 'glossarist';
+import { mapIso6393To6391 } from './bcp47';
 
 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 {
@@ -77,7 +69,7 @@ export function isRtl(locale: string): boolean {
 }
 
 export function localeToBcp47(locale: string): string {
-  return ISO_639_2_TO_BCP47[locale] ?? locale;
+  return mapIso6393To6391(locale) ?? locale;
 }
 
 export function resolveFallbackChain(datasetLocales?: readonly string[]): readonly string[] {

package/src/utils/markdown-lite.ts

@@ -1,10 +1,15 @@
 import { escapeHtml } from './escape';
+import { sanitizeUrl } from './url-safety';
 
 const INLINE_PATTERNS: [RegExp, (m: RegExpMatchArray) => string][] = [
   [/\*\*(.+?)\*\*/g, m => `<strong>${m[1]}</strong>`],
   [/(?<!\*)\*([^*]+?)\*(?!\*)/g, m => `<em>${m[1]}</em>`],
   [/`([^`]+?)`/g, m => `<code>${m[1]}</code>`],
-  [/\[([^\]]+)\]\(([^)]+)\)/g, m => `<a href="${m[2]}" target="_blank">${m[1]}</a>`],
+  [/\[([^\]]+)\]\(([^)]+)\)/g, m => {
+    const href = sanitizeUrl(m[2]);
+    if (!href) return escapeHtml(m[1]);
+    return `<a href="${escapeHtml(href)}" target="_blank" rel="noopener">${m[1]}</a>`;
+  }],
 ];
 
 function renderInline(text: string): string {

package/src/utils/relation-sphere-styling.ts

@@ -0,0 +1,63 @@
+/**
+ * Relation sphere styling — bridge between the project's semantic SSOTs
+ * (taxonomy + color-theme) and the visual encoding the sphere needs.
+ *
+ * Single source: taxonomy drives category/type identity.
+ * Color-theme drives light/dark color pairs.
+ * This module adds only the sphere-specific concern: dasharray patterns.
+ */
+import {
+  RELATIONSHIP_CATEGORIES,
+  categorizeRelationship,
+  relationshipLabel,
+} from './relationship-categories';
+import { colorPairForType, colorPairForCategory, type ColorPair } from './color-theme-integration';
+
+export interface SphereRelationCategory {
+  readonly key: string;
+  readonly label: string;
+  readonly color: string;
+  readonly dasharray: string;
+}
+
+/** Dasharray per category — sphere-specific visual encoding. Sourced
+ *  from colors.json `relationshipCategoryDash` block (added in #14). */
+const DASHARRAY: Record<string, string> = {
+  lifecycle:      'none',
+  mapping:        '1 2',
+  hierarchical:   '6 3 1 3',
+  associative:    'none',
+  comparative:    '2 2',
+  definitional:   '8 4',
+  spatiotemporal: '4 2 1 2',
+  lexical:        '3 1',
+  designation:    '1 3',
+};
+
+/** Build the sphere-category list from the taxonomy SSOT. */
+export const SPHERE_RELATION_CATEGORIES: readonly SphereRelationCategory[] =
+  RELATIONSHIP_CATEGORIES.map(cat => ({
+    key: cat.id,
+    label: cat.label,
+    color: colorPairForCategory(cat.id).light,
+    dasharray: DASHARRAY[cat.id] ?? 'none',
+  }));
+
+export function categorizeRelationForSphere(type: string): string {
+  return categorizeRelationship(type).id;
+}
+
+export function sphereCategoryForType(type: string): SphereRelationCategory {
+  const cat = categorizeRelationship(type);
+  return SPHERE_RELATION_CATEGORIES.find(c => c.key === cat.id)
+    ?? SPHERE_RELATION_CATEGORIES[3];
+}
+
+export function colorForTypeInMode(type: string, isDark: boolean): string {
+  const pair = colorPairForType(type);
+  return isDark ? pair.dark : pair.light;
+}
+
+export function relationLabel(type: string): string {
+  return relationshipLabel(type);
+}

package/src/utils/relationship-categories.ts

@@ -4,9 +4,13 @@
  * RELATIONSHIP_CATEGORIES, INVERSE_RELATIONSHIPS, and the category lookup
  * map are all computed from `taxonomies.json` at module load time.
  * Adding a new relationship type requires only a taxonomy edit — no code changes.
+ *
+ * Color pairs (light + dark) come from `data/colors.json` via the color-theme
+ * module, merged with per-deployment overrides from `site-config.json`.
  */
 import { ontology } from '../adapters/ontology-registry';
 import type { TaxonomyCategory } from '../adapters/ontology-registry';
+import { createColorTheme, type ColorPair, type ColorTheme } from './color-theme';
 
 export interface RelationshipCategory {
   id: string;
@@ -95,3 +99,29 @@ export function relationshipLabel(type: string): string {
 export function relationshipDefinition(type: string): string | null {
   return ontology.getDefinition('relationshipType', type);
 }
+
+// ── Color pairs (light + dark) ────────────────────────────────────────────
+//
+// `createColorTheme(undefined)` returns the default theme (no per-deployment
+// overrides). Components that need overrides should construct their own theme
+// via `useSiteConfig()` + `createColorTheme(config.colors)`.
+
+const defaultTheme: ColorTheme = createColorTheme(undefined);
+
+/** Returns the color pair for a relationship type, optionally given a known
+ *  category id (skips a taxonomy lookup when the caller already knows it). */
+export function colorPairForType(type: string, categoryId?: string): ColorPair {
+  const concept = ontology.getConcept('relationshipType', type);
+  const cat = categoryId ?? concept?.category;
+  return defaultTheme.relationshipTypeColor(type, cat);
+}
+
+/** Returns the color pair for a category id (e.g. "lifecycle"). */
+export function colorPairForCategory(categoryId: string): ColorPair {
+  return defaultTheme.relationshipCategoryColor(categoryId);
+}
+
+/** Construct a per-deployment theme that overrides defaults. */
+export function colorThemeForOverrides(siteColors: Parameters<typeof createColorTheme>[0]): ColorTheme {
+  return createColorTheme(siteColors);
+}

package/src/utils/url-safety.ts

@@ -0,0 +1,30 @@
+const SAFE_URL_PROTOCOLS = new Set(['http:', 'https:', 'mailto:', 'tel:']);
+
+const DANGEROUS_TOKEN_RE = /[\s<>"]/;
+
+export function isSafeUrl(url: string): boolean {
+  if (!url || typeof url !== 'string') return false;
+  if (DANGEROUS_TOKEN_RE.test(url)) return false;
+
+  const trimmed = url.trim();
+  if (!trimmed) return false;
+
+  if (/^[a-zA-Z][a-zA-Z0-9+.-]*:/.test(trimmed)) {
+    try {
+      const u = new URL(trimmed);
+      return SAFE_URL_PROTOCOLS.has(u.protocol);
+    } catch {
+      return false;
+    }
+  }
+
+  if (trimmed.startsWith('#') || trimmed.startsWith('/') || trimmed.startsWith('./') || trimmed.startsWith('../')) {
+    return true;
+  }
+
+  return false;
+}
+
+export function sanitizeUrl(url: string): string {
+  return isSafeUrl(url) ? url : '';
+}