@birdapi/velinstyle 1.2.0 → 1.2.1

package/core/transparency/attach.js

@@ -0,0 +1,74 @@
+import { normalizeDisclosure } from './normalize.js';
+import { renderDisclosure } from './renderer.js';
+import { createRegistry } from './registry.js';
+
+const defaultRegistry = createRegistry();
+
+/**
+ * Attach a disclosure to an element (browser API).
+ * @param {HTMLElement} el
+ * @param {Record<string, unknown>} options
+ * @param {{ registry?: ReturnType<typeof createRegistry>, lang?: string }} [ctx]
+ */
+export function attach(el, options = {}, ctx = {}) {
+  if (!el) throw new Error('VelinTransparency.attach requires an element');
+  const registry = ctx.registry || defaultRegistry;
+  const draft = {
+    ...options,
+    tag: el.tagName,
+    src: el.getAttribute?.('src') || el.getAttribute?.('href') || options.src,
+    selector: el.id ? `#${el.id}` : options.selector,
+    id: options.id || el.getAttribute?.('velin-transparency-id') || el.id,
+    provider: options.provider || 'api',
+  };
+  // Mirror useful attributes if present
+  if (el.hasAttribute?.('velin-transparency') || el.hasAttribute?.('velin-disclosure')) {
+    draft.type = draft.type || el.getAttribute('velin-type') || 'ai';
+    draft.status = draft.status || el.getAttribute('velin-status');
+    draft.review = draft.review || el.getAttribute('velin-review');
+    draft.license = draft.license || el.getAttribute('velin-license');
+    draft.label = draft.label || el.getAttribute('velin-label');
+    draft.description = draft.description || el.getAttribute('velin-description');
+    draft.overlay = draft.overlay || el.getAttribute('velin-overlay') || el.getAttribute('velin-renderer');
+    draft.provenance = {
+      createdBy: el.getAttribute('velin-created-by'),
+      createdAt: el.getAttribute('velin-created-at'),
+      reviewedAt: el.getAttribute('velin-reviewed-at'),
+      approvedBy: el.getAttribute('velin-approved-by'),
+      source: el.getAttribute('velin-source'),
+      license: el.getAttribute('velin-license'),
+      version: el.getAttribute('velin-version'),
+      publishedAt: el.getAttribute('velin-published-at'),
+      ...(options.provenance || {}),
+    };
+  }
+  const record = normalizeDisclosure(draft, { provider: draft.provider, lang: ctx.lang });
+  registry.register(record);
+  if (!el.hasAttribute('velin-transparency')) el.setAttribute('velin-transparency', '');
+  if (!el.hasAttribute('velin-transparency-id')) el.setAttribute('velin-transparency-id', record.id);
+  renderDisclosure(el, record);
+  return record;
+}
+
+/**
+ * Enhance all [velin-transparency] under root.
+ * @param {ParentNode} [root]
+ */
+export function enhanceAll(root = typeof document !== 'undefined' ? document : null) {
+  if (!root?.querySelectorAll) return [];
+  const out = [];
+  root.querySelectorAll('[velin-transparency], [velin-disclosure]').forEach((el) => {
+    out.push(attach(el, {}, { registry: defaultRegistry }));
+  });
+  return out;
+}
+
+export function getDefaultRegistry() {
+  return defaultRegistry;
+}
+
+export const VelinTransparency = {
+  attach,
+  enhanceAll,
+  getRegistry: getDefaultRegistry,
+};

package/core/transparency/claims.js

