From fb10704e3c5dec941d036577c2c6fc00da335b8e Mon Sep 17 00:00:00 2001
From: Abdelrahman Essawy <abdelrahman.mo.essawy@gmail.com>
Date: Wed, 26 Aug 2026 00:04:32 +0300
Subject: [PATCH 1/5] docs(compose): document the shape asset

Covers the centre-anchored position, the 8-digit fill for a constant
scrim, rounded corners and the pixel-square rule for a circle, outlines,
the animated progress bar, and lines and letterbox bars as recipes rather
than schema members. States the two refused combinations and why.

Every JSON snippet on the page was parsed against the live schema, and
the 16:9 circle formula (width 10% pairs with height 17.8%) was rendered
and measured at a 1.000 aspect bounding box before being published.
---
 jobs/compose.mdx | 112 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 112 insertions(+)

diff --git a/jobs/compose.mdx b/jobs/compose.mdx
index eb35326..67761cc 100644
--- a/jobs/compose.mdx
+++ b/jobs/compose.mdx
@@ -356,6 +356,117 @@ A `text` asset renders a styled title. Set the `font`, `size`, `weight`, `color`
   <video src="https://cdn.rendobar.com/assets/showcase/fx/title-lowerthird.mp4" autoPlay loop muted playsInline />
 </Frame>
 
