@orangelogic/design-system 2.190.0 → 2.192.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,20 @@ 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;
+    /**
+     * 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 +215,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 +255,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 +286,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/content-builder.d.ts

@@ -5,7 +5,7 @@ import { default as CxSpinner } from '../../../atoms/src/components/spinner/spin
 import { default as CortexElement } from '../../../base/src/cortex-element.ts';
 import { AssetFormatValue } from '../../../types/src/asset-format-picker';
 import { Asset, AssetTypeString, Device, EditorMode, TeamSpaceRole } from '../../../types/src/content-builder';
-import { Component, Editor, StyleProps } from 'grapesjs';
+import { Component, Editor } from 'grapesjs';
 import { TemplateResult } from 'lit';
 import { CxBlockPicker } from './components/block-picker';
 import { CxConfigManager } from './components/config-manager';
@@ -326,6 +326,35 @@ export default class CxContentBuilder extends CortexElement {
     private handleCanvasScroll;
     private handleHorizontalScroll;
     private handleRootToolbarRightClick;
+    /**
+     * Re-applies the toolbar position GrapesJS computed, clamped to the visible
+     * canvas so the toolbar never gets clipped.
+     *
+     * `getTargetToElementFixed` derives `left` from `elRect.width - toolbarWidth`
+     * (right-aligned to the selected element) and clamps it with
+     * `canvasLiftLimit`, which is measured against the frame rather than the
+     * visible canvas viewport. On an element near the left edge of the visible
+     * area that limit still allows a negative offset, so the toolbar overflows
+     * past the canvas and gets clipped. Clamping against the real canvas box
+     * turns that case into left-alignment.
+     *
+     * Both `left` and `top` are relative to the tools wrapper, which GrapesJS
+     * sizes to the selected element's box — hence the wrapper-to-canvas delta.
+     *
+     * Values are written with `important` so stylesheet rules on `.gjs-toolbar`
+     * cannot override the computed placement.
+     */
+    private clampToolbarPosition;
+    /**
+     * Wraps `updateToolbarPos` so the toolbar position is re-applied after
+     * GrapesJS writes its own inline position.
+     *
+     * `updateToolbarPos` lives on the `select-comp` command (GrapesJS'
+     * `SelectComponent`), which owns the component toolbar / badge / highlight
+     * boxes — not on `CanvasView`. It is absent from the published `grapesjs`
+     * typings, so the command is narrowed through a local structural type.
+     */
+    private patchToolbarPositioning;
     private handleCanvasClick;
     private handleCanvasKeydown;
     private handleTemplateManagerUpdated;
@@ -388,11 +417,7 @@ export default class CxContentBuilder extends CortexElement {
      * @param components - The components to be updated in the component.
      * @param styleProps - The style properties to be set for the component.
      */
-    updateComponent(component: Component, { attributes, properties, styleProps, }: {
-        attributes?: Record<string, string>;
-        properties?: Record<string, unknown>;
-        styleProps?: StyleProps;
-    }): void;
+    private updateComponent;
     private handleOtherChange;
     private handleMouseMove;
     private getScrollableElements;

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/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,6 +25,7 @@ export type GalleryItem = {
     className?: string;
     details?: string;
     docType?: MediaType | '';
+    extension?: string;
     filler?: boolean;
     header?: string;
     id: string;

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

@@ -6,6 +6,7 @@ export declare enum MasonryVariant {
 }
 export type MasonryItem = {
     alt?: string;
+    extension?: string;
     hasError?: boolean;
     id: string;
     loading?: boolean;

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,87 @@ 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;
+/**
+ * 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.
+ *
+ * Candidates wider than `maxWidth` are dropped so the backend is never asked to
+ * upscale past the asset's real dimensions. When `maxWidth` falls below the whole
+ * ladder, the smallest candidate is still emitted so a `srcset` is always produced
+ * for an eligible URL.
+ *
+ * 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;