@@ -0,0 +1,97 @@
+/** Standardized claim taxonomy for Velin Transparency Framework. */
+
+export const CLAIM_CATALOG = {
+  'ai.generated': { pillar: 'ai', label: { en: 'AI generated', de: 'KI-generiert' } },
+  'ai.assisted': { pillar: 'ai', label: { en: 'AI assisted', de: 'KI-unterstützt' } },
+  'review.human': { pillar: 'ai', label: { en: 'Human reviewed', de: 'Mensch geprüft' } },
+  'review.verified': { pillar: 'trust', label: { en: 'Verified', de: 'Verifiziert' } },
+  'security.checked': { pillar: 'trust', label: { en: 'Security checked', de: 'Security geprüft' } },
+  'accessibility.checked': { pillar: 'trust', label: { en: 'Accessibility checked', de: 'Barrierefreiheit geprüft' } },
+  'trust.official': { pillar: 'trust', label: { en: 'Official', de: 'Offiziell' } },
+  'trust.signed': { pillar: 'trust', label: { en: 'Signed', de: 'Signiert' } },
+  'trust.opensource': { pillar: 'trust', label: { en: 'Open source', de: 'Open Source' } },
+  'privacy.gdpr': { pillar: 'compliance', label: { en: 'GDPR', de: 'DSGVO' } },
+  'license.cc-by': { pillar: 'compliance', label: { en: 'CC BY', de: 'CC BY' } },
+  'license.mit': { pillar: 'compliance', label: { en: 'MIT', de: 'MIT' } },
+  'license.apache-2': { pillar: 'compliance', label: { en: 'Apache-2.0', de: 'Apache-2.0' } },
+  'content.updated': { pillar: 'metadata', label: { en: 'Updated', de: 'Aktualisiert' } },
+  'content.author': { pillar: 'metadata', label: { en: 'Author', de: 'Autor' } },
+  'content.source': { pillar: 'metadata', label: { en: 'Source', de: 'Quelle' } },
+  'content.language': { pillar: 'metadata', label: { en: 'Language', de: 'Sprache' } },
+  'version.current': { pillar: 'metadata', label: { en: 'Version', de: 'Version' } },
+  'provenance.complete': { pillar: 'provenance', label: { en: 'Provenance complete', de: 'Nachweis vollständig' } },
+};
+
+const STATUS_TO_CLAIM = {
+  generated: 'ai.generated',
+  assisted: 'ai.assisted',
+  'ai-assisted': 'ai.assisted',
+  'human-reviewed': 'review.human',
+  'human-edited': 'review.human',
+  verified: 'review.verified',
+  edited: 'review.human',
+  draft: null,
+};
+
+const REVIEW_TO_CLAIM = {
+  human: 'review.human',
+  'human-reviewed': 'review.human',
+  verified: 'review.verified',
+  none: null,
+};
+
+const LICENSE_TO_CLAIM = {
+  'cc by 4.0': 'license.cc-by',
+  'cc-by': 'license.cc-by',
+  'cc-by-4.0': 'license.cc-by',
+  mit: 'license.mit',
+  'apache-2.0': 'license.apache-2',
+  apache: 'license.apache-2',
+};
+
+/**
+ * @param {string} [status]
+ * @param {string} [review]
+ * @param {string} [license]
+ * @param {string[]} [extra]
+ */
+export function deriveClaims({ status, review, license, claims = [] } = {}) {
+  const out = new Set(Array.isArray(claims) ? claims.filter(Boolean) : []);
+  const statusClaim = STATUS_TO_CLAIM[String(status || '').toLowerCase()];
+  if (statusClaim) out.add(statusClaim);
+  const reviewClaim = REVIEW_TO_CLAIM[String(review || '').toLowerCase()];
+  if (reviewClaim) out.add(reviewClaim);
+  if (license) {
+    const key = String(license).toLowerCase().trim();
+    const mapped = LICENSE_TO_CLAIM[key] || (key.startsWith('cc') ? 'license.cc-by' : null);
+    if (mapped) out.add(mapped);
+  }
+  return [...out];
+}
+
+/**
+ * @param {string} claim
+ * @param {'en'|'de'} [lang]
+ */
+export function claimLabel(claim, lang = 'en') {
+  const entry = CLAIM_CATALOG[claim];
+  if (!entry) return claim;
+  return entry.label[lang] || entry.label.en || claim;
+}
+
+/**
+ * @param {string[]} claims
+ * @param {'en'|'de'} [lang]
+ */
+export function primaryLabel(claims = [], lang = 'en') {
+  const order = ['ai.generated', 'ai.assisted', 'review.human', 'review.verified', 'trust.official', 'license.cc-by', 'license.mit'];
+  for (const c of order) {
+    if (claims.includes(c)) return claimLabel(c, lang);
+  }
+  if (claims[0]) return claimLabel(claims[0], lang);
+  return lang === 'de' ? 'Transparenz' : 'Transparency';
+}
+
+export function pillarForClaim(claim) {
+  return CLAIM_CATALOG[claim]?.pillar || (String(claim).startsWith('custom.') ? 'custom' : 'metadata');
+}

