@imgly/codesign-mcp 0.1.0

package/assets/docs/guide/rules/asset-handling.md

@@ -0,0 +1,180 @@
+# Asset Handling
+
+Patterns for working with images, URIs, and fills in CE.SDK.
+
+## Image Format: Use PNG or WebP, Not SVG
+
+CE.SDK uses a **Skia-based rendering engine** with limited SVG support. Complex SVGs (gradients, filters, advanced paths) may render incorrectly or as blank.
+
+**Recommended formats:**
+
+- **PNG** — Best compatibility, supports alpha transparency
+- **WebP** — Smaller file size, good browser support
+- **JPEG** — For photos without transparency
+
+**Converting SVGs to PNG:**
+
+```javascript
+import sharp from 'sharp';
+
+await sharp('input.svg')
+  .resize(800, 940)
+  .png({ compressionLevel: 6 })
+  .toFile('output.png');
+
+// Verify alpha channel is preserved
+const meta = await sharp('output.png').metadata();
+console.log(meta.hasAlpha); // true
+console.log(meta.channels); // 4
+```
+
+---
+
+## URI Resolution
+
+CE.SDK resolves **relative URIs** against `config.baseURL`, which defaults to the IMG.LY CDN:
+
+```
+config.baseURL = 'https://cdn.img.ly/packages/imgly/cesdk-js/1.67.0/assets'
+```
+
+A URI like `/mockups/tshirt.png` becomes `https://cdn.img.ly/.../mockups/tshirt.png` — not `https://yourapp.com/mockups/tshirt.png`.
+
+### Resolving Local Assets
+
+For assets served from your app's `public/` directory, prepend the app origin:
+
+```typescript
+function resolveLocalUri(uri: string): string {
+  if (uri.startsWith('/')) {
+    return `${window.location.origin}${uri}`;
+  }
+  return uri;
+}
+
+// Usage
+const absoluteUri = resolveLocalUri('/mockups/tshirt_white_front.png');
+// → 'http://localhost:5173/mockups/tshirt_white_front.png'
+```
+
+Apply this helper **before** passing URIs to any CE.SDK image API.
+
+---
+
+## Source Sets vs. Single URI
+
+CE.SDK supports two ways to set an image on a fill block:
+
+### `setSourceSet` (Preferred)
+
+Provides image dimensions alongside the URI, enabling better layout and cropping:
+
+```typescript
+const fill = engine.block.getFill(block);
+engine.block.setSourceSet(fill, 'fill/image/sourceSet', [
+  { uri: 'https://example.com/mockup.png', width: 800, height: 940 }
+]);
+```
+
+The `Source` type from `@cesdk/engine`:
+
+```typescript
+interface Source {
+  uri: string;
+  width: number;
+  height: number;
+}
+```
+
+### `setString` (Simple but Limited)
+
+Sets only the URI — the engine must load the image to determine dimensions:
+
+```typescript
+engine.block.setString(
+  fill,
+  'fill/image/imageFileURI',
+  'https://example.com/mockup.png'
+);
+```
+
+Use `setSourceSet` when you know the image dimensions (which you usually do for mockups and templates).
+
+---
+
+## Fill Types
+
+CE.SDK supports several fill types:
+
+| Fill Type | Created With                       | Use Case                                  |
+| --------- | ---------------------------------- | ----------------------------------------- |
+| `'image'` | `engine.block.createFill('image')` | Product mockups, user photos, backgrounds |
+| `'color'` | `engine.block.createFill('color')` | Solid color backgrounds, placeholders     |
+| `'video'` | `engine.block.createFill('video')` | Video backgrounds                         |
+
+### Setting Fills
+
+```typescript
+// Image fill
+const imageFill = engine.block.createFill('image');
+engine.block.setFill(block, imageFill);
+engine.block.setSourceSet(imageFill, 'fill/image/sourceSet', sources);
+
+// Color fill (e.g. transparent page background)
+const colorFill = engine.block.getFill(page); // pages have a default fill
+engine.block.setColor(colorFill, 'fill/color/value', {
+  r: 0,
+  g: 0,
+  b: 0,
+  a: 0
+});
+```
+
+---
+
+## Color Variant Pattern
+
+For products with multiple color variants (t-shirt colors, case colors, etc.), use a `{{color}}` placeholder in the URI template:
+
+```typescript
+// Product configuration
+const mockupUri = '/mockups/tshirt_{{color}}_front.png';
+
+// At runtime, replace with the selected color
+const resolvedUri = resolveLocalUri(
+  mockupUri.replace('{{color}}', selectedColor.id)
+);
+// → 'http://localhost:5173/mockups/tshirt_black_front.png'
+```
+
+### File Naming Convention
+
+```
+/public/mockups/
+  tshirt_white_front.png
+  tshirt_white_back.png
+  tshirt_black_front.png
+  tshirt_black_back.png
+  tshirt_red_front.png
+  tshirt_red_back.png
+  ...
+```
+
+Pattern: `{product}_{colorId}_{areaId}.png`
+
+### Pre-creating All Variants
+
+For smooth color switching, pre-create a mockup block for every area × color combination and toggle visibility rather than swapping image URIs:
+
+```typescript
+for (const area of product.areas) {
+  for (const color of product.colors) {
+    const block = createMockupBlock(engine, scene);
+    engine.block.setName(block, `Mockup-${area.id}-${color.id}`);
+    configureMockupBlock(engine, block, area, color);
+    engine.block.setVisible(block, false); // hidden until selected
+  }
+}
+```
+
+This avoids image loading delays when switching colors.

