@cesdk/engine 1.76.0-nightly.20260521 → 1.76.0-rc.0

package/index.d.ts

@@ -899,6 +899,35 @@ export declare interface AssetEnumProperty {
     options: string[];
 }
 
+/**
+ * Filter expression — predicate or logical combinator. Combinators nest
+ * arbitrarily. The union is mutually exclusive: an object with both
+ * `and` and `or`, or with `property` next to a combinator key, is
+ * rejected at the type level.
+ *
+ * Missing-key semantics for `not`: a predicate is `false` on an asset
+ * that lacks the targeted field, so a negated `meta.foo === 'x'` matches
+ * assets where `meta.foo !== 'x'` **and** assets that lack `meta.foo`
+ * entirely.
+ * @public
+ */
+export declare type AssetFilter = AssetPropertyFilter | {
+    and: AssetFilter[];
+    or?: never;
+    not?: never;
+    property?: never;
+} | {
+    or: AssetFilter[];
+    and?: never;
+    not?: never;
+    property?: never;
+} | {
+    not: AssetFilter;
+    and?: never;
+    or?: never;
+    property?: never;
+};
+
 /**
  * Asset transform preset payload fixed aspect ratio
  * @public
@@ -1007,6 +1036,39 @@ export declare interface AssetPayload {
  */
 export declare type AssetProperty = AssetBooleanProperty | AssetColorProperty | AssetEnumProperty | AssetNumberProperty | AssetStringProperty;
 
+/**
+ * A single property predicate. Exactly one of `contains` (case-insensitive
+ * substring) or `equals` (case-insensitive equality) must be set — the
+ * type forbids passing both or neither. On a string-array property
+ * (`tags`, `groups`), the operator matches if any element matches.
+ *
+ * `meta.<key>` values are flat strings in the engine; if a meta value
+ * was originally serialized as a number or boolean, stringify it the
+ * same way before comparing.
+ * @public
+ */
+export declare type AssetPropertyFilter = {
+    property: AssetPropertyPath;
+} & ({
+    contains: string;
+    equals?: never;
+} | {
+    equals: string;
+    contains?: never;
+});
+
+/**
+ * Dot-path against the resolved asset that a property predicate targets:
+ * `label`, `id`, `tags`, `groups`, or `meta.<key>` (one segment — meta
+ * values in the engine are flat strings).
+ *
+ * The template literal accepts `'meta.'` (empty key) because TypeScript's
+ * `${string}` includes the empty string; the engine rejects this at
+ * runtime with an explanatory error.
+ * @public
+ */
+export declare type AssetPropertyPath = 'label' | 'tags' | 'id' | 'groups' | `meta.${string}`;
+
 /**
  * Defines a request for querying assets
  * @public
@@ -1053,6 +1115,34 @@ export declare interface AssetQueryData {
      * Sort assets that are marked as active first.
      */
     sortActiveFirst?: boolean;
