wc-img-ai 0.2.2 → 0.3.0

package/README.md

@@ -1,21 +1,31 @@
-# AI based img-tags
+# wc-img-ai
 
-By simply providing a src to an api that does the AI for you, and you can simply get ai-rendered images anywhere you need based on the prompt-attribute.
+AI-generated images as a web component. Drop an `<ai-img>` anywhere, give it a
+`prompt` and the URL of your own server endpoint, and it renders an
+AI-generated image — while the API key, image generation and storage all stay
+on the server.
 
 ```html
 <ai-img
-  src="http://localhost:4321/api/openai/img"
+  endpoint="/api/img"
   width="256"
   height="256"
-  prompt="funny dolphin up to no good"
-  fallback="https://placekitten.com/200/300"
+  prompt="a funny dolphin up to no good"
+  fallback="https://placehold.co/256x256"
 ></ai-img>
 ```
 
-## installation
+## Why a server endpoint?
+
+The component is deliberately dumb: it never holds an API key, never picks a
+provider, and never talks to OpenAI/Gemini directly. It sends a single POST to
+**your** endpoint, and your server decides what to do. That keeps tokens
+server-side and lets you store, cache and bill generation however you like.
+
+## Install
 
 ```bash
-pnpm i wc-img-ai
+pnpm add wc-img-ai
 ```
 
 ```html
@@ -24,36 +34,124 @@ pnpm i wc-img-ai
 </script>
 ```
 
-The api server itself needs to receive this body and return a string with the url of the image
+## Attributes
+
+| Attribute   | Reflected | Description                                                                 |
+| ----------- | --------- | --------------------------------------------------------------------------- |
+| `src`       | —         | A ready image URL (or data URL). When set, the component acts as a plain `<img>` and never calls the endpoint. Use it when you already have the image. Highest priority. |
+| `endpoint`  | —         | Your server route. Receives the POST below.                                 |
+| `prompt`    | —         | Description used to generate the image.                                     |
+| `image-id`  | ✅ yes    | Storage handle. Provide a known id to fetch a stored image; the server sets it on the element when a new image is minted. |
+| `llm`       | —         | Provider/model hint forwarded to the endpoint (e.g. `gemini`, `openai`).    |
+| `ratio`     | —         | Aspect ratio forwarded to the endpoint (e.g. `16:9`, `4:1`).                |
+| `fallback`  | —         | Image URL shown if nothing resolves. If omitted, a 1×1 transparent PNG is used. |
+| `width`     | ✅ yes    | Intrinsic width (like `<img width>`) — used for the box aspect-ratio and sent to the endpoint. |
+| `height`    | ✅ yes    | Intrinsic height (like `<img height>`).                                     |
+| `alt`       | ✅ yes    | Alt text, passed to the inner `<img>`.                                       |
+
+### Sizing & styling — just like a native `<img>`
+
+Set `width`/`height` and style with `class`/CSS; you rarely need inline
+`style`. `width`/`height` become the inner image's content attributes, so the
+browser reserves the box from their aspect-ratio (no layout shift) while CSS
+controls the displayed size:
+
+```html
+<!-- full-width 3:1 banner, rounded, no layout shift -->
+<ai-img endpoint="/api/img" prompt="…" width="1536" height="512"
+        class="block w-full rounded-xl"></ai-img>
+```
+
+Visual properties bridge the shadow boundary via `inherit`, so utility classes
+like `rounded-xl`, `object-cover`, `shadow-lg` on `<ai-img>` style the image.
+Any other attribute (e.g. `loading`) is passed through to the inner `<img>`.
 
-### Function: POST
+## How it resolves
 
-The web-component sends a POST request to the API to generate an image and expects an image in return.
+```
+src set                   → render it as a plain <img>      (no endpoint call)
+else no prompt, no image-id → fallback → 1×1 transparent PNG (nothing to ask)
+else → POST endpoint once  { prompt, imageId, width, height, llm, ratio }
+   200 {id,url} → render url, reflect image-id, fire `ai-image` event
+   404 / error  → fallback → 1×1 transparent PNG
+```
 
-#### Request Body Format
+`src` is the cheapest path: if you already have the image (a precomputed or
+returning one), set `src` and the component skips the AI entirely. Only when
+`src` is empty does it fall back to the `prompt`/`image-id` flow.
 
