@quikturn/logos 0.2.1 → 0.4.0

package/README.md

@@ -2,11 +2,20 @@
 
 > TypeScript SDK for the Quikturn Logos API -- fetch company logos with type safety.
 
+## Packages
+
+| Package | Description | Install |
+|---------|-------------|---------|
+| [`@quikturn/logos`](https://www.npmjs.com/package/@quikturn/logos) | Core SDK -- URL builder, browser client, server client, web component | `pnpm add @quikturn/logos` |
+| [`@quikturn/logos-react`](https://www.npmjs.com/package/@quikturn/logos-react) | React components -- `<QuikturnLogo>`, `<QuikturnLogoCarousel>`, `<QuikturnLogoGrid>` | `pnpm add @quikturn/logos-react` |
+
 ## Features
 
 - **Zero-dependency URL builder** -- universal, works in any JavaScript runtime
 - **Browser client** -- blob URL management, retry/backoff, scrape polling, event emission
 - **Server client** -- Buffer output, ReadableStream streaming, concurrent batch operations
+- **`<quikturn-logo>` web component** -- zero-effort attribution element with shadow DOM
+- **React components** -- see [`@quikturn/logos-react`](./packages/react/) for `<QuikturnLogo>`, `<QuikturnLogoCarousel>`, and `<QuikturnLogoGrid>`
 - **Full TypeScript support** -- strict types, discriminated union error codes, generic response shapes
 - **Tree-shakeable** -- ESM and CJS dual builds; import only what you need
 
@@ -103,6 +112,59 @@ const stream = await client.getStream("github.com", { format: "png" });
 Readable.fromWeb(stream).pipe(createWriteStream("logo.png"));
 ```
 
+### Web Component
+
+The `<quikturn-logo>` custom element renders a logo with built-in attribution. It uses shadow DOM to protect the attribution badge and requires no framework.
+
+```html
+<script type="module">
+  import "@quikturn/logos/element";
+</script>
+
+<quikturn-logo
+  domain="github.com"
+  token="qt_abc123"
+  size="64"
+  format="webp"
+  theme="dark"
+></quikturn-logo>
+```
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `domain` | `string` | Domain to fetch logo for (required for rendering) |
+| `token` | `string` | Publishable API key |
+| `size` | `string` | Image width in pixels |
+| `format` | `string` | `"png"`, `"jpeg"`, `"webp"`, or `"avif"` |
+| `greyscale` | presence | When present, applies greyscale transformation |
+| `theme` | `string` | `"light"` or `"dark"` |
+
+The element automatically registers as `quikturn-logo` on import and fires an attribution beacon on first render. Attribution styling uses `!important` rules inside the shadow DOM to prevent accidental removal.
+
+### React Components
+
+For React applications, install the companion package:
+
+```bash
+pnpm add @quikturn/logos-react
+```
+
+```tsx
+import { QuikturnProvider, QuikturnLogo, QuikturnLogoCarousel } from "@quikturn/logos-react";
+
+<QuikturnProvider token="qt_your_key">
+  <QuikturnLogo domain="github.com" size={64} />
+  <QuikturnLogoCarousel
+    domains={["github.com", "stripe.com", "vercel.com"]}
+    speed={120}
+    fadeOut
+    pauseOnHover
+  />
+</QuikturnProvider>
+```
+
+See the full API reference in [`@quikturn/logos-react` README](./packages/react/README.md).
+
 ## API Reference
 
 ### Universal (`@quikturn/logos`)
@@ -417,6 +479,18 @@ client.get("github.com", { format: "webp" });
 
 Rate limits and monthly quotas are enforced by the API server and vary by plan. The SDK automatically reads rate-limit headers to provide warnings via the event system and retries with backoff when limits are hit. See [Quikturn pricing](https://getquikturn.io/pricing) for details on your plan's limits.
 
+## Related Packages
+
+### [`@quikturn/logos-react`](https://www.npmjs.com/package/@quikturn/logos-react)
+
+Ready-made React components for displaying Quikturn logos. Includes an infinite scrolling carousel, responsive grid, single logo image, context provider for token propagation, and a `useLogoUrl()` hook. Zero CSS dependencies -- inline styles only.
+
+```bash
+pnpm add @quikturn/logos-react @quikturn/logos
+```
+
+See the full documentation at [`packages/react/README.md`](./packages/react/README.md).
+
 ## License
 
 MIT

package/dist/client/index.cjs

@@ -517,6 +517,18 @@ async function handleScrapeResponse(response, originalUrl, fetchFn, options) {
   }
 }
 
+// src/internal/beacon.ts
+var firedTokens = /* @__PURE__ */ new Set();
+function fireBeacon(token) {
+  if (typeof window === "undefined") return;
+  if (!token) return;
+  if (token.startsWith("sk_")) return;
+  if (firedTokens.has(token)) return;
+  firedTokens.add(token);
+  const img = new Image();
+  img.src = `${BASE_URL}/_beacon?token=${token}&page=${encodeURIComponent(location.href)}`;
+}
+
 // src/client/index.ts
 var QuikturnLogos = class {
   constructor(options) {
@@ -592,6 +604,7 @@ var QuikturnLogos = class {
     const metadata = parseLogoHeaders(response.headers);
     const objectUrl = URL.createObjectURL(blob);
     this.objectUrls.add(objectUrl);
+    fireBeacon(this.token);
     return { url: objectUrl, blob, contentType, metadata };
   }
   /**

package/dist/client/index.mjs

@@ -515,6 +515,18 @@ async function handleScrapeResponse(response, originalUrl, fetchFn, options) {
   }
 }
 
+// src/internal/beacon.ts
+var firedTokens = /* @__PURE__ */ new Set();
+function fireBeacon(token) {
+  if (typeof window === "undefined") return;
+  if (!token) return;
+  if (token.startsWith("sk_")) return;
+  if (firedTokens.has(token)) return;
+  firedTokens.add(token);
+  const img = new Image();
+  img.src = `${BASE_URL}/_beacon?token=${token}&page=${encodeURIComponent(location.href)}`;
+}
+
 // src/client/index.ts
 var QuikturnLogos = class {
   constructor(options) {
@@ -590,6 +602,7 @@ var QuikturnLogos = class {
     const metadata = parseLogoHeaders(response.headers);
     const objectUrl = URL.createObjectURL(blob);
     this.objectUrls.add(objectUrl);
+    fireBeacon(this.token);
     return { url: objectUrl, blob, contentType, metadata };
   }
   /**

package/dist/element/index.cjs

@@ -0,0 +1,288 @@
+'use strict';
+
+// src/constants.ts
+var BASE_URL = "https://logos.getquikturn.io";
+var DEFAULT_WIDTH = 128;
+var MAX_WIDTH = 800;
+var MAX_WIDTH_SERVER = 1200;
+var SUPPORTED_FORMATS = /* @__PURE__ */ new Set([
+  "image/png",
+  "image/jpeg",
+  "image/webp",
+  "image/avif"
+]);
+var FORMAT_ALIASES = {
+  png: "image/png",
+  jpeg: "image/jpeg",
+  webp: "image/webp",
+  avif: "image/avif"
+};
+
+// src/errors.ts
+var LogoError = class extends Error {
+  constructor(message, code, status) {
+    super(message);
+    this.name = "LogoError";
+    this.code = code;
+    this.status = status;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var DomainValidationError = class extends LogoError {
+  constructor(message, domain) {
+    super(message, "DOMAIN_VALIDATION_ERROR");
+    this.name = "DomainValidationError";
+    this.domain = domain;
+  }
+};
+
+// src/url-builder.ts
+var IP_ADDRESS_RE = /^(\d{1,3}\.){3}\d{1,3}$/;
+var LABEL_RE = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/;
+function validateDomain(domain) {
+  const normalized = domain.trim().toLowerCase();
+  const clean = normalized.endsWith(".") ? normalized.slice(0, -1) : normalized;
+  if (clean.length === 0) {
+    throw new DomainValidationError("Domain must not be empty", domain);
+  }
+  if (clean.includes("://")) {
+    throw new DomainValidationError(
+      'Domain must not include a protocol scheme (e.g. remove "https://")',
+      domain
+    );
+  }
+  if (clean.includes("/")) {
+    throw new DomainValidationError(
+      "Domain must not include a path \u2014 provide only the hostname",
+      domain
+    );
+  }
+  if (IP_ADDRESS_RE.test(clean)) {
+    throw new DomainValidationError(
+      "IP addresses are not supported \u2014 provide a domain name",
+      domain
+    );
+  }
+  if (clean === "localhost") {
+    throw new DomainValidationError(
+      '"localhost" is not a valid domain',
+      domain
+    );
+  }
+  if (clean.length > 253) {
+    throw new DomainValidationError(
+      `Domain exceeds maximum length of 253 characters (got ${clean.length})`,
+      domain
+    );
+  }
+  const labels = clean.split(".");
+  if (labels.length < 2) {
+    throw new DomainValidationError(
+      'Domain must contain at least two labels (e.g. "example.com")',
+      domain
+    );
+  }
+  for (const label of labels) {
+    if (label.length === 0) {
+      throw new DomainValidationError(
+        "Domain contains an empty label (consecutive dots)",
+        domain
+      );
+    }
+    if (label.length > 63) {
+      throw new DomainValidationError(
+        `Label "${label}" exceeds maximum length of 63 characters (got ${label.length})`,
+        domain
+      );
+    }
+    if (!LABEL_RE.test(label)) {
+      throw new DomainValidationError(
+        `Label "${label}" contains invalid characters \u2014 only letters, digits, and hyphens are allowed, and labels must not start or end with a hyphen`,
+        domain
+      );
+    }
+  }
+  return clean;
+}
+function resolveFormat(format) {
+  let candidate = format;
+  if (candidate.startsWith("image/")) {
+    candidate = candidate.slice(6);
+  }
+  if (candidate in FORMAT_ALIASES) {
+    return candidate;
+  }
+  if (SUPPORTED_FORMATS.has(format)) {
+    const shorthand = format.slice(6);
+    if (shorthand in FORMAT_ALIASES) {
+      return shorthand;
+    }
+  }
+  return void 0;
+}
+function logoUrl(domain, options) {
+  const validDomain = validateDomain(domain);
+  const {
+    token,
+    size,
+    width,
+    greyscale,
+    theme,
+    format,
+    baseUrl
+  } = options ?? {};
+  const maxWidth = token?.startsWith("sk_") ? MAX_WIDTH_SERVER : MAX_WIDTH;
+  let resolvedSize = size ?? width ?? DEFAULT_WIDTH;
+  if (resolvedSize <= 0) {
+    resolvedSize = DEFAULT_WIDTH;
+  }
+  resolvedSize = Math.max(1, Math.min(resolvedSize, maxWidth));
+  const resolvedFormat = format ? resolveFormat(format) : void 0;
+  const effectiveBaseUrl = baseUrl ?? BASE_URL;
+  const url = new URL(`${effectiveBaseUrl}/${validDomain}`);
+  if (token !== void 0) {
+    url.searchParams.set("token", token);
+  }
+  if (resolvedSize !== DEFAULT_WIDTH) {
+    url.searchParams.set("size", String(resolvedSize));
+  }
+  if (greyscale === true) {
+    url.searchParams.set("greyscale", "1");
+  }
+  if (theme === "light" || theme === "dark") {
+    url.searchParams.set("theme", theme);
+  }
+  if (resolvedFormat !== void 0) {
+    url.searchParams.set("format", resolvedFormat);
+  }
+  url.searchParams.set("autoScrape", "true");
+  return url.toString();
+}
+
+// src/internal/beacon.ts
+var firedTokens = /* @__PURE__ */ new Set();
+function fireBeacon(token) {
+  if (typeof window === "undefined") return;
+  if (!token) return;
+  if (token.startsWith("sk_")) return;
+  if (firedTokens.has(token)) return;
+  firedTokens.add(token);
+  const img = new Image();
+  img.src = `${BASE_URL}/_beacon?token=${token}&page=${encodeURIComponent(location.href)}`;
+}
+
+// src/element/styles.ts
+var STYLES = (
+  /* css */
+  `
+  :host {
+    display: inline-block !important;
+    line-height: 0 !important;
+  }
+
+  .qt-logo-container {
+    display: inline-flex !important;
+    flex-direction: column !important;
+    align-items: center !important;
+    gap: 4px !important;
+  }
+
+  .qt-logo-img {
+    display: block !important;
+    max-width: 100% !important;
+    height: auto !important;
+  }
+
+  .qt-attribution {
+    display: block !important;
+    font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif !important;
+    font-size: 10px !important;
+    color: #888 !important;
+    text-decoration: none !important;
+    white-space: nowrap !important;
+  }
+
+  .qt-attribution:hover {
+    color: #555 !important;
+    text-decoration: underline !important;
+  }
+`
+);
+
+// src/element/index.ts
+var QuikturnLogo = class extends HTMLElement {
+  constructor() {
+    super();
+    this._beaconFired = false;
+    this.attachShadow({ mode: "open" });
+  }
+  static get observedAttributes() {
+    return ["domain", "token", "size", "format", "greyscale", "theme"];
+  }
+  connectedCallback() {
+    this._fireBeaconOnce();
+    this._render();
+  }
+  attributeChangedCallback() {
+    if (this.shadowRoot) {
+      this._render();
+    }
+  }
+  _fireBeaconOnce() {
+    if (this._beaconFired) return;
+    const domain = this.getAttribute("domain");
+    const token = this.getAttribute("token") ?? "";
+    if (!domain) return;
+    this._beaconFired = true;
+    fireBeacon(token);
+  }
+  _clearShadow() {
+    const shadow = this.shadowRoot;
+    if (!shadow) return;
+    while (shadow.firstChild) {
+      shadow.removeChild(shadow.firstChild);
+    }
+  }
+  _render() {
+    const shadow = this.shadowRoot;
+    if (!shadow) return;
+    const domain = this.getAttribute("domain");
+    this._clearShadow();
+    const style = document.createElement("style");
+    style.textContent = STYLES;
+    shadow.appendChild(style);
+    if (!domain) return;
+    const token = this.getAttribute("token") ?? "";
+    const size = this.getAttribute("size");
+    const format = this.getAttribute("format");
+    const greyscale = this.hasAttribute("greyscale");
+    const theme = this.getAttribute("theme");
+    const container = document.createElement("div");
+    container.className = "qt-logo-container";
+    const img = document.createElement("img");
+    img.className = "qt-logo-img";
+    img.loading = "lazy";
+    img.alt = `${domain} logo`;
+    img.src = logoUrl(domain, {
+      token: token || void 0,
+      size: size ? parseInt(size, 10) : void 0,
+      format,
+      greyscale,
+      theme
+    });
+    container.appendChild(img);
+    const link = document.createElement("a");
+    link.className = "qt-attribution";
+    link.href = `https://getquikturn.io?ref=${domain}`;
+    link.target = "_blank";
+    link.rel = "noopener noreferrer";
+    link.textContent = "Powered by Quikturn";
+    container.appendChild(link);
+    shadow.appendChild(container);
+  }
+};
+if (typeof customElements !== "undefined" && !customElements.get("quikturn-logo")) {
+  customElements.define("quikturn-logo", QuikturnLogo);
+}
+
+exports.QuikturnLogo = QuikturnLogo;

