caption-decorations
Caption decoration authoring
Choose the asset form from the behavior, not the visual appearance.
| Need | Declare | Caption row |
|---|---|---|
| Artwork generated from measured word/line geometry | type: "decoration" with a procedural shape definition |
preset: "<asset-id>" plus params |
| Arbitrary editable artwork: shapes, text, media, nested scenes, stickers | type: "scene" with a scene body |
content.kind: "scene_ref" |
| External image/video/Lottie/SVG | its ordinary media asset type | content.kind: "media" |
type: "decoration" is not a general scene container. It is the measured caption-definition language: its shape reads boxW, boxH, optional measured path, and declared params. General artwork already has the full scene language through scene_ref.
Caption-row padding, size, gap, and offset are multiples of the effective caption font em. Platform text measurement still owns x/width, optical centring, and the advance between wrapped lines. Definition-side boxW/boxH are the resulting decoration box after those row fields are applied.
Line wrapping happens at the style's wrapWidth (composition pixels) when it sets one, else at the FULL WIDTH of the composition it renders in (no margin). Either width is fixed in PIXELS, never scaled to font size, so a SMALLER font fits more characters before it wraps: shrinking the font can turn two wrapped lines into one wider one, up to that width.
Generated decoration/segment layer ids share a stem. A caption segment/decoration gets a <layer>__seg<i>__dec<d> stem, so an id containing __seg0__dec0 belongs to the first segment's first decoration. It is followed by a form suffix (e.g. __band, __stick, __bandreveal, __pillw<word>) that is not part of the contract. Select a decoration by its stem or its structure (target/place/row index), never by its full generated id.