@birdapi/velinstyle 1.2.0 → 1.2.1

package/core/transparency/normalize.js

@@ -0,0 +1,125 @@
+import { deriveClaims, primaryLabel } from './claims.js';
+import { stableDisclosureId } from './registry.js';
+
+const PROVENANCE_KEYS = [
+  'createdBy', 'createdAt', 'reviewedAt', 'approvedBy', 'source', 'license', 'version', 'publishedAt',
+];
+
+/**
+ * Normalize a draft disclosure into a registry record.
+ * @param {Record<string, unknown>} draft
+ * @param {{ provider?: string, file?: string, lang?: 'en'|'de' }} [ctx]
+ */
+export function normalizeDisclosure(draft = {}, ctx = {}) {
+  const provider = String(draft.provider || ctx.provider || 'api');
+  const type = String(draft.type || 'ai').toLowerCase();
+  const status = draft.status != null ? String(draft.status).toLowerCase() : undefined;
+  const review = draft.review != null ? String(draft.review).toLowerCase() : undefined;
+  const provenance = normalizeProvenance(draft.provenance || draft);
+  if (draft.license && !provenance.license) provenance.license = String(draft.license);
+  if (draft.model && !provenance.source) provenance.source = `model:${draft.model}`;
+  if (draft.generated === true && !status) {
+    // generated flag without status
+  }
+  const resolvedStatus = status || (draft.generated === true ? 'generated' : undefined);
+  const claims = deriveClaims({
+    status: resolvedStatus,
+    review,
+    license: provenance.license,
+    claims: draft.claims,
+  });
+  const target = {
+    selector: draft.target?.selector || draft.selector || undefined,
+    tag: draft.target?.tag || draft.tag || undefined,
+    src: draft.target?.src || draft.src || undefined,
+    file: draft.target?.file || ctx.file || draft.file || undefined,
+  };
+  const id = stableDisclosureId({
+    id: draft.id || draft.velinTransparencyId,
+    selector: target.selector,
+    src: target.src,
+    tag: target.tag,
+    type,
+    file: target.file,
+  });
+  const lang = ctx.lang === 'de' ? 'de' : 'en';
+  const label = draft.label ? String(draft.label) : primaryLabel(claims, lang);
+  const updated = draft.updated || provenance.publishedAt || provenance.reviewedAt || provenance.createdAt || undefined;
+
+  return {
+    id,
+    type,
+    status: resolvedStatus,
+    review,
+    provider,
+    claims,
+    provenance,
+    updated,
+    label,
+    description: draft.description ? String(draft.description) : undefined,
+    renderer: draft.renderer || draft.overlay || 'badge',
+    tone: draft.tone || toneFromClaims(claims),
+    position: draft.position || 'top-right',
+    target,
+    meta: draft.meta && typeof draft.meta === 'object' ? draft.meta : undefined,
+  };
+}
+
+function normalizeProvenance(src = {}) {
+  /** @type {Record<string, string>} */
+  const out = {};
+  for (const key of PROVENANCE_KEYS) {
+    const v = src[key] ?? src[key.replace(/[A-Z]/g, (m) => `-${m.toLowerCase()}`)];
+    if (v != null && String(v).trim()) out[key] = String(v).trim();
+  }
+  // attribute-style aliases
+  if (src['created-by']) out.createdBy = String(src['created-by']);
+  if (src['created-at']) out.createdAt = String(src['created-at']);
+  if (src['reviewed-at']) out.reviewedAt = String(src['reviewed-at']);
+  if (src['approved-by']) out.approvedBy = String(src['approved-by']);
+  if (src['published-at']) out.publishedAt = String(src['published-at']);
+  return out;
+}
+
+function toneFromClaims(claims) {
+  if (claims.includes('ai.generated')) return 'generated';
+  if (claims.includes('review.verified') || claims.includes('trust.official')) return 'verified';
+  if (claims.includes('review.human')) return 'human';
+  if (claims.includes('ai.assisted')) return 'mixed';
+  return 'neutral';
+}
+
+/**
+ * Merge two records; higher priority (lower rank number) wins field-by-field.
+ * @param {import('./registry.js').DisclosureRecord} a
+ * @param {import('./registry.js').DisclosureRecord} b
+ * @param {(id: string) => number} rankFn
+ */
+export function mergeDisclosures(a, b, rankFn) {
+  const aRank = rankFn(a.provider);
+  const bRank = rankFn(b.provider);
+  const primary = aRank <= bRank ? a : b;
+  const secondary = aRank <= bRank ? b : a;
+  const conflictKeys = [];
+  for (const key of ['type', 'status', 'review']) {
+    if (secondary[key] && primary[key] && secondary[key] !== primary[key]) conflictKeys.push(key);
+  }
+  const claims = [...new Set([...(primary.claims || []), ...(secondary.claims || [])])];
+  const provenance = { ...secondary.provenance, ...primary.provenance };
+  return {
+    record: {
+      ...secondary,
+      ...primary,
+      claims,
+      provenance,
+      provider: primary.provider,
+      meta: {
+        ...(secondary.meta || {}),
+        ...(primary.meta || {}),
+        mergedFrom: [secondary.provider, primary.provider],
+        conflicts: conflictKeys,
+      },
+    },
+    conflicts: conflictKeys,
+  };
+}

