@c9up/nebula 0.1.5 → 0.1.7

package/dist/adapters/tailwind.d.ts

@@ -14,6 +14,13 @@
  *   a v4 setup produces an unstyled page.
  * - `@custom-variant dark` makes `dark:` respond to a `.dark` class rather
  *   than the system preference, so a theme toggle can override the OS.
+ * - `tw-animate-css` supplies `animate-in` / `animate-out` and the `fade-*`,
+ *   `zoom-*` and `slide-*` modifiers — where shadcn gets them too. Imported
+ *   rather than reimplemented, so the components use its class strings
+ *   verbatim. nebula previously declared four keyframes of its own and reached
+ *   them through arbitrary animation values, which Tailwind compiles whether or
+ *   not the keyframes exist: an app that skipped the stylesheet got overlays
+ *   that never finished CLOSING rather than overlays that never animated.
  * - `@theme inline` maps nebula's plain custom properties onto Tailwind's
  *   colour namespace, which is what turns `--primary` into a `bg-primary`
  *   utility.

package/dist/adapters/tailwind.js

@@ -14,6 +14,13 @@
  *   a v4 setup produces an unstyled page.
  * - `@custom-variant dark` makes `dark:` respond to a `.dark` class rather
  *   than the system preference, so a theme toggle can override the OS.
+ * - `tw-animate-css` supplies `animate-in` / `animate-out` and the `fade-*`,
+ *   `zoom-*` and `slide-*` modifiers — where shadcn gets them too. Imported
+ *   rather than reimplemented, so the components use its class strings
+ *   verbatim. nebula previously declared four keyframes of its own and reached
+ *   them through arbitrary animation values, which Tailwind compiles whether or
+ *   not the keyframes exist: an app that skipped the stylesheet got overlays
+ *   that never finished CLOSING rather than overlays that never animated.
  * - `@theme inline` maps nebula's plain custom properties onto Tailwind's
  *   colour namespace, which is what turns `--primary` into a `bg-primary`
  *   utility.
