@sweberdev/witness 0.0.0-stage → 0.1.1

package/src/cli.ts

@@ -0,0 +1,160 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { basename, extname, join } from "node:path";
+import { parseArgs } from "node:util";
+import { detectImageFormat, markImage, readImageMarking } from "./image.js";
+import { iptcSourceType } from "./marking.js";
+import type { ContentKind, MarkingInput } from "./types.js";
+import { readTextWatermark } from "./watermark.js";
+
+export interface CliIo {
+  out: (line: string) => void;
+  err: (line: string) => void;
+}
+
+const HELP = `witness: AI Act Article 50 marking for images and text
+
+Usage
+  witness mark <files...> (--out <dir> | --in-place) [options]
+  witness inspect <files...> [--json] [--require]
+
+mark options
+  --generator <name>         AI system, e.g. "gpt-image-2"
+  --generator-version <v>    its version
+  --kind <kind>              generated (default), edited or deepfake
+  --provider <name>          your company or product
+  --url <url>                page that explains how you use AI
+  --description <text>       free text written to dc:description
+  --overwrite-c2pa           also rewrite files that carry a C2PA manifest
+
+inspect options
+  --json                     one JSON object per file
+  --require                  exit 1 if a file carries no AI marking
+
+Images: PNG, JPEG, WebP (XMP with IPTC Digital Source Type).
+Text files are checked for the Witness text watermark.`;
+
+const KINDS: ContentKind[] = ["generated", "edited", "deepfake"];
+
+export async function runCli(argv: string[], io: CliIo = defaultIo): Promise<number> {
+  const [command, ...rest] = argv;
+  if (!command || command === "--help" || command === "-h" || command === "help") {
+    io.out(HELP);
+    return command ? 0 : 1;
+  }
+  try {
+    if (command === "mark") return await mark(rest, io);
+    if (command === "inspect") return await inspect(rest, io);
+    io.err(`Unknown command "${command}". Run "witness --help".`);
+    return 1;
+  } catch (error) {
+    io.err(error instanceof Error ? error.message : String(error));
+    return 1;
+  }
+}
+
+async function mark(argv: string[], io: CliIo): Promise<number> {
+  const { values, positionals } = parseArgs({
+    args: argv,
+    allowPositionals: true,
+    options: {
+      out: { type: "string" },
+      "in-place": { type: "boolean" },
+      generator: { type: "string" },
+      "generator-version": { type: "string" },
+      kind: { type: "string" },
+      provider: { type: "string" },
+      url: { type: "string" },
+      description: { type: "string" },
+      "overwrite-c2pa": { type: "boolean" },
+    },
+  });
+  if (positionals.length === 0) throw new Error("witness mark: no files given.");
+  if (!values.out && !values["in-place"]) {
+    throw new Error("witness mark: pass --out <dir> or --in-place.");
+  }
+  const kind = (values.kind ?? "generated") as ContentKind;
+  if (!KINDS.includes(kind))
+    throw new Error(`witness mark: --kind must be one of ${KINDS.join(", ")}.`);
+  const input: MarkingInput = { kind };
+  if (values.generator) input.generator = values.generator;
+  if (values["generator-version"]) input.generatorVersion = values["generator-version"];
+  if (values.provider) input.provider = values.provider;
+  if (values.url) input.disclosureUrl = values.url;
+  if (values.description) input.description = values.description;
+  if (values.out) await mkdir(values.out, { recursive: true });
+
+  let failed = 0;
+  for (const file of positionals) {
+    const bytes = new Uint8Array(await readFile(file));
+    const result = markImage(bytes, input, {
+      c2pa: values["overwrite-c2pa"] ? "overwrite" : "skip",
+    });
+    if (result.status === "unsupported") {
+      io.err(`${file}: not a PNG, JPEG or WebP file, skipped`);
+      failed++;
+      continue;
+    }
+    if (result.status === "skipped-c2pa") {
+      io.err(`${file}: carries a C2PA manifest, left unchanged (use --overwrite-c2pa to force)`);
+      continue;
+    }
+    const target = values.out ? join(values.out, basename(file)) : file;
+    await writeFile(target, result.bytes);
+    io.out(`${file}: marked (${result.format}) -> ${target}`);
+  }
+  return failed > 0 ? 1 : 0;
+}
+
+async function inspect(argv: string[], io: CliIo): Promise<number> {
+  const { values, positionals } = parseArgs({
+    args: argv,
+    allowPositionals: true,
+    options: { json: { type: "boolean" }, require: { type: "boolean" } },
+  });
+  if (positionals.length === 0) throw new Error("witness inspect: no files given.");
+  let unmarked = 0;
+  for (const file of positionals) {
+    const bytes = new Uint8Array(await readFile(file));
+    const format = detectImageFormat(bytes);
+    if (format) {
+      const info = readImageMarking(bytes);
+      const marked = info.aiGenerated || info.c2pa;
+      if (!marked) unmarked++;
+      if (values.json) {
+        const { xmp: _xmp, ...rest } = info;
+        io.out(JSON.stringify({ file, ...rest }));
+      } else {
+        const parts = [
+          `${file}: ${format}`,
+          info.sourceType
+            ? `source type ${iptcSourceType(info.sourceType)}`
+            : "no IPTC source type",
+          info.generator ? `generator ${info.generator}` : null,
+          info.c2pa ? "C2PA manifest present (not verified)" : null,
+          marked ? "AI-marked" : "NOT AI-marked",
+        ];
+        io.out(parts.filter(Boolean).join(", "));
+      }
+      continue;
+    }
+    const ext = extname(file).toLowerCase();
+    const text = new TextDecoder().decode(bytes);
+    const watermark = readTextWatermark(text);
+    if (!watermark) unmarked++;
+    if (values.json) {
+      io.out(JSON.stringify({ file, format: ext.slice(1) || "text", watermark }));
+    } else {
+      io.out(
+        watermark
+          ? `${file}: text watermark found${watermark.generator ? `, generator ${watermark.generator}` : ""}${watermark.createdAt ? `, created ${watermark.createdAt}` : ""}`
+          : `${file}: no Witness text watermark`,
+      );
+    }
+  }
+  return values.require && unmarked > 0 ? 1 : 0;
+}
+
+const defaultIo: CliIo = {
+  out: (line) => process.stdout.write(`${line}\n`),
+  err: (line) => process.stderr.write(`${line}\n`),
+};

