@snutig/react 0.1.0

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@snutig/react",
+  "version": "0.1.0",
+  "description": "React bindings for the snutig CAPTCHA widget (<snutig-captcha>), pre-themed to match the snutig WordPress/Elementor plugin.",
+  "license": "Apache-2.0",
+  "homepage": "https://snutig.de",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/snutiggmbh/snutig-captcha.git",
+    "directory": "packages/react"
+  },
+  "bugs": {
+    "url": "https://github.com/snutiggmbh/snutig-captcha/issues"
+  },
+  "keywords": [
+    "captcha",
+    "proof-of-work",
+    "bot-protection",
+    "react",
+    "nextjs",
+    "web-components",
+    "privacy",
+    "gdpr",
+    "snutig"
+  ],
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "sideEffects": [
+    "./dist/theme.css"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./theme.css": "./dist/theme.css"
+  },
+  "files": [
+    "dist",
+    "src",
+    "LICENSE",
+    "README.md"
+  ],
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "devDependencies": {
+    "@types/react": "^19.0.0",
+    "esbuild": "^0.28.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "typescript": "^5.9.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "node build.mjs && tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "node ssr-smoke.mjs"
+  }
+}

package/src/SnutigCaptcha.tsx

@@ -0,0 +1,325 @@
+import {
+  createElement,
+  forwardRef,
+  useCallback,
+  useEffect,
+  useImperativeHandle,
+  useInsertionEffect,
+  useLayoutEffect,
+  useRef,
+} from "react";
+import type { CSSProperties, Ref } from "react";
+import { DEFAULT_API_URL, challengeEndpoint, loadSnutigWidget } from "./loader.js";
+import { LABELS, LABEL_ATTRIBUTES } from "./labels.js";
+import type { SnutigLabels, SnutigLocale } from "./labels.js";
+import { injectSnutigTheme } from "./theme.js";
+import type {
+  SnutigCaptchaElement,
+  SnutigErrorDetail,
+  SolveResult,
+} from "./types.js";
+
+/**
+ * Inline properties that hidden mode touches — ours (`display`) plus the ones the
+ * widget writes when it degrades an unlicensed invisible widget into a floating
+ * badge. Cleared together so `hidden` can be toggled off from either state.
+ */
+const HIDDEN_STYLE_PROPERTIES = [
+  "display",
+  "visibility",
+  "opacity",
+  "position",
+  "inset-inline-end",
+  "inset-block-end",
+  "z-index",
+] as const;
+
+/**
+ * Hiding has to happen before the first paint, or an invisible widget flashes
+ * visible for a frame — but `useLayoutEffect` warns when React renders this
+ * component on a server. Nothing to hide there, so fall back to `useEffect`,
+ * which is never reached during SSR either.
+ */
+const useBeforePaintEffect = typeof document === "undefined" ? useEffect : useLayoutEffect;
+
+export interface SnutigCaptchaProps {
+  /** Website key from the dashboard (Websites → Keys). */
+  siteKey: string;
+  /**
+   * snutig captcha API base URL. Defaults to the managed service
+   * (`https://api.captcha.snutig.dev`) — set it only for a staging deployment.
+   */
+  apiUrl?: string;
+  /**
+   * Full challenge endpoint base, overriding `apiUrl` + `siteKey`
+   * (`<apiUrl>/<siteKey>/`). Rarely needed — for a reverse-proxied path.
+   */
+  endpoint?: string;
+  /**
+   * `name` of the hidden input the token is written to, for plain form posts.
+   * Defaults to `snutig-token`.
+   */
+  fieldName?: string;
+  /**
+   * Blocks native form submission until solved, via constraint validation
+   * (the widget participates as a form-associated element).
+   */
+  required?: boolean;
+  /**
+   * Invisible mode: no visible widget — nothing for the user to click, so the
+   * solve has to be started from the ref (`solve()`, typically in `onSubmit`).
+   *
+   * Plan-gated (`hiddenMode`). A site that is not licensed for invisible solving
+   * gets `widget.hiddenMode: false` on its challenge, and the widget then
+   * degrades to a visible badge in the bottom-right corner rather than letting a
+   * form ship without a check — so this never *breaks*, it only stops being
+   * invisible.
+   *
+   * `required` does not apply: constraint validation cannot report a problem on
+   * an element the user cannot see (the browser refuses to submit and shows
+   * nothing), so it is ignored here.
+   */
+  hidden?: boolean;
+  /** Solver worker count. Defaults to `navigator.hardwareConcurrency`. */
+  workers?: number;
+  /** Label set. Defaults to `"de"` — the wording the WordPress plugin ships. */
+  locale?: SnutigLocale;
+  /** Per-label overrides, merged over the locale's set. */
+  labels?: Partial<SnutigLabels>;
+  /**
+   * `"snutig"` (default) injects the brand theme and marks the wrapper for it.
+   * `"external"` marks the wrapper but injects nothing — for importing
+   * `@snutig/react/theme.css` through your own pipeline (or under a strict CSP).
+   * `"none"` leaves the widget unstyled even when another instance on the page is
+   * themed: the brand CSS targets the wrapper class, so an unthemed instance has to
+   * not carry it.
+   */
+  theme?: "snutig" | "external" | "none";
+  /** Help link, shown only after a failure. */
+  troubleshootingUrl?: string;
+  /** CSP nonce for the injected script + styles. */
+  nonce?: string;
+  className?: string;
+  style?: CSSProperties;
+  /** Solved — `token` goes to your server's `POST /:siteKey/siteverify`. */
+  onSolve?: (token: string) => void;
+  onError?: (error: SnutigErrorDetail) => void;
+  /** Solve progress, 0–100. */
+  onProgress?: (progress: number) => void;
+  /** Token cleared — on expiry, or via `reset()`. */
+  onReset?: () => void;
+}
+
+export interface SnutigCaptchaHandle {
+  /** Starts a solve (the widget also does this on click). */
+  solve(): Promise<SolveResult>;
+  /** Clears the token and the hidden field — call after a failed submit. */
+  reset(): void;
+  /** Current token, or `null` when unsolved. */
+  readonly token: string | null;
+  /** The underlying custom element, once mounted. */
+  readonly element: SnutigCaptchaElement | null;
+}
+
+/** Latest-callback ref, so listeners attach once instead of on every render. */
+function useLatest<T>(value: T) {
+  const ref = useRef(value);
+  useInsertionEffect(() => {
+    ref.current = value;
+  });
+  return ref;
+}
+
+/**
+ * The snutig CAPTCHA widget as a React component.
+ *
+ * Wraps the `<snutig-captcha>` custom element served by the captcha server: this
+ * package loads that bundle, maps props to its attributes, and turns its
+ * `solve`/`error`/`progress`/`reset` DOM events into props. The widget renders
+ * itself into a shadow root and writes the token into a hidden input, so a plain
+ * `<form>` post carries it with no extra wiring.
+ *
+ * With `hidden` it renders nothing and solves only when `solve()` is called from
+ * the ref — the invisible mode, which is a plan entitlement the server asserts on
+ * every challenge.
+ *
+ * A token only proves the check ran in the browser — always verify it
+ * server-side with `POST <apiUrl>/<siteKey>/siteverify` before trusting the
+ * submission.
+ */
+export const SnutigCaptcha = forwardRef(function SnutigCaptcha(
+  props: SnutigCaptchaProps,
+  ref: Ref<SnutigCaptchaHandle>,
+) {
+  const {
+    siteKey,
+    apiUrl = DEFAULT_API_URL,
+    endpoint,
+    fieldName = "snutig-token",
+    required = false,
+    hidden = false,
+    workers,
+    locale = "de",
+    labels,
+    theme = "snutig",
+    troubleshootingUrl,
+    nonce,
+    className,
+    style,
+    onSolve,
+    onError,
+    onProgress,
+    onReset,
+  } = props;
+
+  const elementRef = useRef<SnutigCaptchaElement | null>(null);
+  const handlers = useLatest({ onSolve, onError, onProgress, onReset });
+
+  if (theme === "snutig") injectSnutigTheme(nonce);
+  // The theme is a document-wide stylesheet keyed on this class, so opting out has to
+  // happen here: every wrapper used to get `snutig-captcha` regardless, and one themed
+  // instance therefore themed every "unstyled" one on the page too.
+  const wrapperClass = theme === "none" ? "snutig-captcha-unstyled" : "snutig-captcha";
+
+  // The themed wrapper is `display: inline-block`, so leaving it in flow around a
+  // display:none widget still contributes a line box — a stray gap of one
+  // line-height where the widget should be invisible. `contents` makes it generate
+  // no box at all while still inheriting the theme's custom properties down, and
+  // leaves the degraded badge's `position: fixed` resolving against the viewport
+  // (a `display: none` wrapper would instead suppress the badge entirely).
+  const wrapperStyle = hidden ? { ...style, display: "contents" } : style;
+
+  const resolvedEndpoint = endpoint ?? challengeEndpoint(siteKey, apiUrl);
+
+  const reportError = useCallback(
+    (code: SnutigErrorDetail["code"], message: string) => {
+      handlers.current.onError?.({ isSnutig: true, code, message });
+    },
+    [handlers],
+  );
+
+  useEffect(() => {
+    let cancelled = false;
+    loadSnutigWidget({ apiUrl, nonce }).catch((err: unknown) => {
+      if (cancelled) return;
+      reportError("script_load_failed", err instanceof Error ? err.message : String(err));
+    });
+    return () => {
+      cancelled = true;
+    };
+  }, [apiUrl, nonce, reportError]);
+
+  // Hiding is applied imperatively rather than through the `style` prop because the
+  // widget writes to these same properties to un-hide itself when the site is not
+  // licensed for invisible solving. React must not own them: a re-render would
+  // reapply `display: none` and fight the degrade back into invisibility.
+  useBeforePaintEffect(() => {
+    const el = elementRef.current;
+    if (!el || !hidden) return;
+    el.style.display = "none";
+    return () => {
+      // Clear everything either side may have set, so toggling `hidden` off after a
+      // degrade has fired does not leave the element pinned as a fixed badge.
+      for (const property of HIDDEN_STYLE_PROPERTIES) el.style.removeProperty(property);
+    };
+  }, [hidden]);
+
+  useEffect(() => {
+    if (!hidden || !required) return;
+    console.warn(
+      "[@snutig/react] `required` is ignored on a hidden <SnutigCaptcha>: the browser " +
+        "cannot report a validation error on an invisible control and blocks submission " +
+        "silently. Start the solve from the ref in onSubmit instead.",
+    );
+  }, [hidden, required]);
+
+  // Attached to the element directly: these are CustomEvents, which React's
+  // synthetic event system does not surface as props. Listeners survive the
+  // element's upgrade, so attaching before the bundle arrives is fine.
+  useEffect(() => {
+    const el = elementRef.current;
+    if (!el) return;
+
+    const onSolveEvent = (event: Event) => {
+      const { token } = (event as CustomEvent<{ token: string }>).detail;
+      handlers.current.onSolve?.(token);
+    };
+    const onErrorEvent = (event: Event) => {
+      handlers.current.onError?.((event as CustomEvent<SnutigErrorDetail>).detail);
+    };
+    const onProgressEvent = (event: Event) => {
+      const { progress } = (event as CustomEvent<{ progress: number }>).detail;
+      handlers.current.onProgress?.(progress);
+    };
+    const onResetEvent = () => handlers.current.onReset?.();
+
+    el.addEventListener("solve", onSolveEvent);
+    el.addEventListener("error", onErrorEvent);
+    el.addEventListener("progress", onProgressEvent);
+    el.addEventListener("reset", onResetEvent);
+
+    return () => {
+      el.removeEventListener("solve", onSolveEvent);
+      el.removeEventListener("error", onErrorEvent);
+      el.removeEventListener("progress", onProgressEvent);
+      el.removeEventListener("reset", onResetEvent);
+    };
+  }, [handlers, resolvedEndpoint, fieldName]);
+
+  useImperativeHandle(
+    ref,
+    () => ({
+      solve() {
+        const el = elementRef.current;
+        if (!el?.solve) {
+          return Promise.reject(new Error("The snutig captcha widget is not ready yet"));
+        }
+        return el.solve();
+      },
+      reset() {
+        elementRef.current?.reset?.();
+      },
+      get token() {
+        return elementRef.current?.token ?? null;
+      },
+      get element() {
+        return elementRef.current;
+      },
+    }),
+    [],
+  );
+
+  const i18nAttributes: Record<string, string> = {};
+  const resolved = { ...LABELS[locale], ...labels };
+  for (const [key, value] of Object.entries(resolved)) {
+    if (typeof value !== "string" || value === "") continue;
+    const attribute = LABEL_ATTRIBUTES[key as keyof SnutigLabels];
+    if (attribute) i18nAttributes[attribute] = value;
+  }
+
+  const element = createElement("snutig-captcha", {
+    ref: elementRef,
+    // `data-snutig-hidden-field-name` is only read in connectedCallback, so a
+    // change has to remount the element rather than update it in place.
+    key: `${resolvedEndpoint}|${fieldName}`,
+    "data-snutig-api-endpoint": resolvedEndpoint,
+    "data-snutig-hidden-field-name": fieldName,
+    ...(workers ? { "data-snutig-worker-count": String(workers) } : {}),
+    ...(troubleshootingUrl ? { "data-snutig-troubleshooting-url": troubleshootingUrl } : {}),
+    // Read by the widget only at solve time, to pick the degrade shape: an element
+    // marked invisible has no layout slot to reveal, so it floats as a badge.
+    ...(hidden ? { "data-snutig-invisible": "" } : {}),
+    // The widget checks `hasAttribute("required")`; "" renders a bare attribute.
+    ...(required && !hidden ? { required: "" } : {}),
+    ...i18nAttributes,
+  });
+
+  return createElement(
+    "div",
+    {
+      className: className ? `${wrapperClass} ${className}` : wrapperClass,
+      style: wrapperStyle,
+    },
+    element,
+  );
+});

