@orangelogic/design-system 2.190.0 → 2.192.0

package/library/components/video.js

@@ -1,7 +1,7 @@
 import { _ as kd, a as Sa, b as Be, c as Je } from "../chunks/inheritsLoose.BuSn_CvZ.js";
 import { c as ps, a as Bn } from "../chunks/_commonjsHelpers.DQNKXVTB.js";
 import { r as Sb } from "../chunks/___vite-browser-external_commonjs-proxy.C2tf3HsQ.js";
-import { C as Cb } from "../chunks/image.CTMzUqCC.js";
+import { C as Cb } from "../chunks/image.CiQwSDfe.js";
 import Mb from "./resize-observer.js";
 import { r as Db, R as Pb, a as Rp, b as Lb } from "../chunks/resizable-component.styles.CAfXABBc.js";
 import { c as Rb } from "../chunks/component.styles.CRO4Odto.js";

package/library/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@orangelogic/design-system",
   "type": "module",
-  "version": "2.190.0",
+  "version": "2.192.0",
   "license": "UNLICENSED",
   "types": "library/types.d.ts",
   "scripts": {

package/library/packages/atoms/src/components/image/image.d.ts

@@ -9,15 +9,18 @@ import { default as CxPopup } from '../popup/popup';
 import { default as CxResizeObserver } from '../resize-observer/resize-observer';
 import { default as CxSkeleton } from '../skeleton/skeleton';
 import { default as CxSpace } from '../space/space';
-import { default as CxSpinner } from '../spinner/spinner';
 
 /**
  * @summary Images are wrappers for img elements with built-in lazy loading, skeleton, and fallback support.
  * The cx-image component is a simple way to display images in your application.
  *
+ * @description Set `srcset` and `sizes` to let the browser download and decode only the
+ * pixels the layout needs. This is what bounds memory on image-heavy pages: a large
+ * original decodes to `naturalWidth × naturalHeight × 4` bytes no matter how small it
+ * is displayed, so many full-resolution images on one page can exhaust the renderer.
+ *
  * @csspart image - The `img` element.
- * @csspart skeleton - The skeleton element, will be shown while the image is loading and the `skeleton` property is set.
- * @csspart retry-spinner - The spinner overlay shown while a failed load is being retried (when `retry-on-error` is enabled).
+ * @csspart skeleton - The skeleton element, shown while the image is loading (including while a failed load is being retried) and the `skeleton` property is set.
  * @csspart fallback - The fallback element, always shown when the image fails to load (after retries, when applicable).
  * @csspart base - The component’s outer wrapper.
  * @csspart fallback-icon - The icon rendered inside the fallback slot.
@@ -48,7 +51,6 @@ export default class CxImage extends ResizableElement {
         'cx-resize-observer': typeof CxResizeObserver;
         'cx-skeleton': typeof CxSkeleton;
         'cx-space': typeof CxSpace;
-        'cx-spinner': typeof CxSpinner;
     };
     readonly localize: LocalizeController;
     imageElement?: HTMLImageElement;
@@ -66,6 +68,21 @@ export default class CxImage extends ResizableElement {
      * The path to the image to load.
      */
     src: string;
+    /**
+     * Candidate sources for the underlying `<img>`, as a standard `srcset` value
+     * (e.g. `"…/re_w_400/img.jpg 400w, …/re_w_800/img.jpg 800w"`).
+     *
+     * Lets the browser fetch and decode only the pixels the layout needs, which is what
+     * bounds memory on image-heavy pages — a large original decodes to
+     * `naturalWidth × naturalHeight × 4` bytes regardless of its display size.
+     * Pair with `sizes`; without it the browser assumes the image is `100vw` wide.
+     */
+    srcset: string;
+    /**
+     * The `sizes` attribute for the underlying `<img>`, describing the rendered width
+     * (e.g. `"400px"`). Only meaningful together with `srcset`.
+     */
+    sizes: string;
     /**
      * The path to the placeholder image to be shown if src is not available.
      */
@@ -122,6 +139,12 @@ export default class CxImage extends ResizableElement {
     retryOnError: boolean;
     /**
      * Maximum number of retry attempts when `retry-on-error` is enabled.
+     *
+     * Set high enough to outlast a transient backend overload: a page full of images
+     * can push the transform service into 503s, and those images need to keep retrying
+     * until it recovers rather than falling back to a broken-image icon. The backoff is
+     * exponential and capped at 10s per attempt, so the attempts spread out instead of
+     * adding to the load.
      */
     maxRetries: number;
     /**
@@ -151,6 +174,15 @@ export default class CxImage extends ResizableElement {
     };
     /** The crossorigin value for the `<img>`; `undefined` (attribute omitted) when `noCrossorigin` is set. */
     get crossorigin(): string | undefined;
+    /**
+     * Whether to hold the box with a skeleton rather than the loaded image.
+     *
+     * Retries are included: a retry is still "not loaded yet", so it keeps the same
+     * skeleton instead of swapping in a spinner. A spinner would restate what the
+     * skeleton already shows while changing the visual weight of the cell mid-load,
+     * which reads as a layout change on an image-heavy page.
+     */
+    protected get showPlaceholderSkeleton(): boolean;
     /**
      * Whether the image have zoom action.
      */

package/library/packages/atoms/src/components/popup/popup.d.ts

@@ -42,6 +42,16 @@ export default class CxPopup extends CortexElement {
     static styles: CSSResultGroup;
     private anchorEl;
     private cleanup;
+    /**
+     * Set when the element disconnects, cleared when it reconnects.
+     *
+     * `start()` is debounced, so a pending invocation can still run after
+     * `disconnectedCallback()` has already executed `stopImmediate()` — at which
+     * point nothing is left to release the `autoUpdate()` listeners it registers
+     * on `window`. Checked alongside `isConnected`, which a popup inside a shadow
+     * tree that is discarded as a whole can still report as `true`.
+     */
+    private isTornDown;
     private readonly localize;
     /** A reference to the internal popup container. Useful for animating and styling the popup with JavaScript. */
     popup: HTMLElement;
@@ -172,6 +182,7 @@ export default class CxPopup extends CortexElement {
      */
     autoWidthFactor: number;
     private get isSizeMiddleWareUsed();
+    connectedCallback(): void;
     disconnectedCallback(): void;
     connectedUpdatedCallback(): void;
     updated(changedProps: Map<string, unknown>): Promise<void>;

package/library/packages/atoms/src/components/select/select.d.ts

@@ -68,6 +68,13 @@ export default class CxSelect extends CortexElement implements CortexFormControl
     private readonly localize;
     private typeToSelectString;
     private closeWatcher;
+    /**
+     * The root node the `focusin` listener was attached to, captured at attach
+     * time. `getRootNode()` returns a different node once the element is
+     * detached, so re-calling it during cleanup would fail to remove the
+     * listener that was actually added.
+     */
+    private openListenersRoot;
     popup: CxPopup;
     combobox: HTMLSlotElement;
     displayInput: HTMLInputElement;
@@ -310,6 +317,7 @@ export default class CxSelect extends CortexElement implements CortexFormControl
      */
     filterCallback(option: HTMLElement, value: string): boolean;
     connectedCallback(): void;
+    disconnectedCallback(): void;
     runFirstUpdated(): void;
     private addOpenListeners;
     private removeOpenListeners;

package/library/packages/events/src/cx-asset-transformation-dialog-confirm.d.ts

@@ -2,6 +2,8 @@ import { Transformation } from '../../types/src/asset-link-format';
 
 export type CxAssetTransformationDialogConfirmEvent = CustomEvent<{
     format: string;
+    /** False when the format follows the asset's file extension instead of an explicit pick. */
+    manualFormat: boolean;
     transformations: Transformation[];
 }>;
 declare global {

package/library/packages/molecules/src/asset-picker/asset-picker.d.ts

@@ -57,6 +57,13 @@ export default class CxAssetPicker extends CortexElement {
      * other type are rejected on confirmation. When false, `type` only pre-fills the filter.
      */
     restrict: boolean;
+    /**
+     * Asset types whose original `src` is used as-is, bypassing the API's
+     * representative (thumbnail/preview) URL. Only images are renderable
+     * directly, so every other type — video, audio, documents — falls back to its
+     * representative when the API returns one.
+     */
+    noRepresentativeFor: AssetType[];
     /**
      * A callback function that is called when the user requests to select an asset.
      * It should return a promise that resolves to an Asset object.
@@ -78,8 +85,20 @@ export default class CxAssetPicker extends CortexElement {
     handleValueChange(): Promise<void>;
     handleRecordIdChange(): Promise<void>;
     private handleDeleteClick;
-    /** True when the picker accepts this asset type. */
+    /** True when the picker accepts this asset type. `all` accepts every type. */
     private acceptsType;
+    /**
+     * Resolves the URL a consumer should render as the selected asset's preview.
+     * Types listed in `noRepresentativeFor` keep their original `src`; all other
+     * types prefer the representative and fall back to `src` when the API did not
+     * return one. `src` itself is always emitted unchanged so consumers that need
+     * the original file keep access to it.
+     *
+     * `type` is optional because it originates from the host app's
+     * `onRequestAsset` callback and can be absent at runtime; an asset with no
+     * type prefers its representative.
+     */
+    resolvePreviewSrc(asset: Pick<Asset, 'representative' | 'src'> & Partial<Pick<Asset, 'type'>>): string;
     private renderAssetPreview;
     render(): import('lit').TemplateResult<1>;
 }

package/library/packages/molecules/src/cropper/cropper.d.ts

@@ -28,7 +28,6 @@ export default class CxCropper extends CortexElement {
     image: {
         extension: string;
         height: number;
-        originalUrl: string;
         rotation: number;
         url: string;
         width: number;

package/library/packages/molecules/src/cropper/react/Cropper.d.ts

@@ -17,7 +17,6 @@ type Props = {
     image: {
         extension: string;
         height: number;
-        originalUrl: string;
         rotation: number;
         url: string;
         width: number;

package/library/packages/molecules/src/gallery-item/gallery-item.d.ts

@@ -85,6 +85,16 @@ export default class CxGalleryItem extends HighlightableElement {
      * The source of the image.
      */
     src: string | undefined;
+    /**
+     * Candidate sources forwarded to the inner `<cx-image>` as a standard `srcset` value,
+     * so the browser downloads and decodes only the pixels the grid cell needs.
+     */
+    srcset: string;
+    /**
+     * The rendered width forwarded to the inner `<cx-image>` as `sizes` (e.g. `"400px"`).
+     * Only meaningful together with `srcset`.
+     */
+    sizes: string;
     /**
      * The alt text for the image.
      */

package/library/packages/molecules/src/masonry/masonry.d.ts

@@ -59,6 +59,19 @@ export default class CxMasonry extends CortexElement {
      * The key to use for the id of the items in the masonry layout.
      */
     idKey: keyof MasonryItem;
+    /**
+     * The proxy format the item images were resolved with.
+     *
+     * Only used to decide whether a `srcset` may be generated: an original-file format
+     * paired with an animated source must be delivered untouched.
+     */
+    format: string;
+    /**
+     * Whether `format` was picked by hand. When false each item's format follows its own
+     * file extension instead, so a mixed list can serve animated originals and resizable
+     * raster proxies side by side.
+     */
+    manualFormat: boolean;
     /**
      * When true, forwards `no-crossorigin` to each inner `<cx-image>`, disabling CORS mode
      * (e.g. in Site Builder contexts where CORS headers are absent).
@@ -81,6 +94,17 @@ export default class CxMasonry extends CortexElement {
     handleSortableChange(): void;
     connectedUpdatedCallback(): void;
     disconnectedCallback(): void;
+    /**
+     * The `sizes` hint for item images, expressed as a viewport fraction.
+     *
+     * The layout is CSS-column based, so no exact pixel width is available the way a
+     * measured grid provides one. Each item spans exactly one of `cols` columns, which
+     * makes the fraction an accurate upper bound and keeps the browser from assuming
+     * the default `100vw`.
+     */
+    private get itemSizes();
+    /** The format one item is served under: the configured one, or derived from its extension. */
+    private resolveItemFormat;
     handleItemClick(event: MouseEvent, item: MasonryItem): void;
     handleSortableUpdate(event: Sortable.SortableEvent): void;
     renderActions(item: MasonryItem): import('lit').TemplateResult<1>;

package/library/packages/organisms/src/asset-link-format/asset-link-format.d.ts

@@ -111,6 +111,18 @@ export default class CxAssetLinkFormat extends CortexElement {
      * This is a string that represents the ID of the selected proxy format from the list of available proxies.
      */
     defaultProxy: string;
+    /**
+     * Whether the format listbox offers an `Auto` entry, which derives the proxy from the
+     * asset's file extension instead of the author naming one.
+     */
+    canAutoFormat: boolean;
+    /**
+     * Whether `Auto` is the current choice.
+     *
+     * Tracked next to `selectedProxy` rather than encoded into it, so `selectedProxy` stays
+     * a real proxy id for every consumer that reads it — only the origin of that id differs.
+     */
+    autoFormat: boolean;
     useCustomExtension: boolean;
     noMetadata: boolean;
     noFormat: boolean;
@@ -133,13 +145,12 @@ export default class CxAssetLinkFormat extends CortexElement {
     activeSetting: string;
     /**
      * The currently selected format for the asset link.
-     * This is an object that contains details about the selected format, such as `extension`, `height`, `keepMetadata`, `originalUrl`, `proxyUrl`, `quality`, `rotation`, `url`, `width`, `x`, and `y`.
+     * This is an object that contains details about the selected format, such as `extension`, `height`, `keepMetadata`, `proxyUrl`, `quality`, `rotation`, `url`, `width`, `x`, and `y`.
      */
     selectedFormat: {
         extension: string;
         height: number;
         keepMetadata: boolean;
-        originalUrl: string;
         quality: number;
         rotation: number;
         url: string;
@@ -194,6 +205,10 @@ export default class CxAssetLinkFormat extends CortexElement {
     private frozenIndex;
     /** Snapshot saved on Reset to allow one Undo step back to the pre-reset state. */
     private preResetTransformations;
+    /** The `Auto` state saved alongside `preResetTransformations`, restored by the same Undo. */
+    private preResetAutoFormat;
+    /** The proxy saved alongside `preResetAutoFormat`, so Undo restores the pair together. */
+    private preResetSelectedProxy;
     /** True when there are transformations beyond the frozen index (i.e. user has added new ones). */
     private get hasUnfrozenTransformations();
     private apiGetTransformAssetLink;
@@ -319,6 +334,13 @@ export default class CxAssetLinkFormat extends CortexElement {
     private handleCropperElementChange;
     private handleCropperSelectorChange;
     private handleAssetChange;
+    /**
+     * The proxy id to fall back to when none is set or the current one is not in the list.
+     *
+     * Under `Auto` the asset's extension decides, so the first proxy in the list is only a
+     * last resort — used when the mapped format is not offered for this asset.
+     */
+    private resolveFallbackProxyId;
     private handleProxiesChange;
     handleSelectedProxyChange(oldValue: unknown): Promise<void>;
     handleLoadingChange(): void;
@@ -332,6 +354,14 @@ export default class CxAssetLinkFormat extends CortexElement {
     private onCropDragStart;
     private onDetailsShow;
     private onDetailsHide;
+    /**
+     * The proxy id that `Auto` resolves to for the current asset, or `''` when the mapped
+     * format is not among the available proxies.
+     *
+     * `resolveAutoFormat` yields a proxy *name* (`TRX` / `TR1`) while `selectedProxy` holds
+     * a proxy *id*, so the name has to be looked up in `proxies` rather than used directly.
+     */
+    private get autoResolvedProxyId();
     private onProxyChange;
     private onCropModeChange;
     private onCropFocusModeChange;
@@ -347,6 +377,20 @@ export default class CxAssetLinkFormat extends CortexElement {
     private onMetadataChange;
     private onExtensionChange;
     private syncQuality;
+    /**
+     * Whether there is anything for Reset to undo.
+     *
+     * Transformations are one way to diverge from the defaults; leaving `Auto` for an
+     * explicit format is another, and Reset is what puts that back.
+     */
+    private get hasResettableState();
+    /**
+     * Drops the one-step Reset snapshot.
+     *
+     * Called whenever the user applies a new transformation: at that point Undo means
+     * "remove that transformation", not "go back to before the Reset".
+     */
+    private clearResetSnapshot;
     private handleUndo;
     private handleReset;
     render(): TemplateResult;

package/library/packages/organisms/src/asset-link-format/components/asset-link-format-proxy/asset-link-format-proxy.d.ts

@@ -1,5 +1,6 @@
 import { default as CxButton } from '../../../../../atoms/src/components/button/button.ts';
 import { default as CxDetails } from '../../../../../atoms/src/components/details/details.ts';
+import { default as CxDivider } from '../../../../../atoms/src/components/divider/divider.ts';
 import { default as CxIcon } from '../../../../../atoms/src/components/icon/icon.ts';
 import { default as CxOption } from '../../../../../atoms/src/components/option/option.ts';
 import { default as CxSelect } from '../../../../../atoms/src/components/select/select.ts';
@@ -9,7 +10,23 @@ import { default as CortexElement } from '../../../../../base/src/cortex-element
 import { Proxy } from '../../../../../types/src/asset-link-format';
 import { CSSResultGroup, TemplateResult } from 'lit';
 
-export type CxAssetLinkFormatProxyChangeEvent = CustomEvent<Proxy>;
+/**
+ * Listbox value for the `Auto` entry. Not a proxy id — no `Proxy` can ever carry it, so it
+ * is safe to distinguish the two cases by comparing against this constant.
+ */
+export declare const AUTO_FORMAT_OPTION_VALUE = "auto";
+/**
+ * Either a named proxy or the `Auto` choice.
+ *
+ * `Auto` carries no proxy: this component does not own the asset, so it cannot resolve
+ * which format the extension maps to. The parent does that and sets `selectedProxy`.
+ */
+export type CxAssetLinkFormatProxyChangeDetail = (Proxy & {
+    autoFormat?: false;
+}) | {
+    autoFormat: true;
+};
+export type CxAssetLinkFormatProxyChangeEvent = CustomEvent<CxAssetLinkFormatProxyChangeDetail>;
 /**
  * @summary The `cx-asset-link-format-proxy` component is used to select a proxy format for an asset link.
  *
@@ -20,6 +37,7 @@ export default class CxAssetLinkFormatProxy extends CortexElement {
     static readonly dependencies: {
         'cx-button': typeof CxButton;
         'cx-details': typeof CxDetails;
+        'cx-divider': typeof CxDivider;
         'cx-icon': typeof CxIcon;
         'cx-option': typeof CxOption;
         'cx-select': typeof CxSelect;
@@ -50,6 +68,18 @@ export default class CxAssetLinkFormatProxy extends CortexElement {
      * @default []
      */
     items: Proxy[];
+    /**
+     * Whether the listbox offers an `Auto` entry that derives the format from the asset's
+     * file extension instead of naming one.
+     * @default false
+     */
+    canAutoFormat: boolean;
+    /**
+     * Whether `Auto` is the current choice. Kept separate from `value` so the resolved
+     * format stays readable while the listbox still shows `Auto` as selected.
+     * @default false
+     */
+    autoFormat: boolean;
     /**
      * The loading state of the component.
      * This is used to indicate that an operation is in progress, such as applying a new quality value.
@@ -63,6 +93,11 @@ export default class CxAssetLinkFormatProxy extends CortexElement {
      * @default ''
      */
     scopedValue: string;
+    /**
+     * The listbox value that represents the committed choice: the `Auto` entry when that is
+     * active, otherwise the resolved proxy id.
+     */
+    private get committedValue();
     handleValueChange(): void;
     handleOpenChange(): void;
     private handleProxyChange;

package/library/packages/organisms/src/asset-transformation-dialog/asset-transformation-dialog.d.ts

@@ -20,7 +20,7 @@ import { default as CxAssetLinkFormat } from '../asset-link-format/asset-link-fo
  *   `cx-icon-button`. Automatically disabled when `asset-id` is not set.
  *
  * @event cx-asset-transformation-dialog-cancel - Emitted when the user closes or cancels the dialog.
- * @event {{ detail: { format: string; transformations: Transformation[] } }} cx-asset-transformation-dialog-confirm - Emitted when the user saves, with the selected proxy id and transformation array.
+ * @event {{ detail: { format: string; manualFormat: boolean; transformations: Transformation[] } }} cx-asset-transformation-dialog-confirm - Emitted when the user saves, with the resolved proxy id, whether that id was picked by hand rather than derived from the asset extension, and the transformation array.
  * @event cx-asset-transformation-dialog-delete - Emitted when the user resets the format to its default and clears the saved transformations via the reset button.
  */
 export default class CxAssetTransformationDialog extends CortexElement {
@@ -64,6 +64,11 @@ export default class CxAssetTransformationDialog extends CortexElement {
     format: string;
     /** The default format to fall back to if the asset has no transformations or selected proxy. */
     defaultFormat: string;
+    /**
+     * Whether the author picked the format by hand rather than letting it follow the asset's
+     * file extension. `false` (the default) means `Auto`.
+     */
+    manualFormat: boolean;
     /** Optional label rendered as the dialog title. Falls back to the localized "Asset format" term. */
     dialogLabel: string;
     /** The transformations applied when the user last saved, passed back into cx-asset-link-format on reopen. */
@@ -86,8 +91,21 @@ export default class CxAssetTransformationDialog extends CortexElement {
     private proxies;
     /** False while the authorization check is in flight or after it confirms no access. */
     private canAccess;
+    /**
+     * Whether the author changed anything away from the block's defaults, which is what the
+     * Reset control acts on.
+     *
+     * `Auto` is the default, so any manual format counts as an edit — including one that
+     * happens to resolve to the same proxy as `defaultFormat`. Comparing the codes instead
+     * would leave the author no way back to `Auto` from that format.
+     */
     private get hasTransformations();
-    /** Resolves the selected format code to its proxy label, falling back to the raw code. */
+    /**
+     * The label shown in the settings row.
+     *
+     * Under `Auto` the stored format is only what the extension happened to resolve to, so
+     * naming it would read as an explicit choice the author never made.
+     */
     private get resolvedFormatLabel();
     handleAssetIdChange(): Promise<void>;
     handleCanAccessChange(): void;

package/library/packages/organisms/src/bento-grid/bento-grid.d.ts

@@ -23,6 +23,13 @@ export default class CxBentoGrid extends CortexElement {
     static readonly styles: CSSResultGroup;
     /** Minimum scroll delta (px) required to trigger a virtual range update. */
     private static readonly SCROLL_THRESHOLD;
+    /**
+     * Longest a row may block the next release while waiting for its images.
+     *
+     * Bounds the adaptive wait so a hanging request or an image that never fires
+     * `load`/`error` cannot stall the remaining rows indefinitely.
+     */
+    private static readonly ROW_RELEASE_TIMEOUT;
     static readonly dependencies: {
         'cx-gallery-item': typeof CxGalleryItem;
         'cx-tooltip': typeof CxTooltip;
@@ -109,6 +116,31 @@ export default class CxBentoGrid extends CortexElement {
      * Unloaded slots are approximated as 1×1 items.
      */
     totalItems: number;
+    /**
+     * The proxy format the item images were resolved with.
+     *
+     * Only used to decide whether a `srcset` may be generated: an original-file format
+     * paired with an animated source must be delivered untouched.
+     */
+    format: string;
+    /**
+     * Whether `format` was picked by hand. When false each item's format follows its own
+     * file extension instead, so a mixed grid can serve animated originals and resizable
+     * raster proxies side by side.
+     */
+    manualFormat: boolean;
+    /**
+     * Delay in milliseconds between releasing one row of images and the next.
+     *
+     * Images are held back until their row is released, so the browser opens roughly one
+     * row's worth of requests at a time instead of one per rendered item. Each transform
+     * URL is an uncached backend render, and enough of them in parallel returns 503.
+     *
+     * A row also waits for the previous row's images to finish (capped by
+     * `ROW_RELEASE_TIMEOUT`), so this is the floor between releases rather than the exact
+     * cadence. Set to `0` to disable gating and let every rendered row load immediately.
+     */
+    rowReleaseDelay: number;
     /**
      * The show content type.
      */
@@ -198,6 +230,29 @@ export default class CxBentoGrid extends CortexElement {
     private virtualFirst;
     /** Inclusive index of the last item in the rendered virtual window. */
     private virtualLast;
+    /**
+     * Exclusive upper bound of the grid rows whose images are allowed to load.
+     *
+     * A row's worth of items entering the DOM together makes the browser open that many
+     * image requests at once, and each distinct transform URL is an uncached backend
+     * render — enough parallelism there returns 503. Releasing one row at a time keeps
+     * the request count bounded by the row width instead of the rendered range.
+     *
+     * `Infinity` disables gating entirely (see `rowReleaseDelay`).
+     */
+    private releasedRowCount;
+    /** Pending timer for the next row release; null when no release is scheduled. */
+    private rowReleaseTimer;
+    /**
+     * Images still loading in the most recently released row, by item index.
+     *
+     * The next row waits for this to drain so releases track real network progress
+     * rather than a fixed cadence, with `ROW_RELEASE_TIMEOUT` as the upper bound so a
+     * hanging or broken image cannot stall the rest of the grid.
+     */
+    private readonly pendingRowImages;
+    /** Guards against scheduling a release while one is already in flight. */
+    private isRowReleaseScheduled;
     private isTooltipShown;
     protected galleryItemTag: string;
     /**
@@ -249,6 +304,43 @@ export default class CxBentoGrid extends CortexElement {
     private computeLayout;
     /** Recalculates which items fall within the current scroll viewport. */
     private updateActiveRange;
+    /**
+     * Highest row index currently rendered, or -1 when nothing is rendered.
+     *
+     * Releases stop here rather than at the dataset's last row so scrolled-away rows are
+     * not fetched ahead of the ones the viewer is actually looking at.
+     */
+    private get lastRenderedRow();
+    /**
+     * Whether the item at `index` may load its image yet.
+     *
+     * Items in unreleased rows render their cell and skeleton but receive no `src`, which
+     * is what keeps the grid's shape stable while images fill in progressively.
+     */
+    protected isRowReleased(index: number): boolean;
+    /**
+     * Marks every rendered item in `row` as awaiting its image, synchronously.
+     *
+     * Runs in the same tick as the release so `scheduleRowRelease()` sees a non-empty
+     * set on its next call. Items without a `src` are skipped: they never fire
+     * `cx-load` / `cx-error`, so they would hold the queue open until the timeout.
+     */
+    private markRowImagesPending;
+    /**
+     * Clears an item from the in-flight set once its image settles (loaded or failed) and
+     * lets the next row through as soon as the row drains.
+     */
+    private handleItemImageSettled;
+    /**
+     * Queues the next row release, if one is warranted and not already pending.
+     *
+     * Waits `rowReleaseDelay` when the previous row has drained, or up to
+     * `ROW_RELEASE_TIMEOUT` when it has not, so a stuck image only delays the grid
+     * instead of stopping it.
+     */
+    private scheduleRowRelease;
+    /** Clears any pending release and resets the gate back to its initial state. */
+    private resetRowRelease;
     /**
      * Returns the index of the last item whose rowStart is within maxRows.
      */
@@ -291,6 +383,15 @@ export default class CxBentoGrid extends CortexElement {
      * changes on every computeLayout() call, including resize-driven reflows) or
      * the sync-row-content-height flag itself is toggled.
      */
+    /**
+     * Restarts row gating when the dataset shrinks or is replaced wholesale.
+     *
+     * Row indices refer to a specific layout, so keeping a release count across a new
+     * dataset would let its rows load all at once — the burst this gate exists to prevent.
+     * A dataset that only grew is treated as an appended page: the already-released rows
+     * still hold the same items, so their progress is kept and the new rows queue behind.
+     */
+    handleDataChangeForRowRelease(oldData?: unknown, newData?: unknown): void;
     handleRowContentHeightSync(): Promise<void>;
     /**
      * Get content position based on the size of the item.

package/library/packages/organisms/src/carousel/carousel.d.ts

@@ -72,6 +72,19 @@ export default class CxCarousel extends CortexElement {
      * The real total number of data in the carousel. Not affected by chunking.
      */
     totalData: number;
+    /**
+     * The proxy format the slide images were resolved with.
+     *
+     * Only used to decide whether a `srcset` may be generated: an original-file format
+     * paired with an animated source must be delivered untouched.
+     */
+    format: string;
+    /**
+     * Whether `format` was picked by hand. When false each slide's format follows its own
+     * file extension instead, so a mixed carousel can serve animated originals and
+     * resizable raster proxies side by side.
+     */
+    manualFormat: boolean;
     /**
      * When set, allows the user to navigate the carousel in the same direction indefinitely.
      */
@@ -257,6 +270,19 @@ export default class CxCarousel extends CortexElement {
     get selectedCarouselItem(): string;
     get canMoveCarouselItem(): boolean;
     get canDeleteCarouselItem(): boolean;
+    /**
+     * The `sizes` hint for slide images, derived from the slide layout rather than a
+     * measured width: the carousel sizes slides purely in CSS, so no pixel width is
+     * available at render time.
+     *
+     * Vertical carousels stack slides, so each one spans the full width regardless of
+     * `slidesPerPage` — only the horizontal layout divides the row.
+     *
+     * This uses the viewport rather than the carousel's own box, so a carousel rendered
+     * in a narrow column over-estimates and requests one ladder rung too large. That is
+     * still far better than the full-resolution original served without `sizes`.
+     */
+    private get slideSizes();
     constructor();
     connectedUpdatedCallback(): void;
     runFirstUpdated(): void;