package/src/disclosure.ts

@@ -0,0 +1,172 @@
+import type { DisclosureKind } from "./types.js";
+
+/** Minimal key-value storage, e.g. `localStorage`. */
+export interface DisclosureStorage {
+  getItem(key: string): string | null;
+  setItem(key: string, value: string): void;
+  removeItem(key: string): void;
+}
+
+export interface DisclosureEvent {
+  type: "shown" | "acknowledged";
+  /** Your id for this disclosure, e.g. "support-chat". */
+  id: string;
+  kind: DisclosureKind;
+  /** Bump the version when the wording changes, so people see the new text once. */
+  version: string;
+  locale: string;
+  /** ISO 8601 timestamp. */
+  at: string;
+}
+
+export interface DisclosureOptions {
+  /** Your id for this disclosure. Default: the kind. */
+  id?: string;
+  /** Default `chatbot`. */
+  kind?: DisclosureKind;
+  /** Default `1`. */
+  version?: string;
+  /** Locale shown, recorded in events. Default `en`. */
+  locale?: string;
+  /**
+   * Where the acknowledgement is remembered: `local` (default), `session`, `memory` or your
+   * own storage. Falls back to memory when browser storage is unavailable.
+   */
+  storage?: "local" | "session" | "memory" | DisclosureStorage;
+  /**
+   * Called when the notice is shown or acknowledged. Send these to your log (for example
+   * Logarithm) to keep evidence of what people were told and when.
+   */
+  onEvent?: (event: DisclosureEvent) => void;
+  /** Clock for tests. */
+  now?: () => Date;
+}
+
+export interface Disclosure {
+  readonly id: string;
+  readonly kind: DisclosureKind;
+  readonly version: string;
+  /** True until this version was acknowledged. */
+  needsAcknowledgement(): boolean;
+  /** When this version was acknowledged, or `null`. */
+  acknowledgedAt(): string | null;
+  /** Records that the notice was rendered. Emits a `shown` event once per instance. */
+  markShown(): void;
+  /** Records the acknowledgement and emits an `acknowledged` event. */
+  acknowledge(): void;
+  /** Forgets the acknowledgement. */
+  reset(): void;
+  /** Called whenever the acknowledgement changes. Returns an unsubscribe function. */
+  subscribe(listener: () => void): () => void;
+}
+
+const PREFIX = "witness:ack:";
+
+/**
+ * Tracks whether a person has seen and acknowledged an AI disclosure.
+ *
+ * Article 50(5) asks for the information "at the latest at the time of the first interaction
+ * or exposure". Keep a compact label visible after the acknowledgement: the acknowledgement
+ * only collapses the notice, it does not make it disappear.
+ */
+export function createDisclosure(options: DisclosureOptions = {}): Disclosure {
+  const kind = options.kind ?? "chatbot";
+  const id = options.id ?? kind;
+  const version = options.version ?? "1";
+  const locale = options.locale ?? "en";
+  const now = options.now ?? (() => new Date());
+  const storage = resolveStorage(options.storage);
+  const key = `${PREFIX}${id}`;
+  const listeners = new Set<() => void>();
+  let shown = false;
+
+  const read = (): { version: string; at: string } | null => {
+    try {
+      const raw = storage.getItem(key);
+      if (!raw) return null;
+      const parsed = JSON.parse(raw) as { version?: unknown; at?: unknown };
+      if (typeof parsed.version !== "string" || typeof parsed.at !== "string") return null;
+      return { version: parsed.version, at: parsed.at };
+    } catch {
+      return null;
+    }
+  };
+
+  const emit = (type: DisclosureEvent["type"], at: string) => {
+    options.onEvent?.({ type, id, kind, version, locale, at });
+  };
+
+  const notify = () => {
+    for (const listener of listeners) listener();
+  };
+
+  return {
+    id,
+    kind,
+    version,
+    needsAcknowledgement: () => read()?.version !== version,
+    acknowledgedAt: () => {
+      const entry = read();
+      return entry?.version === version ? entry.at : null;
+    },
+    markShown() {
+      if (shown) return;
+      shown = true;
+      emit("shown", now().toISOString());
+    },
+    acknowledge() {
+      const at = now().toISOString();
+      try {
+        storage.setItem(key, JSON.stringify({ version, at }));
+      } catch {
+        // Storage full or blocked: the acknowledgement lasts for this page only.
+      }
+      emit("acknowledged", at);
+      notify();
+    },
+    reset() {
+      try {
+        storage.removeItem(key);
+      } catch {
+        // ignore
+      }
+      notify();
+    },
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+  };
+}
+
+function resolveStorage(option: DisclosureOptions["storage"]): DisclosureStorage {
+  if (option && typeof option === "object") return option;
+  if (option !== "memory") {
+    try {
+      const candidate = option === "session" ? globalThis.sessionStorage : globalThis.localStorage;
+      if (candidate) {
+        const probe = `${PREFIX}probe`;
+        candidate.setItem(probe, "1");
+        candidate.removeItem(probe);
+        return candidate;
+      }
+    } catch {
+      // fall through to memory
+    }
+  }
+  return memoryStorage();
+}
+
+/** In-memory storage, e.g. for server rendering or tests. */
+export function memoryStorage(): DisclosureStorage {
+  const map = new Map<string, string>();
+  return {
+    getItem: (key) => map.get(key) ?? null,
+    setItem: (key, value) => {
+      map.set(key, value);
+    },
+    removeItem: (key) => {
+      map.delete(key);
+    },
+  };
+}

