@stapel/image 0.1.0

package/README.md

@@ -0,0 +1,64 @@
+# @stapel/image
+
+Image rendering over the stapel-cdn variant ladder: pure tier/branch math,
+a slot-measurement hook, and a blur-up `<Image>` component.
+
+Pairs with the stapel-cdn render-metadata snapshot (`cdn.describe(ref)` /
+`stapel_core.media.describe(ref)`): an immutable `{mime, bytes, width, height,
+aspect, preview_b64, square, variants[]}` object produced on ingest.
+
+## The ladder
+
+Default tiers `16, 32, 64, 120, 160, 240, 480, 560, 720, 1080`:
+
+- **16 (micro)** — inlined as `preview_b64`, the blur-up placeholder;
+- **32/64/120 (thumbnail)** — min-side resize, no w/h branches (`branch: null`),
+  for fixed square-ish slots (avatars, grids);
+- **160–1080 (preview)** — two branches per tier: `{T}w` (width == T) and
+  `{T}h` (height == T), so the limiting axis of any slot is served without
+  upscaling. Square images store one branch and set `square: true`.
+
+## Pure math (`no DOM, no React`)
+
+```ts
+import { pickTier, limitingAxis, chooseVariant } from "@stapel/image";
+
+pickTier(792, [560, 720, 1080]); // 720  — smallest T with needed ≤ T×1.1
+pickTier(793, [560, 720, 1080]); // 1080
+pickTier(616, [560, 720, 1080]); // 560
+
+limitingAxis(0.75, 16 / 9, "cover"); // "w" — portrait in a wide slot
+
+chooseVariant(
+  { slotWidthCss: 640, slotHeightCss: 360, dpr: 2, imgAspect: meta.aspect, fit: "cover" },
+  meta
+); // → VariantMeta (falls back to "original" past the top of the ladder)
+```
+
+`neededPx` always includes DPR: a 400px CSS slot on a dpr=2 screen shops for
+800 physical pixels.
+
+## `useImageSlot()`
+
+ResizeObserver measurement of the rendered slot. SSR-safe (`size` is
+`undefined` until mounted). The reported size is a per-axis high-water mark —
+it only grows, so resize jitter or a transient shrink never re-picks a
+smaller, already-loaded tier.
+
+## `<Image>`
+
+```tsx
+import { Image } from "@stapel/image";
+
+<Image meta={attachment.render_meta} alt={attachment.name} fit="cover" />
+```
+
+1. `aspect-ratio` from metadata lands on the container before any measurement
+   — zero layout shift, zero network.
+2. The 16px `preview_b64` renders instantly underneath (blur-up).
+3. The measured slot picks `(branch, tier)` via `chooseVariant`.
+4. Upgrades only: a bigger pick loads off-DOM and swaps after `decode()`;
+   an equal-or-smaller pick is ignored — never a blank frame, never a
+   visual downgrade.
+
+`fit` defaults to `"cover"`; `alt` is required.

package/dist/Image.d.ts

@@ -0,0 +1,24 @@
+import type { ImgHTMLAttributes, ReactElement } from "react";
+import type { Fit, RenderMetadata } from "./tiers.js";
+export interface ImageProps extends Omit<ImgHTMLAttributes<HTMLImageElement>, "src" | "srcSet" | "alt"> {
+    meta: RenderMetadata;
+    /** Default `"cover"` (chat/catalog/avatar — fill the slot). */
+    fit?: Fit;
+    /** Required, no default. */
+    alt: string;
+}
+/**
+ * CDN-ladder-aware image (images-and-cdn.md §4):
+ *
+ * 1. `aspect-ratio` from metadata goes on the container BEFORE the first slot
+ *    measurement — layout-shift protection entirely from the snapshot, no
+ *    network round-trip.
+ * 2. Blur-up: the inlined 16px `preview_b64` renders instantly underneath
+ *    until the chosen tier has decoded.
+ * 3. `useImageSlot()` measures the actual slot → `chooseVariant(...)` → src.
+ * 4. Upgrades only: a re-measure that picks a variant no bigger than the one
+ *    already rendered is ignored; a bigger pick loads off-DOM and swaps in
+ *    only after `decode()` — never a flash of empty slot, never a downgrade.
+ */
+export declare function Image({ meta, fit, alt, style, className, ...imgProps }: ImageProps): ReactElement;
+//# sourceMappingURL=Image.d.ts.map

package/dist/Image.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Image.d.ts","sourceRoot":"","sources":["../src/Image.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAiB,iBAAiB,EAAE,YAAY,EAAE,MAAM,OAAO,CAAC;AAE5E,OAAO,KAAK,EAAE,GAAG,EAAE,cAAc,EAAe,MAAM,YAAY,CAAC;AAGnE,MAAM,WAAW,UACf,SAAQ,IAAI,CAAC,iBAAiB,CAAC,gBAAgB,CAAC,EAAE,KAAK,GAAG,QAAQ,GAAG,KAAK,CAAC;IAC3E,IAAI,EAAE,cAAc,CAAC;IACrB,+DAA+D;IAC/D,GAAG,CAAC,EAAE,GAAG,CAAC;IACV,4BAA4B;IAC5B,GAAG,EAAE,MAAM,CAAC;CACb;AASD;;;;;;;;;;;;GAYG;AACH,wBAAgB,KAAK,CAAC,EACpB,IAAI,EACJ,GAAa,EACb,GAAG,EACH,KAAK,EACL,SAAS,EACT,GAAG,QAAQ,EACZ,EAAE,UAAU,GAAG,YAAY,CA6G3B"}