@@ -123,7 +130,10 @@ function relativeFromCss(config) {
 export const tailwindAdapter = {
     name: "tailwind",
     summary: "Tailwind CSS v4, configured in CSS. What shadcn/ui itself targets.",
-    packages: ["tailwindcss", "@tailwindcss/cli"],
+    // `tw-animate-css` is where the overlay animations come from — the same
+    // package shadcn tells you to install, and the reason the components can use
+    // its class strings verbatim.
+    packages: ["tailwindcss", "@tailwindcss/cli", "tw-animate-css"],
     files(config) {
         return [
             {

package/dist/adapters/unocss.js

@@ -16,6 +16,7 @@
 const CONFIG_PATH = "uno.config.ts";
 function unoConfig(config) {
     return `import { defineConfig, presetWind4 } from 'unocss'
+import presetAnimations from 'unocss-preset-animations'
 import { readFileSync } from 'node:fs'
 import { createRequire } from 'node:module'
 
@@ -40,7 +41,15 @@ const tokens = readFileSync(require.resolve('@c9up/nebula/theme.css'), 'utf8')
 const color = (name: string) => \`var(--\${name})\`
 
 export default defineConfig({
-  presets: [presetWind4()],
+  /*
+   * \`presetAnimations\` is the UnoCSS port of the same utilities shadcn uses
+   * through \`tw-animate-css\`: \`animate-in\` / \`animate-out\` and the
+   * \`fade-*\` / \`zoom-*\` / \`slide-*\` modifiers. nebula's components emit
+   * shadcn's class strings verbatim, so the utilities have to exist under every
+   * engine — and registering them is what makes a missing setup produce no
+   * animation rather than an overlay that never finishes closing.
+   */
+  presets: [presetWind4(), presetAnimations()],
   content: {
     filesystem: ['${config.paths.components}/**/*.{ts,js}'],
   },
@@ -110,7 +119,7 @@ body {
 export const unocssAdapter = {
     name: "unocss",
     summary: "UnoCSS with presetWind4 — same class syntax, no PostCSS, faster builds.",
-    packages: ["unocss", "@unocss/cli"],
+    packages: ["unocss", "@unocss/cli", "unocss-preset-animations"],
     files(config) {
         return [
             { path: CONFIG_PATH, contents: unoConfig(config), skipIfExists: true },

package/dist/atoms/Image.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Image — one `<img>`, with the attributes that make it fast already filled in.
+ *
+ * A bare `<img src>` costs a page twice: it ships desktop pixels to a phone,
+ * and it reserves no space until it arrives, so everything under it jumps.
+ * Both are solved by attributes nobody writes by hand — a `srcset` of a dozen
+ * widths, a matching `sizes`, `width`/`height` for the ratio, `loading` and
+ * `decoding`. This component writes them.
+ *
+ * The bytes come from whatever {@link setImageResolver} is pointed at; the
+ * component only decides which variants to ask for. See `lib/image.ts` for
+ * why the split is there and what the resolver is allowed to be asked.
+ *
+ * ```ts
+ * Image({ src: "/photos/hero.jpg", alt: "…", width: 1200, height: 800 })
+ * Image({ src: "/logo.png", alt: "…", width: 48, height: 48, layout: "fixed" })
+ * Image({ src: "/banner.jpg", alt: "…", layout: "full-width", priority: true })
+ * ```
+ *
+ * `alt` is required, and not as a gesture: the attribute is what a screen
+ * reader announces, and an `<img>` without one is read out as its file name.
+ * Decorative images pass `alt: ""`, which is the markup that says "skip me"
+ * — a deliberate empty string, not a forgotten prop.
+ */
+import { type ImageFit, type ImageFormat, type ImageLayout, type ImagePosition } from "../lib/image.js";
+import { type Reactive } from "../lib/props.js";
+export interface ImageProps {
+    src: Reactive<string>;
+    /** Required. `""` for a decorative image, which is what hides it. */
+    alt: Reactive<string>;
+    /**
+     * Displayed width in pixels, and the `width` attribute.
+     *
+     * Together with `height` it is what reserves the space before the bytes
+     * arrive. Optional only because `full-width` does not need it.
+     */
+    width?: Reactive<number | undefined>;
+    height?: Reactive<number | undefined>;
+    /** Defaults to `constrained`. */
+    layout?: Reactive<ImageLayout>;
+    /** CSS `object-fit`. The image is never cropped server-side. */
+    fit?: Reactive<ImageFit | undefined>;
+    /** CSS `object-position`, for when `fit` crops. */
+    position?: Reactive<ImagePosition | undefined>;
+    /** Output format to request. Defaults to `webp`. */
+    format?: Reactive<ImageFormat | undefined>;
+    /** 1-100. The endpoint decides which values it accepts. */
+    quality?: Reactive<number | undefined>;
+    /** Override the generated width ladder. Pair it with `sizes`. */
+    widths?: Reactive<readonly number[] | undefined>;
+    /**
+     * Serve by pixel ratio instead of width, e.g. `[1, 2]`.
+     *
+     * Mutually exclusive with `widths` — a `srcset` mixing `w` and `x`
+     * descriptors is invalid, and a browser that sees one ignores the
+     * attribute entirely. `widths` wins if both are given.
+     */
+    densities?: Reactive<readonly number[] | undefined>;
+    /** Override the generated `sizes`. */
+    sizes?: Reactive<string | undefined>;
+    /** Width ladder to draw from. Defaults to the device-width ladder. */
+    breakpoints?: Reactive<readonly number[] | undefined>;
+    /** The source's own width, when known. Stops variants past it being offered. */
+    originalWidth?: Reactive<number | undefined>;
+    /**
+     * Above the fold: load it now.
+     *
+     * Sets `loading="eager"`, `decoding="sync"` and `fetchpriority="high"`
+     * together, because setting one without the others is the usual reason a
+     * hero image is still not the first thing painted.
+     */
+    priority?: Reactive<boolean>;
+    loading?: Reactive<"lazy" | "eager" | undefined>;
+    decoding?: Reactive<"async" | "sync" | "auto" | undefined>;
+    fetchPriority?: Reactive<"high" | "low" | "auto" | undefined>;
+    class?: Reactive<string>;
+}
+/**
+ * The widths this image offers, honouring an explicit `widths` prop.
+ *
+ * Exported because `Picture` needs exactly the same ladder for every one of
+ * its `<source>` elements — computing it twice is how the AVIF and WebP
+ * variants end up offering different sizes.
+ */
+export declare function resolvedWidths(props: ImageProps): number[];
+/** The `srcset` for one format, in whichever descriptor style applies. */
+export declare function resolvedSrcSet(props: ImageProps, format: ImageFormat | undefined): string | undefined;
+/** The `sizes` for this image, or `undefined` when it carries `x` descriptors. */
+export declare function resolvedSizes(props: ImageProps): string | undefined;
+/**
+ * The `src` a browser falls back to.
+ *
+ * The declared width rather than the largest variant: it is what a browser
+ * with no `srcset` support (and every crawler that reads the attribute
+ * literally) will fetch.
+ */
+export declare function resolvedSrc(props: ImageProps, format: ImageFormat | undefined): string;
+/** The class list for the layout, fit and position of an image. */
+export declare function imageClasses(props: ImageProps): string;
+/** `loading`, `decoding` and `fetchpriority`, with `priority` applied. */
+export declare function loadingAttributes(props: ImageProps): {
+    loading: "lazy" | "eager";
+    decoding: "async" | "sync" | "auto";
+    fetchPriority: "high" | "low" | "auto" | undefined;
+};
+export declare const Image: (props?: ImageProps | undefined) => import("@c9up/aurora").TemplateResult;

package/dist/atoms/Image.js

@@ -0,0 +1,139 @@
+/**
+ * Image — one `<img>`, with the attributes that make it fast already filled in.
+ *
+ * A bare `<img src>` costs a page twice: it ships desktop pixels to a phone,
+ * and it reserves no space until it arrives, so everything under it jumps.
+ * Both are solved by attributes nobody writes by hand — a `srcset` of a dozen
+ * widths, a matching `sizes`, `width`/`height` for the ratio, `loading` and
+ * `decoding`. This component writes them.
+ *
+ * The bytes come from whatever {@link setImageResolver} is pointed at; the
+ * component only decides which variants to ask for. See `lib/image.ts` for
+ * why the split is there and what the resolver is allowed to be asked.
+ *
+ * ```ts
+ * Image({ src: "/photos/hero.jpg", alt: "…", width: 1200, height: 800 })
+ * Image({ src: "/logo.png", alt: "…", width: 48, height: 48, layout: "fixed" })
+ * Image({ src: "/banner.jpg", alt: "…", layout: "full-width", priority: true })
+ * ```
+ *
+ * `alt` is required, and not as a gesture: the attribute is what a screen
+ * reader announces, and an `<img>` without one is read out as its file name.
+ * Decorative images pass `alt: ""`, which is the markup that says "skip me"
+ * — a deliberate empty string, not a forgotten prop.
+ */
+import { component, html } from "@c9up/aurora";
+import { cn } from "../lib/cn.js";
+import { densitySrcSet, fitClass, imageSizes, imageSrcSet, imageUrl, imageWidths, layoutClasses, offeredWidth, positionClass, } from "../lib/image.js";
+import { read, readOr } from "../lib/props.js";
+/**
+ * The widths this image offers, honouring an explicit `widths` prop.
+ *
+ * Exported because `Picture` needs exactly the same ladder for every one of
+ * its `<source>` elements — computing it twice is how the AVIF and WebP
+ * variants end up offering different sizes.
+ */
+export function resolvedWidths(props) {
+    const explicit = read(props.widths);
+    if (explicit !== undefined)
+        return [...explicit];
+    return imageWidths({
+        width: read(props.width),
+        layout: readOr(props.layout, "constrained"),
+        breakpoints: read(props.breakpoints),
+        originalWidth: read(props.originalWidth),
+    });
+}
+/** The `srcset` for one format, in whichever descriptor style applies. */
+export function resolvedSrcSet(props, format) {
+    const quality = read(props.quality);
+    const width = read(props.width);
+    const densities = read(props.densities);
+    // `widths` wins: an explicit ladder is the more specific instruction, and
+    // honouring both would emit the invalid mixed-descriptor set.
+    if (densities !== undefined && read(props.widths) === undefined) {
+        if (width === undefined)
+            return undefined;
+        return densitySrcSet({
+            src: read(props.src),
+            width,
+            densities,
+            format,
+            quality,
+            originalWidth: read(props.originalWidth),
+            breakpoints: read(props.breakpoints),
+        });
+    }
+    return imageSrcSet({
+        src: read(props.src),
+        widths: resolvedWidths(props),
+        format,
+        quality,
+    });
+}
+/** The `sizes` for this image, or `undefined` when it carries `x` descriptors. */
+export function resolvedSizes(props) {
+    const explicit = read(props.sizes);
+    if (explicit !== undefined)
+        return explicit;
+    // Density srcsets describe themselves; a `sizes` alongside them means
+    // nothing and browsers ignore it.
+    if (read(props.densities) !== undefined && read(props.widths) === undefined) {
+        return undefined;
+    }
+    return imageSizes({
+        width: read(props.width),
+        layout: readOr(props.layout, "constrained"),
+    });
+}
+/**
+ * The `src` a browser falls back to.
+ *
+ * The declared width rather than the largest variant: it is what a browser
+ * with no `srcset` support (and every crawler that reads the attribute
+ * literally) will fetch.
+ */
+export function resolvedSrc(props, format) {
+    const src = read(props.src);
+    const width = read(props.width);
+    if (width === undefined)
+        return src;
+    return imageUrl(src, {
+        // Snapped like every other entry: the declared width is almost never a
+        // width the endpoint offers, and this URL is the one a browser without
+        // `srcset` support fetches.
+        width: offeredWidth(width, read(props.breakpoints)),
+        format,
+        quality: read(props.quality),
+    });
+}
+/** The class list for the layout, fit and position of an image. */
+export function imageClasses(props) {
+    return cn(layoutClasses(readOr(props.layout, "constrained")), fitClass(read(props.fit)), positionClass(read(props.position)), read(props.class));
+}
+/** `loading`, `decoding` and `fetchpriority`, with `priority` applied. */
+export function loadingAttributes(props) {
+    const priority = readOr(props.priority, false);
+    return {
+        loading: read(props.loading) ?? (priority ? "eager" : "lazy"),
+        decoding: read(props.decoding) ?? (priority ? "sync" : "async"),
+        fetchPriority: read(props.fetchPriority) ?? (priority ? "high" : undefined),
+    };
+}
+export const Image = component((props) => {
+    const format = () => read(props.format) ?? "webp";
+    return html `<img
+		data-slot="image"
+		data-layout="${() => readOr(props.layout, "constrained")}"
+		src="${() => resolvedSrc(props, format())}"
+		srcset="${() => resolvedSrcSet(props, format())}"
+		sizes="${() => resolvedSizes(props)}"
+		alt="${() => read(props.alt)}"
+		width="${() => read(props.width)}"
+		height="${() => read(props.height)}"
+		loading="${() => loadingAttributes(props).loading}"
+		decoding="${() => loadingAttributes(props).decoding}"
+		fetchpriority="${() => loadingAttributes(props).fetchPriority}"
+		class="${() => imageClasses(props)}"
+	/>`;
+});

package/dist/atoms/NativeSelect.js

@@ -44,7 +44,25 @@ export const NativeSelect = component((props) => {
         }
         return out;
     }
-    const renderOption = (option) => html `<option value="${option.value}" ?disabled="${option.disabled === true}">
+    /**
+     * `?selected` on each option, NOT `.value` on the select alone.
+     *
+     * A property binding sits on the opening tag, so it is assigned before the
+     * options exist. `select.value = 'x'` against a childless `<select>` is a
+     * no-op the DOM does not report, and nothing re-runs it afterwards: the
+     * control then shows its FIRST option while holding the value it was given.
+     * Nothing throws and nothing logs, so the value the user sees is not the
+     * value the form will submit — in a form that edits money or tax status
+     * that is a wrong record written on save.
+     *
+     * Marking the option is order-independent, and it is also what makes the
+     * choice correct in server-rendered HTML before any script runs.
+     */
+    const renderOption = (option) => html `<option
+			value="${option.value}"
+			?disabled="${option.disabled === true}"
+			?selected="${() => read(props.value) === option.value}"
+		>
 			${option.label}
 		</option>`;
     return html `<div data-slot="native-select" class="relative inline-flex w-full items-center">
@@ -61,7 +79,14 @@ export const NativeSelect = component((props) => {
 		>
 			${props.placeholder === undefined
         ? null
-        : html `<option value="" disabled selected>${props.placeholder}</option>`}
+        : html `<option
+							value=""
+							disabled
+							?selected="${() => {
+            const current = read(props.value);
+            return current === undefined || current === "";
+        }}"
+						>${props.placeholder}</option>`}
 			${runs().map((run) => run.group === undefined
         ? run.items.map(renderOption)
         : html `<optgroup label="${run.group}">${run.items.map(renderOption)}</optgroup>`)}

package/dist/atoms/index.d.ts

@@ -16,6 +16,7 @@ export { Avatar, type AvatarProps } from "./Avatar.js";
 export { Badge, type BadgeProps, type BadgeVariants, badgeVariants, } from "./Badge.js";
 export { Button, type ButtonProps, type ButtonVariants, buttonVariants, } from "./Button.js";
 export { Checkbox, type CheckboxProps, checkboxClasses } from "./Checkbox.js";
+export { Image, type ImageProps, imageClasses, loadingAttributes, resolvedSizes, resolvedSrc, resolvedSrcSet, resolvedWidths, } from "./Image.js";
 export { Input, type InputProps, inputClasses } from "./Input.js";
 export { Kbd, type KbdProps } from "./Kbd.js";
 export { Label, type LabelProps, labelClasses } from "./Label.js";

package/dist/atoms/index.js

@@ -16,6 +16,7 @@ export { Avatar } from "./Avatar.js";
 export { Badge, badgeVariants, } from "./Badge.js";
 export { Button, buttonVariants, } from "./Button.js";
 export { Checkbox, checkboxClasses } from "./Checkbox.js";
+export { Image, imageClasses, loadingAttributes, resolvedSizes, resolvedSrc, resolvedSrcSet, resolvedWidths, } from "./Image.js";
 export { Input, inputClasses } from "./Input.js";
 export { Kbd } from "./Kbd.js";
 export { Label, labelClasses } from "./Label.js";

package/dist/lib/image.d.ts

@@ -0,0 +1,213 @@
+/**
+ * Responsive image plumbing — the arithmetic behind `Image` and `Picture`.
+ *
+ * Everything here is pure: widths in, strings out. It lives apart from the
+ * components because the interesting part of a responsive image is not the
+ * markup, it is deciding *which* variants to offer the browser, and that
+ * decision is worth testing without a DOM.
+ *
+ * **Where the bytes come from is not nebula's business.** A component that
+ * imported an image processor would drag a native module into a package whose
+ * only peer is Aurora, and would pin every app to one way of serving images.
+ * So the URL is produced by a resolver the app installs once
+ * ({@link setImageResolver}). The default one points at `/__image`, the
+ * endpoint `@c9up/prism` registers; pointing it at a CDN instead is a
+ * one-line change and no component notices.
+ *
+ * The resolver asks for a width, a format and a quality — never a height and
+ * never a crop. Those three axes are the ones the server can safely allow-list,
+ * which is what keeps an open transformation endpoint from becoming a cache
+ * bomb. Cropping is `object-fit` on the element, where it costs nothing.
+ */
+/**
+ * How an image responds to the width of its container.
+ *
+ * - `constrained` — scales down to fit, never past its declared width. The
+ *   default, and what almost every image in a page wants.
+ * - `full-width` — always the width of its container. Hero images, banners.
+ * - `fixed` — the declared size, whatever the viewport. Logos, avatars,
+ *   icons. Still offers a 2x variant for dense screens.
+ * - `none` — no `srcset`, no `sizes`. An escape hatch for when the markup is
+ *   being assembled by something else.
+ */
+export type ImageLayout = "constrained" | "full-width" | "fixed" | "none";
+/** Output formats an image endpoint is expected to understand. */
+export type ImageFormat = "avif" | "webp" | "jpeg" | "png";
+/**
+ * How the rendered box reconciles a different aspect ratio.
+ *
+ * These are the CSS `object-fit` values, and they are applied as CSS — the
+ * image is never cropped server-side. A crop asked for through a URL is an
+ * unbounded axis on a public endpoint, and the same result is one class here.
+ */
+export type ImageFit = "cover" | "contain" | "fill" | "none" | "scale-down";
+/** Where the visible part sits when `fit` crops. CSS `object-position`. */
+export type ImagePosition = "center" | "top" | "bottom" | "left" | "right" | "top left" | "top right" | "bottom left" | "bottom right";
+/** What a resolver is asked to produce one URL for. */
+export interface ImageTransform {
+    /** Target width in pixels. The server must not upscale past the source. */
+    width: number;
+    format?: ImageFormat;
+    /** 1-100. The endpoint decides whether a given value is allowed. */
+    quality?: number;
+}
+/** Turns a source and a transform into the URL to put in a `srcset`. */
+export type ImageUrlResolver = (src: string, transform: ImageTransform) => string;
+/**
+ * Widths for elements that are not the width of a screen.
+ *
+ * Avatars, icons, thumbnails. Without them a 48px avatar's nearest offer is
+ * 640 — thirteen times the pixels it can show — because every other ladder
+ * starts at a phone's viewport.
+ */
+export declare const IMAGE_SIZES: readonly number[];
+/**
+ * The widths worth generating, from real device pixel counts.
+ *
+ * Astro's ladder, close to the one Next.js settled on independently — which is
+ * the reason to reuse it rather than invent one. They are device widths, not
+ * round numbers: 828 is the iPhone XR, 1668 is an iPad. A tidier
+ * `[400, 800, 1200, 1600]` misses every one of them and ships each device a
+ * slightly-too-large image.
+ *
+ * Density is what makes the ladder cheap to round up to. The nearest rung
+ * above 2400 here is 2560, six percent over; on a sparser ladder it would be
+ * 3840.
+ */
+export declare const DEFAULT_RESOLUTIONS: readonly number[];
+/**
+ * The ladder without the sizes only a desktop display asks for.
+ *
+ * Worth choosing deliberately for a full-width image: the top of
+ * {@link DEFAULT_RESOLUTIONS} is eleven extra variants to store and warm, for
+ * screens most sites see rarely.
+ */
+export declare const LIMITED_RESOLUTIONS: readonly number[];
+/**
+ * Every width a component may ask for, ascending.
+ *
+ * This list and the endpoint's allow-list are the same list, and that is the
+ * contract between the two halves: a component that emits a width the endpoint
+ * does not serve produces a `srcset` where every entry is a 400, and the page
+ * silently falls back to the one `src`.
+ *
+ * It is also why a declared width is never emitted literally. `width: 1200`
+ * asking for 1200 and 2400 would be two widths no allow-list contains, and
+ * allow-listing whatever an author happens to type is not an allow-list.
+ */
+export declare function allSizes(breakpoints: readonly number[]): number[];
+/**
+ * The width to actually request for a declared one.
+ *
+ * The `src` attribute and a density entry are single URLs rather than ladders,
+ * and they are subject to the same contract: a literal declared width is a
+ * width no allow-list contains.
+ */
+export declare function offeredWidth(width: number, breakpoints?: readonly number[]): number;
+export interface WidthsOptions {
+    /** The declared display width. Required by every layout but `full-width`. */
+    width?: number;
+    layout: ImageLayout;
+    /** Ladder to draw from. Defaults to {@link DEFAULT_RESOLUTIONS}. */
+    breakpoints?: readonly number[];
+    /**
+     * The source's own width, when it is known.
+     *
+     * Only a refinement: the endpoint must refuse to upscale anyway, so
+     * leaving it out costs a duplicate URL that serves the same bytes, never a
+     * blurry enlargement. Pass it and those duplicates disappear.
+     */
+    originalWidth?: number;
+}
+/**
+ * The widths to offer, ascending.
+ *
+ * Every value comes off {@link allSizes} — see there for why a declared width
+ * is never emitted literally. 1x and 2x are always represented, rounded up, so
+ * the common case of a dense screen at the declared width is never served
+ * fewer pixels than it can show.
+ */
+export declare function imageWidths(options: WidthsOptions): number[];
+/**
+ * The `sizes` attribute for a layout.
+ *
+ * Without it the browser assumes the image is the full width of the viewport
+ * and picks the largest variant on every screen — which is the failure mode
+ * where adding a `srcset` makes a page slower, not faster.
+ */
+export declare function imageSizes(options: {
+    width?: number;
+    layout: ImageLayout;
+}): string | undefined;
+export interface SrcSetOptions {
+    src: string;
+    widths: readonly number[];
+    format?: ImageFormat;
+    quality?: number;
+    /** Defaults to the installed resolver. */
+    resolve?: ImageUrlResolver;
+}
+/** A `srcset` with `w` descriptors, or `undefined` when there is nothing to offer. */
+export declare function imageSrcSet(options: SrcSetOptions): string | undefined;
+export interface DensitySrcSetOptions {
+    src: string;
+    /** The width at 1x. */
+    width: number;
+    /** Pixel ratios to serve, e.g. `[1, 2]`. */
+    densities: readonly number[];
+    format?: ImageFormat;
+    quality?: number;
+    originalWidth?: number;
+    breakpoints?: readonly number[];
+    resolve?: ImageUrlResolver;
+}
+/**
+ * A `srcset` with `x` descriptors.
+ *
+ * The alternative to widths, never a companion to them: a `srcset` mixing `w`
+ * and `x` descriptors is invalid, and browsers handle the mixture by ignoring
+ * the whole attribute.
+ */
+export declare function densitySrcSet(options: DensitySrcSetOptions): string | undefined;
+/** Point the built-in resolver at a different path. */
+export declare function setImageEndpoint(path: string): void;
+/**
+ * The resolver used when an application installs none.
+ *
+ * Parameter names are one letter because they end up in every `srcset` entry
+ * of every image on the page, and a `srcset` with fifteen entries repeats them
+ * fifteen times.
+ */
+export declare const defaultImageResolver: ImageUrlResolver;
+/**
+ * Install the resolver every image uses.
+ *
+ * Call it once at startup — from the app's entry on the client, and from the
+ * same module on the server so SSR and hydration agree. They must agree: an
+ * `src` that differs between the two makes the browser discard the image the
+ * server already started fetching and request another.
+ *
+ * Passing `null` restores {@link defaultImageResolver}.
+ */
+export declare function setImageResolver(next: ImageUrlResolver | null): void;
+/** The resolver currently installed. */
+export declare function getImageResolver(): ImageUrlResolver;
+/** Build one image URL through the installed resolver. */
+export declare function imageUrl(src: string, transform: ImageTransform): string;
+/** Tailwind classes for a layout. Height is always `auto` so the ratio holds. */
+export declare function layoutClasses(layout: ImageLayout): string;
+/** The `object-fit` class for a fit value. */
+export declare function fitClass(fit: ImageFit | undefined): string | undefined;
+/** The `object-position` class for a position value. */
+export declare function positionClass(position: ImagePosition | undefined): string | undefined;
+/** The MIME type a `<source type>` needs for a format. */
+export declare function mimeType(format: ImageFormat): string;
+/**
+ * The format a source's file name claims, if any.
+ *
+ * Used to pick the fallback of a `<picture>`: converting a PNG with
+ * transparency to JPEG puts a black box behind it, so the fallback follows the
+ * source rather than a fixed default. The extension is a claim, not proof —
+ * only the server knows what the bytes really are, and it re-reads them.
+ */
+export declare function formatFromSource(src: string): ImageFormat | undefined;