`/text node with just text content | `text` — `payload`, `color`, `font`, `font_size`, `font_weight`, `text_align`, `vertical_align`. A source `
` or hard line break becomes a literal `\n` inside `payload` (confirmed: `"payload": "PUSH\nHARDER"` rendered as two lines, matching the source's `PUSH
HARDER`) — don't try to split it into two separate text layers. |
| A `
` styled as a button/pill (background + radius + text, e.g. a CTA) | `button` — use this native type directly, don't decompose into shape+text. Same text properties, plus `background_color`, `radius`, and a required nested `padding: {vertical, horizontal}` — see the note right after this table. **No `vertical_align`** — including it fails validation with `unknown_field`. |
| A `
` styled as a filled/bordered box with no text | `shape` — `background_color`, `radius`, optional nested `stroke: {color, width}` |
| An `
`, or a CSS `background-image` on a container | `image` — see `abyssale-import` for supplying the source (hosted URL preferred, inline base64 for a small asset, or the upload-command flow for a local file) |
| An inline `
` | No native SVG/vector layer type exists — rasterize it (e.g. with `cairosvg`) and import as one `image` layer. Don't try to decompose an SVG's sub-elements into separate Abyssale layers unless there's a real reason to animate them independently — flatten it as one piece by default |
| Text baked into a full-canvas transparent PNG rather than a live DOM text node (seen on real production banners using custom stroked/bevelled typography no web font could reproduce) | `image`, not `text` — there's no live font/color/content to extract |
| A `` element | `video` — `properties.default.src` set to a hosted `.mp4` URL, `layout` as usual. Confirmed working; see the Scope section above. |
**Text auto-wraps by declared `width` — a manual `\n` is only needed for a source
` -i render.mp4 -frames:v 1 out.jpg`) to
confirm animation actually progresses — don't trust a clean `validate_only` alone.
Pull a frame near the **end** of the timeline specifically, not just mid-animation
ones: a layer whose `start_at_s`/`end_at_s` window was mistakenly scoped to its own
tween (see above) renders fine early on and only reveals the bug by vanishing late,
which a check at t=0 and t=mid alone won't catch.
A plain solid-color shape's rotation can't be visually confirmed this way (no
asymmetry to judge by) — use a shape with a visible feature, or note plainly that
rotation wasn't verified.
## Animation — best effort, not a full reproduction
If the source animates — CSS `@keyframes`/`transition`, or a GSAP timeline — set the
design's `type` to `"animated"` and add **two** animation blocks: one at the payload
**root** (`"animation": {"duration": , "screenshot_at_s": }`) and
one **per animated layer** (`"animation": {"start_at_s", "end_at_s", "tweens": [...]}`).
Omitting the root one fails with `missing_required`.
**A layer's `start_at_s`/`end_at_s` is its presence window on the timeline, not just
its tween's active span — get this wrong and the element vanishes right when its
fade/slide-in finishes, instead of staying visible.** Confirmed by rendering a design
where every layer's `start_at_s`/`end_at_s` was set to match its own fade-in's timing
(e.g. `0.1`–`0.7` for a layer whose tween ran 0.1→0.7): the layer was only ever
rendered *inside* that window — it wasn't there before `start_at_s`, and it
disappeared again the instant `end_at_s` passed, discarding the fade-in's whole point
(that the element should then stay on screen). Pulling frames from the rendered mp4 at
increasing timestamps showed elements popping out one by one as their individual
windows closed, until only the last-arriving layer remained. **Always set
`start_at_s: 0` and `end_at_s: ` on every layer** (matching the
official multi-format example, where every layer spans the full timeline even though
its tween only moves during a sub-range of it) — the tween's own keyframe `data.time`
values are what stagger the actual movement inside that constant presence window; the
engine holds the first keyframe's value before the tween starts and the last
keyframe's value after it ends.
**Widening a button layer to a full-duration window can then trigger a `cannot fit`
render error that an identical narrower-window version didn't have** — confirmed by
isolating the change to one `button` layer, same `payload`/`padding`/`font_size`,
only the window widened: the narrow-window version rendered fine, the wide-window one
failed with `Element error: The text '' cannot fit within the defined
space.`, reproducibly, across repeated renders. Cause (inferred from the fix that
resolved it, not confirmed from Abyssale internals): a full-duration window puts the
button in a static "resting" pose before its tween starts, and in that pose the
declared `layout.width` seems to be enforced as a hard cap that `padding`-driven
auto-sizing (see the padding note above) doesn't get to override — unlike during the
tween's own active span, where it rendered fine at the same padding. **Fix: give an
animated button's declared `layout.width` real margin beyond `padding.horizontal * 2 +
estimated text width`, don't rely on padding alone once the layer spans the full
timeline** — widening one button from 130px to 175px (same text/padding/font)
resolved it with no other change.
**Tween vocabulary** (confirmed against the official reference,
developers.abyssale.com/rest-api/designs/import/animated):
| Tween type | Keyframe `attr` | Range |
|---|---|---|
| `slide` | `left`, `top` (px, both required) | signed px |
| `scale` | `scale` (+ optional `scale_origin_x`/`scale_origin_y`) | **0–100, hard-capped — 100 is the ceiling, not just "as designed."** A keyframe above 100 fails validation with `out_of_range` (confirmed: `115` rejected outright). A CSS pulse that overshoots past 100% (e.g. `scale(1)` → `scale(1.15)`) has no direct equivalent — remap it as a grow-in *up to* 100 instead (e.g. `88` → `100`), never as `100` → `>100`. |
| `rotate` | `angle` | unbounded signed degrees, not clamped to ±360 |
| `fade` | `opacity` | 0.0–1.0 (a fraction — unlike `scale`'s 0–100) |
| `audioFade` | `volumeEffect` | 0.0–1.0 |
| `textEffect` | `typewriting` (0 or 100 only) + `textEffectType` (`classic`, `softFade`, `focusIn`, `riseUp`, `riseDown`) | — |
GSAP ease strings carry over directly into `ease`, **including parametrized ones**
(`"back.out(1.7)"`, `"elastic.out(1, 0.5)"` both validate and render correctly).
**Multi-format and `slide` tweens don't mix safely.** A layer's `tweens` are declared
*once*, not per format, but a `slide` tween's `attr.left`/`attr.top` are absolute
canvas pixels — and if that layer's `layout` differs by format (the normal case for a
multi-format design), those absolute values can only be correct for one format's box.
Whether the engine silently reinterprets them per-format or just applies the same
pixels everywhere is **not confirmed either way** — it was sidestepped, not tested, by
avoiding `slide` entirely on any layer with per-format `layout` in the one multi-format
animated design built so far (rotate/scale/fade were used instead throughout, since
none of those three reference a position and so can't go wrong across formats). Do the
same unless someone actually confirms the real behavior: on a multi-format animated
design, restrict `slide` to a layer whose `layout` box is byte-identical across every
format, and use rotate/scale/fade for anything whose position varies by format.
**`.from()` is not "`.to()` reversed" — check what it actually animates FROM and TO.**
GSAP's `.from(el, {opacity: 1, ...})` animates from the given values TO the element's
own resting CSS state. If that resting state is `opacity: 0` (e.g. a `.hidden` class),
the call is a flash-then-fade-**out**, not a fade-in — the opposite of what those same
values mean on `.to()`. Don't "normalize" a `.from()` call to match its `.to()`
siblings without checking the element's CSS resting state first — assuming it must be
an authoring mistake produced a real, confusing bug (an element stayed at opacity 1
for the rest of the timeline instead of correctly disappearing, ghosting behind every
later scene).
**A "hold"** (appears, stays, then disappears) is a validated pattern: pack 4
keyframes into one `fade` tween — `[opacity:0 @ start]`, `[opacity:1 @ fade-in end]`,
`[opacity:1 @ hold end — same value, later time]`, `[opacity:0 @ fade-out end]`. If
several layers share one box and take turns being visible (a sequential multi-scene
banner), give each its own hold-pattern tween with non-overlapping visible windows —
compute absolute times from the GSAP timeline by hand (`"+=N"` adds `N`s after the
current end of the timeline; `"<"` starts alongside the immediately-preceding tween's
start). If two scenes end up visible at once, the likely cause is a layer that never
actually reaches opacity 0 — re-check its keyframes (and its `.from()`/`.to()` intent)
before assuming it's an Abyssale bug.
### Effects with no native equivalent — approximate simply, don't over-engineer
None of these have a native Abyssale tween. Use the closest single native
approximation and move on — don't build an elaborate multi-layer or multi-keyframe
reproduction for the sake of fidelity:
- **A curved/bezier motion path** → a plain `slide` from the path's start point to its
end point (skip the intermediate waypoints unless there's a strong reason to keep
them — a straight line is already a reasonable best-effort stand-in).
- **`repeat`/`yoyo` (looping)** → play it once. Only chain a couple of extra keyframe
pairs manually (e.g. `angle` 0→360→720) if a short, obviously-bounded repeat is
clearly the point of the effect — never attempt to fake a long or indefinite loop.
- **`filter: blur()`, `backdrop-filter`, glassmorphism, complex gradients** → don't
approximate with a flat-color Abyssale shape, it reads as visibly wrong rather than
simplified. If the effect is purely decorative, it's fine to drop it. If it matters
to the design, rasterize just that portion with a headless browser
(`google-chrome --headless=new --screenshot=out.png "file://"`, with the
layers you're keeping native hidden via injected `visibility: hidden` CSS first)
and import the result as one `image` layer.
- **Per-character text stagger** → animate the whole text block as one unit; the
stagger itself is lost, not approximated.
- **3D transforms (`rotateX`/`rotateY`)** → drop the 3D aspect, keep any accompanying
2D motion (fade/slide) on the same element.
- **Multiple independently-animated pieces inside one SVG** → flatten the whole SVG
to one rasterized `image` layer and apply a single simple tween to it (fade/scale
in, say) rather than rasterizing each sub-element separately to preserve individual
motion — that level of decomposition is not worth it for a best-effort pass.
## Measuring real positions (non-fixed-canvas layouts)
1. Inject a script before `