@birdapi/velinstyle 1.1.0 → 1.2.1

package/core/meta/sections/registry.json

@@ -0,0 +1,185 @@
+{
+  "version": 1,
+  "sections": [
+    {
+      "id": "hero",
+      "role": "hero",
+      "blueprintFile": "hero-section.html",
+      "inputs": ["title", "subtitle", "cta", "brand"],
+      "requiredContent": ["headline", "primaryCta"],
+      "optionalContent": ["image", "secondaryCta"],
+      "designRules": ["hero-headline-lines", "hero-cta-max", "hero-contrast"],
+      "a11yRules": ["one h1", "cta is real button/link"],
+      "seoRules": ["h1 matches primary intent"],
+      "compatiblePrev": [],
+      "compatibleNext": ["trust-bar", "benefits", "services"],
+      "examplePrompts": ["modern hero with two CTAs"],
+      "commonMistakes": ["three CTAs", "headline longer than two lines"]
+    },
+    {
+      "id": "trust-bar",
+      "role": "trust-bar",
+      "blueprintFile": "trust-bar.html",
+      "inputs": ["logos", "claim"],
+      "requiredContent": ["trustItems"],
+      "optionalContent": ["claim"],
+      "designRules": [],
+      "a11yRules": ["alt text for logos"],
+      "seoRules": [],
+      "compatiblePrev": ["hero"],
+      "compatibleNext": ["benefits", "services"],
+      "examplePrompts": ["trusted by brands bar"],
+      "commonMistakes": ["low-contrast logos"]
+    },
+    {
+      "id": "benefits",
+      "role": "benefits",
+      "blueprintFile": "benefits-grid.html",
+      "inputs": ["items"],
+      "requiredContent": ["benefitItems"],
+      "optionalContent": [],
+      "designRules": [],
+      "a11yRules": ["headings per benefit"],
+      "seoRules": [],
+      "compatiblePrev": ["hero", "trust-bar"],
+      "compatibleNext": ["services", "process"],
+      "examplePrompts": ["three benefits"],
+      "commonMistakes": ["walls of text"]
+    },
+    {
+      "id": "services",
+      "role": "services",
+      "blueprintFile": "services-grid.html",
+      "inputs": ["items"],
+      "requiredContent": ["serviceItems"],
+      "optionalContent": [],
+      "designRules": [],
+      "a11yRules": ["card titles as headings"],
+      "seoRules": ["service names as keywords"],
+      "compatiblePrev": ["benefits", "trust-bar", "hero"],
+      "compatibleNext": ["process", "testimonials", "pricing"],
+      "examplePrompts": ["services grid for tax advisor"],
+      "commonMistakes": ["vague service titles"]
+    },
+    {
+      "id": "process",
+      "role": "process",
+      "blueprintFile": "process-steps.html",
+      "inputs": ["steps"],
+      "requiredContent": ["steps"],
+      "optionalContent": [],
+      "designRules": [],
+      "a11yRules": ["ordered list semantics"],
+      "seoRules": [],
+      "compatiblePrev": ["services", "benefits"],
+      "compatibleNext": ["testimonials", "pricing", "faq"],
+      "examplePrompts": ["how it works in 4 steps"],
+      "commonMistakes": ["more than 6 steps"]
+    },
+    {
+      "id": "testimonials",
+      "role": "testimonials",
+      "blueprintFile": "testimonials.html",
+      "inputs": ["quotes"],
+      "requiredContent": ["quotes"],
+      "optionalContent": ["avatars"],
+      "designRules": [],
+      "a11yRules": ["cite attribution"],
+      "seoRules": [],
+      "compatiblePrev": ["services", "process"],
+      "compatibleNext": ["pricing", "faq", "contact"],
+      "examplePrompts": ["client testimonials"],
+      "commonMistakes": ["anonymous quotes only"]
+    },
+    {
+      "id": "pricing",
+      "role": "pricing",
+      "blueprintFile": "pricing-table.html",
+      "inputs": ["plans"],
+      "requiredContent": ["plans"],
+      "optionalContent": [],
+      "designRules": [],
+      "a11yRules": ["table or card semantics clear"],
+      "seoRules": [],
+      "compatiblePrev": ["services", "testimonials"],
+      "compatibleNext": ["faq", "cta"],
+      "examplePrompts": ["three pricing tiers"],
+      "commonMistakes": ["unclear currency"]
+    },
+    {
+      "id": "faq",
+      "role": "faq",
+      "blueprintFile": "faq-section.html",
+      "inputs": ["items"],
+      "requiredContent": ["questions"],
+      "optionalContent": [],
+      "designRules": ["faq-questions", "faq-pattern"],
+      "a11yRules": ["accordion keyboard support"],
+      "seoRules": ["FAQPage-ready question text"],
+      "compatiblePrev": ["testimonials", "pricing", "process"],
+      "compatibleNext": ["contact", "cta", "footer"],
+      "examplePrompts": ["FAQ with accordion"],
+      "commonMistakes": ["non-questions as titles"]
+    },
+    {
+      "id": "contact",
+      "role": "contact",
+      "blueprintFile": "form-contact.html",
+      "inputs": ["fields"],
+      "requiredContent": ["name", "email", "message"],
+      "optionalContent": ["phone"],
+      "designRules": ["contact-labels", "contact-summary"],
+      "a11yRules": ["labels", "form-summary"],
+      "seoRules": [],
+      "compatiblePrev": ["faq", "testimonials"],
+      "compatibleNext": ["footer", "cta"],
+      "examplePrompts": ["contact form with validation summary"],
+      "commonMistakes": ["placeholder-only labels"]
+    },
+    {
+      "id": "cta",
+      "role": "cta",
+      "blueprintFile": "cta-band.html",
+      "inputs": ["title", "cta"],
+      "requiredContent": ["headline", "primaryCta"],
+      "optionalContent": ["secondaryCta"],
+      "designRules": ["hero-cta-max"],
+      "a11yRules": ["button semantics"],
+      "seoRules": [],
+      "compatiblePrev": ["faq", "pricing", "testimonials"],
+      "compatibleNext": ["footer"],
+      "examplePrompts": ["final CTA band"],
+      "commonMistakes": ["competing CTAs"]
+    },
+    {
+      "id": "footer",
+      "role": "footer",
+      "blueprintFile": "footer-simple.html",
+      "inputs": ["brand", "links"],
+      "requiredContent": ["brand"],
+      "optionalContent": ["legal", "social"],
+      "designRules": [],
+      "a11yRules": ["contentinfo landmark"],
+      "seoRules": ["legal links"],
+      "compatiblePrev": ["cta", "contact", "faq"],
+      "compatibleNext": [],
+      "examplePrompts": ["site footer"],
+      "commonMistakes": ["missing legal links on regulated niches"]
+    },
+    {
+      "id": "navbar",
+      "role": "navbar",
+      "blueprintFile": "navbar-header.html",
+      "inputs": ["brand", "links"],
+      "requiredContent": ["brand"],
+      "optionalContent": ["cta", "search"],
+      "designRules": [],
+      "a11yRules": ["nav landmark"],
+      "seoRules": ["internal links"],
+      "compatiblePrev": [],
+      "compatibleNext": ["hero"],
+      "examplePrompts": ["marketing navbar"],
+      "commonMistakes": ["too many links"]
+    }
+  ]
+}

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;');
+}