package/dist/element/index.d.cts

@@ -0,0 +1,29 @@
+/**
+ * @quikturn/logos SDK — `<quikturn-logo>` Web Component
+ *
+ * Zero-effort attribution element for free-tier users. Uses shadow DOM to
+ * protect the attribution badge from accidental removal.
+ *
+ * Usage:
+ * ```html
+ * <script type="module" src="@quikturn/logos/element"></script>
+ * <quikturn-logo domain="github.com" token="qt_abc123" size="64"></quikturn-logo>
+ * ```
+ */
+/**
+ * Custom element that renders a Quikturn logo with attribution.
+ *
+ * Observed attributes: `domain`, `token`, `size`, `format`, `greyscale`, `theme`.
+ */
+declare class QuikturnLogo extends HTMLElement {
+    static get observedAttributes(): string[];
+    private _beaconFired;
+    constructor();
+    connectedCallback(): void;
+    attributeChangedCallback(): void;
+    private _fireBeaconOnce;
+    private _clearShadow;
+    private _render;
+}
+
+export { QuikturnLogo };

package/dist/element/index.d.ts

@@ -0,0 +1,29 @@
+/**
+ * @quikturn/logos SDK — `<quikturn-logo>` Web Component
+ *
+ * Zero-effort attribution element for free-tier users. Uses shadow DOM to
+ * protect the attribution badge from accidental removal.
+ *
+ * Usage:
+ * ```html
+ * <script type="module" src="@quikturn/logos/element"></script>
+ * <quikturn-logo domain="github.com" token="qt_abc123" size="64"></quikturn-logo>
+ * ```
+ */
+/**
+ * Custom element that renders a Quikturn logo with attribution.
+ *
+ * Observed attributes: `domain`, `token`, `size`, `format`, `greyscale`, `theme`.
+ */
+declare class QuikturnLogo extends HTMLElement {
+    static get observedAttributes(): string[];
+    private _beaconFired;
+    constructor();
+    connectedCallback(): void;
+    attributeChangedCallback(): void;
+    private _fireBeaconOnce;
+    private _clearShadow;
+    private _render;
+}
+
+export { QuikturnLogo };

