@gyeonghokim/authenticated-image 0.0.0-stage → 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 GyeongHo Kim <me@gyeongho.dev>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,311 @@
-# Temporary Holding Version
+# authenticated-image
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> A drop-in `<img>` for images behind `Authorization` headers.
+
+[![npm](https://img.shields.io/npm/v/@gyeonghokim/authenticated-image)](https://www.npmjs.com/package/@gyeonghokim/authenticated-image)
+[![bundle size](https://img.shields.io/bundlejs/size/@gyeonghokim/authenticated-image)](https://bundlejs.com/?q=@gyeonghokim/authenticated-image)
+[![release](https://github.com/GyeongHoKim/authenticated-image/actions/workflows/release.yml/badge.svg)](https://github.com/GyeongHoKim/authenticated-image/actions/workflows/release.yml)
+[![license](https://img.shields.io/npm/l/@gyeonghokim/authenticated-image)](LICENSE)
+
+`<img src>` can't send an `Authorization` header. `<authenticated-image>` fetches the image with your token, displays it, and cleans up after itself. It is a Web Component, so it works in any framework, and it ships a React wrapper.
+
+## Before / After
+
+**Before:** fetch the image yourself and manage the object URL.
+
+```js
+const img = document.querySelector('img');
+
+fetch('/api/avatar', { headers: { Authorization: `Bearer ${token}` } })
+  .then((res) => {
+    if (!res.ok) throw new Error(res.statusText);
+    return res.blob();
+  })
+  .then((blob) => {
+    img.src = URL.createObjectURL(blob);
+  });
+
+// Still to do: abort when src changes, revoke the URL on unmount,
+// lazy-load, dedupe repeated images, show errors...
+```
+
+**After:** configure the token once and use the tag.
+
+```js
+import { configure } from '@gyeonghokim/authenticated-image';
+
+configure({
+  headers: () => ({ Authorization: `Bearer ${getToken()}` }),
+});
+```
+
+```html
+<authenticated-image src="/api/avatar" alt="Avatar"></authenticated-image>
+```
+
+## Install
+
+```sh
+npm install @gyeonghokim/authenticated-image
+# or
+pnpm add @gyeonghokim/authenticated-image
+```
+
+## Quick start
+
+```js
+// main.js: run once when your app starts
+import { configure } from '@gyeonghokim/authenticated-image';
+
+configure({
+  headers: async () => ({ Authorization: `Bearer ${await getToken()}` }),
+});
+```
+
+```html
+<authenticated-image src="/api/invoices/42/scan" alt="Invoice scan" loading="lazy" width="320" height="240">
+  <span slot="loading">Loading…</span>
+  <span slot="error">Could not load the image.</span>
+</authenticated-image>
+```
+
+Importing the package registers the `<authenticated-image>` tag.
+
+## Features
+
+- Sends your `Authorization` header, or loads through your own HTTP client (axios, ky, …).
+- Cancels stale requests when `src` changes and revokes object URLs when removed.
+- `loading="lazy"`, starting 200px before the element enters the viewport.
+- One request for an image shown many times on the page.
+- `loading` and `error` slots, plus a `status` attribute for styling.
+- Presigned URLs, refreshed once if they fail to load.
+- Works in any framework, with a React wrapper included.
+
+## Usage
+
+### React
+
+```tsx
+'use client';
+
+import { useRef } from 'react';
+import {
+  AuthenticatedImage,
+  type AuthenticatedImageElement,
+} from '@gyeonghokim/authenticated-image/react';
+
+export function Avatar({ userId }: { userId: string }) {
+  const ref = useRef<AuthenticatedImageElement>(null);
+
+  return (
+    <AuthenticatedImage
+      ref={ref}
+      src={`/api/users/${userId}/avatar`}
+      alt="Avatar"
+      loading="lazy"
+      onError={(event) => console.warn(event.detail.error.status)}
+    >
+      <span slot="loading">Loading…</span>
+      <button slot="error" type="button" onClick={() => ref.current?.reload()}>
+        Retry
+      </button>
+    </AuthenticatedImage>
+  );
+}
+```
+
+`configure` and `clearCache` are also exported from `@gyeonghokim/authenticated-image/react`. Works with React 18 and 19.
+
+With SSR, the server renders an empty `<authenticated-image>` tag, and the image loads in the browser after hydration.
+
+### Reuse your HTTP client
+
+Pass a `fetcher` to keep your interceptors, token refresh and retries.
+
+```ts
+import axios from 'axios';
+import { configure } from '@gyeonghokim/authenticated-image';
+
+const api = axios.create({ baseURL: '/api' }); // your client with auth interceptors
+
+configure({
+  fetcher: async (src, { signal }) => {
+    const response = await api.get<Blob>(src, { responseType: 'blob', signal });
+    return response.data;
+  },
+});
+```
+
+With [ky](https://github.com/sindresorhus/ky): `fetcher: (src, { signal }) => api.get(src, { signal }).blob()`.
+
+### Presigned URLs
+
+Return a string instead of a `Blob`, and it is used as `img.src` as-is.
+
+```ts
+configure({
+  fetcher: async (src, { signal }) => {
+    const response = await api.get<{ url: string }>(`${src}/presign`, { signal });
+    return response.data.url;
+  },
+});
+```
+
+If a presigned URL fails to load, for example because it expired, the element asks your `fetcher` for a new one once.
+
+### Loading and error states
+
+Use the `loading` and `error` slots, or style the `status` attribute (`idle`, `loading`, `loaded`, `error`).
+
+```css
+authenticated-image[status="error"] {
+  outline: 2px solid crimson;
+}
+```
+
+### Styling
+
+The inner `<img>` sizes itself like a normal `<img>`. To fill a fixed-size box:
+
+```css
+authenticated-image {
+  width: 64px;
+  height: 64px;
+  border-radius: 50%;
+  overflow: hidden;
+  --authenticated-image-object-fit: cover;
+}
+
+authenticated-image::part(img) {
+  width: 100%;
+  height: 100%;
+}
+```
+
+The host is an `inline-grid` that stacks the image and the slots in one cell. If you change its `display`, use `grid` or `inline-grid`.
+
+### Per-element settings
+
+Set `fetcher` or `headers` on one element to override the global configuration. These elements don't use the shared cache.
+
+```js
+document.querySelector('#public-preview').headers = {};
+```
+
+Changing `fetcher` or `headers` doesn't refetch, so passing a new inline object on every React render is fine. The new value takes effect on the next load, when `src` changes. Call `reload()` to apply it immediately.
+
+### Logging out
+
+```js
+import { clearCache } from '@gyeonghokim/authenticated-image';
+
+await logout();
+clearCache();
+```
+
+Images already on screen stay visible. New elements fetch again. Calling `configure()` also clears the cache.
+
+## API
+
+### Attributes
+
+| Name              | Type                          | Default   | Description                                                             |
+| ----------------- | ----------------------------- | --------- | ----------------------------------------------------------------------- |
+| `src`             | `string`                      | `''`      | Image URL. Changing it cancels the current request.                     |
+| `alt`             | `string`                      | `''`      | Alternative text for the inner `<img>`.                                 |
+| `loading`         | `'eager' \| 'lazy'`           | `'eager'` | `lazy` starts the request 200px before the element enters the viewport. |
+| `width`, `height` | `number`                      |           | Forwarded to the inner `<img>` to reserve space.                        |
+| `decoding`        | `'async' \| 'sync' \| 'auto'` | `'async'` | Forwarded to the inner `<img>`.                                         |
+
+### Properties
+
+| Name       | Type                                         | Description                                             |
+| ---------- | -------------------------------------------- | ------------------------------------------------------- |
+| `fetcher`  | `Fetcher`                                    | Loads this element's image. Bypasses the cache.         |
+| `headers`  | `HeadersProvider`                            | Headers for this element's request. Bypasses the cache. |
+| `status`   | `'idle' \| 'loading' \| 'loaded' \| 'error'` | Read-only. Mirrored to the `status` attribute.          |
+| `error`    | `AuthenticatedImageError \| undefined`       | Read-only. Why the last load failed.                    |
+| `reload()` | `() => void`                                 | Loads the image again, skipping the cached copy.        |
+
+### Events
+
+| Name    | Type                                              | When                               |
+| ------- | ------------------------------------------------- | ---------------------------------- |
+| `load`  | `Event`                                           | The image is decoded and rendered. |
+| `error` | `CustomEvent<{ error: AuthenticatedImageError }>` | The request or decoding failed.    |
+
+### Slots, parts and custom properties
+
+| Name                               | Kind            | Description                                        |
+| ---------------------------------- | --------------- | -------------------------------------------------- |
+| `loading`                          | slot            | Shown while loading or waiting to lazy-load.       |
+| `error`                            | slot            | Shown after a failure.                             |
+| `img`                              | part            | The inner `<img>`.                                 |
+| `--authenticated-image-object-fit` | custom property | `object-fit` of the inner `<img>`. Default `fill`. |
+
+### Functions
+
+| Name                | Description                                             |
+| ------------------- | ------------------------------------------------------- |
+| `configure(config)` | Replaces the global configuration and clears the cache. |
+| `clearCache()`      | Clears the shared cache.                                |
+
+```ts
+type Fetcher = (src: string, context: { signal: AbortSignal }) => Promise<Blob | string>;
+type HeadersProvider = HeadersInit | (() => HeadersInit | Promise<HeadersInit>);
+
+interface AuthenticatedImageConfig {
+  fetcher?: Fetcher; // takes precedence over headers
+  headers?: HeadersProvider;
+  cache?: { retainMs?: number }; // default 30000
+}
+
+class AuthenticatedImageError extends Error {
+  readonly src: string;
+  readonly status?: number; // HTTP status from the default fetch
+  // `cause` holds the original error
+}
+```
+
+Also exported: `AuthenticatedImageElement`, `AuthenticatedImageStatus`, `AuthenticatedImageErrorEvent` and `AuthenticatedImageErrorOptions`.
+
+Precedence: element `fetcher` › element `headers` › global `fetcher` › global `headers`.
+
+## Security
+
+`configure({ headers })` sends your token to every `src`, including other origins. If `src` can come from untrusted input, use a `fetcher` that checks the origin:
+
+```ts
+configure({
+  fetcher: async (src, { signal }) => {
+    const url = new URL(src, location.href);
+    if (url.origin !== location.origin) {
+      throw new Error(`Refusing to send the token to ${url.origin}`);
+    }
+    const response = await fetch(url, {
+      headers: { Authorization: `Bearer ${await getToken()}` },
+      signal,
+    });
+    if (!response.ok) throw new Error(`Request failed with status ${response.status}`);
+    return response.blob();
+  },
+});
+```
+
+A cross-origin API must allow the header through CORS: `Access-Control-Allow-Headers: Authorization`.
+
+## Caching
+
+Elements that use the global configuration share an in-memory cache keyed by `src`. An image stays in memory for `retainMs` (30 seconds by default) after the last element using it disconnects, so scrolling back or switching routes is instant. Nothing is written to disk. For caching across page loads, send `Cache-Control: private, max-age=…` from your server, and the browser HTTP cache handles it.
+
+## Browser support
+
+Chrome, Edge, Firefox and Safari released in the last two years. CI tests Chromium, Firefox and WebKit.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+[MIT](LICENSE) © GyeongHo Kim

package/dist/index-Cc9WrVMP.d.mts

@@ -0,0 +1,117 @@
+import { LitElement, PropertyValues, TemplateResult } from "lit";
+/**
+ * Loads an image. Resolve to a `Blob` to display it through an object URL, or to a string
+ * (such as a presigned URL) to use it as `img.src` directly.
+ */
+type Fetcher = (src: string, context: {
+  signal: AbortSignal;
+}) => Promise<Blob | string>;
+/** Headers for the default fetch, or a function that returns them. */
+type HeadersProvider = HeadersInit | (() => HeadersInit | Promise<HeadersInit>);
+/** Global configuration for every `<authenticated-image>`. */
+interface AuthenticatedImageConfig {
+  /** Loads images. Takes precedence over `headers`. */
+  fetcher?: Fetcher;
+  /** Headers sent with the default `fetch`. */
+  headers?: HeadersProvider;
+  cache?: {
+    /**
+     * How long an unused image stays in memory, in milliseconds. `0` releases it immediately,
+     * and `Infinity` keeps it until the cache is cleared.
+     * @defaultValue 30000
+     */
+    retainMs?: number;
+  };
+}
+/**
+ * Replaces the global configuration and clears the cache.
+ *
+ * @example
+ * ```ts
+ * configure({
+ *   headers: async () => ({ Authorization: `Bearer ${await getToken()}` }),
+ * });
+ * ```
+ */
+declare function configure(config: AuthenticatedImageConfig): void;
+/**
+ * Clears the shared cache, for example on logout. Images on screen stay visible; new
+ * elements fetch again.
+ */
+declare function clearCache(): void;
+/** Options for {@link AuthenticatedImageError}. */
+interface AuthenticatedImageErrorOptions {
+  /** The `src` that failed to load. */
+  src: string;
+  /** HTTP status code, when the default fetch received a non-2xx response. */
+  status?: number;
+  /** The original error thrown by `fetch`, a fetcher or a headers function. */
+  cause?: unknown;
+}
+/** Describes why an `<authenticated-image>` failed to load. */
+declare class AuthenticatedImageError extends Error {
+  readonly name = "AuthenticatedImageError";
+  /** The `src` that failed to load. */
+  readonly src: string;
+  /** HTTP status code, when the default fetch received a non-2xx response. */
+  readonly status?: number;
+  constructor(message: string, options: AuthenticatedImageErrorOptions);
+}
+/** Loading state of an `<authenticated-image>`. */
+type AuthenticatedImageStatus = 'idle' | 'loading' | 'loaded' | 'error';
+/** The `error` event of `<authenticated-image>`. */
+type AuthenticatedImageErrorEvent = CustomEvent<{
+  error: AuthenticatedImageError;
+}>;
+/**
+ * An `<img>` that loads its image with `fetch`, so the request can carry an `Authorization`
+ * header.
+ *
+ * @fires load - The image has been decoded and rendered.
+ * @fires error - Loading or decoding failed. `event.detail.error` describes why.
+ * @slot loading - Shown while the image is loading or waiting to be lazily loaded.
+ * @slot error - Shown when the image failed to load.
+ * @csspart img - The inner `<img>`.
+ * @cssprop --authenticated-image-object-fit - `object-fit` of the inner image. Defaults to `fill`.
+ */
+declare class AuthenticatedImageElement extends LitElement {
+  static styles: import("lit").CSSResult;
+  /** URL of the image. Changing it cancels the current request. */
+  src: string;
+  /** Alternative text, forwarded to the inner `<img>`. */
+  alt: string;
+  /** `lazy` waits until the element is within 200px of the viewport before requesting. */
+  loading: 'eager' | 'lazy';
+  /** Forwarded to the inner `<img>`. */
+  decoding: 'async' | 'sync' | 'auto';
+  /** Width in pixels, forwarded to the inner `<img>`. */
+  width?: number;
+  /** Height in pixels, forwarded to the inner `<img>`. */
+  height?: number;
+  /**
+   * Loads this element's image instead of the global configuration. Disables caching. A new
+   * value applies on the next load; call `reload()` to apply it right away.
+   */
+  fetcher?: Fetcher;
+  /**
+   * Headers for this element's request instead of the global configuration. Disables caching.
+   * A new value applies on the next load; call `reload()` to apply it right away.
+   */
+  headers?: HeadersProvider;
+  private readonly _loader;
+  /** Current loading state. Mirrored to the `status` attribute. */
+  get status(): AuthenticatedImageStatus;
+  /** Why the last load failed, or `undefined`. */
+  get error(): AuthenticatedImageError | undefined;
+  /** Loads the image again. Elements that use the shared cache skip the cached copy. */
+  reload(): void;
+  protected willUpdate(changed: PropertyValues<this>): void;
+  protected updated(): void;
+  protected render(): TemplateResult;
+}
+declare global {
+  interface HTMLElementTagNameMap {
+    'authenticated-image': AuthenticatedImageElement;
+  }
+}
+export { AuthenticatedImageErrorOptions as a, HeadersProvider as c, AuthenticatedImageError as i, clearCache as l, AuthenticatedImageErrorEvent as n, AuthenticatedImageConfig as o, AuthenticatedImageStatus as r, Fetcher as s, AuthenticatedImageElement as t, configure as u };

package/dist/index.d.mts

@@ -0,0 +1,2 @@
+import { a as AuthenticatedImageErrorOptions, c as HeadersProvider, i as AuthenticatedImageError, l as clearCache, n as AuthenticatedImageErrorEvent, o as AuthenticatedImageConfig, r as AuthenticatedImageStatus, s as Fetcher, t as AuthenticatedImageElement, u as configure } from "./index-Cc9WrVMP.mjs";
+export { type AuthenticatedImageConfig, AuthenticatedImageElement, AuthenticatedImageError, type AuthenticatedImageErrorEvent, type AuthenticatedImageErrorOptions, type AuthenticatedImageStatus, type Fetcher, type HeadersProvider, clearCache, configure };

package/dist/index.mjs

@@ -0,0 +1 @@
+export { t as AuthenticatedImageElement, i as AuthenticatedImageError, n as clearCache, r as configure } from "./src-BMw-CcQI.mjs";

package/dist/react.d.mts

@@ -0,0 +1,16 @@
+import { a as AuthenticatedImageErrorOptions, c as HeadersProvider, i as AuthenticatedImageError, l as clearCache, n as AuthenticatedImageErrorEvent, o as AuthenticatedImageConfig, r as AuthenticatedImageStatus, s as Fetcher, t as AuthenticatedImageElement, u as configure } from "./index-Cc9WrVMP.mjs";
+import { EventName } from "@lit/react";
+/**
+ * React component for `<authenticated-image>`. Props map to the element's properties, and
+ * `onLoad` / `onError` map to its events. `ref` points to the {@link AuthenticatedImageElement}.
+ *
+ * @example
+ * ```tsx
+ * <AuthenticatedImage src="/api/avatar" alt="Avatar" onError={(e) => console.warn(e.detail.error)} />
+ * ```
+ */
+export declare const AuthenticatedImage: import("@lit/react").ReactWebComponent<AuthenticatedImageElement, {
+  onLoad: EventName<Event>;
+  onError: EventName<AuthenticatedImageErrorEvent>;
+}>;
+export { type AuthenticatedImageConfig, type AuthenticatedImageElement, AuthenticatedImageError, type AuthenticatedImageErrorEvent, type AuthenticatedImageErrorOptions, type AuthenticatedImageStatus, type Fetcher, type HeadersProvider, clearCache, configure };

package/dist/react.mjs

@@ -0,0 +1,25 @@
+"use client";
+import { i as AuthenticatedImageError, n as clearCache, r as configure, t as AuthenticatedImageElement } from "./src-BMw-CcQI.mjs";
+import { createComponent } from "@lit/react";
+import * as React from "react";
+// src/react.ts
+/**
+* React component for `<authenticated-image>`. Props map to the element's properties, and
+* `onLoad` / `onError` map to its events. `ref` points to the {@link AuthenticatedImageElement}.
+*
+* @example
+* ```tsx
+* <AuthenticatedImage src="/api/avatar" alt="Avatar" onError={(e) => console.warn(e.detail.error)} />
+* ```
+*/
+const AuthenticatedImage = createComponent({
+	tagName: "authenticated-image",
+	elementClass: AuthenticatedImageElement,
+	react: React,
+	events: {
+		onLoad: "load",
+		onError: "error"
+	},
+	displayName: "AuthenticatedImage"
+});
+export { AuthenticatedImage, AuthenticatedImageError, clearCache, configure };

package/dist/src-BMw-CcQI.mjs

@@ -0,0 +1,579 @@
+import { LitElement, css, html, nothing } from "lit";
+import { property } from "lit/decorators.js";
+// src/authenticated-image.styles.ts
+/** Styles of `<authenticated-image>`. */
+const styles = css`
+  :host {
+    display: inline-grid;
+    /* Lets ::part(img) { height: 100% } resolve against a sized host. */
+    grid-template: minmax(0, 1fr) / minmax(0, 1fr);
+  }
+
+  img,
+  slot {
+    grid-area: 1 / 1;
+  }
+
+  img {
+    display: block;
+    max-width: 100%;
+    height: auto;
+    object-fit: var(--authenticated-image-object-fit, fill);
+  }
+
+  /* Keep the box so width and height reserve space before the image loads. */
+  img[hidden] {
+    visibility: hidden;
+  }
+
+  slot {
+    display: block;
+  }
+
+  slot[hidden] {
+    display: none;
+  }
+`;
+// src/errors.ts
+/** Describes why an `<authenticated-image>` failed to load. */
+var AuthenticatedImageError = class extends Error {
+	constructor(message, options) {
+		super(message, { cause: options.cause });
+		this.name = "AuthenticatedImageError";
+		this.src = options.src;
+		if (options.status !== void 0) this.status = options.status;
+	}
+};
+/** Wraps any thrown value in an {@link AuthenticatedImageError}. */
+function toAuthenticatedImageError(src, error) {
+	if (error instanceof AuthenticatedImageError) return error;
+	return new AuthenticatedImageError(`Failed to load image: ${src}`, {
+		src,
+		cause: error
+	});
+}
+// src/image-cache.ts
+/** Converts a loader result into a displayable URL. */
+function toImageUrl(result) {
+	if (typeof result === "string") return {
+		url: result,
+		isObjectUrl: false
+	};
+	if (result instanceof Blob) return {
+		url: URL.createObjectURL(result),
+		isObjectUrl: true
+	};
+	throw new TypeError("Expected the image loader to resolve to a Blob or a string.");
+}
+/** Revokes the object URL of an image. Strings are left untouched. */
+function revokeImageUrl(image) {
+	if (image.isObjectUrl) URL.revokeObjectURL(image.url);
+}
+/** The largest delay `setTimeout` accepts. */
+const MAX_TIMEOUT_MS = 2147483647;
+/** Maps `retainMs` to a timer delay. `Infinity` means the entry never expires. */
+function normalizeRetainMs(retainMs) {
+	if (Number.isNaN(retainMs) || retainMs <= 0) return 0;
+	if (retainMs > MAX_TIMEOUT_MS) return Number.POSITIVE_INFINITY;
+	return retainMs;
+}
+/**
+* In-memory image cache keyed by `src`. Concurrent requests for the same key share one load,
+* and an entry is revoked `retainMs` after its last lease is released. A `retainMs` that is not
+* finite or exceeds the `setTimeout` limit keeps entries until they are detached; `NaN` and
+* negative values mean `0`.
+*/
+var ImageCache = class {
+	#entries = /* @__PURE__ */ new Map();
+	#retainMs;
+	constructor(retainMs) {
+		this.#retainMs = normalizeRetainMs(retainMs);
+	}
+	/** Number of entries that new leases can still join. */
+	get size() {
+		return this.#entries.size;
+	}
+	setRetainMs(retainMs) {
+		this.#retainMs = normalizeRetainMs(retainMs);
+	}
+	acquire(key, loader) {
+		let entry = this.#entries.get(key);
+		if (!entry) {
+			entry = this.#create(key, loader);
+			this.#entries.set(key, entry);
+		}
+		if (entry.timer !== void 0) {
+			clearTimeout(entry.timer);
+			entry.timer = void 0;
+		}
+		entry.refCount++;
+		const acquired = entry;
+		let released = false;
+		return {
+			image: acquired.image,
+			release: () => {
+				if (released) return;
+				released = true;
+				this.#release(acquired);
+			},
+			detach: () => {
+				if (!acquired.detached) this.#detach(acquired);
+			}
+		};
+	}
+	/** Stops sharing every entry. */
+	detachAll() {
+		for (const entry of [...this.#entries.values()]) this.#detach(entry);
+	}
+	#create(key, loader) {
+		const controller = new AbortController();
+		let entry;
+		const image = (async () => {
+			try {
+				const loaded = toImageUrl(await Promise.resolve().then(() => loader(controller.signal)));
+				entry.settled = true;
+				if (controller.signal.aborted) {
+					revokeImageUrl(loaded);
+					throw new DOMException("The image request was aborted.", "AbortError");
+				}
+				entry.loaded = loaded;
+				return loaded;
+			} catch (error) {
+				entry.settled = true;
+				this.#detach(entry);
+				throw error;
+			}
+		})();
+		image.catch(() => {});
+		entry = {
+			key,
+			controller,
+			image,
+			refCount: 0,
+			settled: false,
+			detached: false
+		};
+		return entry;
+	}
+	#release(entry) {
+		entry.refCount--;
+		if (entry.refCount > 0) return;
+		if (!entry.settled) {
+			entry.controller.abort();
+			this.#detach(entry);
+			return;
+		}
+		if (entry.detached || this.#retainMs === 0) {
+			this.#dispose(entry);
+			return;
+		}
+		if (this.#retainMs === Number.POSITIVE_INFINITY) return;
+		entry.timer = setTimeout(() => {
+			entry.timer = void 0;
+			this.#dispose(entry);
+		}, this.#retainMs);
+	}
+	#detach(entry) {
+		entry.detached = true;
+		if (this.#entries.get(entry.key) === entry) this.#entries.delete(entry.key);
+		if (entry.refCount === 0) this.#dispose(entry);
+	}
+	#dispose(entry) {
+		if (entry.timer !== void 0) {
+			clearTimeout(entry.timer);
+			entry.timer = void 0;
+		}
+		if (this.#entries.get(entry.key) === entry) this.#entries.delete(entry.key);
+		if (entry.loaded) {
+			revokeImageUrl(entry.loaded);
+			entry.loaded = void 0;
+		}
+	}
+};
+/** The cache shared by elements that use the global configuration. */
+const imageCache = new ImageCache(3e4);
+let globalConfig = {};
+/**
+* Replaces the global configuration and clears the cache.
+*
+* @example
+* ```ts
+* configure({
+*   headers: async () => ({ Authorization: `Bearer ${await getToken()}` }),
+* });
+* ```
+*/
+function configure(config) {
+	globalConfig = { ...config };
+	imageCache.setRetainMs(config.cache?.retainMs ?? 3e4);
+	imageCache.detachAll();
+}
+/**
+* Clears the shared cache, for example on logout. Images on screen stay visible; new
+* elements fetch again.
+*/
+function clearCache() {
+	imageCache.detachAll();
+}
+/** Fetches `src` with the given headers and resolves to the response body. */
+async function defaultFetch(src, headers, signal) {
+	const init = typeof headers === "function" ? await headers() : headers;
+	const response = await fetch(src, {
+		headers: init,
+		signal,
+		credentials: "same-origin"
+	});
+	if (!response.ok) throw new AuthenticatedImageError(`Request failed with status ${response.status}: ${src}`, {
+		src,
+		status: response.status
+	});
+	return response.blob();
+}
+function fromFetcher(fetcher) {
+	return (src, signal) => fetcher(src, { signal });
+}
+function fromHeaders(headers) {
+	return (src, signal) => defaultFetch(src, headers, signal);
+}
+/**
+* Picks the loader for an element. Precedence: element `fetcher`, element `headers`, global
+* `fetcher`, global `headers`, then a plain fetch.
+*/
+function resolveLoader(overrides) {
+	if (overrides.fetcher) return {
+		load: fromFetcher(overrides.fetcher),
+		cacheable: false
+	};
+	if (overrides.headers !== void 0) return {
+		load: fromHeaders(overrides.headers),
+		cacheable: false
+	};
+	if (globalConfig.fetcher) return {
+		load: fromFetcher(globalConfig.fetcher),
+		cacheable: true
+	};
+	return {
+		load: fromHeaders(globalConfig.headers),
+		cacheable: true
+	};
+}
+// src/lazy.ts
+/** How far outside the viewport a lazy image starts loading. */
+const LAZY_ROOT_MARGIN = "200px";
+const callbacks = /* @__PURE__ */ new WeakMap();
+let observer;
+function getObserver() {
+	observer ??= new IntersectionObserver((entries) => {
+		for (const entry of entries) {
+			if (!entry.isIntersecting) continue;
+			const onNear = callbacks.get(entry.target);
+			if (!onNear) continue;
+			unobserveLazy(entry.target);
+			onNear();
+		}
+	}, { rootMargin: LAZY_ROOT_MARGIN });
+	return observer;
+}
+/** Calls `onNear` once when `element` comes within {@link LAZY_ROOT_MARGIN} of the viewport. */
+function observeLazy(element, onNear) {
+	callbacks.set(element, onNear);
+	getObserver().observe(element);
+}
+/** Cancels a pending {@link observeLazy} callback. */
+function unobserveLazy(element) {
+	callbacks.delete(element);
+	observer?.unobserve(element);
+}
+// src/lazy-controller.ts
+/**
+* Runs a callback once the host comes near the viewport, and cancels it when the host
+* disconnects.
+*/
+var LazyController = class {
+	#host;
+	#waiting = false;
+	constructor(host) {
+		this.#host = host;
+		host.addController(this);
+	}
+	/** Whether a callback is waiting for the host to come near the viewport. */
+	get waiting() {
+		return this.#waiting;
+	}
+	/** Calls `callback` once the host comes near the viewport. Replaces a pending callback. */
+	whenVisible(callback) {
+		this.#waiting = true;
+		observeLazy(this.#host, () => {
+			this.#waiting = false;
+			this.#host.requestUpdate();
+			callback();
+		});
+		this.#host.requestUpdate();
+	}
+	/** Cancels a pending callback. */
+	cancel() {
+		if (!this.#waiting) return;
+		this.#waiting = false;
+		unobserveLazy(this.#host);
+		this.#host.requestUpdate();
+	}
+	hostDisconnected() {
+		this.cancel();
+	}
+};
+// src/image-loader-controller.ts
+/**
+* Loads an image for its host and owns everything the load holds: the request, the cache lease
+* and the object URL. Starting a new load or disconnecting the host releases them, and results
+* that arrive after that are dropped.
+*/
+var ImageLoaderController = class {
+	#host;
+	#options;
+	#lazy;
+	#src;
+	#lazyLoad;
+	#status;
+	#url;
+	#error;
+	#generation;
+	#needsStart;
+	#retried;
+	#controller;
+	#lease;
+	#ownedImage;
+	#image;
+	constructor(host, options) {
+		this.#src = "";
+		this.#lazyLoad = false;
+		this.#status = "idle";
+		this.#generation = 0;
+		this.#needsStart = true;
+		this.#retried = false;
+		this.handleImageLoad = () => {
+			if (!this.#image) return;
+			this.#status = "loaded";
+			this.#host.requestUpdate();
+			this.#options.onLoad();
+		};
+		this.handleImageError = () => {
+			if (!this.#image) return;
+			const src = this.#src;
+			this.#lease?.detach();
+			if (!this.#image.isObjectUrl && !this.#retried) {
+				this.#retried = true;
+				const generation = this.#generation;
+				this.#releaseResources();
+				this.#host.requestUpdate();
+				this.#host.updateComplete.then(() => this.#load(generation));
+				return;
+			}
+			this.#fail(new AuthenticatedImageError(`Failed to decode image: ${src}`, { src }));
+		};
+		this.#host = host;
+		this.#options = options;
+		this.#lazy = new LazyController(host);
+		host.addController(this);
+	}
+	get status() {
+		return this.#status;
+	}
+	/** URL for the inner `<img>`, set once the loader resolves. */
+	get url() {
+		return this.#url;
+	}
+	/** Why the last load failed, or `undefined`. */
+	get error() {
+		return this.#error;
+	}
+	/** Whether the image is loading or waiting to be lazily loaded. */
+	get busy() {
+		return this.#status === "loading" || this.#lazy.waiting;
+	}
+	/**
+	* Loads `src` on the host's next update and cancels the current load. With `lazy`, the request
+	* waits until the host comes near the viewport.
+	*/
+	load(src, { lazy = false } = {}) {
+		this.#src = src;
+		this.#lazyLoad = lazy;
+		this.#needsStart = true;
+		this.#host.requestUpdate();
+	}
+	/** Loads the image again. A shared cached copy is skipped. */
+	reload() {
+		this.#lease?.detach();
+		if (!this.#host.isConnected) {
+			this.#needsStart = true;
+			return;
+		}
+		this.#start();
+	}
+	hostConnected() {
+		this.#needsStart = true;
+		this.#host.requestUpdate();
+	}
+	hostUpdate() {
+		if (this.#needsStart && this.#host.isConnected) {
+			this.#needsStart = false;
+			this.#start();
+		}
+	}
+	hostDisconnected() {
+		this.#cleanup();
+		this.#status = "idle";
+		this.#host.requestUpdate();
+	}
+	#start() {
+		this.#cleanup();
+		this.#error = void 0;
+		this.#retried = false;
+		this.#status = "idle";
+		this.#host.requestUpdate();
+		if (!this.#src) return;
+		const generation = this.#generation;
+		if (this.#lazyLoad) {
+			this.#lazy.whenVisible(() => void this.#load(generation));
+			return;
+		}
+		this.#load(generation);
+	}
+	async #load(generation) {
+		if (generation !== this.#generation) return;
+		const src = this.#src;
+		const loader = resolveLoader(this.#options.overrides());
+		this.#status = "loading";
+		this.#host.requestUpdate();
+		let image;
+		try {
+			if (loader.cacheable) {
+				const lease = imageCache.acquire(src, (signal) => loader.load(src, signal));
+				this.#lease = lease;
+				image = await lease.image;
+			} else {
+				const controller = new AbortController();
+				this.#controller = controller;
+				image = toImageUrl(await loader.load(src, controller.signal));
+				if (generation !== this.#generation) {
+					revokeImageUrl(image);
+					return;
+				}
+				this.#ownedImage = image;
+			}
+		} catch (error) {
+			if (generation === this.#generation) this.#fail(toAuthenticatedImageError(src, error));
+			return;
+		}
+		if (generation !== this.#generation) return;
+		this.#image = image;
+		this.#url = image.url;
+		this.#host.requestUpdate();
+	}
+	#fail(error) {
+		this.#releaseResources();
+		this.#error = error;
+		this.#status = "error";
+		this.#host.requestUpdate();
+		this.#options.onError(error);
+	}
+	#releaseResources() {
+		this.#controller?.abort();
+		this.#controller = void 0;
+		this.#lease?.release();
+		this.#lease = void 0;
+		if (this.#ownedImage) {
+			revokeImageUrl(this.#ownedImage);
+			this.#ownedImage = void 0;
+		}
+		this.#image = void 0;
+		this.#url = void 0;
+	}
+	#cleanup() {
+		this.#generation++;
+		this.#lazy.cancel();
+		this.#releaseResources();
+	}
+};
+// \0@oxc-project+runtime@0.155.0/helpers/esm/decorate.js
+function __decorate(decorators, target, key, desc) {
+	var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+	if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+	else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+	return c > 3 && r && Object.defineProperty(target, key, r), r;
+}
+// src/authenticated-image.ts
+const RELOAD_TRIGGERS = ["src", "loading"];
+/**
+* An `<img>` that loads its image with `fetch`, so the request can carry an `Authorization`
+* header.
+*
+* @fires load - The image has been decoded and rendered.
+* @fires error - Loading or decoding failed. `event.detail.error` describes why.
+* @slot loading - Shown while the image is loading or waiting to be lazily loaded.
+* @slot error - Shown when the image failed to load.
+* @csspart img - The inner `<img>`.
+* @cssprop --authenticated-image-object-fit - `object-fit` of the inner image. Defaults to `fill`.
+*/
+var AuthenticatedImageElement = class extends LitElement {
+	constructor(..._args) {
+		super(..._args);
+		this.src = "";
+		this.alt = "";
+		this.loading = "eager";
+		this.decoding = "async";
+		this._loader = new ImageLoaderController(this, {
+			overrides: () => this,
+			onLoad: () => this.dispatchEvent(new Event("load")),
+			onError: (error) => this.dispatchEvent(new CustomEvent("error", { detail: { error } }))
+		});
+	}
+	static {
+		this.styles = styles;
+	}
+	/** Current loading state. Mirrored to the `status` attribute. */
+	get status() {
+		return this._loader.status;
+	}
+	/** Why the last load failed, or `undefined`. */
+	get error() {
+		return this._loader.error;
+	}
+	/** Loads the image again. Elements that use the shared cache skip the cached copy. */
+	reload() {
+		this._loader.reload();
+	}
+	willUpdate(changed) {
+		if (RELOAD_TRIGGERS.some((key) => changed.has(key))) this._loader.load(this.src, { lazy: this.loading === "lazy" });
+	}
+	updated() {
+		this.setAttribute("status", this._loader.status);
+		if (this._loader.busy) this.setAttribute("aria-busy", "true");
+		else this.removeAttribute("aria-busy");
+	}
+	render() {
+		const loaded = this._loader.status === "loaded";
+		return html`<img
+        part="img"
+        ?hidden=${!loaded}
+        src=${this._loader.url ?? nothing}
+        alt=${loaded ? this.alt : ""}
+        decoding=${this.decoding}
+        width=${this.width ?? nothing}
+        height=${this.height ?? nothing}
+        @load=${this._loader.handleImageLoad}
+        @error=${this._loader.handleImageError}
+      /><slot name="loading" ?hidden=${!this._loader.busy}></slot
+      ><slot name="error" ?hidden=${this._loader.status !== "error"}></slot>`;
+	}
+};
+__decorate([property()], AuthenticatedImageElement.prototype, "src", void 0);
+__decorate([property()], AuthenticatedImageElement.prototype, "alt", void 0);
+__decorate([property()], AuthenticatedImageElement.prototype, "loading", void 0);
+__decorate([property()], AuthenticatedImageElement.prototype, "decoding", void 0);
+__decorate([property({ type: Number })], AuthenticatedImageElement.prototype, "width", void 0);
+__decorate([property({ type: Number })], AuthenticatedImageElement.prototype, "height", void 0);
+__decorate([property({ attribute: false })], AuthenticatedImageElement.prototype, "fetcher", void 0);
+__decorate([property({ attribute: false })], AuthenticatedImageElement.prototype, "headers", void 0);
+// src/index.ts
+if (!customElements.get("authenticated-image")) customElements.define("authenticated-image", AuthenticatedImageElement);
+export { AuthenticatedImageError as i, clearCache as n, configure as r, AuthenticatedImageElement as t };

package/package.json

@@ -1,6 +1,95 @@
 {
   "name": "@gyeonghokim/authenticated-image",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.1",
+  "description": "A drop-in <img> for images behind Authorization headers. Web Component + React.",
+  "keywords": [
+    "web-component",
+    "custom-element",
+    "lit",
+    "image",
+    "img",
+    "authorization",
+    "bearer",
+    "jwt",
+    "blob",
+    "object-url",
+    "react",
+    "presigned-url"
+  ],
+  "homepage": "https://github.com/GyeongHoKim/authenticated-image#readme",
+  "bugs": "https://github.com/GyeongHoKim/authenticated-image/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/GyeongHoKim/authenticated-image.git"
+  },
+  "license": "MIT",
+  "author": "GyeongHo Kim <me@gyeongho.dev>",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "default": "./dist/index.mjs"
+    },
+    "./react": {
+      "types": "./dist/react.d.mts",
+      "default": "./dist/react.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": [
+    "./dist/*.mjs"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "packageManager": "pnpm@12.14.0",
+  "scripts": {
+    "dev": "vite",
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit",
+    "typecheck:dist": "tsc -p tsconfig.dist-check.json",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "check": "biome check",
+    "format": "biome check --write",
+    "lint:package": "publint --strict",
+    "prepare": "husky"
+  },
+  "peerDependencies": {
+    "react": "^18 || ^19"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.6.4",
+    "@commitlint/cli": "^21.2.4",
+    "@commitlint/config-conventional": "^21.2.4",
+    "@semantic-release/changelog": "^7.0.0",
+    "@semantic-release/git": "^11.0.1",
+    "@types/node": "^26.6.6",
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
+    "@vitest/browser-playwright": "^5.0.5",
+    "conventional-changelog-conventionalcommits": "^9.3.1",
+    "husky": "^9.1.7",
+    "playwright": "^1.64.1",
+    "publint": "^0.3.25",
+    "react": "^19.3.1",
+    "react-dom": "^19.3.1",
+    "semantic-release": "^25.0.9",
+    "tsdown": "~0.23.3",
+    "typescript": "^7.0.2",
+    "vite": "^8.3.5",
+    "vitest": "^5.0.5"
+  },
+  "dependencies": {
+    "@lit/react": "^1.0.8",
+    "lit": "^3.3.3"
+  }
+}