package/src/css.d.ts

@@ -0,0 +1,5 @@
+// esbuild inlines `*.css` imports as text (see build.mjs `loader`).
+declare module "*.css" {
+  const css: string;
+  export default css;
+}

package/src/index.ts

@@ -0,0 +1,27 @@
+export { SnutigCaptcha } from "./SnutigCaptcha.js";
+export type { SnutigCaptchaHandle, SnutigCaptchaProps } from "./SnutigCaptcha.js";
+
+export {
+  DEFAULT_API_URL,
+  challengeEndpoint,
+  loadSnutigWidget,
+  stripTrailingSlash,
+  widgetScriptUrl,
+} from "./loader.js";
+export type { LoadWidgetOptions } from "./loader.js";
+
+export { LABEL_ATTRIBUTES, LABELS } from "./labels.js";
+export type { SnutigLabels, SnutigLocale } from "./labels.js";
+
+export { injectSnutigTheme, THEME_CSS } from "./theme.js";
+
+export type {
+  SnutigCaptchaElement,
+  SnutigErrorCode,
+  SnutigErrorDetail,
+  SnutigProgressDetail,
+  SnutigSolveDetail,
+  SnutigWidgetErrorCode,
+  SnutigWindow,
+  SolveResult,
+} from "./types.js";