package/dist/element/index.mjs

@@ -0,0 +1,286 @@
+// src/constants.ts
+var BASE_URL = "https://logos.getquikturn.io";
+var DEFAULT_WIDTH = 128;
+var MAX_WIDTH = 800;
+var MAX_WIDTH_SERVER = 1200;
+var SUPPORTED_FORMATS = /* @__PURE__ */ new Set([
+  "image/png",
+  "image/jpeg",
+  "image/webp",
+  "image/avif"
+]);
+var FORMAT_ALIASES = {
+  png: "image/png",
+  jpeg: "image/jpeg",
+  webp: "image/webp",
+  avif: "image/avif"
+};
+
+// src/errors.ts
+var LogoError = class extends Error {
+  constructor(message, code, status) {
+    super(message);
+    this.name = "LogoError";
+    this.code = code;
+    this.status = status;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var DomainValidationError = class extends LogoError {
+  constructor(message, domain) {
+    super(message, "DOMAIN_VALIDATION_ERROR");
+    this.name = "DomainValidationError";
+    this.domain = domain;
+  }
+};
+
+// src/url-builder.ts
+var IP_ADDRESS_RE = /^(\d{1,3}\.){3}\d{1,3}$/;
+var LABEL_RE = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/;
+function validateDomain(domain) {
+  const normalized = domain.trim().toLowerCase();
+  const clean = normalized.endsWith(".") ? normalized.slice(0, -1) : normalized;
+  if (clean.length === 0) {
+    throw new DomainValidationError("Domain must not be empty", domain);
+  }
+  if (clean.includes("://")) {
+    throw new DomainValidationError(
+      'Domain must not include a protocol scheme (e.g. remove "https://")',
+      domain
+    );
+  }
+  if (clean.includes("/")) {
+    throw new DomainValidationError(
+      "Domain must not include a path \u2014 provide only the hostname",
+      domain
+    );
+  }
+  if (IP_ADDRESS_RE.test(clean)) {
+    throw new DomainValidationError(
+      "IP addresses are not supported \u2014 provide a domain name",
+      domain
+    );
+  }
+  if (clean === "localhost") {
+    throw new DomainValidationError(
+      '"localhost" is not a valid domain',
+      domain
+    );
+  }
+  if (clean.length > 253) {
+    throw new DomainValidationError(
+      `Domain exceeds maximum length of 253 characters (got ${clean.length})`,
+      domain
+    );
+  }
+  const labels = clean.split(".");
+  if (labels.length < 2) {
+    throw new DomainValidationError(
+      'Domain must contain at least two labels (e.g. "example.com")',
+      domain
+    );
+  }
+  for (const label of labels) {
+    if (label.length === 0) {
+      throw new DomainValidationError(
+        "Domain contains an empty label (consecutive dots)",
+        domain
+      );
+    }
+    if (label.length > 63) {
+      throw new DomainValidationError(
+        `Label "${label}" exceeds maximum length of 63 characters (got ${label.length})`,
+        domain
+      );
+    }
+    if (!LABEL_RE.test(label)) {
+      throw new DomainValidationError(
+        `Label "${label}" contains invalid characters \u2014 only letters, digits, and hyphens are allowed, and labels must not start or end with a hyphen`,
+        domain
+      );
+    }
+  }
+  return clean;
+}
+function resolveFormat(format) {
+  let candidate = format;
+  if (candidate.startsWith("image/")) {
+    candidate = candidate.slice(6);
+  }
+  if (candidate in FORMAT_ALIASES) {
+    return candidate;
+  }
+  if (SUPPORTED_FORMATS.has(format)) {
+    const shorthand = format.slice(6);
+    if (shorthand in FORMAT_ALIASES) {
+      return shorthand;
+    }
+  }
+  return void 0;
+}
+function logoUrl(domain, options) {
+  const validDomain = validateDomain(domain);
+  const {
+    token,
+    size,
+    width,
+    greyscale,
+    theme,
+    format,
+    baseUrl
+  } = options ?? {};
+  const maxWidth = token?.startsWith("sk_") ? MAX_WIDTH_SERVER : MAX_WIDTH;
+  let resolvedSize = size ?? width ?? DEFAULT_WIDTH;
+  if (resolvedSize <= 0) {
+    resolvedSize = DEFAULT_WIDTH;
+  }
+  resolvedSize = Math.max(1, Math.min(resolvedSize, maxWidth));
+  const resolvedFormat = format ? resolveFormat(format) : void 0;
+  const effectiveBaseUrl = baseUrl ?? BASE_URL;
+  const url = new URL(`${effectiveBaseUrl}/${validDomain}`);
+  if (token !== void 0) {
+    url.searchParams.set("token", token);
+  }
+  if (resolvedSize !== DEFAULT_WIDTH) {
+    url.searchParams.set("size", String(resolvedSize));
+  }
+  if (greyscale === true) {
+    url.searchParams.set("greyscale", "1");
+  }
+  if (theme === "light" || theme === "dark") {
+    url.searchParams.set("theme", theme);
+  }
+  if (resolvedFormat !== void 0) {
+    url.searchParams.set("format", resolvedFormat);
+  }
+  url.searchParams.set("autoScrape", "true");
+  return url.toString();
+}
+
+// src/internal/beacon.ts
+var firedTokens = /* @__PURE__ */ new Set();
+function fireBeacon(token) {
+  if (typeof window === "undefined") return;
+  if (!token) return;
+  if (token.startsWith("sk_")) return;
+  if (firedTokens.has(token)) return;
+  firedTokens.add(token);
+  const img = new Image();
+  img.src = `${BASE_URL}/_beacon?token=${token}&page=${encodeURIComponent(location.href)}`;
+}
+
+// src/element/styles.ts
+var STYLES = (
+  /* css */
+  `
+  :host {
+    display: inline-block !important;
+    line-height: 0 !important;
+  }
+
+  .qt-logo-container {
+    display: inline-flex !important;
+    flex-direction: column !important;
+    align-items: center !important;
+    gap: 4px !important;
+  }
+
+  .qt-logo-img {
+    display: block !important;
+    max-width: 100% !important;
+    height: auto !important;
+  }
+
+  .qt-attribution {
+    display: block !important;
+    font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif !important;
+    font-size: 10px !important;
+    color: #888 !important;
+    text-decoration: none !important;
+    white-space: nowrap !important;
+  }
+
+  .qt-attribution:hover {
+    color: #555 !important;
+    text-decoration: underline !important;
+  }
+`
+);
+
+// src/element/index.ts
+var QuikturnLogo = class extends HTMLElement {
+  constructor() {
+    super();
+    this._beaconFired = false;
+    this.attachShadow({ mode: "open" });
+  }
+  static get observedAttributes() {
+    return ["domain", "token", "size", "format", "greyscale", "theme"];
+  }
+  connectedCallback() {
+    this._fireBeaconOnce();
+    this._render();
+  }
+  attributeChangedCallback() {
+    if (this.shadowRoot) {
+      this._render();
+    }
+  }
+  _fireBeaconOnce() {
+    if (this._beaconFired) return;
+    const domain = this.getAttribute("domain");
+    const token = this.getAttribute("token") ?? "";
+    if (!domain) return;
+    this._beaconFired = true;
+    fireBeacon(token);
+  }
+  _clearShadow() {
+    const shadow = this.shadowRoot;
+    if (!shadow) return;
+    while (shadow.firstChild) {
+      shadow.removeChild(shadow.firstChild);
+    }
+  }
+  _render() {
+    const shadow = this.shadowRoot;
+    if (!shadow) return;
+    const domain = this.getAttribute("domain");
+    this._clearShadow();
+    const style = document.createElement("style");
+    style.textContent = STYLES;
+    shadow.appendChild(style);
+    if (!domain) return;
+    const token = this.getAttribute("token") ?? "";
+    const size = this.getAttribute("size");
+    const format = this.getAttribute("format");
+    const greyscale = this.hasAttribute("greyscale");
+    const theme = this.getAttribute("theme");
+    const container = document.createElement("div");
+    container.className = "qt-logo-container";
+    const img = document.createElement("img");
+    img.className = "qt-logo-img";
+    img.loading = "lazy";
+    img.alt = `${domain} logo`;
+    img.src = logoUrl(domain, {
+      token: token || void 0,
+      size: size ? parseInt(size, 10) : void 0,
+      format,
+      greyscale,
+      theme
+    });
+    container.appendChild(img);
+    const link = document.createElement("a");
+    link.className = "qt-attribution";
+    link.href = `https://getquikturn.io?ref=${domain}`;
+    link.target = "_blank";
+    link.rel = "noopener noreferrer";
+    link.textContent = "Powered by Quikturn";
+    container.appendChild(link);
+    shadow.appendChild(container);
+  }
+};
+if (typeof customElements !== "undefined" && !customElements.get("quikturn-logo")) {
+  customElements.define("quikturn-logo", QuikturnLogo);
+}
+
+export { QuikturnLogo };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quikturn/logos",
-  "version": "0.2.1",
+  "version": "0.4.0",
   "description": "Quikturn Logo SDK — URL builder, browser client, and server client for the Quikturn Logos API",
   "license": "MIT",
   "author": "Quikturn",
@@ -20,7 +20,10 @@
     "sdk"
   ],
   "type": "module",
-  "sideEffects": false,
+  "sideEffects": [
+    "./dist/element/index.mjs",
+    "./dist/element/index.cjs"
+  ],
   "packageManager": "pnpm@10.28.1",
   "engines": {
     "node": ">=18"
@@ -55,6 +58,14 @@
       },
       "import": "./dist/server/index.mjs",
       "require": "./dist/server/index.cjs"
+    },
+    "./element": {
+      "types": {
+        "import": "./dist/element/index.d.ts",
+        "require": "./dist/element/index.d.cts"
+      },
+      "import": "./dist/element/index.mjs",
+      "require": "./dist/element/index.cjs"
     }
   },
   "publishConfig": {
@@ -65,7 +76,7 @@
   "types": "./dist/index.d.ts",
   "scripts": {
     "build": "tsup",
-    "test": "vitest run --project unit --project client --project server",
+    "test": "vitest run --project unit --project client --project server --project element",
     "test:integration": "vitest run --project integration",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",