@kcaptcha/client 0.1.0

package/dist/index.js

@@ -0,0 +1,1044 @@
+// src/options.ts
+var DEFAULTS = {
+  width: 300,
+  height: 74,
+  color: "#3fb950",
+  name: "kcaptcha_token"
+};
+var WIDTH_RANGE = [160, 600];
+var HEIGHT_RANGE = [40, 120];
+var KCaptchaOptionError = class extends Error {
+  constructor(message) {
+    super(`[kCAPTCHA] ${message}`);
+    this.name = "KCaptchaOptionError";
+  }
+};
+var warn = (message) => console.warn(`[kCAPTCHA] ${message}`);
+function endpointOption(raw) {
+  if (typeof raw !== "string" || raw.trim() === "") {
+    throw new KCaptchaOptionError(
+      'Missing required "endpoint" option, so the widget cannot work. Example: <div data-kcaptcha data-endpoint="/login/kcaptcha"></div>'
+    );
+  }
+  const value = raw.trim().replace(/\/+$/, "");
+  const isPath = /^\/(?!\/)/.test(value);
+  const isUrl = /^https?:\/\/[^\s/]+/i.test(value);
+  if (!isPath && !isUrl) {
+    throw new KCaptchaOptionError(
+      `Invalid "endpoint": ${JSON.stringify(raw)}. It must start with "/" (e.g. "/login/kcaptcha") or be a full http(s) URL.`
+    );
+  }
+  return value;
+}
+function numberOption(name, raw, fallback, [min, max]) {
+  if (raw === void 0 || raw === null || raw === "") return fallback;
+  const n = typeof raw === "number" ? raw : Number(raw);
+  if (!Number.isFinite(n)) {
+    warn(`"${name}" must be a number (got ${JSON.stringify(raw)}). Using ${fallback}.`);
+    return fallback;
+  }
+  const rounded = Math.round(n);
+  const clamped = Math.min(max, Math.max(min, rounded));
+  if (clamped !== rounded) {
+    warn(`"${name}" must be between ${min} and ${max} (got ${rounded}). Using ${clamped}.`);
+  }
+  return clamped;
+}
+function colorOption(raw) {
+  if (raw === void 0 || raw === null || raw === "") return DEFAULTS.color;
+  if (typeof raw === "string" && typeof CSS !== "undefined" && CSS.supports("color", raw)) {
+    return raw.trim();
+  }
+  warn(`"color" is not a valid CSS colour (got ${JSON.stringify(raw)}). Using ${DEFAULTS.color}.`);
+  return DEFAULTS.color;
+}
+function nameOption(raw) {
+  if (raw === void 0 || raw === null || raw === "") return DEFAULTS.name;
+  if (typeof raw === "string" && /^[A-Za-z_][\w.-]{0,63}$/.test(raw)) return raw;
+  warn(`"name" is not a valid field name (got ${JSON.stringify(raw)}). Using "${DEFAULTS.name}".`);
+  return DEFAULTS.name;
+}
+function resolveOptions(raw) {
+  const endpoint = endpointOption(raw.endpoint);
+  if (raw.expire !== void 0) {
+    warn('"expire" cannot be set in the browser. Set it on the server: createKCaptcha({ expire }). Ignored.');
+  }
+  if (raw.rateLimit !== void 0) {
+    warn('"rateLimit" cannot be set in the browser. Set it on the server: createKCaptcha({ rateLimit }). Ignored.');
+  }
+  return {
+    endpoint,
+    width: numberOption("width", raw.width, DEFAULTS.width, WIDTH_RANGE),
+    height: numberOption("height", raw.height, DEFAULTS.height, HEIGHT_RANGE),
+    color: colorOption(raw.color),
+    name: nameOption(raw.name),
+    onVerify: typeof raw.onVerify === "function" ? raw.onVerify : void 0,
+    onExpire: typeof raw.onExpire === "function" ? raw.onExpire : void 0
+  };
+}
+
+// src/api.ts
+var ApiError = class extends Error {
+  constructor(code, status, retryAfter) {
+    super(code);
+    this.code = code;
+    this.status = status;
+    this.retryAfter = retryAfter;
+    this.name = "ApiError";
+  }
+};
+var TIMEOUT_MS = 1e4;
+var MAX_PIPES = 200;
+var MAX_NUMBERS_PER_PIPE = 2e3;
+var MAX_DIMENSION = 2e3;
+var MAX_TOKEN_LENGTH = 1024;
+var isRecord = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+var isPositive = (v, max) => typeof v === "number" && Number.isFinite(v) && v > 0 && v <= max;
+function bad() {
+  throw new ApiError("bad_response", 200);
+}
+function parseGeometry(value) {
+  if (!isRecord(value)) return bad();
+  const { width, height, spacing, pipes } = value;
+  if (!isPositive(width, MAX_DIMENSION) || !isPositive(height, MAX_DIMENSION)) return bad();
+  if (!isPositive(spacing, 100)) return bad();
+  if (!Array.isArray(pipes) || pipes.length === 0 || pipes.length > MAX_PIPES) return bad();
+  for (const pipe of pipes) {
+    if (!Array.isArray(pipe)) return bad();
+    if (pipe.length < 4 || pipe.length % 2 !== 0 || pipe.length > MAX_NUMBERS_PER_PIPE) return bad();
+    for (const n of pipe) {
+      if (typeof n !== "number" || !Number.isFinite(n)) return bad();
+    }
+  }
+  return { width, height, spacing, pipes };
+}
+function parseChallenge(data) {
+  const { token, expiresIn } = data;
+  if (typeof token !== "string" || token.length === 0 || token.length > MAX_TOKEN_LENGTH) return bad();
+  if (!isPositive(expiresIn, 3600)) return bad();
+  return { token, expiresIn, geometry: parseGeometry(data.geometry) };
+}
+var KCaptchaApi = class {
+  constructor(endpoint) {
+    this.endpoint = endpoint;
+  }
+  /** POST <endpoint>/new-code */
+  async newCode() {
+    return parseChallenge(await this.post("/new-code"));
+  }
+  /** POST <endpoint>/verify-captcha */
+  async verify(token, answer) {
+    const data = await this.post("/verify-captcha", { token, answer });
+    const { token: pass, expiresIn } = data;
+    if (typeof pass !== "string" || pass.length === 0 || pass.length > MAX_TOKEN_LENGTH) return bad();
+    if (!isPositive(expiresIn, 86400)) return bad();
+    return { token: pass, expiresIn };
+  }
+  async post(path, body) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), TIMEOUT_MS);
+    let res;
+    try {
+      res = await fetch(`${this.endpoint}${path}`, {
+        method: "POST",
+        headers: body === void 0 ? { Accept: "application/json" } : { Accept: "application/json", "Content-Type": "application/json" },
+        body: body === void 0 ? void 0 : JSON.stringify(body),
+        credentials: "same-origin",
+        cache: "no-store",
+        signal: controller.signal
+      });
+    } catch {
+      throw new ApiError("network_error", 0);
+    } finally {
+      clearTimeout(timer);
+    }
+    let data = null;
+    try {
+      data = await res.json();
+    } catch {
+    }
+    const record = isRecord(data) ? data : null;
+    if (!res.ok || !record || record.ok !== true) {
+      const code = record && typeof record.error === "string" ? record.error : `http_${res.status}`;
+      const header = Number(res.headers.get("Retry-After"));
+      const retryAfter = record && typeof record.retryAfter === "number" ? record.retryAfter : Number.isFinite(header) && header > 0 ? header : void 0;
+      throw new ApiError(code, res.status, retryAfter);
+    }
+    return record;
+  }
+};
+
+// src/renderer.ts
+var W = 400;
+var H = 240;
+var TAU = Math.PI * 2;
+var FRAME_MS = 1e3 / 60;
+var DOT_RADIUS = 1.2;
+var DOT_COLOR = "#000000";
+var PARTICLE_COUNT = 3e3;
+var DENSITY = PARTICLE_COUNT / (W * H);
+var BAND_WIDTH = 15;
+var LETTER_SPEED_MIN = 20;
+var LETTER_SPEED_MAX = 20;
+var NOISE_SPEED_MIN = 0.1;
+var NOISE_SPEED_MAX = 0.1;
+var DRIFT_SPEED = 0.5;
+var WATERMARK_CHARS = "QWERTYUIPASDFGHJKLZXCVBNM123456789";
+function randomWatermark() {
+  let out2 = "";
+  for (let i = 0; i < 5; i++) out2 += WATERMARK_CHARS[Math.floor(Math.random() * WATERMARK_CHARS.length)];
+  return out2;
+}
+function preparePipe(flat) {
+  const n = flat.length / 2;
+  const xs = [];
+  const ys = [];
+  const cum = [0];
+  for (let i = 0; i < n; i++) {
+    xs.push(flat[i * 2]);
+    ys.push(flat[i * 2 + 1]);
+    if (i > 0) {
+      cum.push(cum[i - 1] + Math.hypot(xs[i] - xs[i - 1], ys[i] - ys[i - 1]));
+    }
+  }
+  return { xs, ys, cum, total: cum[n - 1] };
+}
+var out = { x: 0, y: 0, nx: 0, ny: 0 };
+function pointAt(pipe, s) {
+  const { xs, ys, cum } = pipe;
+  let lo = 1;
+  let hi = cum.length - 1;
+  while (lo < hi) {
+    const mid = lo + hi >> 1;
+    if (cum[mid] < s) lo = mid + 1;
+    else hi = mid;
+  }
+  const c0 = cum[lo - 1];
+  const c1 = cum[lo];
+  const f = c1 > c0 ? (s - c0) / (c1 - c0) : 0;
+  const dx = xs[lo] - xs[lo - 1];
+  const dy = ys[lo] - ys[lo - 1];
+  const len = Math.hypot(dx, dy) || 1;
+  out.x = xs[lo - 1] + dx * f;
+  out.y = ys[lo - 1] + dy * f;
+  out.nx = -dy / len;
+  out.ny = dx / len;
+}
+var Renderer = class {
+  constructor(canvas) {
+    this.particles = new Float32Array(PARTICLE_COUNT * 4);
+    // x, y, vx, vy
+    this.geometry = null;
+    this.dots = [];
+    this.mask = null;
+    // 1 = inside a stroke band (string space)
+    this.maskW = 0;
+    this.maskH = 0;
+    this.watermark = randomWatermark();
+    this.running = false;
+    this.raf = 0;
+    this.last = 0;
+    this.drift = 0;
+    this.tick = (now) => {
+      if (!this.running) return;
+      const dt = Math.min(Math.max((now - this.last) / FRAME_MS, 0), 3);
+      this.last = now;
+      this.draw(dt);
+      this.raf = requestAnimationFrame(this.tick);
+    };
+    const ctx = canvas.getContext("2d");
+    if (!ctx) throw new Error("[kCAPTCHA] Canvas 2D is not supported in this browser.");
+    this.ctx = ctx;
+    const dpr = Math.min(window.devicePixelRatio || 1, 2);
+    canvas.width = Math.round(W * dpr);
+    canvas.height = Math.round(H * dpr);
+    ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
+    for (let i = 0; i < PARTICLE_COUNT; i++) {
+      const o = i * 4;
+      const angle = Math.random() * TAU;
+      const speed = NOISE_SPEED_MIN + Math.random() * (NOISE_SPEED_MAX - NOISE_SPEED_MIN);
+      this.particles[o] = Math.random() * W;
+      this.particles[o + 1] = Math.random() * H;
+      this.particles[o + 2] = Math.cos(angle) * speed;
+      this.particles[o + 3] = Math.sin(angle) * speed;
+    }
+  }
+  setGeometry(geometry) {
+    this.geometry = geometry;
+    this.dots = [];
+    this.mask = null;
+    this.drift = 0;
+    this.watermark = randomWatermark();
+    if (!geometry) return;
+    for (const flat of geometry.pipes) {
+      const pipe = preparePipe(flat);
+      const expected = pipe.total * BAND_WIDTH * DENSITY;
+      const count = Math.floor(expected + Math.random());
+      for (let k = 0; k < count; k++) {
+        const dir = Math.random() < 0.5 ? -1 : 1;
+        const speed = LETTER_SPEED_MIN + Math.random() * (LETTER_SPEED_MAX - LETTER_SPEED_MIN);
+        this.dots.push({
+          pipe,
+          s: Math.random() * pipe.total,
+          v: dir * speed,
+          u: (Math.random() - 0.5) * BAND_WIDTH
+        });
+      }
+    }
+    this.buildMask(geometry);
+  }
+  start() {
+    if (this.running) return;
+    this.running = true;
+    this.last = performance.now();
+    this.raf = requestAnimationFrame(this.tick);
+  }
+  stop() {
+    this.running = false;
+    cancelAnimationFrame(this.raf);
+  }
+  destroy() {
+    this.stop();
+    this.geometry = null;
+    this.dots = [];
+    this.mask = null;
+  }
+  // Rasterise the stroke bands once per challenge. Background dots that fall
+  // inside a band are not drawn, so the band's total density equals the density outside it.
+  buildMask(geometry) {
+    const w = Math.ceil(geometry.width);
+    const h = Math.ceil(geometry.height);
+    const canvas = document.createElement("canvas");
+    canvas.width = w;
+    canvas.height = h;
+    const mctx = canvas.getContext("2d", { willReadFrequently: true });
+    if (!mctx) return;
+    mctx.strokeStyle = "#000";
+    mctx.lineWidth = BAND_WIDTH;
+    mctx.lineCap = "butt";
+    mctx.lineJoin = "round";
+    for (const flat of geometry.pipes) {
+      mctx.beginPath();
+      mctx.moveTo(flat[0], flat[1]);
+      for (let i = 2; i < flat.length; i += 2) mctx.lineTo(flat[i], flat[i + 1]);
+      mctx.stroke();
+    }
+    const data = mctx.getImageData(0, 0, w, h).data;
+    const mask = new Uint8Array(w * h);
+    for (let i = 0; i < mask.length; i++) mask[i] = data[i * 4 + 3] > 127 ? 1 : 0;
+    this.mask = mask;
+    this.maskW = w;
+    this.maskH = h;
+  }
+  draw(dt) {
+    const { ctx, particles } = this;
+    ctx.clearRect(0, 0, W, H);
+    ctx.save();
+    ctx.font = "bold 46px monospace";
+    ctx.fillStyle = "rgba(0, 0, 0, 0.035)";
+    ctx.textAlign = "center";
+    ctx.textBaseline = "middle";
+    ctx.fillText(this.watermark, W / 2, H / 2);
+    ctx.restore();
+    const g = this.geometry;
+    let x0 = 0;
+    let y0 = 0;
+    if (g) {
+      this.drift += DRIFT_SPEED * dt;
+      const startX = W + 60;
+      const endX = -g.width - 60;
+      x0 = startX - this.drift % (startX - endX);
+      y0 = (H - g.height) / 2;
+    }
+    ctx.fillStyle = DOT_COLOR;
+    ctx.beginPath();
+    const mask = this.mask;
+    for (let i = 0; i < PARTICLE_COUNT; i++) {
+      const o = i * 4;
+      let x = particles[o] + (particles[o + 2] - DRIFT_SPEED) * dt;
+      let y = particles[o + 1] + particles[o + 3] * dt;
+      if (x < 0) x += W;
+      else if (x >= W) x -= W;
+      if (y < 0 || y > H) {
+        particles[o + 3] = -particles[o + 3];
+        y = Math.min(H, Math.max(0, y));
+      }
+      particles[o] = x;
+      particles[o + 1] = y;
+      if (mask) {
+        const mx = Math.floor(x - x0);
+        const my = Math.floor(y - y0);
+        if (mx >= 0 && mx < this.maskW && my >= 0 && my < this.maskH && mask[my * this.maskW + mx]) continue;
+      }
+      ctx.moveTo(x + DOT_RADIUS, y);
+      ctx.arc(x, y, DOT_RADIUS, 0, TAU);
+    }
+    if (g) {
+      for (const dot of this.dots) {
+        const length = dot.pipe.total;
+        dot.s = (dot.s + dot.v * dt) % length;
+        if (dot.s < 0) dot.s += length;
+        pointAt(dot.pipe, dot.s);
+        const x = x0 + out.x + out.nx * dot.u;
+        const y = y0 + out.y + out.ny * dot.u;
+        if (x > 0 && x < W && y > 0 && y < H) {
+          ctx.moveTo(x + DOT_RADIUS, y);
+          ctx.arc(x, y, DOT_RADIUS, 0, TAU);
+        }
+      }
+    }
+    ctx.fill();
+  }
+};
+
+// src/styles.ts
+var STYLES = `
+*, *::before, *::after { box-sizing: border-box; }
+
+:host {
+  display: inline-block;
+  max-width: 100%;
+  font-family: system-ui, -apple-system, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
+}
+
+.root { width: 100%; height: 100%; }
+
+/* ---------- checkbox button (customisable: width, height, colour) ---------- */
+.trigger {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  width: 100%;
+  height: 100%;
+  margin: 0;
+  padding: 0 14px;
+  background: #f8fafc;
+  color: #1f2328;
+  border: 1px solid #d0d7de;
+  border-radius: 6px;
+  font: inherit;
+  font-size: 15px;
+  text-align: left;
+  cursor: pointer;
+  transition: border-color 0.15s;
+}
+.pause { display: none; }
+
+.trigger:hover { border-color: var(--kc-accent); }
+.trigger:focus-visible { outline: 2px solid var(--kc-accent); outline-offset: 2px; }
+.trigger[aria-disabled="true"] { cursor: default; }
+
+.check {
+  flex: none;
+  display: grid;
+  place-items: center;
+  width: 24px;
+  height: 24px;
+  background: #fff;
+  border: 2px solid #8c959f;
+  border-radius: 4px;
+  transition: background 0.15s, border-color 0.15s;
+}
+.check svg {
+  width: 16px;
+  height: 16px;
+  fill: none;
+  stroke: #fff;
+  stroke-width: 3;
+  stroke-linecap: round;
+  stroke-linejoin: round;
+  opacity: 0;
+}
+.trigger[data-state="verified"] .check { background: var(--kc-accent); border-color: var(--kc-accent); }
+.trigger[data-state="verified"] .check svg { opacity: 1; }
+
+.label { flex: 1; min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.brand {
+  flex: none;
+  color: #6e7781;
+  font: 11px ui-monospace, "SF Mono", Menlo, Consolas, monospace;
+  letter-spacing: 0.4px;
+}
+
+/* ---------- small popup dialog (anchored under the checkbox, no backdrop) ---------- */
+.overlay {
+  position: fixed;
+  top: 0;
+  left: 0;
+  z-index: 2147483647;
+  width: 320px; /* the script sets the real width and position */
+}
+.overlay[hidden] { display: none; }
+
+.dialog {
+  padding: 12px;
+  background: #0d1117;
+  color: #e6edf3;
+  border: 1px solid #30363d;
+  border-radius: 10px;
+  box-shadow: 0 8px 28px rgba(0, 0, 0, 0.45);
+}
+
+.head { display: flex; align-items: center; justify-content: space-between; gap: 8px; }
+.head h2 { margin: 0; font-size: 14px; font-weight: 600; }
+.help { margin: 4px 0 0; color: #8b949e; font-size: 12px; line-height: 1.4; }
+
+.stage {
+  position: relative;
+  margin-top: 10px;
+  padding: 6px;
+  background: #ffffff;
+  border: 1px solid #30363d;
+  border-radius: 8px;
+  box-shadow: 0 0 12px rgba(0, 0, 0, 0.5);
+}
+canvas { display: block; width: 100%; height: auto; aspect-ratio: 400 / 240; }
+.loading {
+  position: absolute;
+  inset: 0;
+  display: none;
+  align-items: center;
+  justify-content: center;
+  background: rgba(255, 255, 255, 0.85);
+  border-radius: 8px;
+  color: #000000;
+  font-size: 13px;
+}
+.stage.busy .loading { display: flex; }
+
+.answer {
+  display: block;
+  width: 100%;
+  margin: 10px 0 0;
+  padding: 8px 10px;
+  background: #161b22;
+  color: #e6edf3;
+  border: 1px solid #30363d;
+  border-radius: 6px;
+  outline: none;
+  font: 15px ui-monospace, "SF Mono", Menlo, Consolas, monospace;
+  letter-spacing: 3px;
+  text-transform: uppercase;
+}
+.answer::placeholder { color: #6e7681; letter-spacing: 1px; }
+.answer:focus { border-color: #58a6ff; }
+
+.actions { display: grid; grid-template-columns: 1fr 1fr; gap: 8px; margin-top: 8px; }
+
+.dialog button {
+  padding: 8px 10px;
+  background: #21262d;
+  color: #e6edf3;
+  border: 1px solid #30363d;
+  border-radius: 6px;
+  font: inherit;
+  font-size: 13px;
+  cursor: pointer;
+  transition: border-color 0.15s, background 0.15s;
+}
+.dialog button:hover:not(:disabled) { border-color: #58a6ff; }
+.dialog button:focus-visible { outline: 2px solid #58a6ff; outline-offset: 2px; }
+.dialog button:disabled { opacity: 0.5; cursor: not-allowed; }
+.dialog button.primary { background: #238636; border-color: #2ea043; }
+.dialog button.primary:hover:not(:disabled) { background: #2ea043; border-color: #3fb950; }
+.dialog button.close { padding: 0 8px; font-size: 18px; line-height: 1.4; }
+
+.status { min-height: 16px; margin-top: 8px; font-size: 12px; letter-spacing: 0.3px; color: #8b949e; }
+.status.ok { color: #3fb950; }
+.status.bad { color: #f85149; }
+`;
+
+// src/widget.ts
+var TEMPLATE = `
+<div class="root">
+  <button type="button" class="trigger" data-state="idle" aria-haspopup="dialog" aria-expanded="false">
+    <span class="check" aria-hidden="true">
+      <svg viewBox="0 0 24 24"><path d="M5 12.5l4.5 4.5L19 7.5"/></svg>
+    </span>
+    <span class="label">Verify you are human</span>
+    <span class="brand" aria-hidden="true">kCAPTCHA</span>
+  </button>
+
+  <div class="overlay" hidden>
+    <div class="dialog" role="dialog" aria-modal="true" aria-labelledby="kc-title" aria-describedby="kc-help">
+      <div class="head">
+        <h2 id="kc-title">Verify you are human</h2>
+        <button type="button" class="close" aria-label="Close">&times;</button>
+      </div>
+      <p id="kc-help" class="help">Read the moving letters in the box and enter them below.</p>
+
+      <div class="stage">
+        <canvas></canvas>
+        <div class="loading">Loading&hellip;</div>
+      </div>
+
+      <input class="answer" type="text" placeholder="CAPTCHA" aria-label="CAPTCHA"
+        maxlength="8" autocomplete="off" autocapitalize="characters" spellcheck="false">
+
+            <div class="actions">
+        <button type="button" class="primary submit">Submit</button>
+        <button type="button" class="refresh">New code</button>
+        <button type="button" class="pause" aria-pressed="false">Pause</button>
+      </div>
+
+      <div class="status" role="status" aria-live="polite"></div>
+    </div>
+  </div>
+</div>
+`;
+var LABEL_IDLE = "Verify you are human";
+var LABEL_VERIFIED = "Verified";
+var POPUP_WIDTH = 440;
+function query(root, selector) {
+  const el = root.querySelector(selector);
+  if (!el) throw new Error(`[kCAPTCHA] Internal error: missing element ${selector}`);
+  return el;
+}
+function applyStyles(shadow) {
+  try {
+    if (typeof CSSStyleSheet !== "undefined" && "replaceSync" in CSSStyleSheet.prototype) {
+      const sheet = new CSSStyleSheet();
+      sheet.replaceSync(STYLES);
+      shadow.adoptedStyleSheets = [sheet];
+      return;
+    }
+  } catch {
+  }
+  const style = document.createElement("style");
+  style.textContent = STYLES;
+  shadow.appendChild(style);
+}
+function toApiError(err) {
+  return err instanceof ApiError ? err : new ApiError("network_error", 0);
+}
+var Widget = class {
+  constructor(host, opts) {
+    this.host = host;
+    this.opts = opts;
+    this.state = "idle";
+    this.token = null;
+    this.challenge = null;
+    this.dialogOpen = false;
+    this.busy = false;
+    this.cooling = false;
+    this.paused = false;
+    this.seq = 0;
+    // bumped on every request/reset so stale responses are ignored
+    this.challengeTimer = 0;
+    this.passTimer = 0;
+    this.cooldownTimer = 0;
+    // Keep the popup attached to the checkbox while the page scrolls or resizes.
+    this.reposition = () => {
+      if (this.dialogOpen) this.position();
+    };
+    // A click anywhere outside the widget closes the popup.
+    this.onOutsideClick = (e) => {
+      if (!e.composedPath().includes(this.host)) this.close(false);
+    };
+    // Escape closes; Tab is cycled by hand so focus can never leave the dialog.
+    this.onOverlayKeyDown = (e) => {
+      var _a;
+      if (e.key === "Escape") {
+        e.preventDefault();
+        e.stopPropagation();
+        this.close();
+        return;
+      }
+      if (e.key !== "Tab") return;
+      const items = [this.closeBtn, this.input, this.submitBtn, this.refreshBtn, this.pauseBtn].filter(
+        (el) => !el.disabled
+      );
+      e.preventDefault();
+      if (items.length === 0) return;
+      const idx = items.findIndex((el) => el === this.shadow.activeElement);
+      const next = e.shiftKey ? idx <= 0 ? items.length - 1 : idx - 1 : idx === -1 || idx === items.length - 1 ? 0 : idx + 1;
+      (_a = items[next]) == null ? void 0 : _a.focus();
+    };
+    var _a;
+    this.shadow = (_a = host.shadowRoot) != null ? _a : host.attachShadow({ mode: "open" });
+    this.shadow.replaceChildren();
+    applyStyles(this.shadow);
+    const template = document.createElement("template");
+    template.innerHTML = TEMPLATE;
+    this.shadow.appendChild(template.content.cloneNode(true));
+    this.root = query(this.shadow, ".root");
+    this.trigger = query(this.shadow, ".trigger");
+    this.label = query(this.shadow, ".label");
+    this.overlay = query(this.shadow, ".overlay");
+    this.closeBtn = query(this.shadow, ".close");
+    this.stage = query(this.shadow, ".stage");
+    this.loadingEl = query(this.shadow, ".loading");
+    this.input = query(this.shadow, ".answer");
+    this.submitBtn = query(this.shadow, ".submit");
+    this.refreshBtn = query(this.shadow, ".refresh");
+    this.pauseBtn = query(this.shadow, ".pause");
+    this.statusEl = query(this.shadow, ".status");
+    const canvas = query(this.shadow, "canvas");
+    host.style.width = `${opts.width}px`;
+    host.style.height = `${opts.height}px`;
+    this.root.style.setProperty("--kc-accent", opts.color);
+    this.hidden = document.createElement("input");
+    this.hidden.type = "hidden";
+    this.hidden.name = opts.name;
+    host.appendChild(this.hidden);
+    this.api = new KCaptchaApi(opts.endpoint);
+    this.renderer = new Renderer(canvas);
+    this.trigger.addEventListener("click", () => {
+      if (this.state === "verified") return;
+      if (this.dialogOpen) this.close();
+      else this.open();
+    });
+    this.closeBtn.addEventListener("click", () => this.close());
+    this.overlay.addEventListener("keydown", this.onOverlayKeyDown);
+    this.submitBtn.addEventListener("click", () => void this.submit());
+    this.refreshBtn.addEventListener("click", () => void this.loadChallenge());
+    this.pauseBtn.addEventListener("click", () => this.setPaused(!this.paused));
+    this.input.addEventListener("input", () => {
+      this.input.value = this.input.value.toUpperCase().replace(/[^A-Z0-9]/g, "");
+    });
+    this.input.addEventListener("keydown", (e) => {
+      if (e.key === "Enter") {
+        e.preventDefault();
+        void this.submit();
+      }
+    });
+    this.updateTrigger();
+  }
+  // -------------------------------------------------------------------------
+  // Public API
+  // -------------------------------------------------------------------------
+  getToken() {
+    return this.state === "verified" ? this.token : null;
+  }
+  /** Back to the unchecked state. Call after a failed form submit: a pass token works only once. */
+  reset() {
+    this.resetState();
+  }
+  destroy() {
+    this.resetState();
+    this.renderer.destroy();
+    this.hidden.remove();
+    this.shadow.replaceChildren();
+    this.shadow.adoptedStyleSheets = [];
+    this.host.style.removeProperty("width");
+    this.host.style.removeProperty("height");
+  }
+  // -------------------------------------------------------------------------
+  // Dialog
+  // -------------------------------------------------------------------------
+  open() {
+    this.overlay.hidden = false;
+    this.dialogOpen = true;
+    this.trigger.setAttribute("aria-expanded", "true");
+    this.position();
+    window.addEventListener("resize", this.reposition);
+    window.addEventListener("scroll", this.reposition, true);
+    document.addEventListener("mousedown", this.onOutsideClick, true);
+    this.renderer.start();
+    this.input.focus({ preventScroll: true });
+    if (!this.challenge && !this.busy && !this.cooling) void this.loadChallenge();
+  }
+  close(returnFocus = true) {
+    if (!this.dialogOpen) return;
+    this.overlay.hidden = true;
+    this.dialogOpen = false;
+    this.setPaused(false);
+    this.trigger.setAttribute("aria-expanded", "false");
+    window.removeEventListener("resize", this.reposition);
+    window.removeEventListener("scroll", this.reposition, true);
+    document.removeEventListener("mousedown", this.onOutsideClick, true);
+    this.renderer.stop();
+    if (returnFocus) this.trigger.focus({ preventScroll: true });
+  }
+  // Place the popup under the checkbox, or above it if there is no room below,
+  // and always keep it fully inside the screen.
+  position() {
+    const GAP = 8;
+    const MARGIN = 8;
+    const vw = document.documentElement.clientWidth;
+    const vh = window.innerHeight;
+    const width = Math.min(POPUP_WIDTH, vw - MARGIN * 2);
+    this.overlay.style.width = `${width}px`;
+    const rect = this.trigger.getBoundingClientRect();
+    const height = this.overlay.offsetHeight;
+    const left = Math.min(Math.max(rect.left, MARGIN), vw - width - MARGIN);
+    let top = rect.bottom + GAP;
+    if (top + height > vh - MARGIN) {
+      const above = rect.top - GAP - height;
+      top = above >= MARGIN ? above : Math.max(MARGIN, vh - height - MARGIN);
+    }
+    this.overlay.style.left = `${left}px`;
+    this.overlay.style.top = `${top}px`;
+  }
+  // -------------------------------------------------------------------------
+  // Challenge lifecycle
+  // -------------------------------------------------------------------------
+  async loadChallenge(notice) {
+    const mine = ++this.seq;
+    this.setPaused(false);
+    this.clearTimer("challenge");
+    this.challenge = null;
+    this.renderer.setGeometry(null);
+    this.setStatus(notice != null ? notice : { text: "", kind: "" });
+    this.setBusy(true, "Loading\u2026");
+    try {
+      const challenge = await this.api.newCode();
+      if (mine !== this.seq) return;
+      this.challenge = challenge;
+      this.renderer.setGeometry(challenge.geometry);
+      this.input.value = "";
+      this.challengeTimer = window.setTimeout(() => this.onChallengeExpired(), challenge.expiresIn * 1e3);
+      this.setBusy(false);
+    } catch (err) {
+      if (mine !== this.seq) return;
+      this.setBusy(false);
+      this.handleFailure(err);
+    }
+    if (this.dialogOpen) this.input.focus({ preventScroll: true });
+  }
+  onChallengeExpired() {
+    this.challengeTimer = 0;
+    this.challenge = null;
+    this.renderer.setGeometry(null);
+    if (this.dialogOpen && !this.busy && !this.cooling) {
+      void this.loadChallenge({ text: "Code expired \u2014 here is a new one.", kind: "bad" });
+    }
+  }
+  async submit() {
+    if (this.busy || this.cooling) return;
+    const answer = this.input.value.trim();
+    if (!answer) {
+      this.setStatus({ text: "Type the moving code first.", kind: "bad" });
+      this.input.focus({ preventScroll: true });
+      return;
+    }
+    if (!this.challenge) {
+      void this.loadChallenge();
+      return;
+    }
+    const mine = ++this.seq;
+    const { token } = this.challenge;
+    this.setStatus({ text: "", kind: "" });
+    this.setBusy(true, "Verifying\u2026");
+    try {
+      const result = await this.api.verify(token, answer);
+      if (mine !== this.seq) return;
+      this.setBusy(false);
+      this.onVerified(result.token, result.expiresIn);
+    } catch (err) {
+      if (mine !== this.seq) return;
+      this.setBusy(false);
+      this.handleFailure(err);
+      if (this.dialogOpen) this.input.focus({ preventScroll: true });
+    }
+  }
+  onVerified(token, expiresIn) {
+    var _a, _b;
+    this.clearTimer("challenge");
+    this.challenge = null;
+    this.renderer.setGeometry(null);
+    this.token = token;
+    this.state = "verified";
+    this.hidden.value = token;
+    this.input.value = "";
+    this.setStatus({ text: "", kind: "" });
+    this.close();
+    this.updateTrigger();
+    this.passTimer = window.setTimeout(() => this.onPassExpired(), Math.max(1e3, (expiresIn - 2) * 1e3));
+    this.dispatch("kcaptcha:verify", { token });
+    (_b = (_a = this.opts).onVerify) == null ? void 0 : _b.call(_a, token);
+  }
+  onPassExpired() {
+    var _a, _b;
+    this.passTimer = 0;
+    this.resetState();
+    this.dispatch("kcaptcha:expire");
+    (_b = (_a = this.opts).onExpire) == null ? void 0 : _b.call(_a);
+  }
+  // -------------------------------------------------------------------------
+  // Errors
+  // -------------------------------------------------------------------------
+  handleFailure(err) {
+    var _a;
+    const e = toApiError(err);
+    switch (e.code) {
+      case "incorrect":
+        void this.loadChallenge({ text: "Incorrect \u2014 try again.", kind: "bad" });
+        return;
+      case "expired":
+        void this.loadChallenge({ text: "Code expired \u2014 here is a new one.", kind: "bad" });
+        return;
+      case "replayed":
+      case "invalid":
+      case "malformed":
+        void this.loadChallenge({ text: "Something went wrong \u2014 here is a new code.", kind: "bad" });
+        return;
+      case "rate_limited":
+        this.startCooldown((_a = e.retryAfter) != null ? _a : 30);
+        return;
+      case "network_error":
+        this.setStatus({ text: "Network error \u2014 check your connection and try again.", kind: "bad" });
+        return;
+      default:
+        if (e.status === 404 || e.code.startsWith("http_") || e.code === "bad_response") {
+          console.error(
+            `[kCAPTCHA] Request failed (${e.code}). Is the kCAPTCHA router mounted at "${this.opts.endpoint}"?`
+          );
+        }
+        this.setStatus({ text: "Service unavailable \u2014 please try again later.", kind: "bad" });
+    }
+  }
+  startCooldown(seconds) {
+    this.stopCooldown();
+    this.cooling = true;
+    this.updateButtons();
+    let left = Math.max(1, Math.ceil(seconds));
+    const tick = () => {
+      if (left <= 0) {
+        this.stopCooldown();
+        this.setStatus({ text: "You can try again now.", kind: "" });
+        if (!this.challenge && this.dialogOpen) void this.loadChallenge();
+        return;
+      }
+      this.setStatus({ text: `Too many attempts. Try again in ${left}s.`, kind: "bad" });
+      left -= 1;
+    };
+    tick();
+    this.cooldownTimer = window.setInterval(tick, 1e3);
+  }
+  stopCooldown() {
+    if (this.cooldownTimer) {
+      window.clearInterval(this.cooldownTimer);
+      this.cooldownTimer = 0;
+    }
+    this.cooling = false;
+    this.updateButtons();
+  }
+  // -------------------------------------------------------------------------
+  // State + UI helpers
+  // -------------------------------------------------------------------------
+  resetState() {
+    this.seq += 1;
+    this.clearTimer("challenge");
+    this.clearTimer("pass");
+    this.stopCooldown();
+    this.close(false);
+    this.state = "idle";
+    this.token = null;
+    this.challenge = null;
+    this.busy = false;
+    this.stage.classList.remove("busy");
+    this.renderer.setGeometry(null);
+    this.hidden.value = "";
+    this.input.value = "";
+    this.setStatus({ text: "", kind: "" });
+    this.updateButtons();
+    this.updateTrigger();
+  }
+  clearTimer(which) {
+    if (which === "challenge" && this.challengeTimer) {
+      window.clearTimeout(this.challengeTimer);
+      this.challengeTimer = 0;
+    }
+    if (which === "pass" && this.passTimer) {
+      window.clearTimeout(this.passTimer);
+      this.passTimer = 0;
+    }
+  }
+  setBusy(on, text = "Loading\u2026") {
+    this.busy = on;
+    this.loadingEl.textContent = text;
+    this.stage.classList.toggle("busy", on);
+    this.updateButtons();
+  }
+  // TEMPORARY testing aid: freeze / resume the animation.
+  setPaused(on) {
+    if (this.paused === on) return;
+    this.paused = on;
+    this.pauseBtn.textContent = on ? "Resume" : "Pause";
+    this.pauseBtn.setAttribute("aria-pressed", String(on));
+    if (on) this.renderer.stop();
+    else if (this.dialogOpen) this.renderer.start();
+  }
+  updateButtons() {
+    const disabled = this.busy || this.cooling;
+    this.submitBtn.disabled = disabled;
+    this.refreshBtn.disabled = disabled;
+    this.pauseBtn.disabled = this.busy || this.challenge === null;
+  }
+  updateTrigger() {
+    const verified = this.state === "verified";
+    this.trigger.dataset.state = this.state;
+    this.trigger.setAttribute("aria-disabled", String(verified));
+    this.label.textContent = verified ? LABEL_VERIFIED : LABEL_IDLE;
+  }
+  setStatus(notice) {
+    this.statusEl.textContent = notice.text;
+    this.statusEl.className = `status ${notice.kind}`.trim();
+  }
+  dispatch(name, detail) {
+    this.host.dispatchEvent(new CustomEvent(name, { bubbles: true, composed: true, detail }));
+  }
+};
+
+// src/index.ts
+var version = "0.1.0";
+var registry = /* @__PURE__ */ new WeakMap();
+function isMounted(el) {
+  return registry.has(el);
+}
+function showConfigError(el, message) {
+  const box = document.createElement("div");
+  box.setAttribute("role", "alert");
+  box.textContent = `kCAPTCHA error: ${message}`;
+  box.style.cssText = "padding:10px 12px;border:1px solid #f85149;border-radius:6px;background:#2d0f12;color:#ff7b72;font:13px/1.4 ui-monospace,Menlo,Consolas,monospace;max-width:100%";
+  el.replaceChildren(box);
+}
+function mount(target, options) {
+  const el = typeof target === "string" ? document.querySelector(target) : target;
+  if (!el) {
+    console.error(`[kCAPTCHA] Target element not found: ${String(target)}`);
+    return null;
+  }
+  const existing = registry.get(el);
+  if (existing) {
+    console.warn("[kCAPTCHA] This element already has a kCAPTCHA widget; returning the existing one.");
+    return existing;
+  }
+  let resolved;
+  try {
+    resolved = resolveOptions(options);
+  } catch (err) {
+    if (err instanceof KCaptchaOptionError) {
+      console.error(err.message);
+      showConfigError(el, err.message.replace(/^\[kCAPTCHA\]\s*/, ""));
+      return null;
+    }
+    throw err;
+  }
+  let widget;
+  try {
+    widget = new Widget(el, resolved);
+  } catch (err) {
+    console.error("[kCAPTCHA] Could not create the widget:", err);
+    showConfigError(el, "could not create the widget (see the browser console).");
+    return null;
+  }
+  const handle = {
+    element: el,
+    getToken: () => widget.getToken(),
+    reset: () => widget.reset(),
+    destroy: () => {
+      widget.destroy();
+      registry.delete(el);
+    }
+  };
+  registry.set(el, handle);
+  return handle;
+}
+export {
+  KCaptchaOptionError,
+  isMounted,
+  mount,
+  version
+};