api

## 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 `../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 `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. --- # The edit-code API surface (docs/api/signatures.d.ts) Everything edit code writes through, inline below. The upstream CE.SDK core is the rest of that file — `signatures.d.ts` — when you need a member this section lacks. ```typescript // ============================================================================ // codesign extension: engine.design — write ALL mutations through this API. // engine.block.* is the legacy/extended surface: use it only for reads the // facade lacks (getTextRuns and other diagnostics). Available inside `edit` code alongside the engine.block.* API it // delegates to. One nested-props dialect replaces the typed accessors // (setFloat/getBool/…), the per-property wrappers (setOpacity, // setStrokeWidth, setPositionX, …) and the is*-state reads. // // Contract: setProps/create validate EVERY leaf before touching the scene — // a bad leaf throws (listing every bad path with suggestions) and nothing is // applied. getProps throws on an unknown selector; it never returns // undefined for a typo. create rolls back on failure (never an orphan). // Attachment state (fill/shape/blur/effects/animations) is the typed // unions below — assign { type, ...props } specs via setProps; the raw // engine.block accessors are never needed for it. // // Units: length leaves (width/height/position, paddings, stroke.width, // dropShadow offsets/radii, page margins) and fontSize accept CSS-style // unit STRINGS — '210mm', '32pt', '340px', '1.2in' — converted against the // scene's current designUnit/fontSizeUnit/dpi at write time, so the value // means what you said regardless of ambient unit state. '50%' on // width/height/position also sets the '<leaf>Mode' to 'Percent' (an // absolute unit pins it to 'Absolute'). A plain number stays engine-native — // EXCEPT on a font size (text.fontSize, a range's size), where the unit is // REQUIRED and a bare number is rejected: engine-native font size is POINTS, // so 64 would render ~267px at 300 dpi. Write '64px' (screen) or '24pt'. // letterSpacing is a FACTOR, never a length. lineHeight: write { visual: n } // (CSS-style x fontSize — the facade converts per font); a bare number is the // ENGINE scale (x the font's contentArea) and renders looser than it reads. // Text glyph color is per-character: fill.solid.color on a text block is // REJECTED — write setProps(id, { text: { color } }) instead. // ============================================================================ // Branded attachment ids — nominal guidance (runtime dispatch enforces the // category): a FillId/EffectId/... is where the matching attachment props // tree applies, never BlockProps. // Durable identity: every id parameter also accepts the block's UUID string // (read it via getProps(id, ['uuid']) or a tree read) — the identity that // persists in the scene file and crosses edits/revisions. An unknown uuid // throws "not in this revision"; a stale numeric handle can't be caught. type BlockRef = DesignBlockId | string /* uuid */; // One node of the document read as a tree; feed a (subset of a) node tree // back to setProps to patch every node by uuid. interface PropsNode { uuid: string; name?: string; type: string; props: BlockProps; children: PropsNode[] } type FillId = DesignBlockId & { readonly __kind?: 'fill' }; type EffectId = DesignBlockId & { readonly __kind?: 'effect' }; type BlurId = DesignBlockId & { readonly __kind?: 'blur' }; type ShapeId = DesignBlockId & { readonly __kind?: 'shape' }; type AnimationId = DesignBlockId & { readonly __kind?: 'animation' }; interface DesignApi { /** EVERY member returns a Promise — always: await engine.design.x(...) * (a floating rejection fails the edit at commit). */ /** THE constructor: one block or a whole subtree, same spec shape at * every level. Looks up any font: { family, weight }, applies props, * attaches to the parent, and awaits the subtree's font/image loads * before returning, so measure() is truthful immediately. Rolls the * WHOLE subtree back on failure. Name the nodes you will touch again: * the name lands on the block and findByName resolves it later. */ create(spec: BuildSpec, opts?: { parent?: BlockRef; index?: number }): Promise<DesignBlockId>; /** Partial deep-merge write. Brand-dispatched: pass a FILL/EFFECT/BLUR/ * SHAPE/ANIMATION block id and the matching attachment props tree * (effect/*, fill/*, … paths as nested keys) applies instead. * Given a PropsNode TREE (a node with uuid+props or children) it * patches every node by uuid — read the tree, transform it in JS, * write it back. Patch-only: an absent block/prop is untouched, never * deleted; uuids resolve for the whole tree before anything applies. */ setProps(id: BlockRef, props: BlockProps | PropsNode): Promise<void>; /** Read leaves or whole subtrees — getProps(id, ['opacity', 'stroke']) — * or omit select for EVERY applicable prop of this block, valued. * { children: true, props?: [...] } reads the whole SUBTREE as one * uuid-keyed PropsNode tree — filter it with plain JS (a selector a * block kind lacks is skipped for that block). The snapshot never * enters your reply unless you print it. */ getProps(id: BlockRef, select?: string[] | { children: true; props?: string[] }): Promise<BlockProps>; /** Editor settings, same dialect. */ setSettings(props: SettingsProps): Promise<void>; getSettings(select?: string[]): Promise<SettingsProps>; /** Resolve a font AND its metrics in one call — by family (the same * Google-Fonts lookup create runs) or by uri (brand fonts). Also warms * the metrics cache behind text.lineHeight: { visual } — after create * with text.font, font(), or loadResources, visual line-heights need * no fetch. No other metrics call is needed. */ font(spec: { family?: string; uri?: string; weight?: FontWeight; style?: FontStyle }): Promise<{ typeface?: Typeface; uri: string; contentArea: number; metrics: { ascender: number; descender: number; lineGap: number; unitsPerEm: number; capHeight: number; xHeight: number } }>; // text.path is raw-or-spec like every attachment: a raw SVG string, or // { shape: 'circle', diameter, align?: 'top' | 'bottom' | 0..1 } — the // spec authors the circle, measures the flat glyph run, centers the // offset and sets the D×D frame (align: 'bottom' = upright underside). // No describe: identity IS props. getProps(id, ['type']) names the block, // getCapabilities answers what it supports, and fill/shape/blur/effects/ // animations round-trip as { type, ...props } specs through // setProps/getProps — attachment ids never circulate. /** Editing scopes (what the browser-editor user may change). */ getScopes(id: BlockRef): Promise<Record<Scope, boolean>>; setScopes(id: BlockRef, scopes: Partial<Record<Scope, boolean>>): Promise<void>; getCapabilities(idOrType: BlockRef | DesignBlockType): Promise<readonly string[]>; // Attachment values are the discriminated unions below — the type picks // the arm, the arm names every prop that type carries. A type MATCHING // what is attached edits it in place; a different type replaces it // (replaced attachment blocks are destroyed, no leaks); null detaches: // await setProps(id, { fill: { type: 'color', color: { value } } }) // await setProps(id, { fill: { enabled: false } }) // no type ⇒ host leaves // Gradient fills round-trip stops; image fills round-trip sourceSet — // getProps(id, ['fill']) → tweak → setProps is lossless. // await setProps(id, { shape: { type: 'rect' } }) · { blur: { type: 'uniform' } } // await setProps(id, { effects: [{ type: 'duotone_filter', duotone_filter: {…} }] })