+## Shapes
+
+A `shape` asset draws a rectangle. No image to make, no file to host, and it
+stays sharp at any output resolution.
+
+```json
+"asset": {
+  "type": "shape",
+  "color": "#0A0A0ACC",
+  "position": { "x": "50%", "y": "86%" },
+  "size": { "width": "100%", "height": "22%" }
+}
+```
+
+That is a bar across the lower third, dark enough to read a title on and thin
+enough to see the footage through. Put it on a track below the text.
+
+Two things to know up front. `position` is the **centre** of the shape, not a
+corner, so a full-width bar sits at `x: "50%"` whatever its width. And there is
+no `length`, because a shape has no duration of its own: like text and images it
+runs to the end of its container unless you give it one.
+
+`width` is a percent of the frame's width, `height` a percent of its height.
+
+### Transparency goes in the colour
+
+`color` takes `#RRGGBB` or the 8-digit `#RRGGBBAA`. Use the alpha byte for a
+constant translucency, the way `#0A0A0ACC` does above.
+
+Do not reach for the clip's `opacity` instead. `opacity` dims the fill as well
+as fading it, so a half-opacity white box renders grey rather than white you can
+see through. Keep `opacity` for animated fades.
+
+### Rounded corners and circles
+
+`radius` runs from `0` (square) to `1` (fully round).
+
+At `1`, a wide box becomes a pill and a **pixel-square** box becomes a circle.
+Square in pixels, not in percent: on a 16:9 frame a width of `10%` needs a
+height of `17.8%` (that is `10 × 16/9`). On a 9:16 frame the same width needs
+`5.6%`.
+
+```json
+{ "type": "shape", "color": "#059669", "position": { "x": "12%", "y": "80%" },
+  "size": { "width": "10%", "height": "17.8%" }, "radius": 1 }
+```
+
+### Outlines
+
+`stroke` draws a border just inside the shape's edge. Set `color` to
+`#00000000` and the fill disappears, leaving an outline-only highlight box.
+
+```json
+{ "type": "shape", "color": "#00000000",
+  "position": { "x": "72%", "y": "30%" },
+  "size": { "width": "36%", "height": "34%" },
+  "stroke": { "color": "#F59E0B", "width": 4 } }
+```
+
+`stroke` cannot be combined with `radius` or with `animateTo`, and the API
+rejects both combinations rather than rendering them wrong. The outline is drawn
+as a square band, so a rounded shape would end up with square corners inside a
+rounded edge, and it cannot follow a shape that moves.
+
+### A progress bar is a shape that grows
+
+`animateTo` moves and resizes the shape over the clip, in a straight line.
+Starting from a width of `0%` gives you a progress bar.
+
+```json
+{ "type": "shape", "color": "#FFFFFF",
+  "position": { "x": "50%", "y": "97%" },
+  "size": { "width": "0%", "height": "1.5%" },
+  "animateTo": { "size": { "width": "96%" } } }
+```
+
+A dimension you leave out of `animateTo` keeps its starting value, so the bar
+above grows sideways without changing height. `transform` cannot do this: its
+`scale` is uniform, so it would grow the bar in both directions at once.
+
+### Lines and letterbox bars
+
+There is no `line` type, because a line is a rectangle with a small height.
+
+```json
+{ "type": "shape", "color": "#FFFFFF", "position": { "x": "50%", "y": "50%" },
+  "size": { "width": "60%", "height": "0.4%" } }
+```
+
+For a diagonal, centre the shape and add `transform` to the clip:
+`"transform": { "rotate": 30 }`. Rotation turns the frame about its centre, so a
+centred shape spins in place and an off-centre one swings around the middle of
+the frame.
+
+Letterbox bars are two shapes: one at `y: "5%"`, one at `y: "95%"`, both
+`height: "10%"` and `color: "#000000"`. A full-frame scrim is one shape at
+`100%` by `100%` with a colour like `#00000080`.
+
+### What else a shape takes
+
+Every per-clip field applies. `transform` rotates and repositions it,
+`blendMode` mixes it with the layer below, `blur` softens its edges, and opacity
+keyframes fade it in and out. A track holding only shapes composites as a base
+layer, so a solid colour background is a timeline that references no files at
+all.
+
+What a shape is not is a drawing surface. There is no gradient fill, no ellipse
+and no drop shadow. A rounded rectangle, a pill, a pixel-square circle and an
+outline are the whole set. Anything past that is still an `image` asset.
+
+
 ## Fonts
 
 Name any [Google Fonts](https://fonts.google.com) family in `style.font` and it
@@ -566,6 +677,7 @@ A clip's `asset` is one of:
 | `image` | `src` |
 | `audio` | `src`, `trim`, `volume`, `fadeIn`, `fadeOut` (seconds) |
 | `text` | `text`, `style` |
+| `shape` | `color`, `position` (the shape's **centre**), `size` `{ width, height }`, `radius` (`0` to `1`), `stroke` `{ color, width }`, `animateTo` `{ position, size }`. See [Shapes](#shapes) |
 | `composition` | `timeline`, a nested `{ tracks }` rendered and composited as a single clip. Every clip field below applies to a composition clip too, except `speed` (set speed on the clips inside the composition instead) |
 
 ### Clip fields

From 19fb779167c41b78be946785debdf1b6aab607cf Mon Sep 17 00:00:00 2001
From: Abdelrahman Essawy <abdelrahman.mo.essawy@gmail.com>
Date: Wed, 26 Aug 2026 00:57:04 +0300
Subject: [PATCH 2/5] docs(compose): expand the shape asset to five kinds

Covers the five kinds, the omitted-height rule that is the only way to
get a true circle on a non-square frame, the anchor, outlines whose
interior is genuinely transparent, rotation about the shape's own centre,
softness, and animated geometry with easing.

Adds a table of the combinations the API refuses, each with the fix, so
the two drawing primitives' split is visible rather than surprising.

Every JSON snippet on the page was extracted programmatically, parsed
against the live schema, and rendered on the pinned MLT build: all seven
draw what the prose says they draw.
---
 jobs/compose.mdx | 151 +++++++++++++++++++++++++++++++----------------
 1 file changed, 100 insertions(+), 51 deletions(-)

diff --git a/jobs/compose.mdx b/jobs/compose.mdx
index 67761cc..7d16058 100644
--- a/jobs/compose.mdx
+++ b/jobs/compose.mdx
@@ -358,8 +358,8 @@ A `text` asset renders a styled title. Set the `font`, `size`, `weight`, `color`
 
 ## Shapes
 
-A `shape` asset draws a rectangle. No image to make, no file to host, and it
-stays sharp at any output resolution.
+A `shape` asset draws a rect, ellipse, circle, triangle or diamond. No image to
+make, no file to host, and it stays sharp at any output resolution.
 
 ```json
 "asset": {
@@ -373,13 +373,42 @@ stays sharp at any output resolution.
 That is a bar across the lower third, dark enough to read a title on and thin
 enough to see the footage through. Put it on a track below the text.
 
-Two things to know up front. `position` is the **centre** of the shape, not a
-corner, so a full-width bar sits at `x: "50%"` whatever its width. And there is
-no `length`, because a shape has no duration of its own: like text and images it
-runs to the end of its container unless you give it one.
+Two things to know up front. `position` is the **centre** of the shape unless
+you set `anchor`, so a full-width bar sits at `x: "50%"` whatever its width. And
+there is no `length`, because a shape has no duration of its own: like text and
+images it runs to the end of its container unless you give it one.
 
 `width` is a percent of the frame's width, `height` a percent of its height.
 
+### Leave the height out to get a circle
+
+Omit `size.height` and the shape is made **square in pixels**. That is the only
+way to get a true circle or square on a frame that is not square, and it is the
+one thing about shapes worth memorising.
+
+A `10%` by `10%` box on a 16:9 frame is 192 by 108 pixels. Rounding it fully
+gives a pill, not a circle. Omit the height and the engine derives 17.8% for
+you.
+
+```json
+{ "type": "shape", "shape": "circle", "color": "#059669",
+  "position": { "x": "88%", "y": "18%" }, "size": { "width": "12%" } }
+```
+
+`shape: "circle"` is `ellipse` with that rule applied, so it rejects an explicit
+height rather than quietly ignoring one. The same omission works on every kind:
+a `rect` with no height is a square, a `diamond` with no height is a regular one.
+
+### Anchor
+
+`anchor: "topLeft"` points `position` at the corner instead of the centre. It is
+what makes letterbox bars arithmetic-free.
+
+```json
+{ "type": "shape", "color": "#000000", "anchor": "topLeft",
+  "position": { "x": "0%", "y": "90%" }, "size": { "width": "100%", "height": "10%" } }
+```
+
 ### Transparency goes in the colour
 
 `color` takes `#RRGGBB` or the 8-digit `#RRGGBBAA`. Use the alpha byte for a
@@ -389,82 +418,102 @@ Do not reach for the clip's `opacity` instead. `opacity` dims the fill as well
 as fading it, so a half-opacity white box renders grey rather than white you can
 see through. Keep `opacity` for animated fades.
 
-### Rounded corners and circles
+### Rounded corners
 
-`radius` runs from `0` (square) to `1` (fully round).
+`radius` runs from `0` (square) to `1` (fully round) on a `rect`. At `1` a wide
+box becomes a pill and a square one becomes a circle.
 
-At `1`, a wide box becomes a pill and a **pixel-square** box becomes a circle.
-Square in pixels, not in percent: on a 16:9 frame a width of `10%` needs a
-height of `17.8%` (that is `10 × 16/9`). On a 9:16 frame the same width needs
-`5.6%`.
+```json
+{ "type": "shape", "color": "#0A0A0ACC", "radius": 0.35,
+  "position": { "x": "26%", "y": "50%" },
+  "size": { "width": "34%", "height": "34%" },
+  "stroke": { "color": "#FFFFFF", "width": 3 } }
+```
+
+### Outlines, with a real hole
+
+`stroke` draws a border just inside the shape's edge. Give the shape a `color`
+too and you get a filled shape with a border, and `radius` rounds both together.
+
+Leave `color` out and only the outline draws. What it surrounds is genuinely
+transparent, not filled with black, so the footage shows through the middle.
+That works on every kind.
 
 ```json
-{ "type": "shape", "color": "#059669", "position": { "x": "12%", "y": "80%" },
-  "size": { "width": "10%", "height": "17.8%" }, "radius": 1 }
+{ "type": "shape", "shape": "ellipse",
+  "position": { "x": "62%", "y": "40%" },
+  "size": { "width": "26%", "height": "40%" },
+  "stroke": { "color": "#F59E0B", "width": 5 } }
 ```
 
-### Outlines
+`width` is in pixels of the output frame, so it stays the same visual weight
+whatever the shape's size.
+
+### Rotation turns about the shape, not the frame
 
-`stroke` draws a border just inside the shape's edge. Set `color` to
-`#00000000` and the fill disappears, leaving an outline-only highlight box.
+`rotate` is degrees clockwise about the shape's **own** centre, so a shape spins
+where it sits rather than orbiting the middle of the frame. A diagonal rule is a
+thin rect and one field:
 
 ```json
-{ "type": "shape", "color": "#00000000",
-  "position": { "x": "72%", "y": "30%" },
-  "size": { "width": "36%", "height": "34%" },
-  "stroke": { "color": "#F59E0B", "width": 4 } }
+{ "type": "shape", "color": "#FFFFFF", "rotate": 30,
+  "position": { "x": "50%", "y": "72%" },
+  "size": { "width": "40%", "height": "0.8%" } }
 ```
 
-`stroke` cannot be combined with `radius` or with `animateTo`, and the API
-rejects both combinations rather than rendering them wrong. The outline is drawn
-as a square band, so a rounded shape would end up with square corners inside a
-rounded edge, and it cannot follow a shape that moves.
+There is no `line` type for the same reason there is no `square` type: a line is
+a rect with a small height, and `rotate` is what makes it diagonal.
 
-### A progress bar is a shape that grows
+### Softness
 
-`animateTo` moves and resizes the shape over the clip, in a straight line.
-Starting from a width of `0%` gives you a progress bar.
+`softness` runs 0 to 1 and feathers the edge. At 0.2 to 0.4 an ellipse reads as
+a spotlight or a vignette rather than a hard-edged disc.
+
+### Animation
+
+`animateTo` moves, resizes and turns the shape over the clip. `easing` is
+`linear` by default, which is what a progress bar or a timer wants, or `smooth`
+for an entrance.
 
 ```json
-{ "type": "shape", "color": "#FFFFFF",
-  "position": { "x": "50%", "y": "97%" },
+{ "type": "shape", "color": "#FFFFFF", "anchor": "topLeft",
+  "position": { "x": "2%", "y": "86%" },
   "size": { "width": "0%", "height": "1.5%" },
-  "animateTo": { "size": { "width": "96%" } } }
+  "animateTo": { "size": { "width": "96%" }, "easing": "smooth" } }
 ```
 
 A dimension you leave out of `animateTo` keeps its starting value, so the bar
 above grows sideways without changing height. `transform` cannot do this: its
 `scale` is uniform, so it would grow the bar in both directions at once.
 
-### Lines and letterbox bars
-
-There is no `line` type, because a line is a rectangle with a small height.
+A shape that is square in pixels stays square as it grows, so an animated circle
+does not turn into an ellipse halfway through.
 
-```json
-{ "type": "shape", "color": "#FFFFFF", "position": { "x": "50%", "y": "50%" },
-  "size": { "width": "60%", "height": "0.4%" } }
-```
+### Combinations the API refuses
 
-For a diagonal, centre the shape and add `transform` to the clip:
-`"transform": { "rotate": 30 }`. Rotation turns the frame about its centre, so a
-centred shape spins in place and an off-centre one swings around the middle of
-the frame.
+Two engine primitives draw shapes and they have different abilities, so a few
+combinations are rejected at submit time rather than rendered wrong. Each error
+names the fix.
 
-Letterbox bars are two shapes: one at `y: "5%"`, one at `y: "95%"`, both
-`height: "10%"` and `color: "#000000"`. A full-frame scrim is one shape at
-`100%` by `100%` with a colour like `#00000080`.
+| Not combinable | Why | What to do instead |
+| --- | --- | --- |
+| `radius` on anything but a `rect` | only rectangles have corners | drop it |
+| `radius` with no `color` | an outline-only shape is drawn by the primitive with no corner rounding | give it a fill |
+| `radius` or a two-colour fill plus stroke, with `rotate` or `softness` | the primitive that rounds and carries two colours cannot turn or feather | drop one, or rotate the whole clip with `transform.rotate` |
+| a fill and a stroke on a non-`rect` | that primitive carries one colour | put the fill on its own shape clip below |
+| an animated `rotate` beyond -180 to 180 | the engine turns a shape over exactly one revolution | animate `transform.rotate` for a full spin |
 
 ### What else a shape takes
 
-Every per-clip field applies. `transform` rotates and repositions it,
-`blendMode` mixes it with the layer below, `blur` softens its edges, and opacity
+Every per-clip field applies. `transform` repositions and scales it, `blendMode`
+mixes it with the layer below, `blur` softens the whole thing, and opacity
 keyframes fade it in and out. A track holding only shapes composites as a base
 layer, so a solid colour background is a timeline that references no files at
 all.
 
-What a shape is not is a drawing surface. There is no gradient fill, no ellipse
-and no drop shadow. A rounded rectangle, a pill, a pixel-square circle and an
-outline are the whole set. Anything past that is still an `image` asset.
+What a shape is not is a drawing surface. There is no gradient fill and no drop
+shadow. Anything past a filled or outlined rect, ellipse, circle, triangle or
+diamond is still an `image` asset.
 
 
 ## Fonts
@@ -677,7 +726,7 @@ A clip's `asset` is one of:
 | `image` | `src` |
 | `audio` | `src`, `trim`, `volume`, `fadeIn`, `fadeOut` (seconds) |
 | `text` | `text`, `style` |
-| `shape` | `color`, `position` (the shape's **centre**), `size` `{ width, height }`, `radius` (`0` to `1`), `stroke` `{ color, width }`, `animateTo` `{ position, size }`. See [Shapes](#shapes) |
+| `shape` | `shape` (`rect`, `ellipse`, `circle`, `triangle`, `diamond`), `color` (fill, omit for outline-only), `stroke` `{ color, width }`, `position` (the **centre** by default), `anchor`, `size` `{ width, height? }` (omit the height for a shape square in pixels), `radius`, `rotate`, `softness`, `animateTo` `{ position, size, rotate, easing }`. See [Shapes](#shapes) |
 | `composition` | `timeline`, a nested `{ tracks }` rendered and composited as a single clip. Every clip field below applies to a composition clip too, except `speed` (set speed on the clips inside the composition instead) |
 
 ### Clip fields

From 6285114b9922ff7ed7e56f59437b0a5e97d5d27c Mon Sep 17 00:00:00 2001
From: Abdelrahman Essawy <abdelrahman.mo.essawy@gmail.com>
Date: Wed, 26 Aug 2026 03:01:56 +0300
Subject: [PATCH 3/5] docs(compose): cover gradients, paths, shadows and
 animated properties

Rewrites the Shapes section for what a shape can now do: six kinds
including pasted SVG paths, solid or gradient fills, outlines whose
interior is genuinely transparent, drop shadows, rotation about the
shape's own centre, feathered edges, and position, size, rotation, colour
and radius that all animate.

Leads with the fact that only `type` and `size` are required, so the page
reads as a small feature with a lot of optional depth rather than a large
one.

The refusal table gains the two rules that came out of the rewrite:
`radius` cannot be combined with `rotate` or `softness`, and `transform`
is refused on shapes entirely because it moves the frame rather than the
shape in it.

Every JSON snippet was extracted programmatically, parsed against the
live schema and rendered on the pinned MLT build: all nine draw what the
prose says they draw.
---
 jobs/compose.mdx | 121 +++++++++++++++++++++++++++++++----------------
 1 file changed, 80 insertions(+), 41 deletions(-)

diff --git a/jobs/compose.mdx b/jobs/compose.mdx
index 7d16058..37993ba 100644
--- a/jobs/compose.mdx
+++ b/jobs/compose.mdx
@@ -358,8 +358,9 @@ A `text` asset renders a styled title. Set the `font`, `size`, `weight`, `color`
 
 ## Shapes
 
-A `shape` asset draws a rect, ellipse, circle, triangle or diamond. No image to
-make, no file to host, and it stays sharp at any output resolution.
+A `shape` asset draws a rect, ellipse, circle, triangle, diamond, or any SVG
+path you paste in. No image to make, no file to host, and it stays sharp at any
+output resolution.
 
 ```json
 "asset": {
@@ -373,10 +374,13 @@ make, no file to host, and it stays sharp at any output resolution.
 That is a bar across the lower third, dark enough to read a title on and thin
 enough to see the footage through. Put it on a track below the text.
 
+Only `type` and `size` are required. Everything else on this page is optional,
+and the defaults are chosen so the common cases need almost none of it.
+
 Two things to know up front. `position` is the **centre** of the shape unless
-you set `anchor`, so a full-width bar sits at `x: "50%"` whatever its width. And
-there is no `length`, because a shape has no duration of its own: like text and
-images it runs to the end of its container unless you give it one.
+you set `anchor`, so a full-width bar sits at `x: "50%"` whatever its height.
+And there is no `length`, because a shape has no duration of its own: like text
+and images it runs to the end of its container unless you give it one.
 
 `width` is a percent of the frame's width, `height` a percent of its height.
 
@@ -409,35 +413,36 @@ what makes letterbox bars arithmetic-free.
   "position": { "x": "0%", "y": "90%" }, "size": { "width": "100%", "height": "10%" } }
 ```
 
-### Transparency goes in the colour
+### Fills, flat and gradient
 
-`color` takes `#RRGGBB` or the 8-digit `#RRGGBBAA`. Use the alpha byte for a
-constant translucency, the way `#0A0A0ACC` does above.
+`color` takes `#RRGGBB`, or the 8-digit `#RRGGBBAA` for a constant translucency
+the way `#0A0A0ACC` does above.
 
 Do not reach for the clip's `opacity` instead. `opacity` dims the fill as well
 as fading it, so a half-opacity white box renders grey rather than white you can
 see through. Keep `opacity` for animated fades.
 
-### Rounded corners
-
-`radius` runs from `0` (square) to `1` (fully round) on a `rect`. At `1` a wide
-box becomes a pill and a square one becomes a circle.
+Give `color` **two** colours and it is a gradient. `gradient` names the
+direction: `vertical` (the default), `horizontal`, `diagonal` or `radial`.
 
 ```json
-{ "type": "shape", "color": "#0A0A0ACC", "radius": 0.35,
-  "position": { "x": "26%", "y": "50%" },
-  "size": { "width": "34%", "height": "34%" },
-  "stroke": { "color": "#FFFFFF", "width": 3 } }
+{ "type": "shape", "color": ["#E11D48", "#3B82F6"], "gradient": "diagonal",
+  "position": { "x": "50%", "y": "50%" }, "size": { "width": "40%", "height": "30%" } }
 ```
 
+The gradient maps to the **shape**, not the frame, so a small badge shows the
+whole ramp instead of a sliver of one. Stops take the 8-digit form too, which is
+how you get a scrim that fades to nothing: `["#0A0A0A00", "#0A0A0AFF"]`.
+
 ### Outlines, with a real hole
 
-`stroke` draws a border just inside the shape's edge. Give the shape a `color`
-too and you get a filled shape with a border, and `radius` rounds both together.
+`stroke` draws a border just inside the shape's edge, its `width` in pixels of
+the output frame. Give the shape a `color` too and you get a filled shape with a
+border; `radius` rounds both together.
 
 Leave `color` out and only the outline draws. What it surrounds is genuinely
 transparent, not filled with black, so the footage shows through the middle.
-That works on every kind.
+That works on every kind except a path.
 
 ```json
 { "type": "shape", "shape": "ellipse",
@@ -446,8 +451,22 @@ That works on every kind.
   "stroke": { "color": "#F59E0B", "width": 5 } }
 ```
 
-`width` is in pixels of the output frame, so it stays the same visual weight
-whatever the shape's size.
+### Rounded corners
+
+`radius` runs from `0` (square) to `1` (fully round) on a `rect`. At `1` a wide
+box becomes a pill and a square one becomes a circle.
+
+### Drop shadows
+
+`shadow` follows the shape, including its outline, its rotation and its
+animation. Every field has a default, so `"shadow": {}` is a sensible shadow.
+
+```json
+{ "type": "shape", "color": ["#FFFFFF", "#E5E7EB"], "radius": 0.3,
+  "stroke": { "color": "#111827", "width": 3 },
+  "shadow": { "color": "#00000099", "blur": 14, "x": 8, "y": 10 },
+  "position": { "x": "30%", "y": "50%" }, "size": { "width": "34%", "height": "40%" } }
+```
 
 ### Rotation turns about the shape, not the frame
 
@@ -467,13 +486,32 @@ a rect with a small height, and `rotate` is what makes it diagonal.
 ### Softness
 
 `softness` runs 0 to 1 and feathers the edge. At 0.2 to 0.4 an ellipse reads as
-a spotlight or a vignette rather than a hard-edged disc.
+a spotlight or a vignette rather than a hard-edged disc. A full-frame ellipse
+with `softness: 0.5` and a radial `["#00000000", "#000000CC"]` fill is a
+vignette with no image asset at all.
+
+### Paths
+
+`shape: "path"` takes SVG path data straight out of a design tool. `viewBox`
+gives the coordinate space it was drawn in, defaulting to `"0 0 100 100"`, and
+the path is scaled into `size` so the same data works at any size on any frame.
+
+```json
+{ "type": "shape", "shape": "path", "viewBox": "0 0 24 24",
+  "path": "M12 21C12 21 3 14.5 3 8.5C3 5.5 5.5 3 8.5 3C10.4 3 12 4.5 12 4.5C12 4.5 13.6 3 15.5 3C18.5 3 21 5.5 21 8.5C21 14.5 12 21 12 21Z",
+  "color": "#E11D48", "position": { "x": "50%", "y": "50%" }, "size": { "width": "20%" } }
+```
+
+`M L H V C S Q T Z` are supported, absolute and relative. Elliptical arcs (`A`)
+are refused rather than approximated, so re-export with arcs converted to
+curves. A path takes a fill, a gradient, a shadow, rotation and softness, but
+not a `stroke`: outlining arbitrary path data needs true path offsetting.
 
 ### Animation
 
-`animateTo` moves, resizes and turns the shape over the clip. `easing` is
-`linear` by default, which is what a progress bar or a timer wants, or `smooth`
-for an entrance.
+`animateTo` moves `position`, `size`, `rotate`, `color` and `radius` over the
+clip. `easing` is `linear` by default, which is what a progress bar or a timer
+wants, or `smooth` for an entrance.
 
 ```json
 { "type": "shape", "color": "#FFFFFF", "anchor": "topLeft",
@@ -483,11 +521,13 @@ for an entrance.
 ```
 
 A dimension you leave out of `animateTo` keeps its starting value, so the bar
-above grows sideways without changing height. `transform` cannot do this: its
-`scale` is uniform, so it would grow the bar in both directions at once.
+above grows sideways without changing height. A shape that is square in pixels
+stays square as it grows, so an animated circle does not turn into an ellipse
+halfway through. A solid colour can animate into a gradient, and a square can
+round itself off with `animateTo.radius`.
 
-A shape that is square in pixels stays square as it grows, so an animated circle
-does not turn into an ellipse halfway through.
+An animated `rotate` has to stay within -180 and 180 degrees at both ends,
+because the engine turns a shape over exactly one revolution.
 
 ### Combinations the API refuses
 
@@ -499,21 +539,20 @@ names the fix.
 | --- | --- | --- |
 | `radius` on anything but a `rect` | only rectangles have corners | drop it |
 | `radius` with no `color` | an outline-only shape is drawn by the primitive with no corner rounding | give it a fill |
-| `radius` or a two-colour fill plus stroke, with `rotate` or `softness` | the primitive that rounds and carries two colours cannot turn or feather | drop one, or rotate the whole clip with `transform.rotate` |
-| a fill and a stroke on a non-`rect` | that primitive carries one colour | put the fill on its own shape clip below |
-| an animated `rotate` beyond -180 to 180 | the engine turns a shape over exactly one revolution | animate `transform.rotate` for a full spin |
+| `radius` with `rotate` or `softness` | the primitive that rounds corners cannot turn or feather | drop one of them |
+| `stroke` on a `path` | outlining arbitrary path data needs true path offsetting | draw the outline into the path itself |
+| an animated `rotate` beyond -180 to 180 | the engine turns a shape over exactly one revolution | animate in two clips |
+| `transform` on any shape | it moves the whole frame, not the shape in it, so the result lands somewhere neither value asked for | use `position`, `size` and `rotate` |
 
 ### What else a shape takes
 
-Every per-clip field applies. `transform` repositions and scales it, `blendMode`
-mixes it with the layer below, `blur` softens the whole thing, and opacity
-keyframes fade it in and out. A track holding only shapes composites as a base
-layer, so a solid colour background is a timeline that references no files at
-all.
+`blendMode` mixes it with the layer below, `blur` softens the whole thing,
+colour grading tints it, and opacity keyframes fade it in and out. A track
+holding only shapes composites as a base layer, so a solid colour background is
+a timeline that references no files at all.
 
-What a shape is not is a drawing surface. There is no gradient fill and no drop
-shadow. Anything past a filled or outlined rect, ellipse, circle, triangle or
-diamond is still an `image` asset.
+There is no arbitrary path stroke and no per-corner radius. Anything past that
+is still an `image` asset.
 
 
 ## Fonts
@@ -726,7 +765,7 @@ A clip's `asset` is one of:
 | `image` | `src` |
 | `audio` | `src`, `trim`, `volume`, `fadeIn`, `fadeOut` (seconds) |
 | `text` | `text`, `style` |
-| `shape` | `shape` (`rect`, `ellipse`, `circle`, `triangle`, `diamond`), `color` (fill, omit for outline-only), `stroke` `{ color, width }`, `position` (the **centre** by default), `anchor`, `size` `{ width, height? }` (omit the height for a shape square in pixels), `radius`, `rotate`, `softness`, `animateTo` `{ position, size, rotate, easing }`. See [Shapes](#shapes) |
+| `shape` | `shape` (`rect`, `ellipse`, `circle`, `triangle`, `diamond`, `path`), `color` (one colour, or two for a gradient; omit for outline-only), `gradient`, `stroke` `{ color, width }`, `shadow` `{ color, blur, x, y }`, `position` (the **centre** by default), `anchor`, `size` `{ width, height? }` (omit the height for a shape square in pixels), `radius`, `rotate`, `softness`, `path` + `viewBox`, `animateTo` `{ position, size, rotate, color, radius, easing }`. See [Shapes](#shapes) |
 | `composition` | `timeline`, a nested `{ tracks }` rendered and composited as a single clip. Every clip field below applies to a composition clip too, except `speed` (set speed on the clips inside the composition instead) |
 
 ### Clip fields

From 34b4c364862367e5f565df722a3449e6854d184e Mon Sep 17 00:00:00 2001
From: Abdelrahman Essawy <abdelrahman.mo.essawy@gmail.com>
Date: Wed, 26 Aug 2026 11:15:48 +0300
Subject: [PATCH 4/5] docs(compose): drop the animated rotation limit

Rotation used to be a filter parameter spanning exactly one revolution,
which clamped and made an animation across the wrap turn the long way
round, so the API capped an animated `rotate` at -180 to 180.

Rotation is baked into the shape's own outline now, so there is no wrap
and no cap: 0 to 720 is two full turns.
---
 jobs/compose.mdx | 5 ++---
 1 file changed, 2 insertions(+), 3 deletions(-)

diff --git a/jobs/compose.mdx b/jobs/compose.mdx
index 37993ba..21af444 100644
--- a/jobs/compose.mdx
+++ b/jobs/compose.mdx
@@ -526,8 +526,8 @@ stays square as it grows, so an animated circle does not turn into an ellipse
 halfway through. A solid colour can animate into a gradient, and a square can
 round itself off with `animateTo.radius`.
 
-An animated `rotate` has to stay within -180 and 180 degrees at both ends,
-because the engine turns a shape over exactly one revolution.
+An animated `rotate` has no limit: rotation is baked into the shape's own
+outline, so animating from 0 to 720 is two full turns.
 
 ### Combinations the API refuses
 
@@ -541,7 +541,6 @@ names the fix.
 | `radius` with no `color` | an outline-only shape is drawn by the primitive with no corner rounding | give it a fill |
 | `radius` with `rotate` or `softness` | the primitive that rounds corners cannot turn or feather | drop one of them |
 | `stroke` on a `path` | outlining arbitrary path data needs true path offsetting | draw the outline into the path itself |
-| an animated `rotate` beyond -180 to 180 | the engine turns a shape over exactly one revolution | animate in two clips |
 | `transform` on any shape | it moves the whole frame, not the shape in it, so the result lands somewhere neither value asked for | use `position`, `size` and `rotate` |
 
 ### What else a shape takes

From 501ef62ed05fab6107a1cd0e50f3df0ae62a67eb Mon Sep 17 00:00:00 2001
From: Abdelrahman Essawy <abdelrahman.mo.essawy@gmail.com>
Date: Thu, 27 Aug 2026 11:39:48 +0300
Subject: [PATCH 5/5] docs(compose): show the six shape demos in the shapes
 section

Every clip is a real compose render, now live on the CDN under
assets/showcase/shapes/, matching how the transitions section already works.
---
 jobs/compose.mdx | 21 +++++++++++++++++++++
 1 file changed, 21 insertions(+)

diff --git a/jobs/compose.mdx b/jobs/compose.mdx
index 21af444..e9f93e1 100644
--- a/jobs/compose.mdx
+++ b/jobs/compose.mdx
@@ -374,6 +374,27 @@ output resolution.
 That is a bar across the lower third, dark enough to read a title on and thin
 enough to see the footage through. Put it on a track below the text.
 
+<Columns cols={3}>
+  <Frame caption="a bar, plus a text track">
+    <video src="https://cdn.rendobar.com/assets/showcase/shapes/lower-third.mp4" autoPlay loop muted playsInline controls />
+  </Frame>
+  <Frame caption="animateTo on the width">
+    <video src="https://cdn.rendobar.com/assets/showcase/shapes/progress-bar.mp4" autoPlay loop muted playsInline controls />
+  </Frame>
+  <Frame caption="radius with a shadow">
+    <video src="https://cdn.rendobar.com/assets/showcase/shapes/rounded-card.mp4" autoPlay loop muted playsInline controls />
+  </Frame>
+  <Frame caption="a circle, two colours">
+    <video src="https://cdn.rendobar.com/assets/showcase/shapes/gradient-badge.mp4" autoPlay loop muted playsInline controls />
+  </Frame>
+  <Frame caption="a stroke with no fill">
+    <video src="https://cdn.rendobar.com/assets/showcase/shapes/outline-box.mp4" autoPlay loop muted playsInline controls />
+  </Frame>
+  <Frame caption="pasted path data">
+    <video src="https://cdn.rendobar.com/assets/showcase/shapes/svg-path.mp4" autoPlay loop muted playsInline controls />
+  </Frame>
+</Columns>
+
 Only `type` and `size` are required. Everything else on this page is optional,
 and the defaults are chosen so the common cases need almost none of it.