package/assets/docs/guide/rules/common-pitfalls.md

@@ -0,0 +1,272 @@
+# Common Pitfalls
+
+Non-obvious failure modes when building with CE.SDK and their solutions.
+
+## `alwaysOnBottom` Is Unreliable for Page Children
+
+**Problem:** Setting `alwaysOnBottom: true` on a graphic block that is a child of a page does not reliably keep it behind other page children. The block may render on top of user content.
+
+**Solution:** For background images (like product mockups), attach the graphic block to the **scene** — not to the page. Use `engine.block.insertChild(sceneBlock, block, 0)` to place it behind all pages.
+
+See: `mockup-editor-architecture.md` (in the rules directory)
+
+---
+
+## SVGs Don't Render Reliably
+
+**Problem:** CE.SDK uses a Skia-based rendering engine that has limited SVG support. SVGs with `<linearGradient>`, `<radialGradient>`, complex `<path>` elements, or certain filters may render as blank or broken.
+
+**Solution:** Convert SVGs to PNG (or WebP) before using them in CE.SDK. Use a library like `sharp`:
+
+```javascript
+import sharp from 'sharp';
+await sharp('mockup.svg').resize(800, 940).png().toFile('mockup.png');
+```
+
+Ensure PNGs preserve alpha transparency (`hasAlpha: true`).
+
+---
+
+## Relative URIs Resolve Against the CDN, Not Your App
+
+**Problem:** CE.SDK resolves relative URIs against `config.baseURL` (typically `https://cdn.img.ly/packages/imgly/cesdk-js/...`). A URI like `/mockups/tshirt.png` will resolve to the CDN, not your app's origin.
+
+**Solution:** Convert local asset paths to absolute URLs:
+
+```typescript
+function resolveLocalUri(uri: string): string {
+  if (uri.startsWith('/')) {
+    return `${window.location.origin}${uri}`;
+  }
+  return uri;
+}
+```
+
+Apply this before passing URIs to `setSourceSet` or `setString('fill/image/imageFileURI', ...)`.
+
+---
+
+## Scene Creation Can Reset Feature Flags
+
+**Problem:** Scene creation may reset editor settings like `singlePageMode` or `page/dimOutOfPageAreas`. Settings applied in the config's `featureFlags` may not survive scene creation.
+
+**Solution:** Use the action-based scene creation, or manual `engine.scene.create()` for full control:
+
+```typescript
+// Approach A: Action-based scene creation (recommended)
+await cesdk.actions.run('scene.create', {
+  page: {
+    sourceId: 'ly.img.page.presets',
+    assetId: 'ly.img.page.presets.print.iso.a6.landscape'
+  }
+});
+
+// For video scenes, add mode: 'Video'
+await cesdk.actions.run('scene.create', {
+  mode: 'Video',
+  page: {
+    sourceId: 'ly.img.page.presets',
+    assetId: 'ly.img.page.presets.instagram.story'
+  }
+});
+
+// With custom dimensions
+await cesdk.actions.run('scene.create', {
+  page: { width: 1080, height: 1920, unit: 'Pixel' }
+});
+
+// Approach B: Manual scene creation (preferred for mockup editors)
+engine.scene.create('Free');
+engine.editor.setSettingBool('page/dimOutOfPageAreas', false);
+```
+
+---
+
+## Asset Sources Must Be Added as Plugins
+
+**Problem:** Asset sources are not available by default. Each asset source must be explicitly added as a plugin.
+
+**Solution:** Import and add individual asset source plugins from `@cesdk/cesdk-js/plugins`:
+
+```typescript
+import {
+  BlurAssetSource,
+  ColorPaletteAssetSource,
+  CropPresetsAssetSource,
+  DemoAssetSources,
+  EffectsAssetSource,
+  FiltersAssetSource,
+  PagePresetsAssetSource,
+  StickerAssetSource,
+  TextAssetSource,
+  TextComponentAssetSource,
+  TypefaceAssetSource,
+  UploadAssetSources,
+  VectorShapeAssetSource
+} from '@cesdk/cesdk-js/plugins';
+
+// Default asset source plugins
+await cesdk.addPlugin(new BlurAssetSource());
+await cesdk.addPlugin(new ColorPaletteAssetSource());
+await cesdk.addPlugin(new CropPresetsAssetSource());
+await cesdk.addPlugin(new EffectsAssetSource());
+await cesdk.addPlugin(new FiltersAssetSource());
+await cesdk.addPlugin(new PagePresetsAssetSource());
+await cesdk.addPlugin(new StickerAssetSource());
+await cesdk.addPlugin(new TextAssetSource());
+await cesdk.addPlugin(new TextComponentAssetSource());
+await cesdk.addPlugin(new TypefaceAssetSource());
+await cesdk.addPlugin(new VectorShapeAssetSource());
+
+// Demo and upload sources
+await cesdk.addPlugin(
+  new UploadAssetSources({ include: ['ly.img.image.upload'] })
+);
+await cesdk.addPlugin(
+  new DemoAssetSources({
+    include: ['ly.img.image.*', 'ly.img.templates.social.*']
+  })
+);
+```
+
+Asset source IDs:
+
+| Plugin Class                | Asset Source ID          |
+| --------------------------- | ------------------------ |
+| `BlurAssetSource`           | `ly.img.blur`            |
+| `CaptionPresetsAssetSource` | `ly.img.caption.presets` |
+| `ColorPaletteAssetSource`   | `ly.img.color.palette`   |
+| `CropPresetsAssetSource`    | `ly.img.crop.presets`    |
+| `EffectsAssetSource`        | `ly.img.effect`          |
+| `FiltersAssetSource`        | `ly.img.filter`          |
+| `PagePresetsAssetSource`    | `ly.img.page.presets`    |
+| `StickerAssetSource`        | `ly.img.sticker`         |
+| `TextAssetSource`           | `ly.img.text`            |
+| `TextComponentAssetSource`  | `ly.img.text.components` |
+| `TypefaceAssetSource`       | `ly.img.typeface`        |
+| `VectorShapeAssetSource`    | `ly.img.vector.shape`    |
+
+---
+
+## White-on-White Invisible Fills
+
+**Problem:** Setting a white product mockup as a page's image fill makes it invisible — white image on white canvas background.
+
+**Solution:** Don't use page image fills for mockups. The correct architecture uses:
+
+1. **Transparent** page fill (`{ r: 0, g: 0, b: 0, a: 0 }`)
+2. **Scene-level mockup block** behind the page
+3. CE.SDK's gray canvas background provides contrast
+
+See: `mockup-editor-architecture.md` (in the rules directory)
+
+---
+
+## `contentFillMode` Is Block-Level, Not Fill-Level
+
+**Problem:** Trying to set `fill/content/fillMode` or `contentFillMode` on an `ImageFill` block throws:
+
+```
+Property not found: "fill/content/fillMode"
+Type of member named "contentFillMode" on "ImageFill" is not reflected.
+```
+
+**Solution:** Content fill mode is set on the **block**, not the fill:
+
+```typescript
+// Wrong — this property does not exist on the fill
+engine.block.setString(fill, 'fill/content/fillMode', 'Cover');
+
+// Correct — use the convenience method on the block
+engine.block.setContentFillMode(graphicBlock, 'Cover');
+
+// Also correct — use setEnum with the property path
+engine.block.setEnum(graphicBlock, 'contentFill/mode', 'Cover');
+```
+
+---
+
+## Use `setSourceSet` Instead of `setString` for Images
+
+**Problem:** Using `setString(fill, 'fill/image/imageFileURI', uri)` works but doesn't provide image dimensions to the engine, which can cause layout and cropping issues.
+
+**Solution:** Use `setSourceSet` which includes width and height metadata:
+
+```typescript
+// Preferred
+engine.block.setSourceSet(fill, 'fill/image/sourceSet', [
+  { uri: 'https://example.com/image.png', width: 800, height: 940 }
+]);
+
+// Avoid for production use
+engine.block.setString(
+  fill,
+  'fill/image/imageFileURI',
+  'https://example.com/image.png'
+);
+```
+
+The `Source` type from `@cesdk/engine` defines the shape: `{ uri: string; width: number; height: number }`.
+
+---
+
+## `zoomToBlock` Uses an Options Object
+
+**Problem:** `zoomToBlock` requires an options object for padding, not positional arguments.
+
+**Solution:**
+
+```typescript
+await engine.scene.zoomToBlock(pageBlock, {
+  paddingLeft: 40,
+  paddingTop: 40,
+  paddingRight: 40,
+  paddingBottom: 40
+});
+```
+
+**Note:** `zoomToBlock` is not for page switching. It only changes the viewport, not the active page. Use `cesdk.unstable_switchPage(pageId)` to switch pages in single-page mode.
+
+---
+
+## Page `editor/select` Scope and Canvas Interactions
+
+**Problem:** When the page itself is selectable, users may accidentally select and move it, breaking the layout.
+
+**Solution:** Disable the select scope on page blocks:
+
+```typescript
+engine.block.setScopeEnabled(page, 'editor/select', false);
+```
+
+This prevents the page from being selected while still allowing interaction with child elements (text, images, shapes).
+
+---
+
+## Never Rewrite Starter Kit Files From Scratch
+
+**Problem:** Writing `index.html`, `vite.config.ts`, `tsconfig.json`, or `tsconfig.base.json` from scratch leads to missing styles. The starter kit's `index.html` contains critical CSS resets (zero margin/padding, overflow hidden, overscroll-behavior) required for full-bleed editors.
+
+**Solution:** Copy these files directly from the starter kit and adapt only what's necessary (e.g., changing the script `src` for React). Do not rewrite them from scratch when the kit already provides them.
+
+---
+
+## Starter Kits Are TypeScript: Copy First, Then Transpile for JS
+
+**Problem:** All bundled starter kits use TypeScript (`.ts` files, `tsconfig.json`, type annotations). Copying them into a JavaScript project without conversion leads to syntax errors. Manually rewriting or converting files by hand leads to missing CSS resets, broken Vite configs, or incorrect plugin initialization.
+
+**Solution:** Always **copy the starter kit into the user's project first**, then run the bundled transpile script on the **user's project copy**:
+
+```bash
+# 1. Install typescript temporarily (needed by the transpile script)
+cd /path/to/users/project && npm install --no-save typescript
+
+# 2. Run the transpile script on the user's project copy (NOT on the starter kit source)
+node <path-to-skill>/scripts/transpile-to-js.mjs /path/to/users/project
+```
+
+The script strips type annotations, renames `.ts` to `.js`, removes `tsconfig.json`/`tsconfig.base.json`, updates `index.html` references, and cleans TypeScript dependencies from `package.json`.
+
+Find the script with Glob: `**/skills/build/scripts/transpile-to-js.mjs`
+
+**Never run the transpile script on the starter kit source directory.** Never manually strip types or rewrite files by hand. Copy first, then transpile the copy.