package/core/transparency/doctor.js

@@ -0,0 +1,142 @@
+import { collectAllDisclosures } from './providers.js';
+import { validateRecords, inferMediaKind } from './validator.js';
+import { mediaRequirement, requiredProvenanceFields } from './policy.js';
+import { createRegistry } from './registry.js';
+import { pillarForClaim } from './claims.js';
+
+/**
+ * Run transparency doctor on HTML string (or precollected context).
+ * @param {string} html
+ * @param {{ policy: object, file?: string, lang?: string, meta?: object }} ctx
+ */
+export async function transparencyDoctor(html, ctx) {
+  const { records, conflicts } = await collectAllDisclosures(html, ctx);
+  const registry = createRegistry();
+  for (const r of records) registry.register(r);
+
+  const findings = [];
+  for (const c of conflicts) {
+    findings.push({
+      severity: 'warning',
+      code: 'conflict',
+      message: `Conflicting fields [${c.keys.join(', ')}] from providers ${(c.providers || []).join(' > ')}`,
+      id: c.id,
+    });
+  }
+  findings.push(...validateRecords(records, ctx.policy));
+
+  // Media coverage
+  const media = scanMediaTargets(html);
+  const coveredSrc = new Set(
+    records.map((r) => (r.target?.src || '').split('?')[0].toLowerCase()).filter(Boolean),
+  );
+  const coveredSelectors = new Set(records.map((r) => r.target?.selector).filter(Boolean));
+
+  for (const item of media) {
+    const req = mediaRequirement(item.kind, ctx.policy);
+    if (req !== 'required') continue;
+    const srcKey = (item.src || '').split('?')[0].toLowerCase();
+    const has =
+      (item.id && coveredSelectors.has(`#${item.id}`))
+      || (srcKey && coveredSrc.has(srcKey))
+      || records.some((r) => r.target?.tag === item.tag && !r.target?.src && item.kind === inferMediaKind(r));
+    // Better: check if element itself has velin-transparency in opening tag
+    if (item.disclosed) continue;
+    if (!has) {
+      findings.push({
+        severity: 'error',
+        code: `missing-disclosure.${item.kind}`,
+        message: `Required ${item.kind} lacks velin-transparency (${item.tag}${item.src ? ` ${item.src}` : ''})`,
+        id: item.id || null,
+        target: item,
+      });
+    }
+  }
+
+  const scores = computeScores(records, findings, media, ctx.policy);
+  return {
+    ok: !findings.some((f) => f.severity === 'error'),
+    file: ctx.file || null,
+    registry: registry.export(),
+    findings,
+    scores,
+    summary: {
+      disclosures: records.length,
+      media: media.length,
+      errors: findings.filter((f) => f.severity === 'error').length,
+      warnings: findings.filter((f) => f.severity === 'warning').length,
+      info: findings.filter((f) => f.severity === 'info').length,
+    },
+  };
+}
+
+function scanMediaTargets(html) {
+  const out = [];
+  const re = /<(img|video|audio|a|embed|object)(\s[^>]*)?>/gi;
+  let m;
+  while ((m = re.exec(html))) {
+    const tag = m[1].toUpperCase();
+    const attrs = m[2] || '';
+    const src = attrs.match(/\b(?:src|href)=["']([^"']+)["']/i)?.[1] || '';
+    const id = attrs.match(/\bid=["']([^"']+)["']/i)?.[1];
+    const disclosed = /\bvelin-transparency\b/i.test(attrs) || /\bvelin-disclosure\b/i.test(attrs);
+    let kind = 'text';
+    if (tag === 'IMG') kind = 'images';
+    else if (tag === 'VIDEO') kind = 'videos';
+    else if (tag === 'AUDIO') kind = 'audio';
+    else if (/\.pdf(\?|$)/i.test(src) || /application\/pdf/i.test(attrs)) kind = 'pdf';
+    else if (tag === 'A' && !/\.pdf(\?|$)/i.test(src)) continue;
+    else if (tag === 'EMBED' || tag === 'OBJECT') {
+      if (/\.pdf/i.test(src) || /pdf/i.test(attrs)) kind = 'pdf';
+      else continue;
+    }
+    out.push({ tag, src, id, kind, disclosed });
+  }
+  return out;
+}
+
+function computeScores(records, findings, media, policy) {
+  const pillars = { ai: [], trust: [], compliance: [], metadata: [], provenance: [] };
+  for (const r of records) {
+    for (const c of r.claims || []) {
+      const p = pillarForClaim(c);
+      if (pillars[p]) pillars[p].push(true);
+    }
+    const kind = inferMediaKind(r);
+    const req = requiredCount(kind, policy);
+    const have = Object.keys(r.provenance || {}).length;
+    pillars.provenance.push(req === 0 ? true : have >= req);
+  }
+
+  const requiredMedia = media.filter((m) => mediaRequirement(m.kind, policy) === 'required');
+  const missingMedia = findings.filter((f) => String(f.code).startsWith('missing-disclosure.')).length;
+  const coverage = requiredMedia.length
+    ? Math.round(((requiredMedia.length - missingMedia) / requiredMedia.length) * 100)
+    : 100;
+
+  const pillarScore = (arr) => {
+    if (!arr.length) return records.length ? 100 : coverage;
+    return Math.round((arr.filter(Boolean).length / arr.length) * 100);
+  };
+
+  const errors = findings.filter((f) => f.severity === 'error').length;
+  const transparency = Math.max(0, Math.min(100, Math.round(
+    (coverage * 0.45)
+    + (pillarScore(pillars.provenance) * 0.25)
+    + (Math.max(0, 100 - errors * 8) * 0.3),
+  )));
+
+  return {
+    transparency,
+    ai: pillarScore(pillars.ai),
+    trust: pillarScore(pillars.trust),
+    metadata: pillarScore(pillars.metadata),
+    compliance: pillarScore(pillars.compliance),
+    provenance: pillarScore(pillars.provenance),
+    coverage,
+  };
+}
+
+function requiredCount(kind, policy) {
+  return requiredProvenanceFields(kind, policy).length;
+}