package/dist/Image.js

@@ -0,0 +1,107 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useMemo, useRef, useState } from "react";
+import { chooseVariant } from "./tiers.js";
+import { useImageSlot } from "./useImageSlot.js";
+const FILL = {
+    position: "absolute",
+    inset: 0,
+    width: "100%",
+    height: "100%",
+};
+/**
+ * CDN-ladder-aware image (images-and-cdn.md §4):
+ *
+ * 1. `aspect-ratio` from metadata goes on the container BEFORE the first slot
+ *    measurement — layout-shift protection entirely from the snapshot, no
+ *    network round-trip.
+ * 2. Blur-up: the inlined 16px `preview_b64` renders instantly underneath
+ *    until the chosen tier has decoded.
+ * 3. `useImageSlot()` measures the actual slot → `chooseVariant(...)` → src.
+ * 4. Upgrades only: a re-measure that picks a variant no bigger than the one
+ *    already rendered is ignored; a bigger pick loads off-DOM and swaps in
+ *    only after `decode()` — never a flash of empty slot, never a downgrade.
+ */
+export function Image({ meta, fit = "cover", alt, style, className, ...imgProps }) {
+    const { ref, size } = useImageSlot();
+    const [displayed, setDisplayed] = useState(undefined);
+    const [visible, setVisible] = useState(false);
+    const displayedRef = useRef(undefined);
+    const target = useMemo(() => {
+        if (size === undefined || size.width <= 0 || size.height <= 0) {
+            return undefined;
+        }
+        if (meta.variants.length === 0) {
+            return undefined;
+        }
+        const dpr = typeof window === "undefined" ? 1 : window.devicePixelRatio || 1;
+        return chooseVariant({
+            slotWidthCss: size.width,
+            slotHeightCss: size.height,
+            dpr,
+            imgAspect: meta.aspect,
+            fit,
+        }, meta);
+    }, [size, meta, fit]);
+    useEffect(() => {
+        if (target === undefined) {
+            return;
+        }
+        const current = displayedRef.current;
+        // Upgrade only (§4): never replace an already-rendered variant with an
+        // equal or smaller one (resize jitter, transient shrink).
+        if (current !== undefined && target.width * target.height <= current.width * current.height) {
+            return;
+        }
+        let cancelled = false;
+        const loader = document.createElement("img");
+        const commit = () => {
+            if (cancelled) {
+                return;
+            }
+            displayedRef.current = target;
+            setDisplayed(target);
+        };
+        loader.src = target.url;
+        if (typeof loader.decode === "function") {
+            // Swap only after decode — no blank frame during the upgrade.
+            loader.decode().then(commit, commit);
+        }
+        else {
+            loader.onload = commit;
+            loader.onerror = commit;
+        }
+        return () => {
+            cancelled = true;
+        };
+    }, [target]);
+    useEffect(() => {
+        if (displayed === undefined || visible) {
+            return;
+        }
+        // One frame at opacity 0 so the blur-up → sharp transition actually runs.
+        const id = requestAnimationFrame(() => {
+            setVisible(true);
+        });
+        return () => {
+            cancelAnimationFrame(id);
+        };
+    }, [displayed, visible]);
+    const containerStyle = {
+        position: "relative",
+        overflow: "hidden",
+        aspectRatio: String(meta.aspect),
+        ...style,
+    };
+    return (_jsxs("div", { ref: ref, className: className, style: containerStyle, children: [meta.preview_b64 !== undefined && (_jsx("img", { src: meta.preview_b64, alt: "", "aria-hidden": "true", style: {
+                    ...FILL,
+                    objectFit: fit,
+                    filter: "blur(12px)",
+                    transform: "scale(1.05)",
+                } })), displayed !== undefined && (_jsx("img", { ...imgProps, src: displayed.url, alt: alt, style: {
+                    ...FILL,
+                    objectFit: fit,
+                    opacity: visible ? 1 : 0,
+                    transition: "opacity 200ms ease",
+                } }))] }));
+}
+//# sourceMappingURL=Image.js.map

package/dist/Image.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Image.js","sourceRoot":"","sources":["../src/Image.tsx"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { pickTier, limitingAxis, chooseVariant } from "./tiers.js";
+export type { Branch, ChooseVariantArgs, Fit, RenderMetadata, VariantMeta, } from "./tiers.js";
+export { useImageSlot } from "./useImageSlot.js";
+export type { ImageSlot, ImageSlotSize } from "./useImageSlot.js";
+export { Image } from "./Image.js";
+export type { ImageProps } from "./Image.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AACnE,YAAY,EACV,MAAM,EACN,iBAAiB,EACjB,GAAG,EACH,cAAc,EACd,WAAW,GACZ,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,YAAY,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAGlE,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,YAAY,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,7 @@
+// Pure tier/branch math (no DOM, no React).
+export { pickTier, limitingAxis, chooseVariant } from "./tiers.js";
+// Slot measurement (ResizeObserver, high-water-mark, SSR-safe).
+export { useImageSlot } from "./useImageSlot.js";
+// Blur-up component over the ladder.
+export { Image } from "./Image.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,4CAA4C;AAC5C,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AASnE,gEAAgE;AAChE,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAGjD,qCAAqC;AACrC,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC"}