package/src/labels.ts

@@ -0,0 +1,66 @@
+/**
+ * Widget i18n. The widget reads each label from a `data-snutig-i18n-<key>`
+ * attribute and falls back to its own English string when the attribute is
+ * absent — so `locale: "en"` sets no attributes at all.
+ *
+ * The German set is the WordPress/Elementor plugin's wording verbatim (the three
+ * labels that plugin does not set are filled in here) so both integrations read
+ * identically to a customer.
+ */
+
+export interface SnutigLabels {
+  /** Idle label, e.g. "Ich bin ein Mensch". */
+  initialState: string;
+  verifyingLabel: string;
+  solvedLabel: string;
+  errorLabel: string;
+  /** Constraint-validation message when `required` and unsolved. */
+  requiredLabel: string;
+  groupAriaLabel: string;
+  verifyAriaLabel: string;
+  verifyingAriaLabel: string;
+  verifiedAriaLabel: string;
+  errorAriaLabel: string;
+  /** Banner shown when WebAssembly is unavailable (JS fallback is much slower). */
+  wasmDisabled: string;
+  /** Link text, rendered only when `troubleshootingUrl` is set. */
+  troubleshootingLabel: string;
+}
+
+export type SnutigLocale = "de" | "en";
+
+/** `keyof SnutigLabels` → the attribute the widget actually reads. */
+export const LABEL_ATTRIBUTES: Record<keyof SnutigLabels, string> = {
+  initialState: "data-snutig-i18n-initial-state",
+  verifyingLabel: "data-snutig-i18n-verifying-label",
+  solvedLabel: "data-snutig-i18n-solved-label",
+  errorLabel: "data-snutig-i18n-error-label",
+  requiredLabel: "data-snutig-i18n-required-label",
+  groupAriaLabel: "data-snutig-i18n-group-aria-label",
+  verifyAriaLabel: "data-snutig-i18n-verify-aria-label",
+  verifyingAriaLabel: "data-snutig-i18n-verifying-aria-label",
+  verifiedAriaLabel: "data-snutig-i18n-verified-aria-label",
+  errorAriaLabel: "data-snutig-i18n-error-aria-label",
+  wasmDisabled: "data-snutig-i18n-wasm-disabled",
+  troubleshootingLabel: "data-snutig-i18n-troubleshooting-label",
+};
+
+export const LABELS: Record<SnutigLocale, Partial<SnutigLabels>> = {
+  de: {
+    initialState: "Ich bin ein Mensch",
+    verifyingLabel: "Wird überprüft …",
+    solvedLabel: "Verifiziert",
+    errorLabel: "Fehler – bitte erneut versuchen",
+    requiredLabel: "Bitte bestätigen Sie, dass Sie ein Mensch sind",
+    groupAriaLabel: "CAPTCHA-Überprüfung",
+    verifyAriaLabel: "Klicken, um zu bestätigen, dass Sie ein Mensch sind",
+    verifyingAriaLabel: "Wird überprüft, bitte warten",
+    verifiedAriaLabel:
+      "Wir haben bestätigt, dass Sie ein Mensch sind. Sie können nun fortfahren.",
+    errorAriaLabel: "Ein Fehler ist aufgetreten, bitte erneut versuchen",
+    wasmDisabled: "WASM aktivieren für deutlich schnellere Überprüfung",
+    troubleshootingLabel: "Hilfe",
+  },
+  // The widget's built-in defaults are English; setting nothing keeps them.
+  en: {},
+};