-- **prompt** (string): The description or prompt based on which the image will be generated.
-- **width** (number): The width of the desired image in pixels.
-- **height** (number): The height of the desired image in pixels.
+> **Performance note.** For an image you _already have the URL for_, a plain
+> `<img src>` will paint faster than `<ai-img src>` — the web component can't
+> render until its own script has loaded and defined the element, whereas a
+> native `<img>` loads with the document. Use `src` for a single unified tag;
+> reach for a native `<img>` (and load `<ai-img>` only when you need to
+> generate) when first paint of a known image is critical.
 
-#### Example Request Body
+The component never branches on whether an image exists — the **server** owns
+that decision (see the contract below). If the returned `url` itself fails to
+load in the `<img>` (a transient 404, slow propagation, a stale url), the
+component retries once and then drops to the fallback chain.
+
+## The `ai-image` event
+
+Fired after a successful resolve. Use it to persist the id (and url) to a
+database so you can render the same image again later without re-generating.
+
+```js
+el.addEventListener("ai-image", (e) => {
+  // e.detail = { id, url, prompt }
+  db.save(e.detail)
+})
+```
+
+The minted id is also reflected onto the `image-id` attribute.
+
+## Server contract
+
+The component talks to a single endpoint with one POST. Your server is the
+"smart" side that decides between fetching a stored image and generating a new
+one.
+
+### `POST {endpoint}`
+
+Request body:
 
 ```json
-{
-  "prompt": "a sleeping little kitten",
-  "width": 256,
-  "height": 256
-}
+{ "prompt": "a funny dolphin", "imageId": "V1StGXR8_Z5", "width": 256, "height": 256, "llm": "gemini", "ratio": "16:9" }
 ```
 
-#### Server Return
+`imageId`, `width`, `height`, `llm` and `ratio` are optional. Use `llm`/`ratio`
+to let the server pick a provider and aspect ratio. Expected server behaviour:
+
+| Condition                                   | Response          |
+| ------------------------------------------- | ----------------- |
+| `imageId` given and stored                  | `200 {id,url}` — return it, no AI |
+| `imageId` given but missing, `prompt` given | `200 {id,url}` — generate (mint a new id) |
+| no `imageId`, `prompt` given                | `200 {id,url}` — generate |
+| nothing to do                               | `404`             |
 
-it is expected to return a simple string
+Response body on success:
 
 ```json
-"https://example.com/path/to/generated/image.jpg"
+{ "id": "V1StGXR8_Z5", "url": "/images/V1StGXR8_Z5.png" }
+```
+
+`url` can be anything the browser can load (a hosted/CDN URL, a route on your
+server, or a data URL).
+
+## Reference demo server
+
+`demo/server.mjs` is a complete, dependency-light reference implementation:
+OpenAI `gpt-image-2`, nanoid ids, filesystem storage under `images/`, served
+back as stable URLs.
+
+```bash
+cp .env.example .env   # add OPENAI_API_KEY
+pnpm install
+pnpm build
+pnpm demo              # http://localhost:3000
 ```
 
-#### Demo
+## License
 