+    /**
+     * Optional structured filter, AND-combined with the result of `query` /
+     * `tags` / `groups` / `excludeGroups`. The top-level array is an implicit
+     * AND of its entries. Each entry is either a property predicate
+     * (`{ property, contains?, equals? }`) or a logical combinator
+     * (`{ and: [...] }`, `{ or: [...] }`, `{ not: ... }`). Combinators nest.
+     *
+     * **When to use `filter` vs `tags` / `groups` / `excludeGroups`:**
+     * The legacy `tags` / `groups` / `excludeGroups` fields remain
+     * supported and are equivalent to filter predicates with `equals` and
+     * implicit AND. Prefer `filter` for anything beyond a plain include/
+     * exclude list — case-insensitive substrings, `meta.<key>` matches,
+     * `or` / `not` combinators — and reach for the legacy fields only
+     * when you want their case-sensitive exact-match semantics.
+     *
+     * Malformed filters reject the returned promise with the engine's
+     * parse-error message (e.g. `"Unknown asset property '…'"`).
+     *
+     * @example
+     * ```ts
+     * filter: [
+     *   { property: 'label',          contains: 'Roboto' },
+     *   { property: 'meta.languages', contains: 'de' },
+     *   { not: { property: 'meta.legacy', equals: 'true' } }
+     * ]
+     * ```
+     */
+    filter?: AssetFilter[];
 }
 
 /**
@@ -6565,7 +6655,7 @@ export declare function _createReactiveProperty<T>(initialValue: T, options?: _R
  */
 export declare type CreateSceneOptions = {
     /** The page options */
-    page: {
+    page?: {
         /** The size of the page */
         size: number | {
             width: number;
@@ -6574,6 +6664,15 @@ export declare type CreateSceneOptions = {
         /** The background color of the page */
         color?: Color;
     };
+    /**
+     * The design unit of the new scene. Defaults to `Pixel`.
+     */
+    designUnit?: SceneDesignUnit;
+    /**
+     * The unit in which font sizes for `setTextFontSize` and `getTextFontSizes` are interpreted.
+     * If omitted, it is paired with `designUnit`: `Pixel` scenes get `Pixel`, all other scenes get `Point`.
+     */
+    fontSizeUnit?: SceneFontSizeUnit;
 };
 
 /**
@@ -8429,6 +8528,7 @@ export declare interface _FindAssetsQuery {
     sortingOrder: SortingOrder;
     sortKey: string;
     sortActiveFirst: boolean;
+    filter: AssetFilter[];
 }
 
 /**
@@ -9363,6 +9463,8 @@ export declare class SceneAPI {
      *
      * ```javascript
      * const scene = engine.scene.create(layout);
+     * // With a specific design unit and auto-paired font-size unit:
+     * const pxScene = engine.scene.create('Free', { designUnit: 'Pixel' });
      * ```
      *
      * @category Scene Creation
@@ -9371,6 +9473,9 @@ export declare class SceneAPI {
      *   - `page` - Page options. Properties:
      *     - `size` - The size of the page.
      *     - `color` - Optional background color of the page.
+     *   - `designUnit` - The design unit of the new scene. Defaults to `Pixel`.
+     *   - `fontSizeUnit` - The font-size unit. If omitted, paired with `designUnit`
+     *     (`Pixel` design unit → `Pixel` font unit, others → `Point`).
      * @returns The scene's handle.
      */
     create(sceneLayout?: SceneLayout, options?: CreateSceneOptions): DesignBlockId;
@@ -9514,6 +9619,30 @@ export declare class SceneAPI {
      * @returns The current design unit.
      */
     getDesignUnit(): SceneDesignUnit;
+    /**
+     * Sets the unit in which font sizes for `setTextFontSize` and `getTextFontSizes` are interpreted.
+     * The engine continues to store font sizes in points internally; this only affects how values
+     * are interpreted at the API boundary when callers don't specify a `unit` in `TextFontSizeOptions`.
+     *
+     * ```javascript
+     * engine.scene.setFontSizeUnit('Pixel');
+     * ```
+     *
+     * @category Scene Properties
+     * @param fontSizeUnit - The new font-size unit of the scene.
+     */
+    setFontSizeUnit(fontSizeUnit: SceneFontSizeUnit): void;
+    /**
+     * Returns the font-size unit of the current scene.
+     *
+     * ```javascript
+     * engine.scene.getFontSizeUnit();
+     * ```
+     *
+     * @category Scene Properties
+     * @returns The current font-size unit.
+     */
+    getFontSizeUnit(): SceneFontSizeUnit;
     /**
      * Get the layout of the current scene.
      *
@@ -9859,6 +9988,12 @@ export { SceneDesignUnit }
 /** @public */
 export declare const SceneDesignUnitValues: readonly ["Pixel", "Millimeter", "Inch"];
 
+/** @public */
+export declare type SceneFontSizeUnit = (typeof SceneFontSizeUnitValues)[number];
+
+/** @public */
+export declare const SceneFontSizeUnitValues: readonly ["Pixel", "Point"];
+
 /** @public */
 export declare type SceneLayout = (typeof SceneLayoutValues)[number];
 
@@ -10515,7 +10650,10 @@ export declare type TextDecorationStyle = 'Solid' | 'Double' | 'Dotted' | 'Dashe
  * @public
  */
 export declare interface TextFontSizeOptions {
-    /** The unit of the font size. Defaults to 'Point' */
+    /**
+     * The unit of the font size. Defaults to the scene's `fontSizeUnit`
+     * (configured via `engine.scene.setFontSizeUnit()`), which itself defaults to `'Point'`.
+     */
     unit?: FontSizeUnit;
     /** The start index of the UTF-16 range. Defaults to -1 (start of selection/text) */
     from?: number;