---
name: api
description: |
  Authoritative TypeScript signatures for the CE.SDK CreativeEngine. Use this
  skill whenever you need the exact signature, parameter types, or return type
  of an `engine.*` method — especially before calling a method you haven't
  used yet. Generated from the `.d.ts` of the same `@cesdk/node` package the
  engine runs, it is THE source of truth; prose docs (the `guide` skill) can
  drift.

  This skill's entry document carries the WHOLE edit-code API surface inline
  — the engine.design facade, the props trees, the attachment unions and the
  capability matrix: all edit code needs, in one read.

  The sub-file "signatures.d.ts" is the same surface plus the upstream CE.SDK
  core — JSDoc-free, every string-vocabulary type (property names, block
  types, enum values) flattened to its literal union; the entry document
  explains how to look a member up in it.
---

## Start here: `engine.design` (inside `edit` code)

For reading and writing block state, prefer the codesign facade over the raw
accessors — one nested-props dialect, one call per block:

```js
const page = await engine.design.create(
  { type: 'page', props: { width: 1080, height: 1920 } },
  { parent: stack }
);
const chip = await engine.design.create(
  {
    type: 'text',
    name: 'chip',
    props: {
      backgroundColor: {
        enabled: true,
        color: ACCENT,
        paddingLeft: 24,
        cornerRadius: 999
      }
    }
  },
  { parent: page }
);
await engine.design.setProps(title, {
  opacity: 0.9,
  stroke: { enabled: true, width: 2 }
});
const { width } = await engine.design.getProps(page, ['width']);
```

- `create(spec, { parent?, index? })` (await it!) is THE constructor — one
  block or a whole subtree, the same spec shape at every level. It folds
  create + appendChild + property writes into one call and rolls back on
  failure (never an orphan). Returns the root block id.
- A spec node carries exactly `type`, `name`, `props` and `children` (nested,
  same shape). Everything else IS props — including the font: naming a
  family (`text: { font: { family, weight } }`) makes `create` — and
  `setProps` — do the Google-Fonts lookup and pick that weight's file. Every
  `engine.design` member returns a Promise: always `await` it (the edit gate
  rejects un-awaited calls).
  `text: { string, ranges }` (style ranges
  replayed reshape-safe), inline `fill: { type, ... }` / `shape` / `blur` /
  `effects: [...]` / `animations` specs all sit under `props`. `create`
  awaits the subtree's font/image loads before returning, so measurements
  after it are trustworthy.
- `name` on any node is written onto the block itself:
  `const [chip] = await engine.design.findByName('chip')` resolves it in this edit
  and in every later one. Name every block you may touch again.
- No `describe`: identity IS props — `getProps(id)` for everything valued,
  `getProps(id, ['type'])` for what a block is, `getCapabilities(idOrType)`
  for what it supports. Attachments (fill/shape/blur/effects/animations)
  round-trip as `{ type, ...props }` specs through setProps/getProps —
  attachment ids never circulate.
- Text is all props too: `setProps(id, { text: { string, font, weight,
case, ranges, path, decoration } })` — leaves apply in a safe order and
  a string-only write auto-preserves style ranges. Read back via
  `getProps(id, ['text.ranges'])` / `['text.paragraphs']`.
- Length props take unit strings: `width: '210mm'`, `fontSize: '32pt'`,
  `'50%'` (sets Percent mode too) — converted against the scene's units at
  write time. Plain numbers stay engine-native, EXCEPT font sizes
  (`text.fontSize`, a range's `size`) where the unit is required: a bare
  number is engine-native points and would render ~4.2× too large, so it is
  rejected.
- `setProps` validates **every** leaf before touching the scene: a bad leaf
  throws listing all bad paths with suggestions, and nothing is applied.
- `getProps(id, ['opacity', 'stroke'])` reads leaves or whole subtrees; an
  unknown selector throws — it never answers a typo with `undefined`.
- The full `BlockProps` / `SettingsProps` trees are at the TOP of
  `signatures.d.ts` (search `interface BlockProps`).
- Attachment state is a discriminated union: assign `{ type, ...props }` to
  `fill`/`shape`/`blur`/`effects`/`animations`. The type picks the arm and
  the arm names every prop it carries. A type MATCHING what is attached
  edits it in place; a different type replaces it; `null` detaches (except
  `effects`, replaced wholesale — `[]` clears). Reads answer in the same
  shape, so `getProps` output feeds straight back in. Tree/layout verbs live on `engine.design` (group, appendChild, align); only export-style I/O stays on `engine.block.*`.
- Video, animation, audio: `playback`, `animations`, `audio` and `track`
  props; recipe and traps in `{{skill:handbook#video.md}}`.
- Scalar wrappers (`setOpacity`, `setStrokeWidth`, …), `is*`/`supports*`
  predicates and editor-UI methods moved to the sub-file
  `signatures-extended.d.ts` — search there if you need an old name; prefer
  the facade + the capability matrix.

## Single file: `signatures.d.ts`

The whole CE.SDK call surface is in `signatures.d.ts` (~2000 lines) —
signatures only, no doc comments, with every alias flattened, so a hit is
usually the whole answer:

1. Find the member (e.g. `setProps`) in `{{skill:api#signatures.d.ts}}` —
   search the file if your host can search skill files, otherwise read it
   once and look the member up.
2. Read about 20 lines of context around the match when the matched line is
   not enough.

What the flattening means for you:

- A vocabulary type is its values: `type DesignBlockType = 'scene' | 'page' |
'graphic' | …` — no `Shorthand`/`(typeof …)[number]` chains to chase. Where
  a `// each also valid as '…<name>…'` comment follows a union, the prefixed
  longhand spelling of every member is accepted too.
- Property-name unions (`FloatPropertyName`, `ColorPropertyName`, …) list
  every legal string for `setFloat`/`setColor`/`getString`-style accessors.
  If a string is not in the union, the engine does not accept it — never
  invent property paths.
- A `/** @deprecated … */` one-liner names the replacement; prefer it.
  Deprecated overloads of a surviving method are omitted entirely — the
  listed signature is the current one.

Look members up by name, not by remembered line numbers: a name survives
CE.SDK updates, a line number does not.

## Browsing a whole class

A name lookup can't answer "what can `engine.scene` do?" — for that, read the
contiguous run that starts at the class declaration. At ~2000 lines total,
whole-class reads are cheap (`BlockAPI` is the largest):

| Class        | Start line |
| ------------ | ---------- |
| AssetAPI     | 1208       |
| **BlockAPI** | **1505**   |
| EditorAPI    | 1755       |
| EventAPI     | 1887       |
| **SceneAPI** | **1988**   |
| VariableAPI  | 2209       |

(If a start line looks off, search for `class BlockAPI` instead.)

## What is NOT in this file

- **Parameter semantics** — units, value ranges, defaults for optional
  parameters. Where a signature says only `r: number`, color components are
  in the range 0–1, never 0–255. For anything else a bare `number`/`string`
  leaves open, check the `guide` skill's topic page before guessing.
- Conceptual prose and topic guides (text, fills, export, rules) → use the
  `guide` skill instead.