-Check it out [running](https://john.ro/lab/img-ai) inside an MDX/Astro framework
+MIT

package/dist/wc-img-ai.js

@@ -4,7 +4,7 @@
  * SPDX-License-Identifier: BSD-3-Clause
  */
 var _a;
-const t$3 = globalThis, e$3 = t$3.ShadowRoot && (void 0 === t$3.ShadyCSS || t$3.ShadyCSS.nativeShadow) && "adoptedStyleSheets" in Document.prototype && "replace" in CSSStyleSheet.prototype, s$3 = Symbol(), o$4 = /* @__PURE__ */ new WeakMap();
+const t$2 = globalThis, e$3 = t$2.ShadowRoot && (void 0 === t$2.ShadyCSS || t$2.ShadyCSS.nativeShadow) && "adoptedStyleSheets" in Document.prototype && "replace" in CSSStyleSheet.prototype, s$3 = Symbol(), o$4 = /* @__PURE__ */ new WeakMap();
 let n$4 = class n {
   constructor(t2, e2, o2) {
     if (this._$cssResult$ = true, o2 !== s$3)
@@ -24,7 +24,7 @@ let n$4 = class n {
     return this.cssText;
   }
 };
-const r$5 = (t2) => new n$4("string" == typeof t2 ? t2 : t2 + "", void 0, s$3), i$3 = (t2, ...e2) => {
+const r$6 = (t2) => new n$4("string" == typeof t2 ? t2 : t2 + "", void 0, s$3), i$3 = (t2, ...e2) => {
   const o2 = 1 === t2.length ? t2[0] : e2.reduce((e3, s3, o3) => e3 + ((t3) => {
     if (true === t3._$cssResult$)
       return t3.cssText;
@@ -38,21 +38,21 @@ const r$5 = (t2) => new n$4("string" == typeof t2 ? t2 : t2 + "", void 0, s$3),
     s3.adoptedStyleSheets = o2.map((t2) => t2 instanceof CSSStyleSheet ? t2 : t2.styleSheet);
   else
     for (const e2 of o2) {
-      const o3 = document.createElement("style"), n3 = t$3.litNonce;
+      const o3 = document.createElement("style"), n3 = t$2.litNonce;
       void 0 !== n3 && o3.setAttribute("nonce", n3), o3.textContent = e2.cssText, s3.appendChild(o3);
     }
 }, c$3 = e$3 ? (t2) => t2 : (t2) => t2 instanceof CSSStyleSheet ? ((t3) => {
   let e2 = "";
   for (const s3 of t3.cssRules)
     e2 += s3.cssText;
-  return r$5(e2);
+  return r$6(e2);
 })(t2) : t2;
 /**
  * @license
  * Copyright 2017 Google LLC
  * SPDX-License-Identifier: BSD-3-Clause
  */
-const { is: i$2, defineProperty: e$2, getOwnPropertyDescriptor: r$4, getOwnPropertyNames: h$2, getOwnPropertySymbols: o$3, getPrototypeOf: n$3 } = Object, a$1 = globalThis, c$2 = a$1.trustedTypes, l$1 = c$2 ? c$2.emptyScript : "", p$1 = a$1.reactiveElementPolyfillSupport, d$1 = (t2, s3) => t2, u$1 = { toAttribute(t2, s3) {
+const { is: i$2, defineProperty: e$2, getOwnPropertyDescriptor: r$5, getOwnPropertyNames: h$2, getOwnPropertySymbols: o$3, getPrototypeOf: n$3 } = Object, a$1 = globalThis, c$2 = a$1.trustedTypes, l$1 = c$2 ? c$2.emptyScript : "", p$1 = a$1.reactiveElementPolyfillSupport, d$1 = (t2, s3) => t2, u$1 = { toAttribute(t2, s3) {
   switch (s3) {
     case Boolean:
       t2 = t2 ? l$1 : null;
@@ -96,7 +96,7 @@ class b extends HTMLElement {
     }
   }
   static getPropertyDescriptor(t2, s3, i2) {
-    const { get: e2, set: h2 } = r$4(this.prototype, t2) ?? { get() {
+    const { get: e2, set: h2 } = r$5(this.prototype, t2) ?? { get() {
       return this[s3];
     }, set(t3) {
       this[s3] = t3;
@@ -299,8 +299,8 @@ b.elementStyles = [], b.shadowRootOptions = { mode: "open" }, b[d$1("elementProp
  * Copyright 2017 Google LLC
  * SPDX-License-Identifier: BSD-3-Clause
  */
-const t$2 = globalThis, i$1 = t$2.trustedTypes, s$2 = i$1 ? i$1.createPolicy("lit-html", { createHTML: (t2) => t2 }) : void 0, e$1 = "$lit$", h$1 = `lit$${(Math.random() + "").slice(9)}$`, o$2 = "?" + h$1, n$2 = `<${o$2}>`, r$3 = document, l = () => r$3.createComment(""), c$1 = (t2) => null === t2 || "object" != typeof t2 && "function" != typeof t2, a = Array.isArray, u = (t2) => a(t2) || "function" == typeof (t2 == null ? void 0 : t2[Symbol.iterator]), d = "[ 	\n\f\r]", f$2 = /<(?:(!--|\/[^a-zA-Z])|(\/?[a-zA-Z][^>\s]*)|(\/?$))/g, v = /-->/g, _ = />/g, m = RegExp(`>|${d}(?:([^\\s"'>=/]+)(${d}*=${d}*(?:[^ 	
-\f\r"'\`<>=]|("|')|))|$)`, "g"), p = /'/g, g = /"/g, $ = /^(?:script|style|textarea|title)$/i, y = (t2) => (i2, ...s3) => ({ _$litType$: t2, strings: i2, values: s3 }), x = y(1), w = Symbol.for("lit-noChange"), T = Symbol.for("lit-nothing"), A = /* @__PURE__ */ new WeakMap(), E = r$3.createTreeWalker(r$3, 129);
+const t$1 = globalThis, i$1 = t$1.trustedTypes, s$2 = i$1 ? i$1.createPolicy("lit-html", { createHTML: (t2) => t2 }) : void 0, e$1 = "$lit$", h$1 = `lit$${(Math.random() + "").slice(9)}$`, o$2 = "?" + h$1, n$2 = `<${o$2}>`, r$4 = document, l = () => r$4.createComment(""), c$1 = (t2) => null === t2 || "object" != typeof t2 && "function" != typeof t2, a = Array.isArray, u = (t2) => a(t2) || "function" == typeof (t2 == null ? void 0 : t2[Symbol.iterator]), d = "[ 	\n\f\r]", f$2 = /<(?:(!--|\/[^a-zA-Z])|(\/?[a-zA-Z][^>\s]*)|(\/?$))/g, v = /-->/g, _ = />/g, m = RegExp(`>|${d}(?:([^\\s"'>=/]+)(${d}*=${d}*(?:[^ 	
+\f\r"'\`<>=]|("|')|))|$)`, "g"), p = /'/g, g = /"/g, $ = /^(?:script|style|textarea|title)$/i, y = (t2) => (i2, ...s3) => ({ _$litType$: t2, strings: i2, values: s3 }), x = y(1), w = Symbol.for("lit-noChange"), T = Symbol.for("lit-nothing"), A = /* @__PURE__ */ new WeakMap(), E = r$4.createTreeWalker(r$4, 129);
 function C(t2, i2) {
   if (!Array.isArray(t2) || !t2.hasOwnProperty("raw"))
     throw Error("invalid template strings array");
@@ -359,7 +359,7 @@ class V {
     }
   }
   static createElement(t2, i2) {
-    const s3 = r$3.createElement("template");
+    const s3 = r$4.createElement("template");
     return s3.innerHTML = t2, s3;
   }
 }
@@ -382,7 +382,7 @@ class S {
     return this._$AM._$AU;
   }
   u(t2) {
-    const { el: { content: i2 }, parts: s3 } = this._$AD, e2 = ((t2 == null ? void 0 : t2.creationScope) ?? r$3).importNode(i2, true);
+    const { el: { content: i2 }, parts: s3 } = this._$AD, e2 = ((t2 == null ? void 0 : t2.creationScope) ?? r$4).importNode(i2, true);
     E.currentNode = e2;
     let h2 = E.nextNode(), o2 = 0, n3 = 0, l2 = s3[0];
     for (; void 0 !== l2; ) {
@@ -392,7 +392,7 @@ class S {
       }
       o2 !== (l2 == null ? void 0 : l2.index) && (h2 = E.nextNode(), o2++);
     }
-    return E.currentNode = r$3, e2;
+    return E.currentNode = r$4, e2;
   }
   p(t2) {
     let i2 = 0;
@@ -429,7 +429,7 @@ class M {
     this._$AH !== t2 && (this._$AR(), this._$AH = this.k(t2));
   }
   _(t2) {
-    this._$AH !== T && c$1(this._$AH) ? this._$AA.nextSibling.data = t2 : this.$(r$3.createTextNode(t2)), this._$AH = t2;
+    this._$AH !== T && c$1(this._$AH) ? this._$AA.nextSibling.data = t2 : this.$(r$4.createTextNode(t2)), this._$AH = t2;
   }
   g(t2) {
     var _a2;
@@ -534,8 +534,8 @@ class L {
     N(this, t2);
   }
 }
-const Z = t$2.litHtmlPolyfillSupport;
-Z == null ? void 0 : Z(V, M), (t$2.litHtmlVersions ?? (t$2.litHtmlVersions = [])).push("3.1.0");
+const Z = t$1.litHtmlPolyfillSupport;
+Z == null ? void 0 : Z(V, M), (t$1.litHtmlVersions ?? (t$1.litHtmlVersions = [])).push("3.1.0");
 const j = (t2, i2, s3) => {
   const e2 = (s3 == null ? void 0 : s3.renderBefore) ?? i2;
   let h2 = e2._$litPart$;
@@ -576,25 +576,15 @@ let s$1 = class s extends b {
   }
 };
 s$1._$litElement$ = true, s$1["finalized"] = true, (_a = globalThis.litElementHydrateSupport) == null ? void 0 : _a.call(globalThis, { LitElement: s$1 });
-const r$2 = globalThis.litElementPolyfillSupport;
-r$2 == null ? void 0 : r$2({ LitElement: s$1 });
+const r$3 = globalThis.litElementPolyfillSupport;
+r$3 == null ? void 0 : r$3({ LitElement: s$1 });
 (globalThis.litElementVersions ?? (globalThis.litElementVersions = [])).push("4.0.2");
 /**
  * @license
  * Copyright 2017 Google LLC
  * SPDX-License-Identifier: BSD-3-Clause
  */
-const t$1 = (t2) => (e2, o2) => {
-  void 0 !== o2 ? o2.addInitializer(() => {
-    customElements.define(t2, e2);
-  }) : customElements.define(t2, e2);
-};
-/**
- * @license
- * Copyright 2017 Google LLC
- * SPDX-License-Identifier: BSD-3-Clause
- */
-const o$1 = { attribute: true, type: String, converter: u$1, reflect: false, hasChanged: f$3 }, r$1 = (t2 = o$1, e2, r2) => {
+const o$1 = { attribute: true, type: String, converter: u$1, reflect: false, hasChanged: f$3 }, r$2 = (t2 = o$1, e2, r2) => {
   const { kind: n3, metadata: i2 } = r2;
   let s3 = globalThis.litPropertyMetadata.get(i2);
   if (void 0 === s3 && globalThis.litPropertyMetadata.set(i2, s3 = /* @__PURE__ */ new Map()), s3.set(r2.name, t2), "accessor" === n3) {
@@ -616,11 +606,19 @@ const o$1 = { attribute: true, type: String, converter: u$1, reflect: false, has
   throw Error("Unsupported decorator location: " + n3);
 };
 function n$1(t2) {
-  return (e2, o2) => "object" == typeof o2 ? r$1(t2, e2, o2) : ((t3, e3, o3) => {
+  return (e2, o2) => "object" == typeof o2 ? r$2(t2, e2, o2) : ((t3, e3, o3) => {
     const r2 = e3.hasOwnProperty(o3);
     return e3.constructor.createProperty(o3, r2 ? { ...t3, wrapped: true } : t3), r2 ? Object.getOwnPropertyDescriptor(e3, o3) : void 0;
   })(t2, e2, o2);
 }
+/**
+ * @license
+ * Copyright 2017 Google LLC
+ * SPDX-License-Identifier: BSD-3-Clause
+ */
+function r$1(r2) {
+  return n$1({ ...r2, state: true, attribute: false });
+}
 /**
  * @license
  * Copyright 2017 Google LLC
@@ -890,28 +888,34 @@ class SpreadDirective extends SpreadEventsDirective {
 }
 const spread = e(SpreadDirective);
 const spinner = `<svg width="24" height="24" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"><style>.a{animation:b .8s linear infinite;fill:#888}.c{animation-delay:-.65s}.d{animation-delay:-.5s}@keyframes b{93.75%,100%{r:3px}46.875%{r:.2px}}</style><circle class="a" cx="4" cy="12" r="3"/><circle class="a c" cx="12" cy="12" r="3"/><circle class="a d" cx="20" cy="12" r="3"/></svg>`;
-const getGeneratedImage = async (endpoint, prompt, width, height) => {
-  let response;
+const TRANSPARENT_PIXEL = "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAAC0lEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==";
+const resolveImage = async (endpoint, req) => {
+  if (!endpoint)
+    return null;
   try {
     const r2 = await fetch(endpoint, {
       method: "POST",
-      headers: {
-        "Content-Type": "application/json"
-      },
+      headers: { "Content-Type": "application/json" },
       body: JSON.stringify({
-        prompt,
-        width,
-        height
+        prompt: req.prompt || void 0,
+        imageId: req.imageId || void 0,
+        width: req.width || void 0,
+        height: req.height || void 0,
+        llm: req.llm || void 0,
+        ratio: req.ratio || void 0
       })
     });
-    if (!r2.ok) {
-      throw new Error("Network response was not ok");
+    if (!r2.ok)
+      return null;
+    const data = await r2.json();
+    if (!data || typeof data.url !== "string" || data.url.length === 0) {
+      return null;
     }
-    response = await r2.text();
+    return { id: typeof data.id === "string" ? data.id : "", url: data.url };
   } catch (error) {
-    console.error("There has been a problem with your fetch operation:", error);
+    console.error("ai-img: image request failed:", error);
+    return null;
   }
-  return response;
 };
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
@@ -924,118 +928,150 @@ var __decorateClass = (decorators, target, key, kind) => {
     __defProp(target, key, result);
   return result;
 };
-let AiImg = class extends s$1 {
+const SPINNER_BG = r$6(encodeURIComponent(spinner));
+const RESERVED_ATTRS = /* @__PURE__ */ new Set([
+  "endpoint",
+  "prompt",
+  "image-id",
+  "fallback",
+  "width",
+  "height",
+  "llm",
+  "ratio",
+  "class",
+  "style",
+  "loading",
+  "decoding",
+  "src"
+]);
+const placeholder = (width, height) => "data:image/svg+xml;utf8," + encodeURIComponent(
+  `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ${width} ${height}"><rect width="${width}" height="${height}" fill="#ddd"/></svg>`
+);
+const _AiImg = class _AiImg extends s$1 {
   constructor() {
     super(...arguments);
+    this.src = "";
+    this.endpoint = "";
+    this.prompt = "";
+    this.imageId = "";
+    this.llm = "";
+    this.ratio = "";
     this.fallback = "";
     this.width = "";
     this.height = "";
-    this.src = "";
     this.alt = "";
-    this.imgsrc = "";
-    this.prompt = "";
+    this.imgsrc = TRANSPARENT_PIXEL;
     this.imgAttributes = {};
+    this.onFallback = false;
+    this.retried = false;
+    this.resolvedUrl = "";
+    this.onImgError = () => {
+      if (this.onFallback || !this.resolvedUrl)
+        return;
+      if (!this.retried) {
+        this.retried = true;
+        const sep = this.resolvedUrl.includes("?") ? "&" : "?";
+        const url = `${this.resolvedUrl}${sep}retry=${Date.now()}`;
+        setTimeout(() => {
+          this.imgsrc = url;
+        }, 800);
+        return;
+      }
+      this.resolvedUrl = "";
+      this.settleFallback();
+    };
   }
   connectedCallback() {
     super.connectedCallback();
-    this.initAttributes();
-    this.fetchImage();
+    queueMicrotask(() => this.start());
   }
-  async fetchImage() {
-    if (!this.prompt) {
-      this.imgsrc = this.fallback;
+  start() {
+    this.collectPassThroughAttributes();
+    if (this.src) {
+      this.resolvedUrl = this.src;
+      this.settle(this.src);
       return;
     }
-    try {
-      const openAiResponse = await getGeneratedImage(
-        this.src,
-        this.prompt,
-        Number(this.width),
-        Number(this.height)
-      );
-      this.imgsrc = openAiResponse || this.fallback;
-      this.classList.remove("spin");
-    } catch (error) {
-      console.error("Error fetching AI image:", error);
-      this.imgsrc = this.fallback;
-      this.classList.remove("spin");
+    if (!this.prompt && !this.imageId) {
+      this.settleFallback();
+      return;
     }
+    this.imgsrc = placeholder(this.width, this.height);
+    this.classList.add("spin");
+    void this.resolve();
   }
-  initAttributes() {
-    Array.from(this.attributes).forEach((attr) => {
-      if (![
-        "loading",
-        "decoding",
-        "src",
-        "fallback",
-        "prompt",
-        "style",
-        "width",
-        "height"
-      ].includes(attr.name)) {
+  collectPassThroughAttributes() {
+    for (const attr of Array.from(this.attributes)) {
+      if (!RESERVED_ATTRS.has(attr.name)) {
         this.imgAttributes[attr.name] = attr.value;
       }
-      if (attr.name === "width") {
-        this.width = attr.value;
-      }
-      if (attr.name === "height") {
-        this.height = attr.value;
-      }
+    }
+  }
+  async resolve() {
+    const result = await resolveImage(this.endpoint, {
+      prompt: this.prompt,
+      imageId: this.imageId,
+      width: Number(this.width) || void 0,
+      height: Number(this.height) || void 0,
+      llm: this.llm,
+      ratio: this.ratio
     });
-    this.imgsrc = "data:image/svg+xml;utf8," + encodeURIComponent(
-      `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ${this.width} ${this.height}"><rect width="${this.width}" height="${this.height}" fill="#ddd"/></svg>`
+    if (!result) {
+      this.settleFallback();
+      return;
+    }
+    if (result.id && result.id !== this.imageId) {
+      this.imageId = result.id;
+    }
+    this.dispatchEvent(
+      new CustomEvent("ai-image", {
+        detail: { id: result.id, url: result.url, prompt: this.prompt },
+        bubbles: true,
+        composed: true
+      })
     );
-    this.classList.add("spin");
+    this.resolvedUrl = result.url;
+    this.retried = false;
+    this.onFallback = false;
+    this.settle(result.url);
+  }
+  settle(src) {
+    this.imgsrc = src;
+    this.classList.remove("spin");
+  }
+  settleFallback() {
+    this.onFallback = true;
+    this.settle(this.fallback || TRANSPARENT_PIXEL);
   }
   render() {
     return x`
-      <style>
-        :host(.spin) {
-          position: relative;
-        }
-
-        :host(.spin):before {
-          content: "";
-          position: absolute;
-          margin: auto 0;
-          width: 100%;
-          height: 100%;
-          display: inline-flex;
-          justify-content: center;
-          align-items: center;
-          color: red;
-          background-image: url("data:image/svg+xml;utf8,${encodeURIComponent(
-      spinner
-    )}");
-          background-repeat: no-repeat;
-          background-position: center;
-          background-size: 25%;
-        }
-      </style>
-
-      ${this.imgsrc.length > 0 ? x`
-            <img
-              src=${this.imgsrc}
-              decoding="async"
-              loading="eager"
-              ${spread(this.imgAttributes)}
-            />
-          ` : x`<div>fail</div>`}
+      <img
+        src=${this.imgsrc}
+        alt=${this.alt}
+        width=${this.width || T}
+        height=${this.height || T}
+        decoding="async"
+        @error=${this.onImgError}
+        ${spread(this.imgAttributes)}
+      />
     `;
   }
 };
-AiImg.styles = i$3`
+_AiImg.styles = i$3`
     :host {
       display: inline-block;
+      position: relative;
+      line-height: 0;
     }
 
     img {
       display: block;
-      -webkit-user-select: none;
       width: 100%;
-      height: 100%;
+      height: auto;
+      -webkit-user-select: none;
       object-fit: inherit;
       object-position: inherit;
+      aspect-ratio: inherit;
       filter: inherit;
       transform: inherit;
       transition: inherit;
@@ -1043,7 +1079,37 @@ AiImg.styles = i$3`
       box-shadow: inherit;
       clip-path: inherit;
     }
+
+    :host(.spin)::before {
+      content: "";
+      position: absolute;
+      inset: 0;
+      margin: auto;
+      background-image: url("data:image/svg+xml;utf8,${SPINNER_BG}");
+      background-repeat: no-repeat;
+      background-position: center;
+      background-size: 25%;
+    }
   `;
+let AiImg = _AiImg;
+__decorateClass([
+  n$1({ type: String })
+], AiImg.prototype, "src", 2);
+__decorateClass([
+  n$1({ type: String })
+], AiImg.prototype, "endpoint", 2);
+__decorateClass([
+  n$1({ type: String })
+], AiImg.prototype, "prompt", 2);
+__decorateClass([
+  n$1({ type: String, attribute: "image-id", reflect: true })
+], AiImg.prototype, "imageId", 2);
+__decorateClass([
+  n$1({ type: String })
+], AiImg.prototype, "llm", 2);
+__decorateClass([
+  n$1({ type: String })
+], AiImg.prototype, "ratio", 2);
 __decorateClass([
   n$1({ type: String })
 ], AiImg.prototype, "fallback", 2);
@@ -1053,21 +1119,15 @@ __decorateClass([
 __decorateClass([
   n$1({ type: String, reflect: true })
 ], AiImg.prototype, "height", 2);
-__decorateClass([
-  n$1({ type: String, reflect: true })
-], AiImg.prototype, "src", 2);
 __decorateClass([
   n$1({ type: String, reflect: true })
 ], AiImg.prototype, "alt", 2);
 __decorateClass([
-  n$1({ type: String, reflect: false })
+  r$1()
 ], AiImg.prototype, "imgsrc", 2);
-__decorateClass([
-  n$1({ type: String, reflect: true })
-], AiImg.prototype, "prompt", 2);
-AiImg = __decorateClass([
-  t$1("ai-img")
-], AiImg);
+if (typeof customElements !== "undefined" && !customElements.get("ai-img")) {
+  customElements.define("ai-img", AiImg);
+}
 export {
   AiImg
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "wc-img-ai",
   "private": false,
-  "version": "0.2.2",
+  "version": "0.3.0",
   "description": "Use AI to generate images for your img tags.",
   "author": {
     "name": "John Romani",
@@ -22,15 +22,26 @@
     "types"
   ],
   "main": "./dist/wc-img-ai.js",
+  "types": "./types/ai-img.d.ts",
   "exports": {
-    ".": "./dist/wc-img-ai.js",
-    "./wc-img-ai.d.ts": "./types/wc-img-ai.d.ts"
+    ".": {
+      "types": "./types/ai-img.d.ts",
+      "default": "./dist/wc-img-ai.js"
+    },
+    "./types": "./types/ai-img.d.ts"
+  },
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc && vite build",
+    "preview": "vite preview",
+    "demo": "node demo/server.mjs"
   },
   "devDependencies": {
     "@typescript-eslint/eslint-plugin": "^6.17.0",
     "@typescript-eslint/parser": "^6.17.0",
     "eslint": "^8.56.0",
     "eslint-plugin-wc": "^2.0.4",
+    "nanoid": "^5.0.9",
     "typescript": "^5.2.2",
     "vite": "^5.0.8"
   },
@@ -42,10 +53,5 @@
   },
   "peerDependencies": {
     "lit": "^3.0.0"
-  },
-  "scripts": {
-    "dev": "vite",
-    "build": "tsc && vite build",
-    "preview": "vite preview"
   }
-}
+}

package/types/ai-img.d.ts

@@ -1,18 +1,38 @@
 import { LitElement } from "lit";
 export declare class AiImg extends LitElement {
+    /**
+     * A ready image URL (or data URL). When set, the component acts as a plain
+     * <img> and never calls the AI endpoint — use it when you already have the
+     * image (e.g. a precomputed/returning one). Highest priority.
+     */
+    src: string;
+    /** Server route that owns the API key, generation, storage and lookup. */
+    endpoint: string;
+    /** Description used to generate the image (omit when fetching a known id). */
+    prompt: string;
+    /** Storage handle. Reflected: set by the server when a new image is minted. */
+    imageId: string;
+    /** Provider/model hint forwarded to the endpoint (e.g. "gemini", "openai"). */
+    llm: string;
+    /** Aspect ratio forwarded to the endpoint (e.g. "16:9", "4:1"). */
+    ratio: string;
+    /** Shown when the image cannot be resolved (otherwise a 1x1 transparent PNG). */
     fallback: string;
     width: string;
     height: string;
-    src: string;
     alt: string;
-    imgsrc: string;
-    prompt: string;
-    imgAttributes: {
-        [key: string]: string;
-    };
+    private imgsrc;
+    private imgAttributes;
+    private onFallback;
+    private retried;
+    private resolvedUrl;
     connectedCallback(): void;
-    fetchImage(): Promise<void>;
-    initAttributes(): void;
+    private start;
+    private collectPassThroughAttributes;
+    private resolve;
+    private settle;
+    private settleFallback;
+    private onImgError;
     protected render(): import("lit").TemplateResult<1>;
     static styles: import("lit").CSSResult;
 }

package/types/get-generated-image.d.ts

@@ -1,2 +1,26 @@
 export declare const spinner = "<svg width=\"24\" height=\"24\" viewBox=\"0 0 24 24\" xmlns=\"http://www.w3.org/2000/svg\"><style>.a{animation:b .8s linear infinite;fill:#888}.c{animation-delay:-.65s}.d{animation-delay:-.5s}@keyframes b{93.75%,100%{r:3px}46.875%{r:.2px}}</style><circle class=\"a\" cx=\"4\" cy=\"12\" r=\"3\"/><circle class=\"a c\" cx=\"12\" cy=\"12\" r=\"3\"/><circle class=\"a d\" cx=\"20\" cy=\"12\" r=\"3\"/></svg>";
-export declare const getGeneratedImage: (endpoint: string, prompt: string, width: number, height: number) => Promise<string | undefined>;
+export declare const TRANSPARENT_PIXEL = "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAAC0lEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==";
+export interface ResolveImageRequest {
+    prompt?: string;
+    imageId?: string;
+    width?: number;
+    height?: number;
+    /** Provider/model hint forwarded to the endpoint (e.g. "gemini", "openai"). */
+    llm?: string;
+    /** Aspect ratio forwarded to the endpoint (e.g. "16:9", "4:1"). */
+    ratio?: string;
+}
+export interface ResolvedImage {
+    id: string;
+    url: string;
+}
+/**
+ * Sends a single POST to the endpoint and lets the server decide whether to
+ * return an already-stored image (looked up by `imageId`) or generate a new
+ * one. The component never branches on existence — it just trusts the result.
+ *
+ * Resolves to `{ id, url }` on success, or `null` when the endpoint is missing,
+ * the request fails, or the server reports the image could not be resolved
+ * (e.g. 404). A `null` tells the component to fall back.
+ */
+export declare const resolveImage: (endpoint: string, req: ResolveImageRequest) => Promise<ResolvedImage | null>;