docs: ADR 0074, guide, roadmap and changelog for the gradient tools (M1)

This commit is contained in:
Tanish Manku committed 2026-11-12 14:21:43 -07:00
1 parent 120458c89f
commit a2acaec3d8
9 files changed
+180 -17

No files matched your search

+16
View File
@@ -2,6 +2,22 @@
## Unreleased
* **Gradient editor, the Gradient Transform tool and Lock Fill** (M1, ADR 0074; #208, #203).
* **Added**: a **Colour** section in Properties for the selected fill, or the fill swatch while
a drawing tool is in hand: Solid colour, Linear gradient, Radial gradient or Bitmap fill; a
bar of colour stops (click to add, drag to move, drag off to remove; arrow keys and Delete
on a focused stop), each stop's colour, opacity, hex and position; overflow (Extend,
Reflect, Repeat), Linear RGB and a radial gradient's focal point.
* **Added**: the **Gradient Transform** tool (**F**): move, turn, stretch and resize a gradient,
move a radial gradient's focal point, and scale, turn and skew a bitmap fill. Each drag is
one undo step.
* **Added**: **Lock Fill** for the Paint Bucket and the Brush. Without it, gradients and bitmaps
are fitted to each shape, as in Animate; the Eyedropper turns it on for what it picks.
* **Added**: commands `paint.set_fill`, `paint.transform_fill` and `paint.lock_fill`, for
scripts, the CLI and MCP.
* **Improved**: gradients keep their overflow, Linear RGB, focal point and elliptical shape
from Animate files and SVG drawings, on the GPU stage and in SVG export (HTML canvas draws
them as near as canvas can). Radial gradients on skewed shapes are now drawn exactly.
* **Filters, Subtract and Invert in HTML canvas export** (ADR 0072, M6). Exported web pages now
show every filter (Drop Shadow, Blur, Glow, Bevel, Gradient Glow, Gradient Bevel and Adjust
Color, with inner, knockout, hide object and Inner/Outer/Full) and the Subtract and Invert blend
@@ -0,0 +1,110 @@
# ADR 0074: Gradient editor, the Gradient Transform tool and Lock Fill
* Status: accepted (2026-11-12)
* Relates to: ADR 0002 (render pipeline), ADR 0019 / 0029 (GPU stage), ADR 0034 (Eyedropper),
ADR 0040 (interface languages), ADR 0064 (accessibility), user issues #208 and #203, roadmap M1
## Context
The renderer, the file format, the importers and exporters and the Eyedropper already handled
linear and radial gradients and bitmap fills, but an artist couldn't make or change one: there
was no gradient editor and no way to move, turn or stretch where a fill lies. Animate's
everyday workflow is the Color panel's fill type and colour stops, the Gradient Transform tool
(**F**) and Lock Fill on the Paint Bucket and Brush. Animate's gradients also carry what our
model lacked: overflow (Extend, Reflect, Repeat), Linear RGB, a focal point and elliptical,
turned radial gradients. XFL import reported all four as approximations.
## Decision
### Model (`crates/doc`)
1. **Options on the existing variants, not a new paint type.** `Paint::Linear` gains `spread`
and `linear_rgb`; `Paint::Radial` gains those plus `focal` (Animate's focal point ratio, along
the gradient's own x axis, held to ±0.98 of the radius) and `matrix` (gradient space → shape
space, so any ellipse at any angle). Each is `#[serde(default)]` and skipped when unset, so
older files open unchanged and plain gradients are written byte-for-byte as before.
2. **A radial gradient is stored as a circle when it is one**, else as a circle with a matrix
about its centre (`Paint::with_frame` canonicalises). `Paint::transformed` composes the
matrix, so a radial fill is now exact under any transform (it used the mean scale before).
A linear gradient keeps `start`/`end`: its handles only move, turn and stretch it along its
axis, as Animate's do.
3. **Fill frames.** `Paint::frame` maps the box −1..1 onto a fill (a linear ramp's span, a radial
ring, one copy of a bitmap; Animate's gradient square), and `with_frame` sets it. The tool,
the command and fitting all work on frames, one representation for three kinds of fill.
4. **`Spread::apply`** is the one definition of pad, reflect and repeat; the GPU shader, its
emulator and the HTML exporter follow it.
### Rendering and interchange
5. **CPU oracle**: spread on the ramp position; the focal point by solving
`(1 − f²)t² − 2(f·d)t − d·d = 0` in the ring's unit space (the cone of SVG's and canvas's
two-circle gradient with the inner circle at the focal point, radius 0); Linear RGB by mixing
the stops in linear light when the 256-entry table is built (so the GPU gets it for free).
Analytic tests cover each.
6. **GPU stage**: a gradient's paint record had a free vec4 (its colour slot); it now holds the
spread code and the focal ratio, and `fine.wgsl` evaluates both. The radial `inv` already
included the matrix. Parity scene: reflect + linear RGB, repeat, a repeating focal gradient
on a turned ellipse.
7. **SVG export** writes `spreadMethod`, `color-interpolation="linearRGB"`, `fx`/`fy` and the
matrix in `gradientTransform`: exact. **HTML canvas** has only padded gradients, so reflect
and repeat are drawn as the ramp laid end to end (bounded copies), Linear RGB as sampled
stops, the focal point with the two-circle gradient; an ellipse uses its mean radius.
**Lottie** reports spread, Linear RGB and focal points (it has none of them).
8. **Import**: XFL's `spreadMethod`, `interpolationMethod`, `focalPointRatio` and elliptical
matrices and SVG's `spreadMethod`, `color-interpolation`, `fx`/`fy` and skewed radial
transforms come in exactly. The XFL corpus's gradients golden was regenerated: it now shows
what the file asks for.
### Commands (`crates/engine/src/cmds_paint.rs`)
9. **`paint.set_fill`** sets the fill swatch and, by default, the selected shapes' fills in one
step: `type`, `color`, `stops` (2 to 15, `#rrggbbaa` for opacity), `spread`, `linear_rgb`,
`focal`, `bitmap`. A shape keeping its kind of fill keeps where it lies (editing stops never
moves a gradient); a shape changing kind gets the new fill fitted to its bounds. A new
gradient keeps the colours of the gradient it replaces, else starts white to black
(Animate's default).
10. **`paint.transform_fill`** sets a fill's frame (absolute, `frame`) or changes it (scale, skew,
rotate about its centre, move, centre, focal), in the space being edited. The tool sends
absolute frames worked out from the frame at the press, so a drag inside one gesture is one
undo step and never drifts. Flattening a fill to nothing is refused.
11. **Lock Fill** is tool state (`ToolStyle::lock_fill`, `paint.lock_fill`). Off (the default, as
in Animate): the Paint Bucket, the Brush and the shape tools fit a gradient or bitmap to
each shape (`Paint::fitted`: linear across the width, radial centred touching the longer
side, bitmap tiled from the top-left). On: the swatch's stage-space fill is carried into each
shape, so one ramp runs across many. **The Eyedropper turns Lock Fill on** when it picks a
gradient or bitmap, which keeps ADR 0034's behaviour (a picked gradient stays where it was)
and is what Animate does.
12. The new commands are in the `paint` namespace, which plug-ins may already call; the
`panic_hunt_every_command` fuzz covers them.
### Shell
13. **Colour, a section of Properties**, under the selected shape's rows (the selected fill), or
under a fill tool's options (the swatch). Not a separate dock band: the dock has no room
for it beside the Library at ordinary window heights, and Properties is where an artist
looks for the selection's fill. It has the fill type, overflow, Linear RGB, a stop bar,
the picked stop's colour with opacity and hex field, its position, and the focal point.
14. **The stop bar** is keyboard-operable (ADR 0064): the bar is a button that adds a stop in the
widest gap; each stop is a focusable, named control; arrow keys move it (Shift: 10 %),
Delete removes it; dragging a stop off the bar removes it, as in Animate.
15. **The Gradient Transform tool (F)** draws Animate's handles on the fill's frame: linear (edges,
centre, width square, rotate knob), radial (ring, centre, focal triangle, width square, size
circle, rotate knob) and bitmap (tile box, centre, width and height squares, skew diamonds,
size circle, rotate knob). The plain selection box is hidden while it shows. In Animate it
shares a flyout with Free Transform; AniCraft has no flyouts yet, so it has its own button.
## Consequences
* Gradients round-trip exactly through `.anicraft`, SVG and XFL; files without the new options
are unchanged. Radial fills on skewed shapes are now drawn exactly.
* Scripts can build and place any gradient headless (`paint.set_fill`, `paint.transform_fill`).
* The hex field is the panel's own (`Rgba::parse_hex`); when the shared colour picker of PR #257
lands, the stop swatch can open it instead.
## Not in this slice
* Gradient and bitmap **strokes** (strokes have one colour).
* Saved gradient swatches; the Brush's Lock Fill only for its fill colour mode.
* Overflow on HTML canvas beyond the bounded copies; elliptical radial gradients in Lottie and
canvas (mean radius).
* Skewing a linear gradient's bands (its frame keeps only its axis).
-1
View File
@@ -23,4 +23,3 @@ has to renumber because another PR merged first.
| Number | Pull request | Topic |
|---|---|---|
| 0037 | #38 (outside contribution) | Interface languages |
| 0074 | m1/gradient-tools | Gradient editor, Gradient Transform tool and Lock Fill |
+3 -2
View File
@@ -26,7 +26,7 @@ most of them; they are always there.
| Output | The Output panel inside Test Movie. |
| Align | The Align section on the right, and **Modify › Align**. |
| History | The History section on the right. |
| Color and Swatches | The Fill and Stroke rows in Properties, and in each drawing tool's options. |
| Color and Swatches | The Fill and Stroke rows in Properties, and in each drawing tool's options. The **Colour** section of Properties is the Color panel's fill: type, gradient stops, overflow, Linear RGB (no saved swatches yet). |
| Transform and Info | Position, scale and rotation rows in Properties, and the Free Transform tool. |
| Scene | The scene menu at the top left of the stage, **Insert › Scene** and **Modify › Scene**. |
| Find and Replace | **Edit › Find and Replace** (**Ctrl+F**). |
@@ -44,6 +44,7 @@ Each tool has the key you already know.
| Selection | **V** | Selects raw strokes and fills with the dot pattern; drag an edge to bend it. |
| Subselection | **A** | Points and handles, on raw drawings and drawing objects. |
| Free Transform | **Q** | Scale, rotate and move; Shift and Alt as you'd expect. |
| Gradient Transform | **F** | Its own button (no flyouts yet). Gradient and bitmap fills, with Lock Fill. |
| Width | **U** | Variable-width strokes, with profiles in Properties. |
| Bone | **M** | Joins symbol instances into an armature, or draws bones inside a shape. |
| Bind | **Shift+M** | Chooses which points of a shape follow which bone. |
@@ -64,7 +65,7 @@ Each tool has the key you already know.
| Zoom | **Z** | |
| Object Drawing | **J** | Toggles between merge drawing and drawing objects. |
Not in AniCraft yet: the Lasso, Polygon and Magic Wand tools, Gradient Transform, the 3D tools,
Not in AniCraft yet: the Lasso, Polygon and Magic Wand tools, the 3D tools,
Asset Warp, the Paint Brush and Fluid Brush, Deco and the Spray Brush. More on the tools in
[Drawing](drawing.md).
+44 -7
View File
@@ -19,6 +19,7 @@ your hand.
| Selection | **V** | Select, move and bend artwork |
| Subselection | **A** | Edit points and curve handles |
| Free Transform | **Q** | Scale, rotate and move |
| Gradient Transform | **F** | Move, turn and stretch a gradient or bitmap fill |
| Width | **U** | Vary a line's thickness along it |
| Bone | **M** | Join symbol instances into a poseable armature |
| Pen | **P** | Draw precise curves point by point |
@@ -175,11 +176,47 @@ corner can get before it's bevelled.
### Gradients and bitmap fills
AniCraft draws linear and radial gradients and bitmap fills, and keeps them from Animate
files and SVG drawings you import. There isn't a gradient editor for fills yet, so you can't
make a new gradient from scratch in AniCraft. You can reuse one, though: pick it up with the
Eyedropper and pour it with the Paint Bucket. A picked gradient stays where it was on the
stage, so it carries on across every shape you pour it into.
The **Colour** section of Properties sets a fill's type: **Solid colour**, **Linear
gradient**, **Radial gradient** or **Bitmap fill**. With a shape selected it changes that
shape's fill; with a drawing tool in your hand it sets what new shapes, the Paint Bucket and
the Brush pour.
A gradient shows as a bar with its colour stops under it:
* **Click the bar** to add a stop there. **Drag a stop** to move it, or drag it down off the
bar to remove it. A gradient has 2 to 15 stops.
* Click a stop to edit it below the bar: its colour and opacity, its **hex** value (type
`#rrggbb`, or `#rrggbbaa` with opacity) and its **Position**.
* From the keyboard, **Tab** to a stop, move it with the **arrow keys** (**Shift** for bigger
steps) and press **Delete** to remove it. The bar itself adds a stop in the widest gap.
* **Overflow** sets what shows past the ends: **Extend** (the end colours carry on),
**Reflect** (the ramp mirrors back and forth) or **Repeat**.
* **Linear RGB** mixes the colours in linear light, for brighter, more even blends.
* A radial gradient has a **Focal point**: where its ramp starts, from the centre.
Editing the stops never moves a gradient. A shape that gets a new kind of fill gets it fitted
to its own bounds: a linear gradient runs across its width, a radial one is centred and
touches its longer side, and a bitmap tiles from its top-left corner.
The **Gradient Transform** tool (**F**) changes where a gradient or bitmap fill lies. Click a
shape with one to show its handles:
| Handle | Linear | Radial | Bitmap | What a drag does |
|---|---|---|---|---|
| Round dot in the middle | ✓ | ✓ | ✓ | Moves the fill |
| Square | ✓ | ✓ | ✓ (left and bottom) | Changes its width (bitmap: width or height) |
| Circle with a dot | | ✓ | ✓ (corner) | Changes its size |
| Knob | ✓ | ✓ | ✓ | Turns it (**Shift**: 15° steps) |
| Triangle | | ✓ | | Moves the focal point along its axis |
| Diamonds | | | ✓ (top and right) | Skews it |
Each drag is one undo step. Gradients and bitmap fills from Animate files and SVG drawings
keep their overflow, Linear RGB, focal point and shape.
**Lock Fill** (in the Paint Bucket's and the Brush's options) pours the fill where it lies on
the stage instead of fitting it to each shape, so one gradient runs on across many shapes.
When you pick up a gradient or bitmap with the Eyedropper, Lock Fill turns on, so it stays
where it was.
### Paint Bucket, Ink Bottle and Eyedropper
@@ -293,7 +330,7 @@ on its symbol (see [Symbols and the Library](symbols-and-library.md#9-slice-scal
## Not there yet
Not in AniCraft yet: rulers, a grid and guides; grouping (**Ctrl+G**); a gradient editor and
a Colour panel with swatches; PolyStar's Polygon option; the Paint Selection and Paint Inside
Not in AniCraft yet: rulers, a grid and guides; grouping (**Ctrl+G**); gradient and bitmap
strokes, and saved colour and gradient swatches; PolyStar's Polygon option; the Paint Selection and Paint Inside
brush modes, brush libraries and tilt; erasing inside symbols; and Animate's ragged, stipple
and hatched line styles (drawn solid when you open an Animate file).
+2 -1
View File
@@ -91,7 +91,8 @@ exactly; the status bar names them after the export:
* bitmaps and bitmap fills, and sound;
* masks inside masks (the innermost is kept);
* symbols fading as one (each shape fades on its own);
* stretched round gradients (drawn as circles).
* stretched round gradients (drawn as circles), gradient focal points (drawn centred),
reflected or repeated gradients (drawn extended) and linear-RGB gradients.
### HTML canvas
+3 -2
View File
@@ -72,7 +72,8 @@ SVG files from illustration tools come in as artwork you can keep editing, not a
limits and dashes.
* Groups, reused parts (`use` and symbols), transforms and the drawing's view box.
* Inline and attribute styles, and opacity.
* Linear and radial gradients.
* Linear and radial gradients, with their spread (reflect, repeat), linear-RGB blending, focal
point and transform.
* **Clip paths and masks.** A drawing with clipping comes in as a layer folder named after the
file. Each clipped group sits on a masked layer under a mask layer that holds the clip's shape,
so you can move or reshape the mask afterwards. Clips that cut nothing, like the frame clip
@@ -89,7 +90,7 @@ SVG files from illustration tools come in as artwork you can keep editing, not a
AniCraft lists these in the status bar after the import, instead of guessing:
* images embedded in the SVG, filters, style sheets (inline styles are read) and pattern fills;
* gradient strokes (drawn in one colour), and repeated or reflected gradients (drawn padded).
* gradient strokes (drawn in one colour).
### An SVG as a symbol
-2
View File
@@ -83,8 +83,6 @@ each) and any fonts that are missing.
These come across, but look a little different from Animate, and the report counts them:
* repeating and reflecting gradients (drawn padded), radial gradient focal points (drawn
centred), elliptical radial gradients (drawn round) and linear-RGB gradients;
* gradient and bitmap strokes (drawn in one colour);
* ragged, stipple and hatched strokes (drawn solid);
* reverse loop modes (played forward) and extra spins on classic tweens (turned the shortest
+2 -2
View File
@@ -9,7 +9,7 @@ milestone ends with a green tree: build, tests, clippy, a `--screenshot` check a
| Dimension | Status |
|---|---|
| Architecture | M0 skeleton in place: geom → doc → render → engine → cli → shell, layering enforced by `cargo test` (`src/architecture_tests.rs`: lower layers only, no UI crates below the shell, and the AGENTS.md map must match). |
| Rendering | CPU oracle with analytic AA, non-zero/even-odd, solid + linear/radial gradients, round-join strokes. **Mask clipping**: the display list carries nested clips; a clip is the anti-aliased union of its mask fills (strokes and opacity ignored), intersected with any enclosing clip, computed once per render band; an empty mask hides everything under it. **Soft masks** (ADR 0070): a mask layer's mask type is Shape (coverage), Alpha (its artwork's opacity as drawn: gradients, faded shapes, strokes, bitmaps) or Luminance (brightness × opacity, SVG's coefficients), in the CPU oracle (analytic tests), the GPU stage (parity: mean 0.00006, worst 1 step of 255), SVG export (`<mask>` with `mask-type`), Lottie (alpha and luma track mattes) and the HTML canvas; Layer Properties › Mask type. **Group alpha**: a symbol instance below full opacity is a group in the display list; each render band composites the group's run of ops into its own buffer (nested groups stack) and blends it once at the group's alpha, so overlaps don't show through; SVG export writes `<g opacity>`. **Blend modes** (Animate's 14, on movie clip and button instances): an instance with one is an isolated group that blends at its close with the W3C separable formulas on premultiplied colour (Alpha and Erase keep or clear the backdrop); SVG gets CSS `mix-blend-mode`, Lottie the layer `bm`. **Bitmaps**: `Paint::Bitmap` fills (once or tiled) with bilinear sampling in premultiplied space, colour effects per sample; PNG/JPEG import to stage (a rectangle of the image's size); stored in the document as PNG (base64 in `.anicraft`), decoded once on first use; SVG export embeds each image once as a pattern. **Filters**: a filtered group is drawn on its own (by the same renderer, recursively, so nested filters work) into a buffer over its artwork grown by the filters' reach, filtered (box-blur passes; shadow and glow from the blurred, offset opacity; **bevel and gradient bevel** from the difference of the blurred opacity offset towards and away from the light, **gradient glow** from the glow's intensity, both through a colour ramp whose rest stop is pinned transparent, inner/outer/full and knockout, ADR 0025; colour matrix), and composited back as one image in its group, so alpha and blend apply; clips from inside the symbol apply before filtering and the instance's own clip after. **GPU stage, first slice** (M3, ADR 0019; `--features gpu-stage`, off by default): Preferences › Stage › Renderer *GPU (preview)* draws the stage with wgpu compute from the oracle's own prepared fills (tile binning with per-row backdrops on the CPU, exact area coverage and src-over per pixel on the GPU): solid and gradient fills and strokes, non-zero and even-odd; masks, group opacity, blend modes, filters and bitmaps fall back to the CPU per tile, and the status bar says so. Parity with the oracle: max 1/255, mean < 0.0001/255 on the sample, stress and analytic scenes (tests skip without an adapter). 4K with 1,000 shapes: 8.8–9.0 ms vs the CPU's 17.4–17.8 ms. **Second slice** (ADR 0029): on the window's wgpu device the stage tiles are drawn straight into textures egui shows (no readback; a headless device with readback when the window is on OpenGL); **masks** (nested, united artwork), **group opacity** and **all 14 blend modes** on the GPU, same parity (max 1/255, mean ≤ 0.0011/255); 4K: 1,000 shapes in 2.1–2.4 ms, 10k shapes in 10.2 ms as stage tiles, masked scenes 7× the CPU. **Third slice** (ADR 0032): **bitmap fills** (textures uploaded once per image and cached under a 256 MB budget, sampled with the oracle's own bilinear filter, colour effect and repeat rules: byte-identical) and **all seven filters** (each filtered symbol drawn into a layer of its own and filtered by compute passes that run the oracle's resolved steps: max 1/255, mean ≤ 0.007/255) on the GPU; the shaders now build with Direct3D's FXC, so DX12 windows get the GPU stage too (parity suite green on Vulkan and DX12); software adapters are refused (the CPU is faster), the start-up self-test compares with the oracle. **The GPU is the default stage renderer**: the shell's `gpu-stage` feature is on by default, Preferences › Stage › Renderer defaults to *Graphics card (GPU)*, and the CPU draws whenever there is no usable card, a tile is past the GPU's limits (more than 16 images, filters nested deeper than 4) or anything fails. 4K: the filtered sample in 3.9 ms (CPU 31.5), 200 bitmap fills in 4.4 ms (CPU 37.2). **Fourth slice** (ADR 0048): **tile binning on the GPU** for heavy frames without masks or groups (count, prefix sum, scatter and tile-list passes, no atomics, no readback; the CPU binning stays the reference and does the rest; one tile format for both: an integer backdrop per tile and steps on the tiles' left edges): on Vulkan, 10k shapes at 4K in one texture 21.7 → 4.7 ms, 50k shapes 122 → 22.5 ms, the 50k-shape 4K stage 75 → 37 ms (Direct3D 12 keeps CPU binning: slower therLine truncated
| Rendering | CPU oracle with analytic AA, non-zero/even-odd, solid + linear/radial gradients (with reflect/repeat, focal points, elliptical radials and linear RGB, ADR 0074), round-join strokes. **Mask clipping**: the display list carries nested clips; a clip is the anti-aliased union of its mask fills (strokes and opacity ignored), intersected with any enclosing clip, computed once per render band; an empty mask hides everything under it. **Soft masks** (ADR 0070): a mask layer's mask type is Shape (coverage), Alpha (its artwork's opacity as drawn: gradients, faded shapes, strokes, bitmaps) or Luminance (brightness × opacity, SVG's coefficients), in the CPU oracle (analytic tests), the GPU stage (parity: mean 0.00006, worst 1 step of 255), SVG export (`<mask>` with `mask-type`), Lottie (alpha and luma track mattes) and the HTML canvas; Layer Properties › Mask type. **Group alpha**: a symbol instance below full opacity is a group in the display list; each render band composites the group's run of ops into its own buffer (nested groups stack) and blends it once at the group's alpha, so overlaps don't show through; SVG export writes `<g opacity>`. **Blend modes** (Animate's 14, on movie clip and button instances): an instance with one is an isolated group that blends at its close with the W3C separable formulas on premultiplied colour (Alpha and Erase keep or clear the backdrop); SVG gets CSS `mix-blend-mode`, Lottie the layer `bm`. **Bitmaps**: `Paint::Bitmap` fills (once or tiled) with bilinear sampling in premultiplied space, colour effects per sample; PNG/JPEG import to stage (a rectangle of the image's size); stored in the document as PNG (base64 in `.anicraft`), decoded once on first use; SVG export embeds each image once as a pattern. **Filters**: a filtered group is drawn on its own (by the same renderer, recursively, so nested filters work) into a buffer over its artwork grown by the filters' reach, filtered (box-blur passes; shadow and glow from the blurred, offset opacity; **bevel and gradient bevel** from the difference of the blurred opacity offset towards and away from the light, **gradient glow** from the glow's intensity, both through a colour ramp whose rest stop is pinned transparent, inner/outer/full and knockout, ADR 0025; colour matrix), and composited back as one image in its group, so alpha and blend apply; clips from inside the symbol apply before filtering and the instance's own clip after. **GPU stage, first slice** (M3, ADR 0019; `--features gpu-stage`, off by default): Preferences › Stage › Renderer *GPU (preview)* draws the stage with wgpu compute from the oracle's own prepared fills (tile binning with per-row backdrops on the CPU, exact area coverage and src-over per pixel on the GPU): solid and gradient fills and strokes, non-zero and even-odd; masks, group opacity, blend modes, filters and bitmaps fall back to the CPU per tile, and the status bar says so. Parity with the oracle: max 1/255, mean < 0.0001/255 on the sample, stress and analytic scenes (tests skip without an adapter). 4K with 1,000 shapes: 8.8–9.0 ms vs the CPU's 17.4–17.8 ms. **Second slice** (ADR 0029): on the window's wgpu device the stage tiles are drawn straight into textures egui shows (no readback; a headless device with readback when the window is on OpenGL); **masks** (nested, united artwork), **group opacity** and **all 14 blend modes** on the GPU, same parity (max 1/255, mean ≤ 0.0011/255); 4K: 1,000 shapes in 2.1–2.4 ms, 10k shapes in 10.2 ms as stage tiles, masked scenes 7× the CPU. **Third slice** (ADR 0032): **bitmap fills** (textures uploaded once per image and cached under a 256 MB budget, sampled with the oracle's own bilinear filter, colour effect and repeat rules: byte-identical) and **all seven filters** (each filtered symbol drawn into a layer of its own and filtered by compute passes that run the oracle's resolved steps: max 1/255, mean ≤ 0.007/255) on the GPU; the shaders now build with Direct3D's FXC, so DX12 windows get the GPU stage too (parity suite green on Vulkan and DX12); software adapters are refused (the CPU is faster), the start-up self-test compares with the oracle. **The GPU is the default stage renderer**: the shell's `gpu-stage` feature is on by default, Preferences › Stage › Renderer defaults to *Graphics card (GPU)*, and the CPU draws whenever there is no usable card, a tile is past the GPU's limits (more than 16 images, filters nested deeper than 4) or anything fails. 4K: the filtered sample in 3.9 ms (CPU 31.5), 200 bitmap fills in 4.4 ms (CPU 37.2). **Fourth slice** (ADR 0048): **tile binning on the GPU** for heavy frames without masks or groups (count, prefix sum, scatter and tile-list passes, no atomics, no readback; the CPU binning stays the reference and does the rest; one tile format for both: an integer backdrop per tile and steps on the tiles' left edges): on Vulkan, 10k shapes at 4K in one texture 21.7 → 4.7 ms, 50k shapes 122 → 22.5 msLine truncated
| Timeline | **Frame selection**: click, Shift-click or drag across frames and layers; F5/Shift+F5, F6/F7 and Shift+F6 (keys, icon buttons and right-click menu) act on the whole selection; with no frame selection F5 extends every layer with frames at or after the playhead, and F5/F6/F7 move the playhead on as in Animate (F6/F7 on a keyframe key the next frame; `all_layers`/`advance` headless); drag selected keyframes left or right to move them, and up or down onto other layers (the source keeps empty frames, as in Animate) (with a drop outline; one undo step; keys they land on are replaced, and spans fill the frames left behind); removing or clearing selected frames that hold artwork asks first. **Cut/Copy/Paste Frames** (Ctrl+Alt+X/C/V, and plain Ctrl+X/C/V after clicking the timeline): own clipboard, copies cut exactly at the selection edges (mid-tween state kept), paste inserts like Animate, several layers paste onto the layers below (missing ones are created), fresh element ids, symbols travel with them. **Span length by dragging its end** (resize cursor, live outline with the length in frames and seconds; later frames move with it). Headless: `layers`/`count` on the frame commands, `timeline.move_keyframes`, `timeline.cut_frames/copy_frames/paste_frames`. Layers (show/lock/outline), **timeline polish** (ADR 0061): a per-layer **onion skin toggle** column (Alt-click solos; left-out layers aren't onion-skinned; Edit Multiple Frames unaffected), the colour square toggles **View as Outlines** in the layer colour **on the stage only** (exports, Test Movie and the player draw the artwork as it is), the **colour chip** opens the layer colour (swatches, hex, More…), **onion frames of the parent timeline** dimmed around a symbol edited in place, **Layer Height** 100/200/300 %, **Layer Properties** (double-click the layer icon; name, show/lock, type, outline colour, outlines, onion, height; one undo step), **Frame View** (Tiny/Small/Normal/Medium/Large, Short rows) with the frame zoom in the timeline's bottom bar (the header fits at the default window size, tested); headless `layer.set_onion/set_color/set_height/set_properties/properties`; XFL `heightMultiplier`. Not yet: folder onion toggles, onion of deeper parent timelines, multi-layer Layer Properties and layer transparency, frame thumbnails (Preview). Keyframes, blank keyframes, insert/remove frames, classic tweens with 8 easing presets + curve preview, **shape tweens** (morph between any two shapes: segments made cubic, subpaths paired by size and grown from or shrunk to a point when counts differ, segment counts equalized by subdivision, windings matched and start points aligned; amber spans; classic ⇄ shape keeps the easing; **shape hints** (ADR 0023): Modify › Shape › Add Shape Hint (Ctrl+Shift+H) adds lettered markers `a`–`z` that the artist drags onto an edge on the first and last keyframe (rose until placed, amber placed on the first, mint on the last; right-click removes), the morph cuts both outlines at the hinted points and matches the pieces in order by length; `tween.add_hint/move_hint/remove_hint/clear_hints/hints`; not yet: View › Show Shape Hints, hints inside symbols edited in place), auto-key when editing inside a tween, frame labels, symbol nesting: graphics keep step with their timeline (loop, play once, single frame, first frame; set in Properties), movie clips loop their own timeline from when the instance appears (continuous across keyframes holding the same instance), buttons show their Up frame, looping playback. **Onion skin and Edit Multiple Frames** (ADR 0047): onion markers on the frame ruler (drag the start and end brackets; Always Show Markers, Anchor Markers, Onion 2 / Onion 5 / Onion All, also on a right-click on the ruler), frames before and after the playhead tinted in their own colours (theme blue and green, changeable in the onion menu, Reset) and fading with distance, Outlines, Keyframes Only, locked layers left out as in Animate, each layer's onion frames under its own artwork and over the layers below; options saved in the preferences; the stage's frame cache keys every look apart. **Edit Multiple Frames** shows every keyframe within the markers at full strength and selects (click, Shift-click, marquee, Select All) and moves (drag, arrow keys) artwork across them, one undo step, motion tween paths moving with their objects. Headless: `frames.artwork`, `frames.edit_multiple`. **Edit Multiple Frames, complete** (ADR 0051): Cut, Copy, Paste (current frame), Paste in Place (back keyframe by keyframe, or a one-frame copy onto every keyframe between the markers), Clear, Align (Ctrl+Alt+1…6, To Stage), Rotate 90° and Flip, and **Free Transform** of the selection on every keyframe about one shared pivot (one box, one undo step per drag); raw shapes moved, transformed or pasted merge again on their own keyframe; **onion skin and Edit Multiple Frames inside a symbol edited in place**, on its own timeline and markLine truncated
| Drawing | Selection (click, shift-add, marquee, drag-move, arrow nudge; **across layers**, ADR 0044: a selection holds artwork on several visible, unlocked layers, the timeline marks them, Properties shows mixed values), **Free Transform (Q)**: scale from corner/edge handles (Shift proportional, Alt from centre), rotate outside corners (Shift snaps 15°), move; one undo step per drag. Rectangle (corner radius), oval, PolyStar, line (45° snap), hand, zoom. **Pen (P)**: click for corners, drag for smooth handles (Alt breaks them), close on the first point, Enter/Esc/last-point click finishes, Backspace takes back a point; one undo step per path. **Pencil (Shift+Y)**: Smooth (Schneider curve fitting with corner detection), Straighten and Ink modes, smoothing relative to the screen. **Subselection (A)**: anchors and handles on selected shapes, drag points/handles (anchors bring their handles; one undo step per drag), point marquee, double-click an edge to add a point, Delete removes points, right-click Make Smooth/Corner; closed shapes' start point and closing edge edit like any other. **Cut/Copy/Paste in Center/Paste in Place** (the clipboard carries symbols across documents). **Rotate 90° CW/CCW, Flip H/V. Align** left/centre/right/top/middle/bottom (Ctrl+Alt+1…6; a single element aligns to the stage) and distribute. Convert to symbol / break apart; arrange; duplicate. Headless: `draw.path`, `draw.freehand`, `path.move_points/add_point/delete_points/convert_point`. **Paint Bucket (K)**: click a fill to recolour it, or inside an outline (one shape or several) to fill the enclosed area; gap size None/Small/Medium/Large closes openings; the fill is traced and curve-fitted into a new shape placed under its lines; open areas say so instead of flooding. **Ink Bottle (S)**: gives the clicked shape the current stroke. Headless: `paint.bucket`, `paint.ink`. Tool options show first in Properties while a drawing tool is active. **Text (T)** (ADR 0012): click to type on the stage, click or double-click text to edit it; font (installed families, plus the embedded Inter), size, colour, bold, italic, alignment, letter/line spacing, wrap width; the last style is kept for new text; laid out by `anicraft-text` (`fontdb` discovery, `harfrust` shaping, `skrifa` outlines) and stored as outlines with the source, so rendering never needs the font; Break Apart makes a shape. **Variable-width strokes** (ADR 0018): a stroke's width varies along it through width points (position by arc length, a width on each side as a factor of the stroke width, smooth monotone interpolation); built-in profiles (Uniform, Taper both ends, Taper start, Taper end, Bulge, Pinch) in Properties › Width with a picture of each, and in the drawing tools' options for new strokes; the **Width tool (U)**: hover a stroke to see its width points, drag a handle to widen or narrow (Alt: one side), drag the dot to slide a point, drag anywhere on the stroke to add one, Delete removes; one undo step per drag; rendered by the oracle as trapezoids with outer round joins and cross-section caps, written by SVG and Lottie export as the same filled outlines; shape tweens blend profiles; `.anicraft` keeps them (older files open as uniform). Headless: `stroke.set_profile`, `stroke.set_width_point`, `stroke.delete_width_point`, `stroke.width_at`, `profile` on `element.set_stroke`, the drawing commands and `paint.ink`. Not yet: width data from or to Animate files, saved custom profiles, pressure. **Stroke styles** (ADR 0046): Properties › Style (Solid, Dashed with dash and gap, Dotted with spacing), Cap (None, Round, Square), Join (Miter, Round, Bevel) and Miter limit, also in the drawing tools' options for new strokes; drawn exactly by the oracle (butt and square caps, miters bevelled past the limit, dashes by arc length restarting per subpath, round dots, dashes keeping a width profile's widths; sub-pixel patterns solid and faded) and so by the GPU stage; the Ink Bottle carries the style and the Eyedropper picks it; merge drawing keeps it on cut pieces; shape tweens blend miter limits and dash lengths; SVG, HTML canvas and Lottie export write it. Headless: `stroke.set_style`, and `cap`, `join`, `miter`, `style`, `dash`, `dash_offset`, `dot_spacing` on `element.set_stroke`, the drawing commands and `paint.ink`. Not yet: Animate's ragged, stipple and hatched styles, multi-dash patterns in Properties (kept and editable by command), stroke scale modes and hairlines. **Merge drawing** (ADR 0031, first slice): with Object Drawing (J) off, the editor's default, the shape tools, Pen and Pencil draw raw strokes and fills that cut and join the raw shapes they touch (a fill on top replaces what it covers or joins the same colour, lines cut each other and the fills they cross, a fill hides the lines under it, points within 0.2 px are one; exact Bézier pieces, `anicraft_geom::planar`); one element per fill region and stroke run, selected with Animate's dot pattern; double-click Line truncated
| Plug-ins | **WebAssembly plug-ins** (ADR 0017, `docs/plugins.md`): sandboxed modules run by `wasmi` with no imports but the AniCraft ABI (`anicraft.call`/`anicraft.response`: JSON requests that run registry commands, read a compact document view or the active layer's elements, and log); fuel (10⁹ instructions), memory (256 MiB), wall-clock (5 s), request, size and log limits, a fresh instance per run; file, plug-in, undo and clipboard commands refused. `plugin.install/list/run/remove/reload`; a run is atomic and one undo step named after the plug-in. App: **Commands** menu (Plug-ins, Install, Manage, Reload), palette entries, a dialog generated from the manifest's parameters with a live preview; plug-ins load from `<settings>/plugins` or `ANICRAFT_PLUGINS`; CLI `--plugins`. Samples in Rust (Star Field, Jitter Selection, guest SDK) in `examples/plugins`. Frame scripts: see Interactivity. Not yet: exporter and easing kinds, background runs with cancel, a binary document view. |
@@ -34,7 +34,7 @@ milestone ends with a green tree: build, tests, clippy, a `--screenshot` check a
| M | Theme | Exit criteria |
|---|---|---|
| **M0** | Foundations *(this version)* | Workspace + layering; document model; timeline evaluation with classic tweens and easing; CPU oracle renderer; command registry with undo; `.anicraft`; CLI render + JSON-lines; egui shell with stage, tools, timeline, properties, library; `--screenshot`. |
| **M1** | Authoring core ✅ *(v0.1.0)* | ~~Free transform tool with handles~~ ✅; ~~subselection and Bézier point editing~~ ✅; ~~Pen and Pencil~~ ✅; ~~Paint bucket / Ink bottle~~ ✅; ~~copy/paste~~ ✅, ~~duplicate, arrange~~ ✅, ~~align~~ ✅ (commands and menus; and the dock's Align panel ✅); ~~onion skin~~ ✅ (markers, tint, fade, outlines, keyframes only, Edit Multiple Frames: ADR 0047; its delete, copy/paste, Free Transform, align and re-merge, and both inside symbols: ADR 0051); ~~frame selection ranges in the timeline (multi-frame insert/remove/move keyframes by drag)~~ ✅ (including between layers); ~~PNG sequence + animated GIF export~~ ✅; ~~keyboard shortcut map editor~~ ✅. |
| **M1** | Authoring core ✅ *(v0.1.0)* | ~~Free transform tool with handles~~ ✅; ~~subselection and Bézier point editing~~ ✅; ~~Pen and Pencil~~ ✅; ~~Paint bucket / Ink bottle~~ ✅; ~~copy/paste~~ ✅, ~~duplicate, arrange~~ ✅, ~~align~~ ✅ (commands and menus; and the dock's Align panel ✅); ~~onion skin~~ ✅ (markers, tint, fade, outlines, keyframes only, Edit Multiple Frames: ADR 0047; its delete, copy/paste, Free Transform, align and re-merge, and both inside symbols: ADR 0051); ~~frame selection ranges in the timeline (multi-frame insert/remove/move keyframes by drag)~~ ✅ (including between layers); ~~PNG sequence + animated GIF export~~ ✅; ~~keyboard shortcut map editor~~ ✅; ~~gradient editor, Gradient Transform tool and Lock Fill~~ ✅ (ADR 0074: Colour section in Properties with a keyboard-operable stop bar, overflow, Linear RGB, focal point and bitmap fills; the Gradient Transform tool (F) on linear, radial and bitmap fills; Lock Fill; gradients exact through SVG and XFL. Not yet: gradient and bitmap strokes, saved swatches, ellipses and focal points in Lottie). |
| **M2** | Model at scale | ~~`Arc` structural sharing (O(changed) undo)~~ done early (ADR 0001); ~~scenes~~ ✅ (ADR 0011); ~~layer folders~~ ✅, ~~guide and motion-guide layers~~ ✅; ~~mask layers~~ ✅; ~~Movie Clip and Button behaviours~~ ✅ (playback; button states and scripting come with M6); ~~group alpha / offscreen compositing~~ ✅; ~~shape tween~~ ✅, ~~shape hints~~ ✅ (ADR 0023); ~~motion tween + Motion Editor curves~~ ✅ first slice (ADR 0016); ~~motion paths on the stage with orient to path~~ ✅ first slice (ADR 0030), ~~path point add/delete/convert and moving the whole path~~ ✅ (ADR 0038), ~~anchors pinned to frames~~ ✅ (ADR 0049; 3D and XFL import later); ~~library management~~ ✅ first slice (ADR 0050: folders, rename, duplicate, Swap Symbol, use counts and unused items, sort, search, preview, Allow Smoothing), ~~Library and Properties polish~~ ✅ (ADR 0053: drag onto the stage, Swap Bitmap, Convert to Symbol folders, mixed on every Properties row), ~~9-slice scaling~~ ✅ first slice (ADR 0055); ~~colour effects, complete~~ ✅ (ADR 0056: Properties' Style menu with None, Brightness, Tint, Advanced and Alpha, one exact colour transform in the CPU oracle, the GPU stage, SVG `feColorMatrix`, HTML canvas and Lottie, XFL `Color` import with a corpus package, classic tweens across styles, motion tween tint colour, brightness and Advanced tracks; not yet: camera colour effects beyond tint, a colour picker for the Motion Editor's tint colour); ~~MCP server~~ ✅; perf budgets ✅ (machine-independent ones gate every PR; timing via `bench --check` on a known machine, CI once a benchmark runner exists); ~~layering check~~ ✅ (`src/architecture_tests.rs`, runs with `cargo test`). |
| **M3** | GPU stage *(in progress; the default stage renderer since ADR 0032)* | ~~wgpu renderer behind a feature flag~~ ✅ first slice (ADR 0019: the oracle's fills, CPU tile binning with backdrops, compute coverage; gradient tables in a storage buffer); ~~per-pixel parity tests vs the CPU oracle~~ ✅ (max 1/255, mean < 0.0001/255); ~~4K at 60 fps for 1,000 shapes~~ ✅ (8.8–9.0 ms); ~~no-readback textures, masks/groups/blend modes on the GPU~~ ✅ second slice (ADR 0029: window's device, 4K 10k shapes in 10.2 ms as tiles); ~~GPU binning~~ ✅ fourth slice (ADR 0048: heavy frames without masks or groups binned on the GPU, 50k shapes at 4K 122 → 22.5 ms in one texture; outline mode's hairlines as fast as tinted onion skin); ~~bitmaps and filters on the GPU~~ ✅ third slice (ADR 0032: bitmaps byte-identical, filters max 1/255; 4K filtered sample 3.9 ms, 200 bitmaps 4.4 ms); ~~hardware breadth~~ ✅ Vulkan and DX12 (FXC), software adapters refused, oracle-checked self-test; ~~GPU as the default stage renderer~~ ✅ (`gpu-stage` on by default for the app, automatic CPU fallback); next: GPU binning inside masks and groups, shared filtered layers across tiles, an image atlas, GPU exports. |
| **M4** | Interchange *(in progress)* | **XFL import** (DOMDocument.xml, symbols, edges/fill styles decoded from the public format descriptions) with a corpus of self-authored files: first slice ✅ (see Files above); ~~larger self-authored corpus with golden render tests~~ ✅ (ADR 0035: twelve packages covering every mapped feature, exact report expectations, hostile variants, CPU-oracle goldens); ~~`.fla` variants of the corpus and a hardened zip reader~~ ✅ (ADR 0054: nine zip layouts imported identically to the folder, ZIP64, CP437 names, a 9,664-archive hostile fuzz; a 54.6 MB `.fla` imports in 0.31 s); not yet: sound and video items, self-extracting and top-folder `.fla` archives; ~~SVG import (Import to Stage)~~ ✅, ~~SVG frame export~~ ✅; ~~Lottie export~~ ✅ (frame-accurate; easing curves instead of per-frame keys later); ~~sprite sheet + JSON~~ ✅; ~~MP4/WebM via ffmpeg pipe~~ ✅; ~~animated PNG and WebP~~ ✅ (ADR 0063; lossless WebP; lossy WebP not yet). |