package/core/transparency/policy.js

@@ -0,0 +1,105 @@
+/** Default and merge helpers for transparency policy. */
+
+/**
+ * Soft framework defaults so existing sites are not hard-failed by `velinstyle check`.
+ * Projects opt into strict media/provenance rules via velin.transparency.policy.json.
+ */
+export const DEFAULT_POLICY = {
+  media: {
+    images: 'optional',
+    videos: 'optional',
+    audio: 'optional',
+    text: 'optional',
+    pdf: 'optional',
+  },
+  rules: {
+    requireReview: false,
+    allowGenerated: true,
+    minimumStatus: null,
+    staleDays: 365,
+  },
+  provenance: {
+    required: [],
+    recommended: ['approvedBy', 'source', 'version', 'createdAt', 'license'],
+    images: { required: [] },
+    videos: { required: [] },
+    audio: { required: [] },
+    pdf: { required: [] },
+  },
+  providers: {
+    priority: ['api', 'json', 'meta', 'html'],
+  },
+};
+
+/** Strict example policy for teams that require disclosure on media. */
+export const STRICT_MEDIA_POLICY = {
+  media: {
+    images: 'required',
+    videos: 'required',
+    audio: 'required',
+    text: 'optional',
+    pdf: 'required',
+  },
+  provenance: {
+    required: [],
+    recommended: ['approvedBy', 'source', 'version'],
+    images: { required: ['createdAt', 'license', 'source'] },
+    videos: { required: ['createdAt'] },
+    audio: { required: ['createdAt'] },
+    pdf: { required: ['license'] },
+  },
+};
+
+/**
+ * @param {unknown} raw
+ */
+export function normalizePolicy(raw) {
+  const input = raw && typeof raw === 'object' ? raw : {};
+  const nested = input.policy && typeof input.policy === 'object' ? input.policy : input;
+  return {
+    media: { ...DEFAULT_POLICY.media, ...(nested.media || {}) },
+    rules: { ...DEFAULT_POLICY.rules, ...(nested.rules || {}) },
+    provenance: {
+      ...DEFAULT_POLICY.provenance,
+      ...(nested.provenance || {}),
+      images: { ...DEFAULT_POLICY.provenance.images, ...(nested.provenance?.images || {}) },
+      videos: { ...DEFAULT_POLICY.provenance.videos, ...(nested.provenance?.videos || {}) },
+      audio: { ...DEFAULT_POLICY.provenance.audio, ...(nested.provenance?.audio || {}) },
+      pdf: { ...DEFAULT_POLICY.provenance.pdf, ...(nested.provenance?.pdf || {}) },
+    },
+    providers: {
+      ...DEFAULT_POLICY.providers,
+      ...(nested.providers || {}),
+      priority: nested.providers?.priority || DEFAULT_POLICY.providers.priority,
+    },
+  };
+}
+
+/**
+ * @param {string} mediaKind images|videos|audio|text|pdf
+ * @param {ReturnType<typeof normalizePolicy>} policy
+ */
+export function mediaRequirement(mediaKind, policy) {
+  return policy.media[mediaKind] || 'optional';
+}
+
+/**
+ * @param {string} mediaKind
+ * @param {ReturnType<typeof normalizePolicy>} policy
+ */
+export function requiredProvenanceFields(mediaKind, policy) {
+  const base = policy.provenance.required || [];
+  const specific = policy.provenance[mediaKind]?.required || [];
+  return [...new Set([...base, ...specific])];
+}
+
+/**
+ * Provider priority index (lower = higher priority).
+ * @param {string} providerId
+ * @param {ReturnType<typeof normalizePolicy>} policy
+ */
+export function providerRank(providerId, policy) {
+  const list = policy.providers.priority || DEFAULT_POLICY.providers.priority;
+  const idx = list.indexOf(providerId);
+  return idx === -1 ? 999 : idx;
+}