package/src/loader.ts

@@ -0,0 +1,116 @@
+import type { SnutigWindow } from "./types.js";
+
+/**
+ * The snutig captcha API. snutig runs this as a managed service, so there is one
+ * of these and consumers do not host it — which is why `apiUrl` is optional
+ * everywhere it appears. Override it only to point at a staging deployment or a
+ * reverse proxy.
+ */
+export const DEFAULT_API_URL = "https://api.captcha.snutig.dev";
+
+/**
+ * Loads the widget bundle from the snutig captcha API that will also answer its
+ * challenges — the same origin rule the WordPress plugin follows
+ * (`/widget/v1/widget.js`, `access-control-allow-origin: *`). There is no CDN
+ * copy on purpose: the wire protocol is versioned with the server, and the bundle
+ * fetches `solver.wasm` relative to its own URL.
+ */
+export interface LoadWidgetOptions {
+  /** API base URL. Defaults to {@link DEFAULT_API_URL}. */
+  apiUrl?: string;
+  /** Full script URL — overrides `apiUrl`. */
+  scriptUrl?: string;
+  /** CSP nonce, applied to the script tag and the widget's own injected CSS/worker. */
+  nonce?: string;
+}
+
+const ELEMENT_NAME = "snutig-captcha";
+const SCRIPT_MARKER = "data-snutig-widget";
+
+/** In-flight/settled loads, keyed by resolved script URL. */
+const loads = new Map<string, Promise<void>>();
+
+export function stripTrailingSlash(url: string): string {
+  return url.replace(/\/+$/, "");
+}
+
+/** `https://api.captcha.snutig.dev` → `…/widget/v1/widget.js` */
+export function widgetScriptUrl(apiUrl: string = DEFAULT_API_URL): string {
+  return `${stripTrailingSlash(apiUrl)}/widget/v1/widget.js`;
+}
+
+/** `(https://api.captcha.snutig.dev, abc123)` → `https://api.captcha.snutig.dev/abc123/` */
+export function challengeEndpoint(siteKey: string, apiUrl: string = DEFAULT_API_URL): string {
+  return `${stripTrailingSlash(apiUrl)}/${siteKey}/`;
+}
+
+/**
+ * Loads the widget bundle once per URL and resolves when `<snutig-captcha>` is
+ * defined. Safe to call from every component instance: concurrent calls share
+ * one promise, and an already-defined element (another instance, a
+ * server-rendered tag, a WordPress page) resolves immediately.
+ */
+export function loadSnutigWidget(options: LoadWidgetOptions = {}): Promise<void> {
+  if (typeof document === "undefined") {
+    return Promise.reject(
+      new Error(
+        "loadSnutigWidget() needs a DOM — call it from an effect, not during server rendering",
+      ),
+    );
+  }
+
+  if (customElements.get(ELEMENT_NAME)) return Promise.resolve();
+
+  const url = options.scriptUrl ?? widgetScriptUrl(options.apiUrl);
+
+  const cached = loads.get(url);
+  if (cached) return cached;
+
+  const win = window as unknown as SnutigWindow;
+  // Must be set before the bundle evaluates: it stamps the CSS nonce onto the
+  // style it injects into its shadow root.
+  if (options.nonce) {
+    win.SNUTIG_CSS_NONCE = options.nonce;
+    win.SNUTIG_SCRIPT_NONCE = options.nonce;
+  }
+
+  const load = new Promise<void>((resolve, reject) => {
+    const settle = () => customElements.whenDefined(ELEMENT_NAME).then(() => resolve());
+    const fail = (tag: HTMLScriptElement) => {
+      // Drop the rejected promise so a later mount (or a recovered network) retries
+      // instead of replaying the failure forever — and drop the dead <script> with it.
+      // A script element that already fired `error` never fires it again and never
+      // re-fetches, so leaving it in the DOM would make the retry below adopt it and
+      // wait on events that can no longer arrive (a promise that never settles).
+      loads.delete(url);
+      tag.remove();
+      reject(new Error(`Failed to load the snutig captcha widget from ${url}`));
+    };
+
+    // Compare resolved `.src` rather than building an attribute selector: the tag
+    // may carry a relative URL, and URLs need no escaping this way.
+    const href = new URL(url, document.baseURI).href;
+    const existing = Array.from(
+      document.querySelectorAll<HTMLScriptElement>(`script[${SCRIPT_MARKER}]`),
+    ).find((tag) => tag.src === href);
+    if (existing) {
+      existing.addEventListener("load", settle, { once: true });
+      existing.addEventListener("error", () => fail(existing), { once: true });
+      // It may have finished before we got here.
+      if (customElements.get(ELEMENT_NAME)) resolve();
+      return;
+    }
+
+    const script = document.createElement("script");
+    script.src = url;
+    script.async = true;
+    script.setAttribute(SCRIPT_MARKER, "");
+    if (options.nonce) script.nonce = options.nonce;
+    script.addEventListener("load", settle, { once: true });
+    script.addEventListener("error", () => fail(script), { once: true });
+    document.head.appendChild(script);
+  });
+
+  loads.set(url, load);
+  return load;
+}