package/dist/tiers.d.ts

@@ -0,0 +1,76 @@
+/** One generated variant file of an image (images-and-cdn.md §5). */
+export interface VariantMeta {
+    /** Ladder tier (px along the branch axis) or the untouched original. */
+    tier: number | "original";
+    /**
+     * `"w"` / `"h"` — preview-class branch (resize so that width/height == tier);
+     * `null` — thumbnail-class (min-side resize) and `"original"`.
+     */
+    branch: "w" | "h" | null;
+    url: string;
+    /** Actual pixel width of the file (after the no-upscale cap on native). */
+    width: number;
+    /** Actual pixel height of the file (after the no-upscale cap on native). */
+    height: number;
+}
+/**
+ * Immutable render-metadata snapshot produced on ingest by stapel-cdn (or the
+ * PIL provider) and resolved via `cdn.describe(ref)` — images-and-cdn.md §5,
+ * an additive extension of the chat-design.md attachment snapshot.
+ */
+export interface RenderMetadata {
+    mime: string;
+    bytes: number;
+    width: number;
+    height: number;
+    /** width / height. */
+    aspect: number;
+    /** Video/audio duration; `null`/absent for still images. */
+    duration_ms?: number | null;
+    /** `data:image/webp;base64,...` — the 16px micro tier, blur-up placeholder. */
+    preview_b64?: string;
+    /** `true` ⇒ w/h branches are identical; `variants[].branch` is irrelevant (§3.3). */
+    square?: boolean;
+    variants: VariantMeta[];
+}
+export type Fit = "cover" | "contain";
+export type Branch = "w" | "h";
+/**
+ * Smallest tier that does not upscale beyond the ×1.1 tolerance (§2.2):
+ * the smallest `T` in `tiers` with `neededPx ≤ T × 1.1`; if none qualifies,
+ * the largest tier (upscaling is forbidden at this level too — past the
+ * ladder the consumer falls back to "original", see `chooseVariant`).
+ *
+ * `neededPx` must already include DPR (`cssSize × devicePixelRatio`).
+ */
+export declare function pickTier(neededPx: number, tiers: readonly number[]): number;
+/**
+ * Which axis of the slot limits the pixel budget (§3.5, mode Б):
+ * `cover` scales by `max(slotW/imgW, slotH/imgH)` — the limiting side is the
+ * one where the image is "narrower" relative to the slot; `contain` is the
+ * exact opposite. Tie-break on aspect equality is "w" (branches equivalent).
+ */
+export declare function limitingAxis(imgAspect: number, slotAspect: number, fit: Fit): Branch;
+export interface ChooseVariantArgs {
+    slotWidthCss: number;
+    slotHeightCss: number;
+    dpr: number;
+    /** width / height of the image — from metadata, known before any pixel loads. */
+    imgAspect: number;
+    fit: Fit;
+}
+/**
+ * Full selection (§3.5): limiting axis from (image aspect × slot aspect × fit),
+ * needed pixels along that axis (CSS × DPR), then the smallest non-upscaling
+ * tier among the variants that can serve that axis:
+ *
+ * - branch === axis — the matching preview branch;
+ * - branch === null (numeric tier) — thumbnail-class min-side variants, whose
+ *   BOTH sides are ≥ tier, so they serve either axis;
+ * - `meta.square` — any branch (w/h identical, §3.3).
+ *
+ * Past the top of the ladder (needed > maxTier × 1.1) the "original" variant
+ * is returned when present — no tier would avoid an upscale (§2.2).
+ */
+export declare function chooseVariant(args: ChooseVariantArgs, meta: RenderMetadata): VariantMeta;
+//# sourceMappingURL=tiers.d.ts.map

package/dist/tiers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tiers.d.ts","sourceRoot":"","sources":["../src/tiers.ts"],"names":[],"mappings":"AAIA,qEAAqE;AACrE,MAAM,WAAW,WAAW;IAC1B,wEAAwE;IACxE,IAAI,EAAE,MAAM,GAAG,UAAU,CAAC;IAC1B;;;OAGG;IACH,MAAM,EAAE,GAAG,GAAG,GAAG,GAAG,IAAI,CAAC;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,2EAA2E;IAC3E,KAAK,EAAE,MAAM,CAAC;IACd,4EAA4E;IAC5E,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,sBAAsB;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,4DAA4D;IAC5D,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,+EAA+E;IAC/E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,qFAAqF;IACrF,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,WAAW,EAAE,CAAC;CACzB;AAED,MAAM,MAAM,GAAG,GAAG,OAAO,GAAG,SAAS,CAAC;AAEtC,MAAM,MAAM,MAAM,GAAG,GAAG,GAAG,GAAG,CAAC;AAE/B;;;;;;;GAOG;AACH,wBAAgB,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAW3E;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,GAAG,EAAE,GAAG,GAAG,MAAM,CASpF;AAED,MAAM,WAAW,iBAAiB;IAChC,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,GAAG,EAAE,MAAM,CAAC;IACZ,iFAAiF;IACjF,SAAS,EAAE,MAAM,CAAC;IAClB,GAAG,EAAE,GAAG,CAAC;CACV;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,iBAAiB,EAAE,IAAI,EAAE,cAAc,GAAG,WAAW,CAoCxF"}