package/core/transparency/providers.js

@@ -0,0 +1,235 @@
+import { normalizeDisclosure, mergeDisclosures } from './normalize.js';
+import { providerRank } from './policy.js';
+
+/** @type {Map<string, { collect: Function, apply?: Function }>} */
+const providers = new Map();
+
+export function registerTransparencyProvider(id, handler) {
+  if (!id || typeof handler?.collect !== 'function') {
+    throw new Error('registerTransparencyProvider requires id and collect()');
+  }
+  providers.set(id, handler);
+}
+
+export function listTransparencyProviders() {
+  return [...providers.keys()];
+}
+
+export function getTransparencyProvider(id) {
+  return providers.get(id) || null;
+}
+
+function mergeById(records, policy) {
+  const map = new Map();
+  const conflicts = [];
+  const rankFn = (pid) => providerRank(pid, policy);
+  for (const rec of records) {
+    if (!map.has(rec.id)) {
+      map.set(rec.id, rec);
+      continue;
+    }
+    const { record, conflicts: c } = mergeDisclosures(map.get(rec.id), rec, rankFn);
+    map.set(rec.id, record);
+    if (c.length) {
+      conflicts.push({ id: rec.id, keys: c, providers: record.meta?.mergedFrom });
+    }
+  }
+  return { records: [...map.values()], conflicts };
+}
+
+/**
+ * Collect from all providers, normalize, merge by id using policy priority.
+ * @param {string|Document|ParentNode|object} root
+ * @param {{ policy: object, file?: string, lang?: string, meta?: object, apiDisclosures?: object[] }} ctx
+ */
+export async function collectAllDisclosures(root, ctx) {
+  const drafts = [];
+  for (const [id, handler] of providers) {
+    const items = await handler.collect(root, { ...ctx, providerId: id });
+    for (const item of items || []) {
+      drafts.push(normalizeDisclosure({ ...item, provider: item.provider || id }, {
+        provider: item.provider || id,
+        file: ctx.file,
+        lang: ctx.lang,
+      }));
+    }
+  }
+  return mergeById(drafts, ctx.policy);
+}
+
+function attr(tag, name) {
+  const re = new RegExp(`\\b${name}=["']([^"']*)["']`, 'i');
+  return tag.match(re)?.[1];
+}
+
+function hasAttr(tag, name) {
+  return new RegExp(`(?:\\s|^|<)${name}(?:[\\s>=/]|$)`, 'i').test(tag);
+}
+
+/**
+ * Parse HTML string for velin-transparency hosts and JSON blocks.
+ */
+export function collectFromHtmlString(html) {
+  const items = [];
+  const tagRe = /<([a-z0-9-]+)(\s[^>]*)?>/gi;
+  let m;
+  while ((m = tagRe.exec(html))) {
+    const full = m[0];
+    if (!hasAttr(full, 'velin-transparency') && !hasAttr(full, 'velin-disclosure')) continue;
+    const tagName = m[1].toUpperCase();
+    const id = attr(full, 'velin-transparency-id') || attr(full, 'id');
+    const type = attr(full, 'velin-type') || 'ai';
+    const status = attr(full, 'velin-status');
+    const review = attr(full, 'velin-review');
+    const license = attr(full, 'velin-license');
+    const label = attr(full, 'velin-label') || attr(full, 'velin-ai-label');
+    const description = attr(full, 'velin-description') || attr(full, 'velin-ai-description');
+    const overlay = attr(full, 'velin-overlay') || attr(full, 'velin-renderer') || attr(full, 'velin-ai-overlay');
+    const tone = attr(full, 'velin-tone') || attr(full, 'velin-ai-tone');
+    const position = attr(full, 'velin-position') || attr(full, 'velin-ai-position');
+    const src = attr(full, 'src') || attr(full, 'href');
+    items.push({
+      id,
+      type,
+      status,
+      review,
+      license,
+      label,
+      description,
+      overlay,
+      tone,
+      position,
+      src,
+      tag: tagName,
+      selector: id ? `#${id}` : undefined,
+      provenance: {
+        createdBy: attr(full, 'velin-created-by'),
+        createdAt: attr(full, 'velin-created-at'),
+        reviewedAt: attr(full, 'velin-reviewed-at'),
+        approvedBy: attr(full, 'velin-approved-by'),
+        source: attr(full, 'velin-source'),
+        license: license || undefined,
+        version: attr(full, 'velin-version'),
+        publishedAt: attr(full, 'velin-published-at'),
+      },
+      provider: 'html',
+    });
+  }
+
+  const scriptRe = /<script\b[^>]*type=["']application\/vnd\.velinstyle\.transparency\+json["'][^>]*>([\s\S]*?)<\/script>/gi;
+  let sm;
+  while ((sm = scriptRe.exec(html))) {
+    try {
+      const data = JSON.parse(sm[1].trim());
+      const list = Array.isArray(data) ? data : data.items || [data];
+      for (const item of list) items.push({ ...item, provider: item.provider || 'json' });
+    } catch { /* ignore */ }
+  }
+
+  const jsonAttrRe = /<([a-z0-9-]+)([^>]*\bvelin-transparency-json=["']([^"']+)["'][^>]*)>/gi;
+  let jm;
+  while ((jm = jsonAttrRe.exec(html))) {
+    try {
+      const data = JSON.parse(jm[3].replace(/&quot;/g, '"'));
+      items.push({ ...data, tag: jm[1].toUpperCase(), provider: 'json' });
+    } catch { /* ignore */ }
+  }
+
+  return items;
+}
+
+function collectFromDom(root) {
+  if (typeof root?.querySelectorAll !== 'function') return [];
+  const items = [];
+  root.querySelectorAll('[velin-transparency], [velin-disclosure]').forEach((el) => {
+    const get = (n) => el.getAttribute(n);
+    items.push({
+      id: get('velin-transparency-id') || el.id || undefined,
+      type: get('velin-type') || 'ai',
+      status: get('velin-status'),
+      review: get('velin-review'),
+      license: get('velin-license'),
+      label: get('velin-label') || get('velin-ai-label'),
+      description: get('velin-description'),
+      overlay: get('velin-overlay') || get('velin-renderer'),
+      tone: get('velin-tone'),
+      position: get('velin-position'),
+      src: el.getAttribute('src') || el.getAttribute('href') || undefined,
+      tag: el.tagName,
+      selector: el.id ? `#${el.id}` : undefined,
+      provenance: {
+        createdBy: get('velin-created-by'),
+        createdAt: get('velin-created-at'),
+        reviewedAt: get('velin-reviewed-at'),
+        approvedBy: get('velin-approved-by'),
+        source: get('velin-source'),
+        license: get('velin-license'),
+        version: get('velin-version'),
+        publishedAt: get('velin-published-at'),
+      },
+      provider: 'html',
+    });
+  });
+  root.querySelectorAll('script[type="application/vnd.velinstyle.transparency+json"]').forEach((script) => {
+    try {
+      const data = JSON.parse(script.textContent || '{}');
+      const list = Array.isArray(data) ? data : data.items || [data];
+      for (const item of list) items.push({ ...item, provider: item.provider || 'json' });
+    } catch { /* ignore */ }
+  });
+  return items;
+}
+
+registerTransparencyProvider('html', {
+  async collect(root) {
+    if (typeof root === 'string') return collectFromHtmlString(root).filter((i) => i.provider === 'html');
+    return collectFromDom(root);
+  },
+});
+
+registerTransparencyProvider('json', {
+  async collect(root) {
+    if (root && typeof root === 'object' && !root.querySelectorAll && (Array.isArray(root) || root.type || root.items)) {
+      const list = Array.isArray(root) ? root : root.items || [root];
+      return list.map((item) => ({ ...item, provider: 'json' }));
+    }
+    if (typeof root === 'string') {
+      return collectFromHtmlString(root).filter((i) => i.provider === 'json');
+    }
+    return [];
+  },
+});
+
+registerTransparencyProvider('meta', {
+  async collect(root, ctx = {}) {
+    if (ctx.meta?.transparency) {
+      const t = ctx.meta.transparency;
+      const list = Array.isArray(t) ? t : t.disclosures || t.items || [];
+      return list.map((item) => ({ ...item, provider: 'meta' }));
+    }
+    if (typeof root === 'string') {
+      const m = root.match(
+        /<script\b[^>]*(?:id=["']velin-meta["']|type=["']application\/vnd\.velinstyle\.meta\+json["'])[^>]*>([\s\S]*?)<\/script>/i,
+      );
+      if (!m) return [];
+      try {
+        const meta = JSON.parse(m[1].trim());
+        const t = meta.transparency || meta.aiDisclosure;
+        if (!t) return [];
+        const list = Array.isArray(t) ? t : t.disclosures || t.items || [];
+        return list.map((item) => ({ ...item, provider: 'meta' }));
+      } catch {
+        return [];
+      }
+    }
+    return [];
+  },
+});
+
+registerTransparencyProvider('api', {
+  async collect(_root, ctx = {}) {
+    return Array.isArray(ctx.apiDisclosures)
+      ? ctx.apiDisclosures.map((i) => ({ ...i, provider: 'api' }))
+      : [];
+  },
+});

package/core/transparency/registry.js

@@ -0,0 +1,104 @@
+/** In-memory disclosure registry. */
+
+/**
+ * @typedef {object} Provenance
+ * @property {string} [createdBy]
+ * @property {string} [createdAt]
+ * @property {string} [reviewedAt]
+ * @property {string} [approvedBy]
+ * @property {string} [source]
+ * @property {string} [license]
+ * @property {string} [version]
+ * @property {string} [publishedAt]
+ */
+
+/**
+ * @typedef {object} DisclosureRecord
+ * @property {string} id
+ * @property {string} [type]
+ * @property {string} [status]
+ * @property {string} [review]
+ * @property {string} provider
+ * @property {string[]} claims
+ * @property {Provenance} provenance
+ * @property {string} [updated]
+ * @property {string} [label]
+ * @property {string} [description]
+ * @property {string} [renderer]
+ * @property {string} [tone]
+ * @property {string} [position]
+ * @property {{ selector?: string, tag?: string, src?: string, file?: string }} [target]
+ * @property {Record<string, unknown>} [meta]
+ */
+
+export function createRegistry() {
+  /** @type {Map<string, DisclosureRecord>} */
+  const map = new Map();
+
+  return {
+    register(record) {
+      if (!record?.id) throw new Error('DisclosureRecord requires id');
+      map.set(record.id, structuredCloneSafe(record));
+      return map.get(record.id);
+    },
+    get(id) {
+      return map.get(id) || null;
+    },
+    has(id) {
+      return map.has(id);
+    },
+    remove(id) {
+      return map.delete(id);
+    },
+    list() {
+      return [...map.values()].map((r) => structuredCloneSafe(r));
+    },
+    query(predicate) {
+      return this.list().filter(predicate);
+    },
+    clear() {
+      map.clear();
+    },
+    size() {
+      return map.size;
+    },
+    export() {
+      return { schema: 'velinstyle.transparency.registry', version: 1, items: this.list() };
+    },
+    diff(otherList = []) {
+      const other = new Map(otherList.map((r) => [r.id, r]));
+      const added = [];
+      const removed = [];
+      const changed = [];
+      for (const r of map.values()) {
+        if (!other.has(r.id)) added.push(r.id);
+        else if (JSON.stringify(r) !== JSON.stringify(other.get(r.id))) changed.push(r.id);
+      }
+      for (const id of other.keys()) {
+        if (!map.has(id)) removed.push(id);
+      }
+      return { added, removed, changed };
+    },
+  };
+}
+
+function structuredCloneSafe(obj) {
+  return JSON.parse(JSON.stringify(obj));
+}
+
+/**
+ * Stable id from target hints.
+ * @param {{ id?: string, selector?: string, src?: string, tag?: string, type?: string, file?: string }} parts
+ */
+export function stableDisclosureId(parts = {}) {
+  if (parts.id) return String(parts.id).trim();
+  const raw = [parts.file || '', parts.selector || '', parts.src || '', parts.tag || '', parts.type || '']
+    .join('|')
+    .toLowerCase();
+  let h = 2166136261;
+  for (let i = 0; i < raw.length; i += 1) {
+    h ^= raw.charCodeAt(i);
+    h = Math.imul(h, 16777619);
+  }
+  return `tx-${(h >>> 0).toString(16)}`;
+}

package/core/transparency/renderer.js

@@ -0,0 +1,111 @@
+/** @type {Map<string, (el: HTMLElement, record: object) => void>} */
+const renderers = new Map();
+
+export function registerTransparencyRenderer(name, fn) {
+  renderers.set(name, fn);
+}
+
+export function listTransparencyRenderers() {
+  return [...renderers.keys()];
+}
+
+/**
+ * Render a disclosure mark onto an element.
+ * @param {HTMLElement} el
+ * @param {import('./registry.js').DisclosureRecord} record
+ */
+export function renderDisclosure(el, record) {
+  if (typeof document === 'undefined' || !el) return null;
+  const name = record.renderer || 'badge';
+  const custom = renderers.get(name);
+  if (custom) {
+    custom(el, record);
+    return el.querySelector('.velin-transparency');
+  }
+  return defaultRender(el, record);
+}
+
+function defaultRender(el, record) {
+  const cs = getComputedStyle(el);
+  if (cs.position === 'static') el.style.position = 'relative';
+
+  let mark = el.querySelector(':scope > .velin-transparency');
+  if (!mark) {
+    mark = document.createElement('div');
+    el.prepend(mark);
+  }
+
+  const renderer = record.renderer || 'badge';
+  const tone = record.tone || 'neutral';
+  const position = record.position || 'top-right';
+  mark.className = [
+    'velin-transparency',
+    `velin-transparency--${renderer}`,
+    `velin-transparency--tone-${tone}`,
+    `velin-transparency--pos-${position}`,
+  ].join(' ');
+  mark.setAttribute('data-velin-transparency-id', record.id);
+  mark.setAttribute('role', 'note');
+
+  const claimsText = (record.claims || []).join(', ');
+  const prov = record.provenance || {};
+  const sr = document.createElement('span');
+  sr.className = 'velin-sr-only';
+  const lang = (el.closest('[lang]')?.getAttribute('lang') || document.documentElement.lang || 'en').startsWith('de')
+    ? 'de'
+    : 'en';
+  sr.textContent = lang === 'de'
+    ? `Transparenzhinweis: ${record.label}. ${claimsText}. ${provenanceSr(prov, 'de')}`
+    : `Transparency notice: ${record.label}. ${claimsText}. ${provenanceSr(prov, 'en')}`;
+
+  const visible = document.createElement('span');
+  visible.className = 'velin-transparency__label';
+  visible.textContent = record.label || 'Transparency';
+
+  const details = document.createElement('span');
+  details.className = 'velin-transparency__details';
+  details.hidden = renderer === 'badge' || renderer === 'icon';
+  details.textContent = formatDetails(record, lang);
+
+  mark.replaceChildren(sr, visible, details);
+
+  if (record.description) mark.title = record.description;
+  else if (details.textContent) mark.title = details.textContent;
+
+  el.setAttribute('data-velin-transparency', record.id);
+  return mark;
+}
+
+function provenanceSr(p, lang) {
+  const parts = [];
+  if (p.createdBy) parts.push(lang === 'de' ? `Erstellt von ${p.createdBy}` : `Created by ${p.createdBy}`);
+  if (p.createdAt) parts.push(lang === 'de' ? `am ${p.createdAt}` : `on ${p.createdAt}`);
+  if (p.approvedBy) parts.push(lang === 'de' ? `Freigegeben von ${p.approvedBy}` : `Approved by ${p.approvedBy}`);
+  if (p.license) parts.push(p.license);
+  if (p.version) parts.push(`v${p.version}`);
+  return parts.join('. ');
+}
+
+function formatDetails(record, lang) {
+  const p = record.provenance || {};
+  const bits = [];
+  if (p.approvedBy) bits.push(lang === 'de' ? `Freigabe: ${p.approvedBy}` : `Approved: ${p.approvedBy}`);
+  if (p.license) bits.push(p.license);
+  if (p.version) bits.push(`v${p.version}`);
+  if (p.updated || record.updated) bits.push(record.updated || p.publishedAt || '');
+  return bits.filter(Boolean).join(' · ');
+}
+
+// Register alias names to default path
+for (const name of ['overlay', 'badge', 'inline', 'tooltip', 'footer', 'ribbon', 'panel', 'icon', 'corner-badge', 'stamp', 'sidebar', 'floating-card', 'banner']) {
+  registerTransparencyRenderer(name, (el, record) => {
+    defaultRender(el, { ...record, renderer: normalizeRendererName(name) });
+  });
+}
+
+function normalizeRendererName(name) {
+  if (name === 'corner-badge' || name === 'stamp') return 'badge';
+  if (name === 'floating-card' || name === 'sidebar') return 'panel';
+  if (name === 'banner') return 'footer';
+  return name;
+}