@orangelogic/design-system 2.191.0 → 2.193.0

package/library/packages/organisms/src/content-builder/blocks/image/image.d.ts

@@ -41,12 +41,13 @@ export default class CxSbImage extends CxImage {
         'cx-resize-observer': typeof import('../../../../../atoms/src/index.ts').CxResizeObserver;
         'cx-skeleton': typeof import('../../../../../atoms/src/index.ts').CxSkeleton;
         'cx-space': typeof import('../../../../../atoms/src/index.ts').CxSpace;
-        'cx-spinner': typeof import('../../../../../atoms/src/index.ts').CxSpinner;
     };
     /**
      * Override the default behavior of retrying to load the image when it fails to load.
      */
     retryOnError: boolean;
+    /** Content-builder images keep their measured box visible while the asset loads. */
+    skeleton: boolean;
     /**
      * The path to the image to load in dark mode.
      */
@@ -87,6 +88,14 @@ export default class CxSbImage extends CxImage {
      * Asset transformation proxy format key for dark mode.
      */
     formatDarkMode: string;
+    /**
+     * Whether `format` was picked by hand. When false the format follows the asset's file
+     * extension instead, so an animated GIF keeps its original file and everything else
+     * takes the transcoded raster proxy that `srcset` is allowed to resize.
+     */
+    manualFormat: boolean;
+    /** Whether `formatDarkMode` was picked by hand. See `manualFormat`. */
+    manualFormatDarkMode: boolean;
     /**
      * Asset transformations applied to the image.
      */
@@ -162,6 +171,22 @@ export default class CxSbImage extends CxImage {
     private resolvedSrc;
     /** Fresh URL re-resolved when the stored `srcDarkMode` has expired. */
     private resolvedSrcDarkMode;
+    /**
+     * The asset's file extension. Lets an animated GIF opt out of `srcset`, which a
+     * server-side resize would flatten to a still frame.
+     */
+    private assetExtension;
+    /** Width of the proxy currently displayed; caps `srcset` so it never asks to upscale. */
+    private assetProxyWidth;
+    /**
+     * Whether an asset fetch has reported back for the current record.
+     *
+     * Tracked separately from `assetExtension` because "no extension" is a legitimate
+     * answer — a missing asset or a record without the field both yield an empty string.
+     * Gating on the empty string alone would hold `srcset` back forever in those cases;
+     * gating on this flag releases it as soon as the answer is in, whatever it says.
+     */
+    private hasResolvedAssetExtension;
     /**
      * Space list supplied by `cx-content-builder-viewer`, which fetches it once per
      * surface. The only source — this block never fetches the list itself.
@@ -192,6 +217,24 @@ export default class CxSbImage extends CxImage {
     get currentRecordId(): string;
     get currentSrc(): string;
     get currentTransformations(): Transformation[];
+    /** Whether the variant being displayed had its format picked by hand. */
+    get isCurrentFormatManual(): boolean;
+    /**
+     * The proxy format of the variant actually being displayed.
+     *
+     * Under `Auto` the asset's extension decides, so this stays a real proxy name and every
+     * consumer — the transformation URL and `srcset` alike — reads the same resolved value.
+     */
+    get currentFormat(): string;
+    /**
+     * Fields the child `cx-asset-data-display` must fetch for this block.
+     *
+     * The extension is always requested rather than only for the format that can serve
+     * an animated original. Requesting it unconditionally keeps the fetch shape stable
+     * (it does not change when the author switches format) and means `srcset` never has
+     * to wait on a follow-up fetch to learn whether this asset may be resized.
+     */
+    private get requestedAssetFields();
     get highlighterTabindex(): "0" | undefined;
     get highlighterRole(): "button" | "img";
     get highlighterClass(): {
@@ -214,10 +257,25 @@ export default class CxSbImage extends CxImage {
      * Whether the image has an click action.
      */
     private get hasClickAction();
+    /**
+     * The rendered width in CSS pixels, used as the `sizes` hint so the browser can pick
+     * the smallest `srcset` candidate that still covers the box.
+     *
+     * A `%` width carries no pixel value, so the measured `clientWidth` is used instead.
+     * Returns 0 when neither is known yet (before first layout), which makes the caller
+     * omit `sizes` and fall back to the browser's default `100vw` assumption.
+     */
+    private get displayWidth();
     handleClickActionChange(): Promise<void>;
     handleClickSpaceChange(): void;
     handleObjectFitChange(): Promise<void>;
     handleSrcChange(): void;
+    /**
+     * Drops a cached extension once the asset it described is replaced, so a new record
+     * cannot inherit the previous one's answer about whether it may be resized — nor its
+     * resolved flag, which would let `srcset` be built before the new answer arrives.
+     */
+    handleRecordIdChangeForExtension(): void;
     handleFetchedAssetDataChange(): void;
     /**
      * Support CMS5 click action for the image.
@@ -230,6 +288,14 @@ export default class CxSbImage extends CxImage {
      * own `cx-asset-data-display` fetch) into alt text and overlay content.
      */
     private applyFetchedAssetData;
+    /**
+     * Captures the asset's extension from a fetch result and marks the answer as in.
+     *
+     * A blank value leaves any previously known extension in place — a response that
+     * omitted the field says nothing about the asset — but still resolves the wait, so a
+     * record whose extension never arrives does not block `srcset` indefinitely.
+     */
+    private applyExtensionFromAssetData;
     /**
      * A stored space URL breaks once the space moves domain, so the link target is
      * re-resolved against the list the viewer supplies. Without that list the stored

package/library/packages/organisms/src/content-builder/blocks/video/video.d.ts

@@ -72,6 +72,11 @@ export default class CxSbVideo extends CxVideo {
      * Thumbnail proxy format key (e.g. "webp", "jpg").
      */
     thumbnailFormat: string;
+    /**
+     * Whether `thumbnailFormat` was picked by hand. When false the thumbnail's format
+     * follows the poster asset's file extension instead.
+     */
+    manualThumbnailFormat: boolean;
     /**
      * Transformations applied to the thumbnail image.
      */

package/library/packages/organisms/src/content-builder/components/config-form/config-form.d.ts

@@ -27,7 +27,6 @@ import { default as CxTooltip } from '../../../../../atoms/src/components/toolti
 import { default as CxTypography } from '../../../../../atoms/src/components/typography/typography.ts';
 import { default as CxVisuallyHidden } from '../../../../../atoms/src/components/visually-hidden/visually-hidden.ts';
 import { default as CortexElement } from '../../../../../base/src/cortex-element.ts';
-import { CxFontPicker, CxIconPicker } from '../../../../../molecules/src/index.ts';
 import { default as CxAssetFormatPicker } from '../../../../../molecules/src/asset-format-picker/asset-format-picker.ts';
 import { default as CxAssetPicker } from '../../../../../molecules/src/asset-picker/asset-picker.ts';
 import { default as CxBicolorPicker } from '../../../../../molecules/src/bicolor-picker/bicolor-picker.ts';
@@ -36,6 +35,8 @@ import { default as CxConfirmPopover } from '../../../../../molecules/src/confir
 import { default as CxCornerPositionInputGroup } from '../../../../../molecules/src/corner-position-input-group/corner-position-input-group.ts';
 import { default as CxDownloadFormatPicker } from '../../../../../molecules/src/download-format-picker/download-format-picker.ts';
 import { default as CxDynamicSelect } from '../../../../../molecules/src/dynamic-select/dynamic-select.ts';
+import { default as CxFontPicker } from '../../../../../molecules/src/font-picker/font-picker.ts';
+import { default as CxIconPicker } from '../../../../../molecules/src/icon-picker/icon-picker.ts';
 import { default as CxPaddingInputGroup } from '../../../../../molecules/src/padding-input-group/padding-input-group.ts';
 import { default as CxPositionPicker } from '../../../../../molecules/src/position-picker/position-picker.ts';
 import { default as CxShadowInputGroup } from '../../../../../molecules/src/shadow-input-group/shadow-input-group.ts';

package/library/packages/organisms/src/content-builder/components/gallery-picker/gallery-picker.d.ts

@@ -55,6 +55,11 @@ export default class CxGalleryPicker extends CortexElement implements CortexForm
      * The asset format code used to resolve image src URLs.
      */
     format: string;
+    /**
+     * Whether `format` was picked by hand. When false each item's format follows its own
+     * file extension instead.
+     */
+    manualFormat: boolean;
     /**
      * The boundary property of the confirm popover's dropdown/dialog popup.
      */
@@ -69,6 +74,7 @@ export default class CxGalleryPicker extends CortexElement implements CortexForm
     loading: boolean;
     masonryData: Array<{
         alt?: string;
+        extension?: string;
         id: string;
         rawId?: string;
         src?: string;

package/library/packages/organisms/src/content-builder/configs/carousel.d.ts

@@ -27,6 +27,7 @@ type Attributes = {
     'highlight-drop-shadow': boolean;
     'item-height': string;
     loop: boolean;
+    'manual-format'?: boolean;
     navigation: string;
     orientation: string;
     'peek-slides': boolean;

package/library/packages/organisms/src/content-builder/configs/gallery.d.ts

@@ -29,6 +29,7 @@ type Attribute = {
     'highlight-siblings-fade-out': boolean;
     'item-height': string;
     'large-content-position': GalleryItemContentPosition;
+    'manual-format'?: boolean;
     'max-rows': string;
     navigation: 'both' | 'arrows' | 'pagination';
     orientation: Orientation;

package/library/packages/organisms/src/content-builder/configs/image.d.ts

@@ -32,6 +32,8 @@ type Attribute = {
     'highlight-border'?: CxImage['highlightBorder'];
     'highlight-color-overlay'?: CxImage['highlightColorOverlay'];
     'highlight-drop-shadow'?: CxImage['highlightDropShadow'];
+    'manual-format'?: CxImage['manualFormat'];
+    'manual-format-dark-mode'?: CxImage['manualFormatDarkMode'];
     'object-fit': CxImage['objectFit'];
     'open-in-new-tab'?: CxImage['openInNewTab'];
     'page-url'?: CxImage['pageUrl'];

package/library/packages/organisms/src/content-builder/configs/timeline.d.ts

@@ -4,6 +4,7 @@ import { LocalizeController } from '../../../../utils/src/custom-element/i18n';
 type Attributes = {
     data: string;
     format: string;
+    'manual-format'?: boolean;
     'min-tab-width': string;
     'multi-language': boolean;
     'navigation-arrows': boolean;

package/library/packages/organisms/src/content-builder/configs/video.d.ts

@@ -30,6 +30,7 @@ type Attribute = {
     height: CxVideo['height'];
     'height-mode': CxVideo['heightMode'];
     loop: CxVideo['loop'];
+    'manual-thumbnail-format'?: boolean;
     name: CxVideo['name'];
     'name-source-field': CxVideo['nameSourceField'];
     'open-in-new-tab'?: CxVideo['openInNewTab'];

package/library/packages/organisms/src/content-builder/configs-controller.d.ts

@@ -70,6 +70,7 @@ export default class ConfigsController {
         'highlight-drop-shadow': boolean;
         'item-height': string;
         loop: boolean;
+        'manual-format'?: boolean;
         navigation: string;
         orientation: string;
         'peek-slides': boolean;
@@ -204,6 +205,7 @@ export default class ConfigsController {
         'highlight-siblings-fade-out': boolean;
         'item-height': string;
         'large-content-position': import('../../../types/src/highlightable-element').HighlightableElementContentPosition;
+        'manual-format'?: boolean;
         'max-rows': string;
         navigation: "both" | "arrows" | "pagination";
         orientation: import('../../../types/src/index.ts').Orientation;
@@ -264,6 +266,8 @@ export default class ConfigsController {
         'highlight-border'?: import('./blocks/image/image').default["highlightBorder"];
         'highlight-color-overlay'?: import('./blocks/image/image').default["highlightColorOverlay"];
         'highlight-drop-shadow'?: import('./blocks/image/image').default["highlightDropShadow"];
+        'manual-format'?: import('./blocks/image/image').default["manualFormat"];
+        'manual-format-dark-mode'?: import('./blocks/image/image').default["manualFormatDarkMode"];
         'object-fit': import('./blocks/image/image').default["objectFit"];
         'open-in-new-tab'?: import('./blocks/image/image').default["openInNewTab"];
         'page-url'?: import('./blocks/image/image').default["pageUrl"];
@@ -299,6 +303,7 @@ export default class ConfigsController {
     }>[] | import('../../../types/src/content-builder').PropertyConfig<{
         data: string;
         format: string;
+        'manual-format'?: boolean;
         'min-tab-width': string;
         'multi-language': boolean;
         'navigation-arrows': boolean;
@@ -332,6 +337,7 @@ export default class ConfigsController {
         height: import('./blocks/video/video').default["height"];
         'height-mode': import('./blocks/video/video').default["heightMode"];
         loop: import('./blocks/video/video').default["loop"];
+        'manual-thumbnail-format'?: boolean;
         name: import('./blocks/video/video').default["name"];
         'name-source-field': import('./blocks/video/video').default["nameSourceField"];
         'open-in-new-tab'?: import('./blocks/video/video').default["openInNewTab"];
@@ -412,6 +418,7 @@ export default class ConfigsController {
         'highlight-drop-shadow': boolean;
         'item-height': string;
         loop: boolean;
+        'manual-format'?: boolean;
         navigation: string;
         orientation: string;
         'peek-slides': boolean;
@@ -543,6 +550,7 @@ export default class ConfigsController {
         'highlight-siblings-fade-out': boolean;
         'item-height': string;
         'large-content-position': import('../../../types/src/highlightable-element').HighlightableElementContentPosition;
+        'manual-format'?: boolean;
         'max-rows': string;
         navigation: "both" | "arrows" | "pagination";
         orientation: import('../../../types/src/index.ts').Orientation;
@@ -575,6 +583,7 @@ export default class ConfigsController {
     } | {
         data: string;
         format: string;
+        'manual-format'?: boolean;
         'min-tab-width': string;
         'multi-language': boolean;
         'navigation-arrows': boolean;
@@ -608,6 +617,7 @@ export default class ConfigsController {
         height: import('./blocks/video/video').default["height"];
         'height-mode': import('./blocks/video/video').default["heightMode"];
         loop: import('./blocks/video/video').default["loop"];
+        'manual-thumbnail-format'?: boolean;
         name: import('./blocks/video/video').default["name"];
         'name-source-field': import('./blocks/video/video').default["nameSourceField"];
         'open-in-new-tab'?: import('./blocks/video/video').default["openInNewTab"];

package/library/packages/organisms/src/content-builder/styleController.d.ts

@@ -59,6 +59,7 @@ export default class StyleController {
             defaultFormat?: string;
             dialogLabel?: string;
             formatKey?: string;
+            manualFormatKey?: string;
             multiple?: boolean;
             noCrop?: boolean;
             noResize?: boolean;
@@ -102,6 +103,7 @@ export default class StyleController {
         galleryPickerConfigs?: {
             dialog: import('../../../types/src/content-builder').DialogType;
             formatKey?: string;
+            manualFormatKey?: string;
             transformationRecordIdKey?: string;
             transformationsKey?: string;
         };

package/library/packages/services/src/api/asset/asset.d.ts

@@ -1,4 +1,4 @@
-import { GetAllFormatCodesResponse, GetAssetsInFolderRequest, GetAssetsInFolderResponse, GetAssetsRequest, GetAssetsResponse, GetAuthorizedObjectsRequest, GetAuthorizedObjectsResponse, GetAvailableProxiesResponse, GetCropZoneSuggestionRequest, GetCropZoneSuggestionResponse, GetTransformAssetLinkResponse, SearchAssetsParams, SearchAssetsResponse } from './asset.types';
+import { GetAllFormatCodesResponse, GetAssetsInFolderRequest, GetAssetsInFolderResponse, GetAssetsRequest, GetAssetsResponse, GetAuthorizedObjectsRequest, GetAuthorizedObjectsResponse, GetAvailableProxiesResponse, GetCropZoneSuggestionRequest, GetCropZoneSuggestionResponse, GetTransformAssetLinkResponse, SearchAssetsItem, SearchAssetsParams, SearchAssetsResponse } from './asset.types';
 
 export declare const DEFAULT_VIEW_SIZE = "CoreField.LargeSizePreview";
 export declare const FIELD_CORTEX_PATH = "Document.CortexPath";
@@ -19,6 +19,8 @@ export declare const FIELD_ORIGINAL_FILE_NAME = "CoreField.OriginalFileName";
 export declare const FIELD_UPDATED_FILE_NAME = "CoreField.UpdatedFileName";
 export declare const FIELD_LARGE_SIZE_PREVIEW_ID = "Document.DocumentDirectRepresentativeRID";
 export declare const LIBRARY_NAME = "Library";
+/** Appended to a `path_*` key to carry that proxy's rendered width alongside its URI. */
+export declare const MEDIA_FIELD_WIDTH_SUFFIX = "__width";
 export declare const MESSAGE_NEW_LINE = "\n";
 export declare const ORIGINAL_VIEW_SIZE = "CoreField.OriginalPreview";
 export declare const FIELD_DOC_SUBTYPE = "Document.DocSubType";
@@ -41,6 +43,13 @@ export declare function apiGetTransformAssetLink({ assetId, extension, format, s
     useSession?: string;
 }): Promise<GetTransformAssetLinkResponse | null>;
 export declare function apiGetAssets({ extraFields, getPermanentAssetsPaths, isSiteBuilder, recordIds, securityByPassToken, token, }: GetAssetsRequest): Promise<GetAssetsResponse>;
+/**
+ * Reads the pixel width a `path_*` proxy field actually has.
+ *
+ * Each proxy is rendered at its own size, so this is the ceiling for resizing that URL —
+ * distinct from `CoreField.MaximumWidth`, which describes the original file.
+ */
+export declare function readSearchAssetItemWidth(item: SearchAssetsItem, field: string): number | undefined;
 export declare function apiGetAssetsInFolder({ countPerPage, directParentFolderIdentifier, extraFields, getPermanentAssetsPaths, isSiteBuilder, limitedDocTypes, pageNumber, parentFolderIdentifier, searchTerm, securityByPassToken, sortOrder, token, }: GetAssetsInFolderRequest): Promise<GetAssetsInFolderResponse>;
 export declare function apiGetCropFocusMode({ autoCropMode, cropHeight, cropWidth, imageUrl, useSession, }: GetCropZoneSuggestionRequest): Promise<GetCropZoneSuggestionResponse | null>;
 export declare function apiGetAvailableProxies({ assetRecordId, isSiteBuilder, siteUrl, token, useSession, }: {

package/library/packages/tools/src/fetch-image/fetch-image.d.ts

@@ -28,46 +28,69 @@ export declare class FetchImageController implements ReactiveController {
     constructor(host: ReactiveElement, options?: FetchImageControllerOptions);
     get totalDataCount(): number;
     setSecurityByPassToken(token: string | undefined): void;
-    fetchImages({ end, extraFields, format, start, transformations, }: {
+    /**
+     * Changes how many items each request asks for.
+     *
+     * A new size moves every page boundary, so cached pages are dropped and the next fetch
+     * starts from page 1. `data` is kept — it is indexed absolutely, so the refetch
+     * overwrites in place instead of blanking the grid.
+     *
+     * Shrinking is ignored once pages are cached: collapsing already has what it needs.
+     */
+    setPageSize(pageSize: number): void;
+    fetchImages({ end, extraFields, format, manualFormat, start, transformations, }: {
         end: number;
         extraFields: string[];
         format?: string;
+        /**
+         * When false, `format` is ignored and each item resolves its own from its file
+         * extension. Defaults to true so existing callers keep their explicit format.
+         */
+        manualFormat?: boolean;
         start: number;
         transformations?: Transformation[];
     }): Promise<ExtendedGalleryItem[] | undefined>;
-    fetchImagesInFolderBySlide({ activeSlide, extraFields, folderId, forceRefetch, format, minLimit, noPlaceholders, transformations, }: {
+    fetchImagesInFolderBySlide({ activeSlide, extraFields, folderId, forceRefetch, format, manualFormat, minLimit, noPlaceholders, transformations, }: {
         activeSlide: number;
         extraFields?: string[];
         folderId: string;
         forceRefetch?: boolean;
         format?: string;
+        manualFormat?: boolean;
         minLimit?: number;
         noPlaceholders?: boolean;
         transformations?: Transformation[];
     }): Promise<ExtendedGalleryItem[]>;
-    fetchImagesByIDs({ extraFields, format, recordIds, transformations, }: {
+    fetchImagesByIDs({ extraFields, format, manualFormat, recordIds, transformations, }: {
         extraFields?: string[];
         format?: string;
+        /**
+         * When false, `format` is ignored and each item resolves its own from its file
+         * extension. Defaults to true so existing callers keep their explicit format.
+         */
+        manualFormat?: boolean;
         recordIds: string[];
         transformations?: Transformation[];
     }): Promise<ExtendedGalleryItem[]>;
-    fetchImagesInFolderByPage({ extraFields, folderId, forceRefetch, format, noPlaceholders, page, pageSize, transformations, }: {
+    fetchImagesInFolderByPage({ extraFields, folderId, forceRefetch, format, manualFormat, noPlaceholders, page, pageSize, transformations, }: {
         extraFields?: string[];
         folderId: string;
         forceRefetch?: boolean;
         format?: string;
+        manualFormat?: boolean;
         noPlaceholders?: boolean;
         page: number;
         pageSize?: number;
         transformations?: Transformation[];
     }): Promise<ExtendedGalleryItem[]>;
-    fetchImagesInFolderByChunk({ chunkSize: rawChunkSize, end, extraFields, folderId, forceRefetch, format, start, transformations, }: {
+    fetchImagesInFolderByChunk({ chunkSize: rawChunkSize, end, extraFields, folderId, forceRefetch, format, manualFormat, start, transformations, }: {
         chunkSize?: number;
         end?: number;
         extraFields?: string[];
         folderId: string;
         forceRefetch?: boolean;
         format?: string;
+        manualFormat?: boolean;
         start?: number;
         transformations?: Transformation[];
     }): AsyncGenerator<ExtendedGalleryItem[], void, unknown>;

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

@@ -58,7 +58,6 @@ export type Asset = {
     identifier: string;
     imageUrl: string;
     name: string;
-    originalUrl: string;
     scrubUrl: string;
     size: string;
     tags: string;

package/library/packages/types/src/content-builder.d.ts

@@ -64,6 +64,11 @@ export type PropertyConfig<T = Record<string, any>> = Omit<TraitProperties, 'opt
         defaultFormat?: string;
         dialogLabel?: string;
         formatKey?: string;
+        /**
+         * The block-attribute key that records whether the format was picked by hand. When
+         * absent or false the format follows the asset's file extension.
+         */
+        manualFormatKey?: string;
         multiple?: boolean;
         noCrop?: boolean;
         noResize?: boolean;
@@ -114,6 +119,8 @@ export type PropertyConfig<T = Record<string, any>> = Omit<TraitProperties, 'opt
         dialog: DialogType;
         /** The block-attribute key for the format used to resolve records' src URLs after picking. */
         formatKey?: string;
+        /** The block-attribute key recording whether that format was picked by hand. */
+        manualFormatKey?: string;
         transformationRecordIdKey?: string;
         transformationsKey?: string;
     };

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

@@ -25,10 +25,12 @@ export type GalleryItem = {
     className?: string;
     details?: string;
     docType?: MediaType | '';
+    extension?: string;
     filler?: boolean;
     header?: string;
     id: string;
     isClone?: boolean;
+    maxWidth?: string;
     name?: string;
     objectFit?: ObjectFit;
     openInNewTab?: boolean;

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

@@ -6,9 +6,11 @@ export declare enum MasonryVariant {
 }
 export type MasonryItem = {
     alt?: string;
+    extension?: string;
     hasError?: boolean;
     id: string;
     loading?: boolean;
+    maxWidth?: string;
     objectFit?: ObjectFit;
     src: string;
 };

package/library/packages/utils/src/transformation/transformation.d.ts

@@ -1,5 +1,12 @@
 import { Asset, Parameter, Transformation } from '../../../types/src/asset-link-format';
 
+/**
+ * Width ladder used for `srcset` candidates, in CSS pixels.
+ *
+ * Kept as a small fixed ladder rather than a per-item computed width so that many
+ * items sharing a display size resolve to the same URLs and stay CDN-cache friendly.
+ */
+export declare const SRCSET_WIDTH_LADDER: readonly [400, 800, 1200, 1600, 2400];
 export declare function buildTransformationString({ asset, baseUrl, extension, options, parameters, transformations, useSession, }: {
     asset?: Asset;
     baseUrl?: string;
@@ -19,3 +26,96 @@ export declare function buildTransformationString({ asset, baseUrl, extension, o
  * and merged into an existing `/t/`. Other URLs keep the plain append behavior.
  */
 export declare function applyTransformationsToUrl(url: string, transformations: Transformation[]): string;
+/**
+ * Inserts a width-only resize into an asset-link URL, preserving any transformations
+ * already present.
+ *
+ * `applyTransformationsToUrl` is deliberately not reused here: it *replaces* an existing
+ * `/t/` segment (dropping a configured crop/rotate/quality) and drops the prettyName tail
+ * when doing so. This function prepends the resize to an existing segment instead, so a
+ * user's configured transformations survive.
+ *
+ * Returns the URL unchanged when it is not an asset-link URL, so arbitrary external
+ * sources are never rewritten.
+ */
+export declare function applyWidthToAssetUrl(url: string, width: number): string;
+/**
+ * Whether the URL already carries a transformation segment.
+ *
+ * An existing `/t/` means a width was already chosen deliberately (a configured resize,
+ * crop or proxy format), so a ladder must not add a competing one.
+ */
+export declare function hasTransformSegment(url: string): boolean;
+/** Proxy format that is always transcoded to a raster image, whatever the source file is. */
+export declare const AUTO_FALLBACK_FORMAT = "TR1";
+/**
+ * Largest original file `Auto` will serve untouched, in bytes.
+ *
+ * Past this the transcoded proxy wins even for extensions that would normally keep their
+ * original: delivering a very large original costs the viewer more than the animation or
+ * alpha it preserves.
+ */
+export declare const AUTO_ORIGINAL_FORMAT_MAX_BYTES: number;
+/**
+ * Reads an asset file size into bytes, or `undefined` when the value says nothing usable.
+ *
+ * `CoreField.FileSize` is typed as a string and has been observed both as a plain byte
+ * count (`'1024'`) and as a formatted value (`'63.47 KB'`), so both are accepted. A bare
+ * number is read as bytes, matching the raw form.
+ *
+ * Returns `undefined` rather than `0` for unusable input so callers can tell "no size
+ * reported" apart from "genuinely empty file" — the two lead to different decisions.
+ */
+export declare function parseFileSizeToBytes(size: string | number | null | undefined): number | undefined;
+/**
+ * The largest width `Auto` may request for an item.
+ *
+ * Each proxy is rendered at a fixed size (a `TR1` may be 1200px where its `TRX` is 7360px),
+ * so resizing past it only asks the backend to upscale. Returns `undefined` under a manual
+ * format — the author's choice is left alone — and when the proxy reported no width.
+ */
+export declare function resolveAutoMaxWidth(manualFormat: boolean, proxyWidth: string | number | null | undefined): number | undefined;
+/**
+ * Picks the proxy format an asset should be served under when the author chose `Auto`
+ * instead of naming a format.
+ *
+ * Extensions that would lose something to a transcode (animation, alpha, bit depth) take
+ * the original-file proxy, but only up to `AUTO_ORIGINAL_FORMAT_MAX_BYTES`; everything
+ * else takes the transcoded raster proxy, which is the one `buildAssetSrcset` may resize.
+ *
+ * An unknown or missing extension resolves to the raster proxy — the safe default for the
+ * majority of assets, and the same value the format ladders already fall back to.
+ *
+ * An unknown *size* does not: a size the API did not report is treated as within the
+ * limit, so a missing field never silently strips a GIF of its animation.
+ */
+export declare function resolveAutoFormat(extension: string | null | undefined, size?: string | number | null): string;
+/**
+ * Builds a `srcset` value for an asset-link URL by emitting one width-only resize
+ * candidate per ladder entry, letting the browser fetch and decode only the pixels
+ * the layout actually needs.
+ *
+ * When `maxWidth` is known the list is bounded by the asset itself: rungs above it are
+ * dropped so the backend is never asked to upscale, rungs within
+ * `ORIGINAL_INSTEAD_OF_RESIZE_MARGIN` of it are dropped as near-duplicates, and the
+ * untransformed URL closes the list at its real width. That last candidate costs no
+ * render and is the only one that can serve the image sharp at full size.
+ *
+ * Returns an empty string when the URL is not an asset link, when it already carries
+ * a transformation (the width was configured upstream), or when it is an animated GIF
+ * served as the original file — resizing that flattens it to a still frame, so the
+ * original has to be delivered untouched.
+ */
+export declare function buildAssetSrcset(url: string, options?: {
+    extension?: string | null;
+    format?: string;
+    maxWidth?: number;
+    widths?: readonly number[];
+}): string;
+/**
+ * Builds a `sizes` value from a known display width in CSS pixels.
+ *
+ * Rounded up to `step` so small layout changes (a resize that shifts a grid cell by a
+ * few pixels) do not produce a new value on every frame.
+ */
+export declare function buildSizesFromDisplayWidth(displayWidth: number, step?: number): string;