package/dist/tiers.js

@@ -0,0 +1,83 @@
+// Pure tier/branch math for the stapel-cdn variant ladder
+// (docs/pending/images-and-cdn.md §2-3, §5). No DOM, no React — unit-testable
+// against the owner's examples verbatim and reusable outside the component.
+/**
+ * Smallest tier that does not upscale beyond the ×1.1 tolerance (§2.2):
+ * the smallest `T` in `tiers` with `neededPx ≤ T × 1.1`; if none qualifies,
+ * the largest tier (upscaling is forbidden at this level too — past the
+ * ladder the consumer falls back to "original", see `chooseVariant`).
+ *
+ * `neededPx` must already include DPR (`cssSize × devicePixelRatio`).
+ */
+export function pickTier(neededPx, tiers) {
+    if (tiers.length === 0) {
+        throw new TypeError("pickTier: tiers must be non-empty");
+    }
+    const sorted = [...tiers].sort((a, b) => a - b);
+    for (const tier of sorted) {
+        if (neededPx <= tier * 1.1) {
+            return tier;
+        }
+    }
+    return sorted[sorted.length - 1];
+}
+/**
+ * Which axis of the slot limits the pixel budget (§3.5, mode Б):
+ * `cover` scales by `max(slotW/imgW, slotH/imgH)` — the limiting side is the
+ * one where the image is "narrower" relative to the slot; `contain` is the
+ * exact opposite. Tie-break on aspect equality is "w" (branches equivalent).
+ */
+export function limitingAxis(imgAspect, slotAspect, fit) {
+    if (imgAspect === slotAspect) {
+        return "w";
+    }
+    const imageWiderThanSlot = imgAspect > slotAspect;
+    if (fit === "cover") {
+        return imageWiderThanSlot ? "h" : "w";
+    }
+    return imageWiderThanSlot ? "w" : "h";
+}
+/**
+ * Full selection (§3.5): limiting axis from (image aspect × slot aspect × fit),
+ * needed pixels along that axis (CSS × DPR), then the smallest non-upscaling
+ * tier among the variants that can serve that axis:
+ *
+ * - branch === axis — the matching preview branch;
+ * - branch === null (numeric tier) — thumbnail-class min-side variants, whose
+ *   BOTH sides are ≥ tier, so they serve either axis;
+ * - `meta.square` — any branch (w/h identical, §3.3).
+ *
+ * Past the top of the ladder (needed > maxTier × 1.1) the "original" variant
+ * is returned when present — no tier would avoid an upscale (§2.2).
+ */
+export function chooseVariant(args, meta) {
+    const { slotWidthCss, slotHeightCss, dpr, imgAspect, fit } = args;
+    const slotAspect = slotWidthCss / slotHeightCss;
+    const axis = limitingAxis(imgAspect, slotAspect, fit);
+    const neededPx = (axis === "w" ? slotWidthCss : slotHeightCss) * dpr;
+    const square = meta.square === true;
+    const candidates = meta.variants.filter((v) => typeof v.tier === "number" && (square || v.branch === null || v.branch === axis));
+    const original = meta.variants.find((v) => v.tier === "original");
+    if (candidates.length === 0) {
+        if (original !== undefined) {
+            return original;
+        }
+        throw new TypeError("chooseVariant: metadata has no usable variants");
+    }
+    const tiers = [...new Set(candidates.map((v) => v.tier))];
+    const maxTier = Math.max(...tiers);
+    if (neededPx > maxTier * 1.1 && original !== undefined) {
+        return original;
+    }
+    const tier = pickTier(neededPx, tiers);
+    const exact = candidates.find((v) => v.tier === tier && v.branch === axis);
+    if (exact !== undefined) {
+        return exact;
+    }
+    const minSide = candidates.find((v) => v.tier === tier && v.branch === null);
+    if (minSide !== undefined) {
+        return minSide;
+    }
+    return candidates.find((v) => v.tier === tier);
+}
+//# sourceMappingURL=tiers.js.map

package/dist/tiers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tiers.js","sourceRoot":"","sources":["../src/tiers.ts"],"names":[],"mappings":"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"}

package/dist/useImageSlot.d.ts

@@ -0,0 +1,22 @@
+import type { RefObject } from "react";
+export interface ImageSlotSize {
+    width: number;
+    height: number;
+}
+export interface ImageSlot<T extends HTMLElement = HTMLElement> {
+    ref: RefObject<T | null>;
+    /** `undefined` until mounted and first measured (SSR-safe, useBreakpoint pattern). */
+    size: ImageSlotSize | undefined;
+}
+/**
+ * Measures the rendered slot of an element with a ResizeObserver
+ * (images-and-cdn.md §4). SSR-safe: `size` is `undefined` until mounted, so
+ * server and first client render agree.
+ *
+ * High-water-mark per axis: the reported size only ever GROWS. A transient
+ * shrink (splitter drag, viewport resize down, sidebar toggle) must not
+ * re-pick a smaller, already-loaded tier — upgrades only (§4 "докачка только
+ * вверх").
+ */
+export declare function useImageSlot<T extends HTMLElement = HTMLElement>(): ImageSlot<T>;
+//# sourceMappingURL=useImageSlot.d.ts.map