package/src/elements-auto.ts

@@ -0,0 +1,5 @@
+import { defineWitnessElements } from "./elements.js";
+
+defineWitnessElements();
+
+export { defineWitnessElements, WitnessLabelElement, WitnessNoticeElement } from "./elements.js";

package/src/elements.ts

@@ -0,0 +1,363 @@
+/**
+ * Framework-free custom elements:
+ *
+ * - `<witness-notice>`: the chatbot notice (Art. 50(1)). Expanded until acknowledged, then a
+ *   compact label that can be reopened.
+ * - `<witness-label>`: a badge for AI-generated or AI-edited content with a details popover.
+ *
+ * Import `@sweberdev/witness/elements` to register both, or call `defineWitnessElements()`.
+ */
+
+import { createDisclosure, type Disclosure, type DisclosureEvent } from "./disclosure.js";
+import { format, getMessages } from "./i18n.js";
+import { DISCLOSURE_KINDS, type DisclosureKind } from "./types.js";
+
+const BaseElement: typeof HTMLElement =
+  typeof HTMLElement === "undefined" ? (class {} as unknown as typeof HTMLElement) : HTMLElement;
+
+const SHARED_CSS = `
+:host { --witness-accent: #003399; --witness-accent-text: #ffffff; --witness-bg: #ffffff;
+  --witness-fg: #1a1a1a; --witness-muted: #555b66; --witness-border: #d7dbe3; --witness-radius: 8px;
+  font: inherit; color: var(--witness-fg); }
+@media (prefers-color-scheme: dark) {
+  :host { --witness-accent: #8fb0ff; --witness-accent-text: #0b1530; --witness-bg: #15181f;
+    --witness-fg: #eef1f6; --witness-muted: #a9b0bd; --witness-border: #2c323d; }
+}
+.icon { display: inline-flex; align-items: center; justify-content: center; min-width: 1.75em;
+  height: 1.5em; padding: 0 .3em; border-radius: 4px; background: var(--witness-accent);
+  color: var(--witness-accent-text); font-weight: 700; font-size: .75em; letter-spacing: .02em;
+  line-height: 1; flex: none; }
+button { font: inherit; cursor: pointer; }
+button:focus-visible, a:focus-visible { outline: 2px solid var(--witness-accent); outline-offset: 2px; }
+a { color: inherit; }
+.muted { color: var(--witness-muted); }
+`;
+
+const NOTICE_CSS = `${SHARED_CSS}
+:host { display: block; }
+.notice { display: flex; gap: .75em; align-items: flex-start; padding: .875em 1em;
+  border: 1px solid var(--witness-border); border-left: 4px solid var(--witness-accent);
+  border-radius: var(--witness-radius); background: var(--witness-bg); }
+.notice h2 { font-size: 1em; margin: 0 0 .25em; }
+.notice p { margin: 0 0 .75em; line-height: 1.45; }
+.actions { display: flex; gap: .75em; align-items: center; flex-wrap: wrap; }
+.ack { padding: .4em .9em; border-radius: 6px; border: 0; background: var(--witness-accent);
+  color: var(--witness-accent-text); font-weight: 600; }
+.compact { display: inline-flex; gap: .5em; align-items: center; padding: .25em .5em;
+  border: 1px solid var(--witness-border); border-radius: 999px; background: var(--witness-bg);
+  color: var(--witness-fg); font-size: .875em; }
+`;
+
+const LABEL_CSS = `${SHARED_CSS}
+:host { display: inline-block; position: relative; font-size: .875em; }
+:host([variant="overlay"]) { position: absolute; inset-block-start: .5em; inset-inline-end: .5em; z-index: 1; }
+.badge { display: inline-flex; gap: .4em; align-items: center; padding: .2em .55em .2em .25em;
+  border: 1px solid var(--witness-border); border-radius: 999px; background: var(--witness-bg);
+  color: var(--witness-fg); }
+.panel { position: absolute; inset-block-start: calc(100% + .4em); inset-inline-end: 0; z-index: 10;
+  width: max-content; max-width: min(22em, 80vw); padding: .75em .875em; text-align: start;
+  border: 1px solid var(--witness-border); border-radius: var(--witness-radius);
+  background: var(--witness-bg); box-shadow: 0 6px 24px rgb(0 0 0 / .15); line-height: 1.45; }
+:host([variant="inline"]) .panel, :host(:not([variant])) .panel { inset-inline-end: auto; inset-inline-start: 0; }
+.panel strong { display: block; margin-bottom: .25em; }
+.panel p { margin: 0 0 .4em; }
+.panel ul { margin: .4em 0; padding-inline-start: 1.1em; }
+.close { position: absolute; inset-block-start: .35em; inset-inline-end: .35em; border: 0;
+  background: none; color: var(--witness-muted); font-size: 1.1em; line-height: 1; padding: .2em .35em; }
+[hidden] { display: none !important; }
+`;
+
+function locale(el: HTMLElement): string[] {
+  const own = el.getAttribute("locale") ?? el.closest("[lang]")?.getAttribute("lang");
+  if (own) return [own];
+  return typeof navigator !== "undefined" ? [...navigator.languages] : [];
+}
+
+function kindOf(el: HTMLElement, fallback: DisclosureKind): DisclosureKind {
+  const value = el.getAttribute("kind") as DisclosureKind | null;
+  return value && DISCLOSURE_KINDS.includes(value) ? value : fallback;
+}
+
+function h<K extends keyof HTMLElementTagNameMap>(
+  doc: Document,
+  tag: K,
+  attrs: Record<string, string> = {},
+  ...children: Array<Node | string | null>
+): HTMLElementTagNameMap[K] {
+  const el = doc.createElement(tag);
+  for (const [name, value] of Object.entries(attrs)) el.setAttribute(name, value);
+  for (const child of children) {
+    if (child !== null) el.append(child);
+  }
+  return el;
+}
+
+function icon(doc: Document): HTMLElement {
+  return h(doc, "span", { class: "icon", "aria-hidden": "true", part: "icon" }, "AI");
+}
+
+/** `<witness-notice kind="chatbot" locale="de" disclosure-id="support" version="2" href="/ki">` */
+export class WitnessNoticeElement extends BaseElement {
+  static observedAttributes = ["kind", "locale", "disclosure-id", "version", "href", "storage"];
+
+  #disclosure: Disclosure | null = null;
+  #unsubscribe: (() => void) | null = null;
+  #expanded = false;
+  /** `id@version` of the disclosure a `shown` event was sent for, so attribute changes don't repeat it. */
+  #shownFor: string | null = null;
+
+  connectedCallback(): void {
+    if (!this.shadowRoot) this.attachShadow({ mode: "open" });
+    this.#setup();
+  }
+
+  disconnectedCallback(): void {
+    this.#unsubscribe?.();
+    this.#unsubscribe = null;
+  }
+
+  attributeChangedCallback(_name: string, oldValue: string | null, newValue: string | null): void {
+    if (oldValue === newValue) return;
+    if (this.isConnected && this.shadowRoot) this.#setup();
+  }
+
+  /** Forgets the acknowledgement and shows the full notice again. */
+  reset(): void {
+    this.#disclosure?.reset();
+  }
+
+  get disclosure(): Disclosure | null {
+    return this.#disclosure;
+  }
+
+  #setup(): void {
+    this.#unsubscribe?.();
+    const storage = this.getAttribute("storage");
+    const kind = kindOf(this, "chatbot");
+    const tags = locale(this);
+    this.#disclosure = createDisclosure({
+      kind,
+      id: this.getAttribute("disclosure-id") ?? kind,
+      version: this.getAttribute("version") ?? "1",
+      locale: getLocaleCode(tags),
+      ...(storage === "session" || storage === "memory" || storage === "local" ? { storage } : {}),
+      onEvent: (event) => this.#dispatch(event),
+    });
+    this.#expanded = false;
+    this.#unsubscribe = this.#disclosure.subscribe(() => {
+      this.#expanded = false;
+      this.#render();
+    });
+    this.#render();
+  }
+
+  #dispatch(event: DisclosureEvent): void {
+    this.dispatchEvent(
+      new CustomEvent(`witness-${event.type}`, { detail: event, bubbles: true, composed: true }),
+    );
+  }
+
+  #render(): void {
+    const root = this.shadowRoot;
+    const disclosure = this.#disclosure;
+    if (!root || !disclosure) return;
+    const doc = this.ownerDocument;
+    const messages = getMessages(locale(this));
+    const text = messages.kinds[disclosure.kind];
+    const href = this.getAttribute("href");
+    const full = this.#expanded || disclosure.needsAcknowledgement();
+
+    const style = h(doc, "style", {}, NOTICE_CSS);
+    if (full) {
+      const ack = h(
+        doc,
+        "button",
+        { type: "button", class: "ack", part: "button" },
+        messages.ui.acknowledge,
+      );
+      ack.addEventListener("click", () => disclosure.acknowledge());
+      const link = href ? h(doc, "a", { href, part: "link" }, messages.ui.moreInfo) : null;
+      const box = h(
+        doc,
+        "section",
+        { class: "notice", role: "note", "aria-labelledby": "title", part: "notice" },
+        icon(doc),
+        h(
+          doc,
+          "div",
+          {},
+          h(doc, "h2", { id: "title", part: "title" }, text.title),
+          h(doc, "p", { part: "body" }, h(doc, "slot", {}, text.body)),
+          h(doc, "div", { class: "actions" }, ack, link),
+        ),
+      );
+      root.replaceChildren(style, box);
+      const shownFor = `${disclosure.id}@${disclosure.version}`;
+      if (this.#shownFor !== shownFor) {
+        this.#shownFor = shownFor;
+        disclosure.markShown();
+      }
+    } else {
+      const reopen = h(
+        doc,
+        "button",
+        {
+          type: "button",
+          class: "compact",
+          "aria-label": `${text.label}: ${messages.ui.details}`,
+          part: "compact",
+        },
+        icon(doc),
+        text.label,
+      );
+      reopen.addEventListener("click", () => {
+        this.#expanded = true;
+        this.#render();
+      });
+      root.replaceChildren(style, reopen);
+    }
+  }
+}
+
+/** `<witness-label kind="generated" generator="Claude" created="2026-10-05" reviewed href="/ki">` */
+export class WitnessLabelElement extends BaseElement {
+  static observedAttributes = [
+    "kind",
+    "locale",
+    "generator",
+    "generator-version",
+    "created",
+    "reviewed",
+    "href",
+    "variant",
+  ];
+
+  #open = false;
+  #onKey = (event: KeyboardEvent) => {
+    if (event.key === "Escape" && this.#open) {
+      this.#toggle(false);
+      this.shadowRoot?.querySelector<HTMLButtonElement>(".badge")?.focus();
+    }
+  };
+  #onOutside = (event: Event) => {
+    if (this.#open && !event.composedPath().includes(this)) this.#toggle(false);
+  };
+
+  connectedCallback(): void {
+    if (!this.shadowRoot) this.attachShadow({ mode: "open" });
+    this.ownerDocument.addEventListener("keydown", this.#onKey);
+    this.ownerDocument.addEventListener("click", this.#onOutside);
+    this.#render();
+  }
+
+  disconnectedCallback(): void {
+    this.ownerDocument.removeEventListener("keydown", this.#onKey);
+    this.ownerDocument.removeEventListener("click", this.#onOutside);
+  }
+
+  attributeChangedCallback(): void {
+    if (this.isConnected && this.shadowRoot) this.#render();
+  }
+
+  #toggle(open: boolean): void {
+    this.#open = open;
+    this.#render();
+  }
+
+  #render(): void {
+    const root = this.shadowRoot;
+    if (!root) return;
+    const doc = this.ownerDocument;
+    const tags = locale(this);
+    const messages = getMessages(tags);
+    const kind = kindOf(this, "generated");
+    const text = messages.kinds[kind];
+    const generator = [this.getAttribute("generator"), this.getAttribute("generator-version")]
+      .filter(Boolean)
+      .join(" ");
+    const created = this.getAttribute("created");
+    const href = this.getAttribute("href");
+
+    const badge = h(
+      doc,
+      "button",
+      {
+        type: "button",
+        class: "badge",
+        part: "badge",
+        "aria-expanded": String(this.#open),
+        "aria-controls": "panel",
+        title: messages.ui.details,
+      },
+      icon(doc),
+      h(doc, "span", { part: "label" }, text.label),
+    );
+    badge.addEventListener("click", () => this.#toggle(!this.#open));
+
+    const facts = h(doc, "ul", {});
+    if (generator) facts.append(h(doc, "li", {}, format(messages.ui.generatedWith, { generator })));
+    if (created) {
+      facts.append(
+        h(doc, "li", {}, format(messages.ui.createdOn, { date: formatDate(created, tags) })),
+      );
+    }
+    if (this.hasAttribute("reviewed")) facts.append(h(doc, "li", {}, messages.ui.humanReviewed));
+
+    const close = h(
+      doc,
+      "button",
+      { type: "button", class: "close", "aria-label": messages.ui.close },
+      "×",
+    );
+    close.addEventListener("click", () => this.#toggle(false));
+
+    const panel = h(
+      doc,
+      "div",
+      { id: "panel", class: "panel", role: "dialog", "aria-label": text.title, part: "panel" },
+      close,
+      h(doc, "strong", {}, text.title),
+      h(doc, "p", {}, text.body),
+      facts.childElementCount > 0 ? facts : null,
+      href ? h(doc, "a", { href, part: "link" }, messages.ui.moreInfo) : null,
+    );
+    if (!this.#open) panel.hidden = true;
+    root.replaceChildren(h(doc, "style", {}, LABEL_CSS), badge, panel);
+  }
+}
+
+function formatDate(value: string, tags: string[]): string {
+  const date = new Date(value);
+  if (Number.isNaN(date.getTime())) return value;
+  try {
+    return new Intl.DateTimeFormat(tags.length > 0 ? tags : undefined, {
+      dateStyle: "medium",
+    }).format(date);
+  } catch {
+    return value;
+  }
+}
+
+function getLocaleCode(tags: string[]): string {
+  return tags[0] ?? "en";
+}
+
+/** Registers `<witness-notice>` and `<witness-label>` once. Safe to call during SSR. */
+export function defineWitnessElements(): void {
+  if (typeof customElements === "undefined") return;
+  if (!customElements.get("witness-notice"))
+    customElements.define("witness-notice", WitnessNoticeElement);
+  if (!customElements.get("witness-label"))
+    customElements.define("witness-label", WitnessLabelElement);
+}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    "witness-notice": WitnessNoticeElement;
+    "witness-label": WitnessLabelElement;
+  }
+  interface HTMLElementEventMap {
+    "witness-shown": CustomEvent<DisclosureEvent>;
+    "witness-acknowledged": CustomEvent<DisclosureEvent>;
+  }
+}