@imgly/codesign-mcp 0.1.5 → 0.1.6

package/assets/docs/guide/api/SceneAPI.md

@@ -7,7 +7,6 @@
 Load the contents of a scene file.
 The string must be the binary contents of a scene file and is directly imported as blocks. Any existing scene is replaced by the new one.
 This is useful for loading scenes that were saved with `saveToString` or scenes that were created in another editor instance.
-
 ```javascript
 const sceneContent = await creativeEngine.scene.saveToString();
 creativeEngine.scene.loadFromString(sceneContent);
@@ -18,7 +17,6 @@ loadFromString(sceneContent: string, overrideEditorConfig?: boolean, waitForReso
 ```
 
 **Parameters:**
-
 - `sceneContent` - The scene file contents, a base64 string.
 - `overrideEditorConfig` - Whether to override editor configuration with settings and data from the scene file. Defaults to false.
 - `waitForResources` - Whether to wait for all resources to finish loading before resolving. Defaults to false.
@@ -29,7 +27,6 @@ loadFromString(sceneContent: string, overrideEditorConfig?: boolean, waitForReso
 
 Load a scene from the URL to the scene file.
 The scene file will be fetched asynchronously by the engine and loaded into the engine once it is available. Any existing scene is replaced by the new one.
-
 ```javascript
 const sceneURL = 'https://example.com/my-scene.json';
 creativeEngine.scene.loadFromURL(sceneURL);
@@ -40,7 +37,6 @@ loadFromURL(url: string, overrideEditorConfig?: boolean, waitForResources?: bool
 ```
 
 **Parameters:**
-
 - `url` - The URL of the scene file.
 - `overrideEditorConfig` - Whether to override editor configuration with settings and data from the scene file. Defaults to false.
 - `waitForResources` - Whether to wait for all resources to finish loading before resolving. Defaults to false.
@@ -58,7 +54,6 @@ loadFromArchiveURL(url: string, overrideEditorConfig?: boolean, waitForResources
 ```
 
 **Parameters:**
-
 - `url` - The URL of the scene archive file.
 - `overrideEditorConfig` - Whether to override editor configuration with settings and data from the scene file. Defaults to false.
 - `waitForResources` - Whether to wait for all resources to finish loading before resolving. Defaults to false.
@@ -83,7 +78,6 @@ saveToString(options?: {
 ```
 
 **Parameters:**
-
 - `options` - Save options containing:
   - allowedResourceSchemes: The resource schemes to allow in the saved string. Defaults to ['blob', 'bundle', 'file', 'http', 'https', 'opfs'].
   - onDisallowedResourceScheme: An optional callback that is called for each resource URL that has a scheme absent from
@@ -114,9 +108,10 @@ saveToArchive(): Promise<Blob>
 ### create()
 
 Create a new design scene, along with its own camera.
-
 ```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' });
 ```
 
 ```typescript
@@ -124,16 +119,18 @@ create(sceneLayout?: SceneLayout, options?: CreateSceneOptions): DesignBlockId
 ```
 
 **Parameters:**
-
 - `sceneLayout` - The layout of the scene.
 - `options` - Optional parameters for the scene. Properties:
   - `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.
 
-### createVideo() _(deprecated)_
+### createVideo() *(deprecated)*
 
 Create a new scene in video mode, along with its own camera.
 
@@ -142,7 +139,6 @@ createVideo(options?: CreateSceneOptions): DesignBlockId
 ```
 
 **Parameters:**
-
 - `options` - Optional parameters for the scene. Properties:
   - `page` - Page options. Properties:
     - `size` - The size of the page.
@@ -154,11 +150,8 @@ createVideo(options?: CreateSceneOptions): DesignBlockId
 
 Loads the given image and creates a scene with a single page showing the image.
 Fetching the image may take an arbitrary amount of time, so the scene isn't immediately available.
-
 ```javascript
-const scene = await engine.scene.createFromImage(
-  'https://img.ly/static/ubq_samples/sample_4.jpg'
-);
+const scene = await engine.scene.createFromImage('https://img.ly/static/ubq_samples/sample_4.jpg');
 ```
 
 ```typescript
@@ -166,7 +159,6 @@ createFromImage(url: string, dpi?: number, pixelScaleFactor?: number, sceneLayou
 ```
 
 **Parameters:**
-
 - `url` - The image URL.
 - `dpi` - The scene's DPI.
 - `pixelScaleFactor` - The display's pixel scale factor.
@@ -178,11 +170,8 @@ createFromImage(url: string, dpi?: number, pixelScaleFactor?: number, sceneLayou
 Loads the given video and creates a scene with a single page showing the video.
 Fetching the video may take an arbitrary amount of time, so the scene isn't immediately
 available.
-
 ```javascript
-const scene = await engine.scene.createFromVideo(
-  'https://img.ly/static/ubq_video_samples/bbb.mp4'
-);
+const scene = await engine.scene.createFromVideo('https://img.ly/static/ubq_video_samples/bbb.mp4');
 ```
 
 ```typescript
@@ -190,7 +179,6 @@ createFromVideo(url: string): Promise<DesignBlockId>
 ```
 
 **Parameters:**
-
 - `url` - The video URL.
 
 **Returns:** A promise that resolves with the scene ID on success or rejected with an error otherwise.
@@ -200,7 +188,6 @@ createFromVideo(url: string): Promise<DesignBlockId>
 ### get()
 
 Return the currently active scene.
-
 ```javascript
 const scene = engine.scene.get();
 ```
@@ -211,7 +198,7 @@ get(): DesignBlockId | null
 
 **Returns:** The scene or null, if none was created yet.
 
-### getMode() _(deprecated)_
+### getMode() *(deprecated)*
 
 Get the current scene mode.
 
@@ -221,7 +208,7 @@ getMode(): SceneMode | null
 
 **Returns:** The current mode of the scene, or null if no mode has been set.
 
-### setMode() _(deprecated)_
+### setMode() *(deprecated)*
 
 Set the mode of the scene.
 
@@ -230,13 +217,11 @@ setMode(mode: SceneMode): void
 ```
 
 **Parameters:**
-
 - `mode` - The new mode for the scene.
 
 ### setDesignUnit()
 
 Converts all values of the current scene into the given design unit.
-
 ```javascript
 engine.scene.setDesignUnit('Pixel');
 ```
@@ -246,13 +231,11 @@ setDesignUnit(designUnit: DesignUnit): void
 ```
 
 **Parameters:**
-
 - `designUnit` - The new design unit of the scene
 
 ### getDesignUnit()
 
 Returns the design unit of the current scene.
-
 ```javascript
 engine.scene.getDesignUnit();
 ```
@@ -263,10 +246,38 @@ getDesignUnit(): DesignUnit
 
 **Returns:** The current design unit.
 
+### setFontSizeUnit()
+
+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');
+```
+
+```typescript
+setFontSizeUnit(fontSizeUnit: FontSizeUnit): void
+```
+
+**Parameters:**
+- `fontSizeUnit` - The new font-size unit of the scene.
+
+### getFontSizeUnit()
+
+Returns the font-size unit of the current scene.
+```javascript
+engine.scene.getFontSizeUnit();
+```
+
+```typescript
+getFontSizeUnit(): FontSizeUnit
+```
+
+**Returns:** The current font-size unit.
+
 ### getLayout()
 
 Get the layout of the current scene.
-
 ```javascript
 const layout = engine.scene.getLayout();
 ```
@@ -284,7 +295,6 @@ This will handle all necessary conversions including creating or destroying stac
 and reparenting pages as needed.
 When transitioning from stack layouts (VerticalStack, HorizontalStack, DepthStack) to Free layout,
 the global positions of pages are preserved to maintain their visual appearance in the scene.
-
 ```javascript
 engine.scene.setLayout('VerticalStack');
 ```
@@ -294,7 +304,6 @@ setLayout(layout: SceneLayout): void
 ```
 
 **Parameters:**
-
 - `layout` - The new layout for the scene.
 
 ## Template Operations
@@ -305,9 +314,8 @@ Applies the contents of the given template scene to the currently loaded scene.
 This loads the template scene while keeping the design unit and page dimensions
 of the current scene. The content of the pages is automatically adjusted to fit
 the new dimensions.
-
 ```javascript
-engine.scene.applyTemplateFromString('UBQ1ewoiZm9ybWF0Ij...');
+engine.scene.applyTemplateFromString("UBQ1ewoiZm9ybWF0Ij...");
 ```
 
 ```typescript
@@ -315,7 +323,6 @@ applyTemplateFromString(content: string): Promise<void>
 ```
 
 **Parameters:**
-
 - `content` - The template scene file contents, a base64 string.
 
 **Returns:** A Promise that resolves once the template was applied or rejects if there was an error.
@@ -326,11 +333,8 @@ Applies the contents of the given template scene to the currently loaded scene.
 This loads the template scene while keeping the design unit and page dimensions
 of the current scene. The content of the pages is automatically adjusted to fit
 the new dimensions.
-
 ```javascript
-engine.scene.applyTemplateFromURL(
-  'https://cdn.img.ly/assets/demo/v4/ly.img.template/templates/cesdk_postcard_1.scene'
-);
+engine.scene.applyTemplateFromURL('https://cdn.img.ly/assets/demo/v4/ly.img.template/templates/cesdk_postcard_1.scene');
 ```
 
 ```typescript
@@ -338,7 +342,6 @@ applyTemplateFromURL(url: string): Promise<void>
 ```
 
 **Parameters:**
-
 - `url` - The url to the template scene file.
 
 **Returns:** A Promise that resolves once the template was applied or rejects if there was an error.
@@ -348,7 +351,6 @@ applyTemplateFromURL(url: string): Promise<void>
 ### getPages()
 
 Get the sorted list of pages in the scene.
-
 ```javascript
 const pages = engine.scene.getPages();
 ```
@@ -363,7 +365,6 @@ getPages(): DesignBlockId[]
 
 Get the current page, i.e., the page of the first selected element if this page
 is at least 25% visible or, otherwise, the page nearest to the viewport center.
-
 ```javascript
 const currentPage = engine.scene.getCurrentPage();
 ```
@@ -377,11 +378,9 @@ getCurrentPage(): DesignBlockId | null
 ### findNearestToViewPortCenterByType()
 
 Find all blocks with the given type sorted by the distance to viewport center.
-
 ```javascript
 // Use longhand block type ID to find nearest pages.
-let nearestPageByType =
-  engine.scene.findNearestToViewPortCenterByType('//ly.img.ubq/page')[0];
+let nearestPageByType = engine.scene.findNearestToViewPortCenterByType('//ly.img.ubq/page')[0];
 // Or use shorthand block type ID.
 nearestPageByType = engine.scene.findNearestToViewPortCenterByType('page')[0];
 ```
@@ -391,7 +390,6 @@ findNearestToViewPortCenterByType(type: DesignBlockType): DesignBlockId[]
 ```
 
 **Parameters:**
-
 - `type` - The type to search for.
 
 **Returns:** A list of block ids sorted by distance to viewport center.
@@ -399,10 +397,8 @@ findNearestToViewPortCenterByType(type: DesignBlockType): DesignBlockId[]
 ### findNearestToViewPortCenterByKind()
 
 Find all blocks with the given kind sorted by the distance to viewport center.
-
 ```javascript
-let nearestImageByKind =
-  engine.scene.findNearestToViewPortCenterByKind('image')[0];
+let nearestImageByKind = engine.scene.findNearestToViewPortCenterByKind('image')[0];
 ```
 
 ```typescript
@@ -410,7 +406,6 @@ findNearestToViewPortCenterByKind(kind: string): DesignBlockId[]
 ```
 
 **Parameters:**
-
 - `kind` - The kind to search for.
 
 **Returns:** A list of block ids sorted by distance to viewport center.
@@ -422,7 +417,6 @@ findNearestToViewPortCenterByKind(kind: string): DesignBlockId[]
 Set the zoom level of the scene, e.g., for headless versions.
 This only shows an effect if the zoom level is not handled/overwritten by the UI.
 Setting a zoom level of 2.0f results in one dot in the design to be two pixels on the screen.
-
 ```javascript
 // Zoom to 100%
 engine.scene.setZoomLevel(1.0);
@@ -435,14 +429,12 @@ setZoomLevel(zoomLevel?: number): void
 ```
 
 **Parameters:**
-
 - `zoomLevel` - The new zoom level.
 
 ### getZoomLevel()
 
 Get the zoom level of the scene or for a camera in the scene in unit `dpx/dot`. A zoom level of 2.0 results in one pixel in the design to be two pixels
 on the screen.
-
 ```javascript
 const zoomLevel = engine.scene.getZoomLevel();
 ```
@@ -453,12 +445,11 @@ getZoomLevel(): number
 
 **Returns:** The zoom level of the block's camera.
 
-### zoomToBlock() _(deprecated)_
+### zoomToBlock() *(deprecated)*
 
 Sets the zoom and focus to show a block.
 This only shows an effect if the zoom level is not handled/overwritten by the UI.
 Without padding, this results in a tight view on the block.
-
 ```javascript
 // Bring entire scene in view with padding of 20px in all directions
 engine.scene.zoomToBlock(scene, 20.0, 20.0, 20.0, 20.0);
@@ -469,7 +460,6 @@ zoomToBlock(id: DesignBlockId, paddingLeft?: number, paddingTop?: number, paddin
 ```
 
 **Parameters:**
-
 - `id` - The block that should be focused on.
 - `paddingLeft` - Optional padding in screen pixels to the left of the block.
 - `paddingTop` - Optional padding in screen pixels to the top of the block.
@@ -484,7 +474,6 @@ Continually adjusts the zoom level to fit the width or height of a block's axis-
 This only shows an effect if the zoom level is not handled/overwritten by the UI.
 Without padding, this results in a tight view on the block.
 Calling `setZoomLevel` or `zoomToBlock` disables the continuous adjustment.
-
 ```javascript
 // Follow page with padding of 20px in both directions
 engine.scene.enableZoomAutoFit(page, 'Both', 20.0, 20.0, 20.0, 20.0);
@@ -495,7 +484,6 @@ enableZoomAutoFit(id: DesignBlockId, axis: 'Both', paddingLeft?: number, padding
 ```
 
 **Parameters:**
-
 - `id` - The block for which the zoom is adjusted.
 - `axis` - The block axis for which the zoom is adjusted.
 - `paddingLeft` - Optional padding in screen pixels to the left of the block.
@@ -506,7 +494,6 @@ enableZoomAutoFit(id: DesignBlockId, axis: 'Both', paddingLeft?: number, padding
 ### disableZoomAutoFit()
 
 Disables any previously set zoom auto-fit.
-
 ```javascript
 engine.scene.disableZoomAutoFit(scene);
 ```
@@ -516,13 +503,11 @@ disableZoomAutoFit(blockOrScene: DesignBlockId): void
 ```
 
 **Parameters:**
-
 - `blockOrScene` - The scene or a block in the scene for which to disable zoom auto-fit.
 
 ### isZoomAutoFitEnabled()
 
 Queries whether zoom auto-fit is enabled for the given block.
-
 ```javascript
 engine.scene.isZoomAutoFitEnabled(scene);
 ```
@@ -532,7 +517,6 @@ isZoomAutoFitEnabled(blockOrScene: DesignBlockId): boolean
 ```
 
 **Parameters:**
-
 - `blockOrScene` - The scene or a block in the scene for which to query the zoom auto-fit.
 
 **Returns:** True if the given block has auto-fit set or the scene contains a block for which auto-fit is set, false
@@ -546,22 +530,10 @@ Experimental features that may change or be removed in future versions.
 
 Continually ensures the camera position to be within the width and height of the blocks axis-aligned bounding box.
 Disables any previously set camera position clamping in the scene and also takes priority over clamp camera commands.
-
 ```javascript
 // Keep the scene with padding of 10px within the camera
-engine.scene.unstable_enableCameraPositionClamping(
-  [scene],
-  10.0,
-  10.0,
-  10.0,
-  10.0,
-  0.0,
-  0.0,
-  0.0,
-  0.0
-);
+engine.scene.unstable_enableCameraPositionClamping([scene], 10.0, 10.0, 10.0, 10.0, 0.0, 0.0, 0.0, 0.0);
 ```
-
 Without padding, this results in a tight clamp on the block. With padding, the padded part of the
 blocks is ensured to be visible.
 
@@ -570,7 +542,6 @@ unstable_enableCameraPositionClamping(ids: DesignBlockId[], paddingLeft?: number
 ```
 
 **Parameters:**
-
 - `ids` - The blocks to which the camera position is adjusted to, usually, the scene or a page.
 - `paddingLeft` - Optional padding in screen pixels to the left of the block.
 - `paddingTop` - Optional padding in screen pixels to the top of the block.
@@ -584,7 +555,6 @@ unstable_enableCameraPositionClamping(ids: DesignBlockId[], paddingLeft?: number
 ### unstable_disableCameraPositionClamping()
 
 Disables any previously set position clamping for the current scene.
-
 ```javascript
 engine.scene.unstable_disableCameraPositionClamping();
 ```
@@ -594,13 +564,11 @@ unstable_disableCameraPositionClamping(blockOrScene?: number | null): void
 ```
 
 **Parameters:**
-
 - `blockOrScene` - Optionally, the scene or a block in the scene for which to query the position clamping.
 
 ### unstable_isCameraPositionClampingEnabled()
 
 Queries whether position clamping is enabled.
-
 ```javascript
 engine.scene.unstable_isCameraPositionClampingEnabled();
 ```
@@ -610,7 +578,6 @@ unstable_isCameraPositionClampingEnabled(blockOrScene?: number | null): boolean
 ```
 
 **Parameters:**
-
 - `blockOrScene` - Optionally, the scene or a block in the scene for which to query the position clamping.
 
 **Returns:** True if the given block has position clamping set or the scene contains a block for which position clamping is set, false
@@ -619,18 +586,9 @@ otherwise.
 ### unstable_enableCameraZoomClamping()
 
 Continually ensures the zoom level of the camera in the active scene to be in the given range.
-
 ```javascript
 // Allow zooming from 12.5% to 800% relative to the size of a page
-engine.scene.unstable_enableCameraZoomClamping(
-  [page],
-  0.125,
-  8.0,
-  0.0,
-  0.0,
-  0.0,
-  0.0
-);
+engine.scene.unstable_enableCameraZoomClamping([page], 0.125, 8.0, 0.0, 0.0, 0.0, 0.0);
 ```
 
 ```typescript
@@ -638,7 +596,6 @@ unstable_enableCameraZoomClamping(ids: DesignBlockId[], minZoomLimit?: number, m
 ```
 
 **Parameters:**
-
 - `ids` - The blocks to which the camera zoom limits are adjusted to, usually, the scene or a page.
 - `minZoomLimit` - The minimum zoom level limit when zooming out, unlimited when negative.
 - `maxZoomLimit` - The maximum zoom level limit when zooming in, unlimited when negative.
@@ -650,7 +607,6 @@ unstable_enableCameraZoomClamping(ids: DesignBlockId[], minZoomLimit?: number, m
 ### unstable_disableCameraZoomClamping()
 
 Disables any previously set zoom clamping for the current scene.
-
 ```javascript
 engine.scene.unstable_disableCameraZoomClamping();
 ```
@@ -660,13 +616,11 @@ unstable_disableCameraZoomClamping(blockOrScene?: number | null): void
 ```
 
 **Parameters:**
-
 - `blockOrScene` - Optionally, the scene or a block for which to query the zoom clamping.
 
 ### unstable_isCameraZoomClampingEnabled()
 
 Queries whether zoom clamping is enabled.
-
 ```javascript
 engine.scene.unstable_isCameraZoomClampingEnabled();
 ```
@@ -676,7 +630,6 @@ unstable_isCameraZoomClampingEnabled(blockOrScene?: number | null): boolean
 ```
 
 **Parameters:**
-
 - `blockOrScene` - Optionally, the scene or a block for which to query the zoom clamping.
 
 **Returns:** True if the given block has zoom clamping set or the scene contains a block for which zoom clamping is set, false otherwise.
@@ -686,7 +639,6 @@ unstable_isCameraZoomClampingEnabled(blockOrScene?: number | null): boolean
 ### onZoomLevelChanged()
 
 Subscribe to changes to the zoom level.
-
 ```javascript
 const unsubscribeZoomLevelChanged = engine.scene.onZoomLevelChanged(() => {
   const zoomLevel = engine.scene.getZoomLevel();
@@ -699,7 +651,6 @@ onZoomLevelChanged(callback: () => void): (() => void)
 ```
 
 **Parameters:**
-
 - `callback` - This function is called at the end of the engine update, if the zoom level has changed.
 
 **Returns:** A method to unsubscribe.
@@ -707,7 +658,6 @@ onZoomLevelChanged(callback: () => void): (() => void)
 ### onActiveChanged()
 
 Subscribe to changes to the active scene rendered by the engine.
-
 ```javascript
 const unsubscribe = engine.scene.onActiveChanged(() => {
   const newActiveScene = engine.scene.get();
@@ -719,11 +669,10 @@ onActiveChanged(callback: () => void): (() => void)
 ```
 
 **Parameters:**
-
 - `callback` - This function is called at the end of the engine update, if the active scene has changed.
 
 **Returns:** A method to unsubscribe.
 
 ---
 
-For complete type definitions, see the [CE.SDK TypeScript API Reference](https://img.ly/docs/cesdk/engine/api/).
+For complete type definitions, see the [CE.SDK TypeScript API Reference](https://img.ly/docs/cesdk/engine/api/).

package/assets/docs/guide/api/VariableAPI.md

@@ -24,7 +24,6 @@ setString(key: string, value: string): void
 ```
 
 **Parameters:**
-
 - `key` - The variable's key.
 - `value` - The text value to assign to the variable.
 
@@ -37,7 +36,6 @@ getString(key: string): string
 ```
 
 **Parameters:**
-
 - `key` - The variable's key.
 
 **Returns:** The text value of the variable.
@@ -51,9 +49,8 @@ remove(key: string): void
 ```
 
 **Parameters:**
-
 - `key` - The variable's key to remove.
 
 ---
 
-For complete type definitions, see the [CE.SDK TypeScript API Reference](https://img.ly/docs/cesdk/engine/api/).
+For complete type definitions, see the [CE.SDK TypeScript API Reference](https://img.ly/docs/cesdk/engine/api/).