package/dist/useImageSlot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useImageSlot.d.ts","sourceRoot":"","sources":["../src/useImageSlot.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAEvC,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,SAAS,CAAC,CAAC,SAAS,WAAW,GAAG,WAAW;IAC5D,GAAG,EAAE,SAAS,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IACzB,sFAAsF;IACtF,IAAI,EAAE,aAAa,GAAG,SAAS,CAAC;CACjC;AAED;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,WAAW,GAAG,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,CAkDhF"}

package/dist/useImageSlot.js

@@ -0,0 +1,59 @@
+import { useEffect, useRef, useState } from "react";
+/**
+ * Measures the rendered slot of an element with a ResizeObserver
+ * (images-and-cdn.md §4). SSR-safe: `size` is `undefined` until mounted, so
+ * server and first client render agree.
+ *
+ * High-water-mark per axis: the reported size only ever GROWS. A transient
+ * shrink (splitter drag, viewport resize down, sidebar toggle) must not
+ * re-pick a smaller, already-loaded tier — upgrades only (§4 "докачка только
+ * вверх").
+ */
+export function useImageSlot() {
+    const ref = useRef(null);
+    const [size, setSize] = useState(undefined);
+    useEffect(() => {
+        const el = ref.current;
+        if (el === null) {
+            return;
+        }
+        const grow = (width, height) => {
+            if (width <= 0 && height <= 0) {
+                return;
+            }
+            setSize((prev) => {
+                const next = {
+                    width: Math.max(prev?.width ?? 0, width),
+                    height: Math.max(prev?.height ?? 0, height),
+                };
+                if (prev !== undefined && next.width === prev.width && next.height === prev.height) {
+                    return prev;
+                }
+                return next;
+            });
+        };
+        if (typeof ResizeObserver === "undefined") {
+            // Environment without ResizeObserver: single static measurement.
+            const rect = el.getBoundingClientRect();
+            grow(rect.width, rect.height);
+            return;
+        }
+        const observer = new ResizeObserver((entries) => {
+            for (const entry of entries) {
+                const box = entry.contentBoxSize[0];
+                if (box !== undefined) {
+                    grow(box.inlineSize, box.blockSize);
+                }
+                else {
+                    grow(entry.contentRect.width, entry.contentRect.height);
+                }
+            }
+        });
+        observer.observe(el);
+        return () => {
+            observer.disconnect();
+        };
+    }, []);
+    return { ref, size };
+}
+//# sourceMappingURL=useImageSlot.js.map