package/core/transparency/engine.js

@@ -0,0 +1,75 @@
+import { normalizePolicy } from './policy.js';
+import { createRegistry } from './registry.js';
+import { collectAllDisclosures } from './providers.js';
+import { validateRecords } from './validator.js';
+import { transparencyDoctor } from './doctor.js';
+import { buildTransparencyReports } from './reporter.js';
+import { exportDisclosures } from './export.js';
+import { transparencyMigrate } from './migrate.js';
+import { normalizeDisclosure } from './normalize.js';
+
+/**
+ * Create a Transparency Engine instance.
+ * @param {{ policy?: object, lang?: 'en'|'de' }} [options]
+ */
+export function createTransparencyEngine(options = {}) {
+  const policy = normalizePolicy(options.policy);
+  const registry = createRegistry();
+  const lang = options.lang === 'de' ? 'de' : 'en';
+
+  return {
+    policy,
+    registry,
+    lang,
+
+    /**
+     * Collect → validate → register from HTML string / DOM / JSON.
+     */
+    async ingest(root, ctx = {}) {
+      const { records, conflicts } = await collectAllDisclosures(root, {
+        policy,
+        lang,
+        file: ctx.file,
+        meta: ctx.meta,
+        apiDisclosures: ctx.apiDisclosures,
+      });
+      registry.clear();
+      for (const r of records) registry.register(r);
+      const findings = validateRecords(records, policy);
+      return { records, conflicts, findings, registry: registry.export() };
+    },
+
+    register(draft, ctx = {}) {
+      const record = normalizeDisclosure(draft, { provider: draft.provider || 'api', lang, file: ctx.file });
+      return registry.register(record);
+    },
+
+    async doctor(html, ctx = {}) {
+      return transparencyDoctor(html, { policy, lang, ...ctx });
+    },
+
+    async validate(html, ctx = {}) {
+      const report = await transparencyDoctor(html, { policy, lang, ...ctx });
+      return {
+        ok: report.ok && !report.findings.some((f) => f.severity === 'error'),
+        findings: report.findings,
+        scores: report.scores,
+      };
+    },
+
+    async report(html, ctx = {}) {
+      const doctor = await transparencyDoctor(html, { policy, lang, ...ctx });
+      return buildTransparencyReports(doctor, { title: ctx.title });
+    },
+
+    export(format = 'json') {
+      return exportDisclosures(registry.list(), format);
+    },
+
+    async migrate(html, ctx = {}) {
+      return transparencyMigrate(html, { policy, lang, ...ctx });
+    },
+  };
+}
+
+export const TransparencyMIME = 'application/vnd.velinstyle.transparency+json';