package/assets/docs/guide/rules/content-fill-mode.md

@@ -0,0 +1,29 @@
+# Content Fill Mode Belongs on the Block
+
+The `contentFill/mode` property is set on the **graphic block**, not on the fill object. The correct property path is `'contentFill/mode'`, not `'fill/image/contentFillMode'`.
+
+## Rule
+
+Always set `contentFill/mode` on the block that owns the fill, not on the fill itself.
+
+```ts
+// WRONG — this property does not exist on the fill
+engine.block.setEnum(fill, 'fill/image/contentFillMode', 'Cover');
+
+// CORRECT — set on the graphic block
+engine.block.setEnum(block, 'contentFill/mode', 'Cover');
+```
+
+## Common Values
+
+| Value       | Behavior                                               |
+| ----------- | ------------------------------------------------------ |
+| `'Contain'` | Scale to fit within the block, preserving aspect ratio |
+| `'Cover'`   | Scale to fill the block, cropping as needed            |
+| `'Crop'`    | Manual crop region                                     |
+
+## Why This Is Confusing
+
+The fill object holds the image source (`fill/image/imageFileURI`), so it seems logical that the fill mode would also live on the fill. However, `contentFill/mode` controls how the block **displays** its content fill — a layout concern that belongs to the block, not the fill data.
+
+When in doubt, use `engine.block.findAllProperties(block)` to check which object owns the property you need.