package/dist/useImageSlot.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useImageSlot.js","sourceRoot":"","sources":["../src/useImageSlot.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAcpD;;;;;;;;;GASG;AACH,MAAM,UAAU,YAAY;IAC1B,MAAM,GAAG,GAAG,MAAM,CAAI,IAAI,CAAC,CAAC;IAC5B,MAAM,CAAC,IAAI,EAAE,OAAO,CAAC,GAAG,QAAQ,CAA4B,SAAS,CAAC,CAAC;IAEvE,SAAS,CAAC,GAAG,EAAE;QACb,MAAM,EAAE,GAAG,GAAG,CAAC,OAAO,CAAC;QACvB,IAAI,EAAE,KAAK,IAAI,EAAE,CAAC;YAChB,OAAO;QACT,CAAC;QAED,MAAM,IAAI,GAAG,CAAC,KAAa,EAAE,MAAc,EAAQ,EAAE;YACnD,IAAI,KAAK,IAAI,CAAC,IAAI,MAAM,IAAI,CAAC,EAAE,CAAC;gBAC9B,OAAO;YACT,CAAC;YACD,OAAO,CAAC,CAAC,IAAI,EAAE,EAAE;gBACf,MAAM,IAAI,GAAG;oBACX,KAAK,EAAE,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,IAAI,CAAC,EAAE,KAAK,CAAC;oBACxC,MAAM,EAAE,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,MAAM,IAAI,CAAC,EAAE,MAAM,CAAC;iBAC5C,CAAC;gBACF,IAAI,IAAI,KAAK,SAAS,IAAI,IAAI,CAAC,KAAK,KAAK,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,MAAM,KAAK,IAAI,CAAC,MAAM,EAAE,CAAC;oBACnF,OAAO,IAAI,CAAC;gBACd,CAAC;gBACD,OAAO,IAAI,CAAC;YACd,CAAC,CAAC,CAAC;QACL,CAAC,CAAC;QAEF,IAAI,OAAO,cAAc,KAAK,WAAW,EAAE,CAAC;YAC1C,iEAAiE;YACjE,MAAM,IAAI,GAAG,EAAE,CAAC,qBAAqB,EAAE,CAAC;YACxC,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;YAC9B,OAAO;QACT,CAAC;QAED,MAAM,QAAQ,GAAG,IAAI,cAAc,CAAC,CAAC,OAAO,EAAE,EAAE;YAC9C,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;gBAC5B,MAAM,GAAG,GAAG,KAAK,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC;gBACpC,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;oBACtB,IAAI,CAAC,GAAG,CAAC,UAAU,EAAE,GAAG,CAAC,SAAS,CAAC,CAAC;gBACtC,CAAC;qBAAM,CAAC;oBACN,IAAI,CAAC,KAAK,CAAC,WAAW,CAAC,KAAK,EAAE,KAAK,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;gBAC1D,CAAC;YACH,CAAC;QACH,CAAC,CAAC,CAAC;QACH,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;QACrB,OAAO,GAAG,EAAE;YACV,QAAQ,CAAC,UAAU,EAAE,CAAC;QACxB,CAAC,CAAC;IACJ,CAAC,EAAE,EAAE,CAAC,CAAC;IAEP,OAAO,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC;AACvB,CAAC"}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@stapel/image",
+  "version": "0.1.0",
+  "description": "Stapel image rendering: tier/branch math for the CDN variant ladder (pickTier, limitingAxis, chooseVariant), slot measurement hook (useImageSlot), and a blur-up <Image> component with upgrade-only tier fetching.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/usestapel/stapel-react.git",
+    "directory": "packages/image"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src",
+    "tsconfig.json",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "lint": "eslint .",
+    "size": "size-limit"
+  },
+  "size-limit": [
+    {
+      "path": "dist/index.js",
+      "limit": "6 KB"
+    }
+  ],
+  "peerDependencies": {
+    "react": ">=19"
+  },
+  "devDependencies": {
+    "@size-limit/preset-small-lib": "^11.2.0",
+    "@testing-library/react": "^16.3.0",
+    "@types/react": "^19.1.0",
+    "@types/react-dom": "^19.1.0",
+    "jsdom": "^26.1.0",
+    "react": "^19.1.0",
+    "react-dom": "^19.1.0",
+    "size-limit": "^11.2.0",
+    "typescript": "^5.8.3",
+    "vitest": "^3.2.4"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/Image.tsx

@@ -0,0 +1,152 @@
+import { useEffect, useMemo, useRef, useState } from "react";
+import type { CSSProperties, ImgHTMLAttributes, ReactElement } from "react";
+import { chooseVariant } from "./tiers.js";
+import type { Fit, RenderMetadata, VariantMeta } from "./tiers.js";
+import { useImageSlot } from "./useImageSlot.js";
+
+export interface ImageProps
+  extends Omit<ImgHTMLAttributes<HTMLImageElement>, "src" | "srcSet" | "alt"> {
+  meta: RenderMetadata;
+  /** Default `"cover"` (chat/catalog/avatar — fill the slot). */
+  fit?: Fit;
+  /** Required, no default. */
+  alt: string;
+}
+
+const FILL: CSSProperties = {
+  position: "absolute",
+  inset: 0,
+  width: "100%",
+  height: "100%",
+};
+
+/**
+ * CDN-ladder-aware image (images-and-cdn.md §4):
+ *
+ * 1. `aspect-ratio` from metadata goes on the container BEFORE the first slot
+ *    measurement — layout-shift protection entirely from the snapshot, no
+ *    network round-trip.
+ * 2. Blur-up: the inlined 16px `preview_b64` renders instantly underneath
+ *    until the chosen tier has decoded.
+ * 3. `useImageSlot()` measures the actual slot → `chooseVariant(...)` → src.
+ * 4. Upgrades only: a re-measure that picks a variant no bigger than the one
+ *    already rendered is ignored; a bigger pick loads off-DOM and swaps in
+ *    only after `decode()` — never a flash of empty slot, never a downgrade.
+ */
+export function Image({
+  meta,
+  fit = "cover",
+  alt,
+  style,
+  className,
+  ...imgProps
+}: ImageProps): ReactElement {
+  const { ref, size } = useImageSlot<HTMLDivElement>();
+
+  const [displayed, setDisplayed] = useState<VariantMeta | undefined>(undefined);
+  const [visible, setVisible] = useState(false);
+  const displayedRef = useRef<VariantMeta | undefined>(undefined);
+
+  const target = useMemo(() => {
+    if (size === undefined || size.width <= 0 || size.height <= 0) {
+      return undefined;
+    }
+    if (meta.variants.length === 0) {
+      return undefined;
+    }
+    const dpr = typeof window === "undefined" ? 1 : window.devicePixelRatio || 1;
+    return chooseVariant(
+      {
+        slotWidthCss: size.width,
+        slotHeightCss: size.height,
+        dpr,
+        imgAspect: meta.aspect,
+        fit,
+      },
+      meta
+    );
+  }, [size, meta, fit]);
+
+  useEffect(() => {
+    if (target === undefined) {
+      return;
+    }
+    const current = displayedRef.current;
+    // Upgrade only (§4): never replace an already-rendered variant with an
+    // equal or smaller one (resize jitter, transient shrink).
+    if (current !== undefined && target.width * target.height <= current.width * current.height) {
+      return;
+    }
+    let cancelled = false;
+    const loader = document.createElement("img");
+    const commit = (): void => {
+      if (cancelled) {
+        return;
+      }
+      displayedRef.current = target;
+      setDisplayed(target);
+    };
+    loader.src = target.url;
+    if (typeof loader.decode === "function") {
+      // Swap only after decode — no blank frame during the upgrade.
+      loader.decode().then(commit, commit);
+    } else {
+      loader.onload = commit;
+      loader.onerror = commit;
+    }
+    return () => {
+      cancelled = true;
+    };
+  }, [target]);
+
+  useEffect(() => {
+    if (displayed === undefined || visible) {
+      return;
+    }
+    // One frame at opacity 0 so the blur-up → sharp transition actually runs.
+    const id = requestAnimationFrame(() => {
+      setVisible(true);
+    });
+    return () => {
+      cancelAnimationFrame(id);
+    };
+  }, [displayed, visible]);
+
+  const containerStyle: CSSProperties = {
+    position: "relative",
+    overflow: "hidden",
+    aspectRatio: String(meta.aspect),
+    ...style,
+  };
+
+  return (
+    <div ref={ref} className={className} style={containerStyle}>
+      {meta.preview_b64 !== undefined && (
+        <img
+          src={meta.preview_b64}
+          alt=""
+          aria-hidden="true"
+          style={{
+            ...FILL,
+            objectFit: fit,
+            filter: "blur(12px)",
+            transform: "scale(1.05)",
+          }}
+        />
+      )}
+      {displayed !== undefined && (
+        <img
+          {...imgProps}
+          src={displayed.url}
+          alt={alt}
+          style={{
+            ...FILL,
+            objectFit: fit,
+            opacity: visible ? 1 : 0,
+            transition: "opacity 200ms ease",
+          }}
+        />
+      )}
+    </div>
+  );
+}

package/src/index.ts

@@ -0,0 +1,17 @@
+// Pure tier/branch math (no DOM, no React).
+export { pickTier, limitingAxis, chooseVariant } from "./tiers.js";
+export type {
+  Branch,
+  ChooseVariantArgs,
+  Fit,
+  RenderMetadata,
+  VariantMeta,
+} from "./tiers.js";
+
+// Slot measurement (ResizeObserver, high-water-mark, SSR-safe).
+export { useImageSlot } from "./useImageSlot.js";
+export type { ImageSlot, ImageSlotSize } from "./useImageSlot.js";
+
+// Blur-up component over the ladder.
+export { Image } from "./Image.js";
+export type { ImageProps } from "./Image.js";

package/src/tiers.ts

@@ -0,0 +1,142 @@
+// Pure tier/branch math for the stapel-cdn variant ladder
+// (docs/pending/images-and-cdn.md §2-3, §5). No DOM, no React — unit-testable
+// against the owner's examples verbatim and reusable outside the component.
+
+/** One generated variant file of an image (images-and-cdn.md §5). */
+export interface VariantMeta {
+  /** Ladder tier (px along the branch axis) or the untouched original. */
+  tier: number | "original";
+  /**
+   * `"w"` / `"h"` — preview-class branch (resize so that width/height == tier);
+   * `null` — thumbnail-class (min-side resize) and `"original"`.
+   */
+  branch: "w" | "h" | null;
+  url: string;
+  /** Actual pixel width of the file (after the no-upscale cap on native). */
+  width: number;
+  /** Actual pixel height of the file (after the no-upscale cap on native). */
+  height: number;
+}
+
+/**
+ * Immutable render-metadata snapshot produced on ingest by stapel-cdn (or the
+ * PIL provider) and resolved via `cdn.describe(ref)` — images-and-cdn.md §5,
+ * an additive extension of the chat-design.md attachment snapshot.
+ */
+export interface RenderMetadata {
+  mime: string;
+  bytes: number;
+  width: number;
+  height: number;
+  /** width / height. */
+  aspect: number;
+  /** Video/audio duration; `null`/absent for still images. */
+  duration_ms?: number | null;
+  /** `data:image/webp;base64,...` — the 16px micro tier, blur-up placeholder. */
+  preview_b64?: string;
+  /** `true` ⇒ w/h branches are identical; `variants[].branch` is irrelevant (§3.3). */
+  square?: boolean;
+  variants: VariantMeta[];
+}
+
+export type Fit = "cover" | "contain";
+
+export type Branch = "w" | "h";
+
+/**
+ * Smallest tier that does not upscale beyond the ×1.1 tolerance (§2.2):
+ * the smallest `T` in `tiers` with `neededPx ≤ T × 1.1`; if none qualifies,
+ * the largest tier (upscaling is forbidden at this level too — past the
+ * ladder the consumer falls back to "original", see `chooseVariant`).
+ *
+ * `neededPx` must already include DPR (`cssSize × devicePixelRatio`).
+ */
+export function pickTier(neededPx: number, tiers: readonly number[]): number {
+  if (tiers.length === 0) {
+    throw new TypeError("pickTier: tiers must be non-empty");
+  }
+  const sorted = [...tiers].sort((a, b) => a - b);
+  for (const tier of sorted) {
+    if (neededPx <= tier * 1.1) {
+      return tier;
+    }
+  }
+  return sorted[sorted.length - 1] as number;
+}
+
+/**
+ * Which axis of the slot limits the pixel budget (§3.5, mode Б):
+ * `cover` scales by `max(slotW/imgW, slotH/imgH)` — the limiting side is the
+ * one where the image is "narrower" relative to the slot; `contain` is the
+ * exact opposite. Tie-break on aspect equality is "w" (branches equivalent).
+ */
+export function limitingAxis(imgAspect: number, slotAspect: number, fit: Fit): Branch {
+  if (imgAspect === slotAspect) {
+    return "w";
+  }
+  const imageWiderThanSlot = imgAspect > slotAspect;
+  if (fit === "cover") {
+    return imageWiderThanSlot ? "h" : "w";
+  }
+  return imageWiderThanSlot ? "w" : "h";
+}
+
+export interface ChooseVariantArgs {
+  slotWidthCss: number;
+  slotHeightCss: number;
+  dpr: number;
+  /** width / height of the image — from metadata, known before any pixel loads. */
+  imgAspect: number;
+  fit: Fit;
+}
+
+/**
+ * Full selection (§3.5): limiting axis from (image aspect × slot aspect × fit),
+ * needed pixels along that axis (CSS × DPR), then the smallest non-upscaling
+ * tier among the variants that can serve that axis:
+ *
+ * - branch === axis — the matching preview branch;
+ * - branch === null (numeric tier) — thumbnail-class min-side variants, whose
+ *   BOTH sides are ≥ tier, so they serve either axis;
+ * - `meta.square` — any branch (w/h identical, §3.3).
+ *
+ * Past the top of the ladder (needed > maxTier × 1.1) the "original" variant
+ * is returned when present — no tier would avoid an upscale (§2.2).
+ */
+export function chooseVariant(args: ChooseVariantArgs, meta: RenderMetadata): VariantMeta {
+  const { slotWidthCss, slotHeightCss, dpr, imgAspect, fit } = args;
+  const slotAspect = slotWidthCss / slotHeightCss;
+  const axis = limitingAxis(imgAspect, slotAspect, fit);
+  const neededPx = (axis === "w" ? slotWidthCss : slotHeightCss) * dpr;
+
+  const square = meta.square === true;
+  const candidates = meta.variants.filter(
+    (v): v is VariantMeta & { tier: number } =>
+      typeof v.tier === "number" && (square || v.branch === null || v.branch === axis)
+  );
+  const original = meta.variants.find((v) => v.tier === "original");
+
+  if (candidates.length === 0) {
+    if (original !== undefined) {
+      return original;
+    }
+    throw new TypeError("chooseVariant: metadata has no usable variants");
+  }
+
+  const tiers = [...new Set(candidates.map((v) => v.tier))];
+  const maxTier = Math.max(...tiers);
+  if (neededPx > maxTier * 1.1 && original !== undefined) {
+    return original;
+  }
+
+  const tier = pickTier(neededPx, tiers);
+  const exact = candidates.find((v) => v.tier === tier && v.branch === axis);
+  if (exact !== undefined) {
+    return exact;
+  }
+  const minSide = candidates.find((v) => v.tier === tier && v.branch === null);
+  if (minSide !== undefined) {
+    return minSide;
+  }
+  return candidates.find((v) => v.tier === tier) as VariantMeta;
+}

package/src/useImageSlot.ts

@@ -0,0 +1,75 @@
+import { useEffect, useRef, useState } from "react";
+import type { RefObject } from "react";
+
+export interface ImageSlotSize {
+  width: number;
+  height: number;
+}
+
+export interface ImageSlot<T extends HTMLElement = HTMLElement> {
+  ref: RefObject<T | null>;
+  /** `undefined` until mounted and first measured (SSR-safe, useBreakpoint pattern). */
+  size: ImageSlotSize | undefined;
+}
+
+/**
+ * Measures the rendered slot of an element with a ResizeObserver
+ * (images-and-cdn.md §4). SSR-safe: `size` is `undefined` until mounted, so
+ * server and first client render agree.
+ *
+ * High-water-mark per axis: the reported size only ever GROWS. A transient
+ * shrink (splitter drag, viewport resize down, sidebar toggle) must not
+ * re-pick a smaller, already-loaded tier — upgrades only (§4 "докачка только
+ * вверх").
+ */
+export function useImageSlot<T extends HTMLElement = HTMLElement>(): ImageSlot<T> {
+  const ref = useRef<T>(null);
+  const [size, setSize] = useState<ImageSlotSize | undefined>(undefined);
+
+  useEffect(() => {
+    const el = ref.current;
+    if (el === null) {
+      return;
+    }
+
+    const grow = (width: number, height: number): void => {
+      if (width <= 0 && height <= 0) {
+        return;
+      }
+      setSize((prev) => {
+        const next = {
+          width: Math.max(prev?.width ?? 0, width),
+          height: Math.max(prev?.height ?? 0, height),
+        };
+        if (prev !== undefined && next.width === prev.width && next.height === prev.height) {
+          return prev;
+        }
+        return next;
+      });
+    };
+
+    if (typeof ResizeObserver === "undefined") {
+      // Environment without ResizeObserver: single static measurement.
+      const rect = el.getBoundingClientRect();
+      grow(rect.width, rect.height);
+      return;
+    }
+
+    const observer = new ResizeObserver((entries) => {
+      for (const entry of entries) {
+        const box = entry.contentBoxSize[0];
+        if (box !== undefined) {
+          grow(box.inlineSize, box.blockSize);
+        } else {
+          grow(entry.contentRect.width, entry.contentRect.height);
+        }
+      }
+    });
+    observer.observe(el);
+    return () => {
+      observer.disconnect();
+    };
+  }, []);
+
+  return { ref, size };
+}

package/tsconfig.json

@@ -0,0 +1,26 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "_comment": "Self-contained on purpose: standalone-buildable per frontend-standard §7. Mirrors the root tsconfig.base.json settings.",
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "jsx": "react-jsx",
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true,
+    "exactOptionalPropertyTypes": true,
+    "isolatedModules": true,
+    "isolatedDeclarations": true,
+    "verbatimModuleSyntax": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src"]
+}