package/core/transparency/export.js

@@ -0,0 +1,98 @@
+/**
+ * Export registry items to interoperable formats.
+ * @param {import('./registry.js').DisclosureRecord[]} items
+ * @param {'json'|'json-ld'|'csv'|'html'} format
+ */
+export function exportDisclosures(items, format = 'json') {
+  switch (format) {
+    case 'json-ld':
+      return JSON.stringify(toJsonLd(items), null, 2);
+    case 'csv':
+      return toCsv(items);
+    case 'html':
+      return toHtmlTable(items);
+    case 'json':
+    default:
+      return JSON.stringify({
+        schema: 'velinstyle.transparency.export',
+        mime: 'application/vnd.velinstyle.transparency+json',
+        version: 1,
+        exportedAt: new Date().toISOString(),
+        items,
+      }, null, 2);
+  }
+}
+
+function toJsonLd(items) {
+  return {
+    '@context': 'https://schema.org',
+    '@graph': items.map((r) => ({
+      '@type': 'CreativeWork',
+      '@id': r.id,
+      name: r.label,
+      description: r.description,
+      creativeWorkStatus: r.status,
+      dateCreated: r.provenance?.createdAt,
+      dateModified: r.updated || r.provenance?.reviewedAt,
+      version: r.provenance?.version,
+      license: r.provenance?.license,
+      author: r.provenance?.createdBy
+        ? { '@type': 'Person', name: r.provenance.createdBy }
+        : undefined,
+      contributor: r.provenance?.approvedBy
+        ? { '@type': 'Person', name: r.provenance.approvedBy }
+        : undefined,
+      isBasedOn: r.provenance?.source,
+      additionalProperty: (r.claims || []).map((c) => ({
+        '@type': 'PropertyValue',
+        name: 'velin.claim',
+        value: c,
+      })),
+    })),
+  };
+}
+
+function toCsv(items) {
+  const headers = [
+    'id', 'type', 'status', 'review', 'label', 'claims',
+    'createdBy', 'createdAt', 'reviewedAt', 'approvedBy', 'source', 'license', 'version', 'publishedAt',
+  ];
+  const lines = [headers.join(',')];
+  for (const r of items) {
+    const p = r.provenance || {};
+    const row = [
+      r.id, r.type, r.status, r.review, r.label, (r.claims || []).join('|'),
+      p.createdBy, p.createdAt, p.reviewedAt, p.approvedBy, p.source, p.license, p.version, p.publishedAt,
+    ].map(csvEscape);
+    lines.push(row.join(','));
+  }
+  return `${lines.join('\n')}\n`;
+}
+
+function csvEscape(v) {
+  const s = String(v ?? '');
+  if (/[",\n]/.test(s)) return `"${s.replace(/"/g, '""')}"`;
+  return s;
+}
+
+function toHtmlTable(items) {
+  const rows = items.map((r) => {
+    const p = r.provenance || {};
+    return `<tr>
+      <td>${esc(r.id)}</td><td>${esc(r.label)}</td><td>${esc((r.claims || []).join(', '))}</td>
+      <td>${esc(p.createdBy)}</td><td>${esc(p.createdAt)}</td><td>${esc(p.approvedBy)}</td>
+      <td>${esc(p.license)}</td><td>${esc(p.version)}</td><td>${esc(p.source)}</td>
+    </tr>`;
+  }).join('');
+  return `<!DOCTYPE html><html lang="en"><head><meta charset="utf-8"><title>Transparency export</title></head>
+<body><table border="1" cellpadding="6">
+<thead><tr><th>Id</th><th>Label</th><th>Claims</th><th>Created by</th><th>Created</th><th>Approved by</th><th>License</th><th>Version</th><th>Source</th></tr></thead>
+<tbody>${rows}</tbody></table></body></html>`;
+}
+
+function esc(s) {
+  return String(s ?? '')
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;');
+}

package/core/transparency/index.js

@@ -0,0 +1,30 @@
+export { CLAIM_CATALOG, deriveClaims, claimLabel, primaryLabel, pillarForClaim } from './claims.js';
+export {
+  DEFAULT_POLICY,
+  STRICT_MEDIA_POLICY,
+  normalizePolicy,
+  mediaRequirement,
+  requiredProvenanceFields,
+  providerRank,
+} from './policy.js';
+export { createRegistry, stableDisclosureId } from './registry.js';
+export { normalizeDisclosure, mergeDisclosures } from './normalize.js';
+export {
+  registerTransparencyProvider,
+  listTransparencyProviders,
+  getTransparencyProvider,
+  collectAllDisclosures,
+  collectFromHtmlString,
+} from './providers.js';
+export { validateRecord, validateRecords, inferMediaKind } from './validator.js';
+export { transparencyDoctor } from './doctor.js';
+export { buildTransparencyReports } from './reporter.js';
+export { exportDisclosures } from './export.js';
+export { transparencyMigrate } from './migrate.js';
+export { createTransparencyEngine, TransparencyMIME } from './engine.js';
+export {
+  registerTransparencyRenderer,
+  listTransparencyRenderers,
+  renderDisclosure,
+} from './renderer.js';
+export { attach, enhanceAll, getDefaultRegistry, VelinTransparency } from './attach.js';

package/core/transparency/migrate.js

@@ -0,0 +1,130 @@
+import { transparencyDoctor } from './doctor.js';
+import { stableDisclosureId } from './registry.js';
+
+/**
+ * Analyze HTML and suggest disclosures + optional apply.
+ * @param {string} html
+ * @param {{ policy: object, file?: string, apply?: boolean, dryRun?: boolean }} opts
+ */
+export async function transparencyMigrate(html, opts) {
+  const doctor = await transparencyDoctor(html, opts);
+  const suggestions = [];
+
+  for (const f of doctor.findings) {
+    if (!String(f.code).startsWith('missing-disclosure.')) continue;
+    const target = f.target || {};
+    const kind = f.code.replace('missing-disclosure.', '');
+    const type = kind === 'images' || kind === 'videos' || kind === 'audio' ? 'ai' : kind === 'pdf' ? 'license' : 'ai';
+    const id = stableDisclosureId({
+      id: target.id,
+      src: target.src,
+      tag: target.tag,
+      type,
+      file: opts.file,
+    });
+    const attrs = {
+      'velin-transparency': '',
+      'velin-transparency-id': id,
+      'velin-type': type,
+      'velin-status': type === 'ai' ? 'generated' : 'verified',
+      'velin-review': 'human-reviewed',
+    };
+    if (kind === 'images' || kind === 'pdf') {
+      attrs['velin-created-at'] = new Date().toISOString().slice(0, 10);
+      attrs['velin-license'] = 'CC BY 4.0';
+    }
+    if (kind === 'images') attrs['velin-source'] = target.src || '';
+    suggestions.push({
+      id,
+      kind,
+      target,
+      attrs,
+      reason: f.message,
+    });
+  }
+
+  // Provenance gaps on existing disclosures
+  for (const f of doctor.findings) {
+    if (!String(f.code).startsWith('missing-provenance.')) continue;
+    const field = f.code.replace('missing-provenance.', '');
+    suggestions.push({
+      id: f.id,
+      kind: 'provenance',
+      field,
+      attrs: { [`velin-${kebab(field)}`]: field === 'license' ? 'CC BY 4.0' : field.includes('At') ? new Date().toISOString().slice(0, 10) : 'unknown' },
+      reason: f.message,
+    });
+  }
+
+  let nextHtml = html;
+  let applied = 0;
+  if (opts.apply && opts.dryRun !== true) {
+    const result = applySuggestions(html, suggestions.filter((s) => s.kind !== 'provenance' || s.target));
+    nextHtml = result.html;
+    applied = result.applied;
+    // provenance-only patches on existing tags
+    for (const s of suggestions.filter((x) => x.kind === 'provenance' && x.id)) {
+      const patched = patchAttrsById(nextHtml, s.id, s.attrs);
+      if (patched.changed) {
+        nextHtml = patched.html;
+        applied += 1;
+      }
+    }
+  }
+
+  return {
+    doctor,
+    suggestions,
+    applied,
+    html: nextHtml,
+    dryRun: opts.dryRun !== false && !opts.apply,
+  };
+}
+
+function kebab(s) {
+  return String(s).replace(/[A-Z]/g, (m) => `-${m.toLowerCase()}`);
+}
+
+function applySuggestions(html, suggestions) {
+  let out = html;
+  let applied = 0;
+  for (const s of suggestions) {
+    if (!s.target?.tag) continue;
+    const tag = s.target.tag.toLowerCase();
+    const src = s.target.src;
+    const id = s.target.id;
+    let re;
+    if (id) {
+      re = new RegExp(`<${tag}\\b([^>]*\\bid=["']${escapeRe(id)}["'][^>]*)>`, 'i');
+    } else if (src) {
+      re = new RegExp(`<${tag}\\b([^>]*\\b(?:src|href)=["']${escapeRe(src)}["'][^>]*)>`, 'i');
+    } else continue;
+    const m = out.match(re);
+    if (!m) continue;
+    if (/\bvelin-transparency\b/i.test(m[0])) continue;
+    const attrStr = Object.entries(s.attrs)
+      .map(([k, v]) => (v === '' ? k : `${k}="${String(v).replace(/"/g, '&quot;')}"`))
+      .join(' ');
+    const next = m[0].replace(/>$/, ` ${attrStr}>`);
+    out = out.replace(m[0], next);
+    applied += 1;
+  }
+  return { html: out, applied };
+}
+
+function patchAttrsById(html, id, attrs) {
+  const re = new RegExp(`<([a-z0-9-]+)\\b([^>]*\\b(?:velin-transparency-id|id)=["']${escapeRe(id)}["'][^>]*)>`, 'i');
+  const m = html.match(re);
+  if (!m) return { html, changed: false };
+  let open = m[0];
+  for (const [k, v] of Object.entries(attrs)) {
+    if (new RegExp(`\\b${k}=`, 'i').test(open)) continue;
+    open = open.replace(/>$/, ` ${k}="${String(v).replace(/"/g, '&quot;')}">`);
+  }
+  if (open === m[0]) return { html, changed: false };
+  return { html: html.replace(m[0], open), changed: true };
+}
+
+function escapeRe(s) {
+  return String(s).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}