@cesdk/node 1.77.0-rc.0 → 1.77.0-rc.2

package/index.d.mts

@@ -1022,6 +1022,8 @@ export declare interface AssetPayload {
     typeface?: Typeface;
     transformPreset?: AssetTransformPreset;
     properties?: AssetProperty[];
+    /** A declarative style preset the engine applies to text/caption blocks. */
+    stylePreset?: AssetStylePreset;
 }
 
 /**
@@ -1311,6 +1313,166 @@ export declare interface AssetStringProperty {
     defaultValue: string;
 }
 
+/**
+ * A declarative style preset the engine applies to text and caption blocks. The engine parses and
+ * applies it identically on every platform. Lives in {@link AssetPayload.stylePreset}.
+ *
+ * Most of the look is in {@link AssetStylePreset.properties}; the other fields cover the font,
+ * size-relative scaling and animations.
+ * @public
+ */
+export declare interface AssetStylePreset {
+    /**
+     * The block type this preset is for. Used as the type to create when the preset is applied with no
+     * target block, and as the apply filter (it only restyles a block of this type). Omitted applies to any
+     * block. Style presets target text and caption blocks; the value is the longhand id, which the engine
+     * matches against the block's `getType()`.
+     */
+    blockType?: '//ly.img.ubq/text' | '//ly.img.ubq/caption';
+    /**
+     * How the preset combines with the block's current look. `'replace'` (the default) also clears the
+     * decorations and animations the preset omits, so switching presets never stacks; `'merge'` layers
+     * the preset on top, keeping everything it does not set. Either way the block's text content is never
+     * touched, and its size only changes when the preset asks for it (`fontSize.resizeExistingOnApply`,
+     * or a `text/path` baseline adopting its bounding box).
+     */
+    mode?: 'replace' | 'merge';
+    /**
+     * Font to apply. The engine resolves `family` against the registered typefaces and matches
+     * `weight`/`style`. Ignored when the family is empty or not registered.
+     */
+    typeface?: {
+        family: string;
+        weight?: FontWeight;
+        style?: FontStyle;
+    };
+    /**
+     * Scene-relative font size. `scale` is a unitless multiplier on the scene's base font size (1 = the
+     * base size), sizing a block created from the preset. With `resizeExistingOnApply: true` the same size
+     * also resizes an existing block on apply. For an absolute size, set `properties['text/fontSize']`
+     * instead (it takes precedence).
+     */
+    fontSize?: {
+        scale: number;
+        resizeExistingOnApply?: boolean;
+    };
+    /**
+     * Lengths that scale with the block's font size. Each entry sets its `property` to `ratio × fontSize`
+     * — e.g. `{ property: 'stroke/width', ratio: 0.012 }` makes the stroke width `0.012 × fontSize`. Keeps
+     * a preset's stroke width, drop-shadow offset/blur, … proportional at any size.
+     */
+    scaleWithFontSize?: Array<{
+        property: AssetStylePresetScalableProperty;
+        ratio: number;
+    }>;
+    /**
+     * The bulk of the look: typography plus the `fill/*`, `stroke/*`, `dropShadow/*` and
+     * `backgroundColor/*` decorations with their `…/enabled` toggles. Known paths are value-checked and
+     * autocomplete. See {@link AssetStylePresetProperties}.
+     */
+    properties?: AssetStylePresetProperties;
+    /** Entrance animation. */
+    inAnimation?: AssetStylePresetAnimation;
+    /** Exit animation. */
+    outAnimation?: AssetStylePresetAnimation;
+    /** Looping animation. */
+    loopAnimation?: AssetStylePresetAnimation;
+}
+
+/**
+ * An animation slot of an {@link AssetStylePreset} (`inAnimation`, `outAnimation` or `loopAnimation`).
+ * @public
+ */
+export declare interface AssetStylePresetAnimation {
+    /** The animation block type to apply, e.g. `'//ly.img.ubq/animation/slide'`. */
+    type: AnimationTypeLonghand;
+    /** Configures the animation as a map of its property paths to values. */
+    properties?: AssetStylePresetAnimationProperties;
+}
+
+/**
+ * The parameters of an {@link AssetStylePresetAnimation}: a map of the animation's property paths to
+ * values. The animation's `animation/*` properties (e.g. `animation/slide/fade`,
+ * `animation/grow/scaleFactor`) are value-checked and autocomplete, as are the animation controls
+ * (`playback/duration`, `animationEasing`, `textWritingStyle`, `textWritingOverlap`); any other
+ * property path is still accepted. These are animation paths, distinct from the block-property paths
+ * in {@link AssetStylePresetProperties}.
+ * @public
+ */
+export declare type AssetStylePresetAnimationProperties = {
+    [K in Extract<BoolPropertyName, `animation/${string}`>]?: boolean;
+} & {
+    [K in Extract<EnumPropertyName, `animation/${string}`>]?: string;
+} & {
+    [K in Extract<FloatPropertyName, `animation/${string}`>]?: number;
+} & {
+    [K in Extract<ColorPropertyName, `animation/${string}`>]?: RGBColor | RGBAColor;
+} & {
+    /** Animation controls applied outside the `animation/*` properties. */
+    'playback/duration'?: number;
+    animationEasing?: string;
+    textWritingStyle?: string;
+    textWritingOverlap?: number;
+} & {
+    [path: string]: AssetStylePresetPropertyValue;
+};
+
+/**
+ * The look of an {@link AssetStylePreset}: a map of property paths to values. Known paths are
+ * value-checked and autocomplete (e.g. `stroke/enabled` must be a boolean, `stroke/width` a number,
+ * `fill/solid/color` a color); any other property path is still accepted with the broader
+ * {@link AssetStylePresetPropertyValue}. Keys without a `/` are namespaced to the block (`text/` or
+ * `caption/`); keys with a `/` are used verbatim.
+ * @public
+ */
+export declare type AssetStylePresetProperties = {
+    [K in BoolPropertyName as string extends K ? never : K]?: boolean;
+} & {
+    [K in IntPropertyName as string extends K ? never : K]?: number;
+} & {
+    [K in FloatPropertyName as string extends K ? never : K]?: number;
+} & {
+    [K in DoublePropertyName as string extends K ? never : K]?: number;
+} & {
+    [K in StringPropertyName as string extends K ? never : K]?: string;
+} & {
+    [K in EnumPropertyName as string extends K ? never : K]?: string;
+} & {
+    [K in ColorPropertyName as string extends K ? never : K]?: RGBColor | RGBAColor;
+} & {
+    /**
+     * The text-on-path baseline (see `setTextOnPath`): a single-subpath SVG path string in the block's
+     * local coordinate space wraps the block's text on the path and resizes the block to the path's
+     * bounding box; an explicit `null` clears the path and restores normal layout. This is a virtual
+     * preset property — the baseline path is not a reflected block property, so the engine routes it
+     * through `setTextOnPath`, inheriting its validation. Pair it with `text/pathOffset` and
+     * `text/pathFlipped` (plain reflected properties) to fully define the path state. Which curve is
+     * applied is identified by the path value itself — compare `getTextOnPath` against an entry's
+     * `text/path`.
+     */
+    'text/path'?: string | null;
+} & {
+    [path: string]: AssetStylePresetPropertyValue;
+};
+
+/**
+ * A value a style preset can set on a property: a boolean, number, string (including enum values) or
+ * an RGB(A) color. Colors must be RGB(A) (`{ r, g, b, a? }`); CMYK and spot colors are not supported in
+ * presets. Structs and source sets cannot be set from a preset. A `null` value is ignored for regular
+ * properties; for the virtual `text/path` property it clears the baseline path.
+ * @public
+ */
+export declare type AssetStylePresetPropertyValue = boolean | number | string | RGBColor | RGBAColor | null;
+
+/**
+ * A length property a style preset may scale with the block's font size (see
+ * {@link AssetStylePreset.scaleWithFontSize}). Restricted to the decoration lengths for which scaling is
+ * meaningful — stroke width, drop-shadow offset/blur and the caption background corner radius — not
+ * arbitrary numeric properties like `rotation` or `opacity`.
+ * @public
+ */
+export declare type AssetStylePresetScalableProperty = 'stroke/width' | 'dropShadow/offset/x' | 'dropShadow/offset/y' | 'dropShadow/blurRadius/x' | 'dropShadow/blurRadius/y' | 'backgroundColor/cornerRadius';
+
 /**
  * Transform preset payload
  * @public

package/index.d.ts

@@ -1022,6 +1022,8 @@ export declare interface AssetPayload {
     typeface?: Typeface;
     transformPreset?: AssetTransformPreset;
     properties?: AssetProperty[];
+    /** A declarative style preset the engine applies to text/caption blocks. */
+    stylePreset?: AssetStylePreset;
 }
 
 /**
@@ -1311,6 +1313,166 @@ export declare interface AssetStringProperty {
     defaultValue: string;
 }
 
+/**
+ * A declarative style preset the engine applies to text and caption blocks. The engine parses and
+ * applies it identically on every platform. Lives in {@link AssetPayload.stylePreset}.
+ *
+ * Most of the look is in {@link AssetStylePreset.properties}; the other fields cover the font,
+ * size-relative scaling and animations.
+ * @public
+ */
+export declare interface AssetStylePreset {
+    /**
+     * The block type this preset is for. Used as the type to create when the preset is applied with no
+     * target block, and as the apply filter (it only restyles a block of this type). Omitted applies to any
+     * block. Style presets target text and caption blocks; the value is the longhand id, which the engine
+     * matches against the block's `getType()`.
+     */
+    blockType?: '//ly.img.ubq/text' | '//ly.img.ubq/caption';
+    /**
+     * How the preset combines with the block's current look. `'replace'` (the default) also clears the
+     * decorations and animations the preset omits, so switching presets never stacks; `'merge'` layers
+     * the preset on top, keeping everything it does not set. Either way the block's text content is never
+     * touched, and its size only changes when the preset asks for it (`fontSize.resizeExistingOnApply`,
+     * or a `text/path` baseline adopting its bounding box).
+     */
+    mode?: 'replace' | 'merge';
+    /**
+     * Font to apply. The engine resolves `family` against the registered typefaces and matches
+     * `weight`/`style`. Ignored when the family is empty or not registered.
+     */
+    typeface?: {
+        family: string;
+        weight?: FontWeight;
+        style?: FontStyle;
+    };
+    /**
+     * Scene-relative font size. `scale` is a unitless multiplier on the scene's base font size (1 = the
+     * base size), sizing a block created from the preset. With `resizeExistingOnApply: true` the same size
+     * also resizes an existing block on apply. For an absolute size, set `properties['text/fontSize']`
+     * instead (it takes precedence).
+     */
+    fontSize?: {
+        scale: number;
+        resizeExistingOnApply?: boolean;
+    };
+    /**
+     * Lengths that scale with the block's font size. Each entry sets its `property` to `ratio × fontSize`
+     * — e.g. `{ property: 'stroke/width', ratio: 0.012 }` makes the stroke width `0.012 × fontSize`. Keeps
+     * a preset's stroke width, drop-shadow offset/blur, … proportional at any size.
+     */
+    scaleWithFontSize?: Array<{
+        property: AssetStylePresetScalableProperty;
+        ratio: number;
+    }>;
+    /**
+     * The bulk of the look: typography plus the `fill/*`, `stroke/*`, `dropShadow/*` and
+     * `backgroundColor/*` decorations with their `…/enabled` toggles. Known paths are value-checked and
+     * autocomplete. See {@link AssetStylePresetProperties}.
+     */
+    properties?: AssetStylePresetProperties;
+    /** Entrance animation. */
+    inAnimation?: AssetStylePresetAnimation;
+    /** Exit animation. */
+    outAnimation?: AssetStylePresetAnimation;
+    /** Looping animation. */
+    loopAnimation?: AssetStylePresetAnimation;
+}
+
+/**
+ * An animation slot of an {@link AssetStylePreset} (`inAnimation`, `outAnimation` or `loopAnimation`).
+ * @public
+ */
+export declare interface AssetStylePresetAnimation {
+    /** The animation block type to apply, e.g. `'//ly.img.ubq/animation/slide'`. */
+    type: AnimationTypeLonghand;
+    /** Configures the animation as a map of its property paths to values. */
+    properties?: AssetStylePresetAnimationProperties;
+}
+
+/**
+ * The parameters of an {@link AssetStylePresetAnimation}: a map of the animation's property paths to
+ * values. The animation's `animation/*` properties (e.g. `animation/slide/fade`,
+ * `animation/grow/scaleFactor`) are value-checked and autocomplete, as are the animation controls
+ * (`playback/duration`, `animationEasing`, `textWritingStyle`, `textWritingOverlap`); any other
+ * property path is still accepted. These are animation paths, distinct from the block-property paths
+ * in {@link AssetStylePresetProperties}.
+ * @public
+ */
+export declare type AssetStylePresetAnimationProperties = {
+    [K in Extract<BoolPropertyName, `animation/${string}`>]?: boolean;
+} & {
+    [K in Extract<EnumPropertyName, `animation/${string}`>]?: string;
+} & {
+    [K in Extract<FloatPropertyName, `animation/${string}`>]?: number;
+} & {
+    [K in Extract<ColorPropertyName, `animation/${string}`>]?: RGBColor | RGBAColor;
+} & {
+    /** Animation controls applied outside the `animation/*` properties. */
+    'playback/duration'?: number;
+    animationEasing?: string;
+    textWritingStyle?: string;
+    textWritingOverlap?: number;
+} & {
+    [path: string]: AssetStylePresetPropertyValue;
+};
+
+/**
+ * The look of an {@link AssetStylePreset}: a map of property paths to values. Known paths are
+ * value-checked and autocomplete (e.g. `stroke/enabled` must be a boolean, `stroke/width` a number,
+ * `fill/solid/color` a color); any other property path is still accepted with the broader
+ * {@link AssetStylePresetPropertyValue}. Keys without a `/` are namespaced to the block (`text/` or
+ * `caption/`); keys with a `/` are used verbatim.
+ * @public
+ */
+export declare type AssetStylePresetProperties = {
+    [K in BoolPropertyName as string extends K ? never : K]?: boolean;
+} & {
+    [K in IntPropertyName as string extends K ? never : K]?: number;
+} & {
+    [K in FloatPropertyName as string extends K ? never : K]?: number;
+} & {
+    [K in DoublePropertyName as string extends K ? never : K]?: number;
+} & {
+    [K in StringPropertyName as string extends K ? never : K]?: string;
+} & {
+    [K in EnumPropertyName as string extends K ? never : K]?: string;
+} & {
+    [K in ColorPropertyName as string extends K ? never : K]?: RGBColor | RGBAColor;
+} & {
+    /**
+     * The text-on-path baseline (see `setTextOnPath`): a single-subpath SVG path string in the block's
+     * local coordinate space wraps the block's text on the path and resizes the block to the path's
+     * bounding box; an explicit `null` clears the path and restores normal layout. This is a virtual
+     * preset property — the baseline path is not a reflected block property, so the engine routes it
+     * through `setTextOnPath`, inheriting its validation. Pair it with `text/pathOffset` and
+     * `text/pathFlipped` (plain reflected properties) to fully define the path state. Which curve is
+     * applied is identified by the path value itself — compare `getTextOnPath` against an entry's
+     * `text/path`.
+     */
+    'text/path'?: string | null;
+} & {
+    [path: string]: AssetStylePresetPropertyValue;
+};
+
+/**
+ * A value a style preset can set on a property: a boolean, number, string (including enum values) or
+ * an RGB(A) color. Colors must be RGB(A) (`{ r, g, b, a? }`); CMYK and spot colors are not supported in
+ * presets. Structs and source sets cannot be set from a preset. A `null` value is ignored for regular
+ * properties; for the virtual `text/path` property it clears the baseline path.
+ * @public
+ */
+export declare type AssetStylePresetPropertyValue = boolean | number | string | RGBColor | RGBAColor | null;
+
+/**
+ * A length property a style preset may scale with the block's font size (see
+ * {@link AssetStylePreset.scaleWithFontSize}). Restricted to the decoration lengths for which scaling is
+ * meaningful — stroke width, drop-shadow offset/blur and the caption background corner radius — not
+ * arbitrary numeric properties like `rotation` or `opacity`.
+ * @public
+ */
+export declare type AssetStylePresetScalableProperty = 'stroke/width' | 'dropShadow/offset/x' | 'dropShadow/offset/y' | 'dropShadow/blurRadius/x' | 'dropShadow/blurRadius/y' | 'backgroundColor/cornerRadius';
+
 /**
  * Transform preset payload
  * @public