package/src/theme.css

@@ -0,0 +1,59 @@
+/**
+ * Snutig brand theme for the widget.
+ *
+ * Kept byte-for-byte in sync with the WordPress/Elementor plugin's
+ * `assets/snutig-captcha.css` (snutiggmbh/snutig-captcha-wp) so a React form and
+ * an Elementor form render the identical widget. Only the Elementor-specific
+ * field-wrapper reset is omitted here.
+ *
+ * Brand:
+ *   primary  #99b596   (sage green)
+ *   surface  #000000   (black)
+ *   text     #ffffff   (white)
+ */
+.snutig-captcha {
+  display: inline-block;
+  max-width: 100%;
+
+  /* Brand tokens — reuse these if you embed the widget elsewhere. */
+  --snutig-primary: #99b596;
+  --snutig-primary-soft: rgba(153, 181, 150, 0.18);
+  --snutig-bg: #000000;
+  --snutig-fg: #ffffff;
+  --snutig-fg-dim: rgba(255, 255, 255, 0.55);
+  --snutig-border: rgba(255, 255, 255, 0.12);
+  --snutig-error: #d97171;
+  --snutig-error-soft: rgba(217, 113, 113, 0.3);
+
+  /* Widget surfaces (@snutig/widget custom properties) */
+  --snutig-background: var(--snutig-bg);
+  --snutig-color: var(--snutig-fg);
+  --snutig-border-color: var(--snutig-border);
+  --snutig-border-radius: 12px;
+  --snutig-widget-padding: 14px 18px;
+  --snutig-gap: 12px;
+  --snutig-font: inherit;
+
+  /* Checkbox */
+  --snutig-checkbox-background: transparent;
+  --snutig-checkbox-border: 1.5px solid var(--snutig-primary);
+  --snutig-checkbox-border-radius: 4px;
+  --snutig-checkbox-size: 20px;
+
+  /* Checkmark + cross drawn in brand colors (background sits over the dark widget). */
+  --snutig-checkmark: url("data:image/svg+xml;utf8,<svg xmlns='http://www.w3.org/2000/svg' width='24' height='24' viewBox='0 0 24 24' fill='none' stroke='%2399b596' stroke-width='3' stroke-linecap='round' stroke-linejoin='round'><polyline points='4 12 10 18 20 6'/></svg>");
+  --snutig-error-cross: url("data:image/svg+xml;utf8,<svg xmlns='http://www.w3.org/2000/svg' width='24' height='24' viewBox='0 0 24 24' fill='none' stroke='%23d97171' stroke-width='2.5' stroke-linecap='round' stroke-linejoin='round'><line x1='6' y1='6' x2='18' y2='18'/><line x1='6' y1='18' x2='18' y2='6'/></svg>");
+
+  /* Spinner during solving */
+  --snutig-spinner-color: var(--snutig-primary);
+  --snutig-spinner-background-color: var(--snutig-primary-soft);
+  --snutig-spinner-thickness: 2px;
+
+  /* Focus + auxiliary */
+  --snutig-focus-ring: var(--snutig-primary);
+  --snutig-troubleshoot-color: var(--snutig-fg-dim);
+
+  /* Invalid state */
+  --snutig-invalid-border-color: var(--snutig-error);
+  --snutig-invalid-ring-color: var(--snutig-error-soft);
+}