Repository navigation
SVG Animator
The SVG Animator is a separate design type (design_type: "svg-animation") with its own page, web/svg-animation.html. It imports a static SVG, animates its elements on independent per-property keyframe tracks, and exports a native animated SVG (SMIL). It does not use the Rust engine or the shape serializer. The document keeps shapes: [], and all animation data lives in a versioned svg_animation member that only the web/svg-animation-*.js modules understand. The key fact: the editor preview and the exported file are built by the same function, animationScene() in svg-animation-svg.js. Preview and export agree because they share that code, so change it carefully.
The Windows alpha.21 preview includes Pen and Pencil drawing, direct stage selection, base-path editing, Add/Replace SVG import, independent gradient animation, and detachable parent panels. Panel Workspace explains icon docks, side flyouts, separate windows and saved layouts. The Dev Log records releases separately from proposed roadmap work.
- Pen: click for corners or drag for Bézier handles. A stroke appears immediately. Enter, Escape, Finish path, or switching to Select keeps an open path; Discard cancels it. Closing a loop is optional. An open path can supply a motion route.
- Pencil: draw editable curves with 0–100% smoothing and round stroke ends; Shift constrains a straight line.
- Select: click artwork on the stage, including near thin strokes. Drag to move, use Shift to constrain, and delete a selected path with the keyboard, palette or inspector. Removing an element also removes its animation. Undo restores both.
- Direct Selection: move or nudge anchors/handles, insert a midpoint, remove anchors, change corner/smooth type, split or open a path, and join endpoints within the same element. Multi-node selection and joining separate objects remain future work.
- Base edits preserve existing animation. A path with a Morph track uses the separate timed-node workflow; topology changes are rejected when they would invalidate animation.
Choose a linear or radial gradient for Fill or Stroke. Gradient rotation is independent of the object's Rotation animator. Stop colors, offsets and opacity can be keyframed. Preview, Undo, .pixl save/reopen and native animated SVG export share the same model.
fillGradientRotation and strokeGradientRotation hold numeric angles. fillGradient and strokeGradient hold ordered stop arrays; every key in one track must contain the same number of stops. Imported inherited paint and supported named/HSL/currentColor stop values are normalized for editing. Solid color tracks remain separate properties.
Import SVG offers Add and Replace. Add preserves existing tracks and origins and remaps incoming IDs/references. Replace explicitly replaces the artwork and clears its animation. Both are atomic Undo operations with edit-permission and stale-document checks. Importing an exported animated SVG still imports static artwork; use .pixl to retain the editable timeline.
| Key files | web/svg-animation.js (controller), svg-animation-model.js (data model), svg-animation-keyframes.js (group operations), svg-animation-timeline.js (dock UI), svg-animation-svg.js (sanitize, scene, export), svg-animation-interactions.js (export player) |
| Entry points |
/editor/svg-animation.html?draft=<id> (local) or ?cloud=<id> → start() in svg-animation.js; export preview /editor/svg-animation-preview.html
|
| Depends on |
svg-path.js (parsePath), local-drafts.js, local-persistence.js, local-recovery.js, cloud-session.js, team-session.js, inspector-settings.js, inspector-dropdown.js, context-menu.js, icons.js, desktop-integration.js; esbuild (preview bundle) |
| Used by | Projects home (design-browser.js "New design → SVG Animation"), project-navigation.js, editor-entry.js, cloud-files.js, app.js (import redirect), project-preview.js (thumbnails) |
| Related docs | docs/SVG_ANIMATION.md (user workflow + verification log), docs/DESKTOP.md, Interface reference log |
- Import and sanitize arbitrary SVG into a safe, canonical subset with stable element IDs (
sanitizeSvg). - Hold a document of per-element, per-property tracks of keyframes with segment easing, and validate it (
validateAnimation). - Provide a dedicated docked timeline: multi-select, marquee, group drag with snapping, copy/paste, paste to another element, duplicate at playhead, reverse, retime, delete, and previous/next-keyframe navigation.
- Provide a right inspector for property values, keyframe easing (presets and a cubic-Bézier editor), selection timing, motion paths and morph nodes.
- Play back in the editor by seeking a live DOM scene once per animation frame.
- Export static SVG (first frame) or animated SVG. Interactive (hover or click) exports embed a small player.
-
Persist as
.pixlthrough local drafts or revision-checked cloud saves, using the shared editing lease for team files.
newSvgAnimation(name) in svg-animation-model.js creates:
shapes must be empty, and version must be 2. A generic engine loader that sees this file finds no shapes. The type check (isSvgAnimation) sends the file to the SVG page before any engine code runs.
properties in the model is the single registry. It sets each property's label, initial value and range. It also decides how the property is rendered:
| Key | Label | Value | Rendered as |
|---|---|---|---|
x, y
|
Position X/Y | number ±100000 (offset from imported geometry) |
translate wrapper → animateTransform
|
rotation |
Rotation | degrees ±36000 |
rotate wrapper |
scaleX, scaleY
|
Scale X/Y | 0.001–100 (multiplier) |
scale wrapper |
opacity |
Opacity | 0–1 |
opacity attribute → animate
|
fill, stroke
|
Fill/Stroke color |
#rrggbb only |
attribute; interpolated per RGB channel |
strokeWidth |
Stroke width | 0–10000 | stroke-width |
strokeOffset |
Stroke offset | ±100000 | stroke-dashoffset |
motionProgress |
Path progress (%) | 0–100 |
animateMotion along track.motion.d
|
fillGradientRotation, strokeGradientRotation
|
Gradient rotation | degrees ±36000 | gradient transform, independent of object wrappers |
fillGradient, strokeGradient
|
Gradient stops | ordered stop arrays, fixed count across keys | native gradient stop animation |
morph |
Morph | node array (see below) |
d attribute on a <path>
|
Values with attribute bind to the element itself. Values without one (x, y, rotation, scale*) bind to generated wrapper groups. motion: true and morph: true mark the special cases.
- Keys are sorted by strictly increasing integer
time, all within[0, duration]. A track holds at most 200 keys.putKeyrounds times and clamps them to the duration. -
easingis a preset name (linear,ease,ease-in,ease-out,ease-in-out) or a custom[x1,y1,x2,y2]array. All four values must lie in 0–1, so overshoot and bounce curves are not possible (validEasing). -
Easing belongs to the outgoing segment. A key's curve controls the motion from that key to the next.
eased()solves the cubic Bézier for x by 28 bisection steps, then evaluates y. -
trackValue(track, time)holds the first and last values outside the key range. It lerps numbers, lerps colors per channel, and lerps morph nodes point by point (interpolateMorph). -
putKeyon a missing track also inserts a held key at 0 with the element's base value, so animation never starts partway through the timeline.addAnimatorin the controller also adds an end key atduration. -
resizeDurationrefuses to shorten the duration past any existing key. It never drops keys.
setMotionPath(animation, element, motion, origin) creates a motionProgress track (0→100 over the duration) and stores motion = {d, name, rotate}, where rotate is none, auto or auto-reverse. The route is a snapshot. captureMotionPath(source, target) in svg-animation-path.js converts the source shape to path data (pathGeometry handles path, line, polyline, polygon, rect including rounded corners, circle and ellipse). It then maps the result into the target's parent coordinate space with getScreenCTM(). A valid route must be a single subpath with nonzero length, and it cannot be the target or one of the target's descendants. Later edits to the source shape do not change the animation. Replacing a route keeps the progress keys and the orientation.
A morph value is [{closed, points:[[ax,ay, inx,iny, outx,outy], …]}, …]: each node stores its anchor, incoming handle and outgoing handle in local units. A value may hold up to 64 subpaths and 512 nodes in total. All coordinates must lie within ±100000 (svg-animation-morph.js). Every key on a morph track must have the same topology (sameMorphTopology): the same subpath count, the same node count per subpath, and the same closed flags. That rule keeps both preview interpolation and SMIL d interpolation exact. morphData always serializes to M plus cubic C commands, with Z for closed subpaths. When a rect, circle or other shape gets a morph track, animationScene replaces it with a <path> that keeps the shape's paint, ID and transform.
interaction is optional. Older files without it use interactionDefaults = {trigger:'load', onLeave:'reverse', onClick:'restart'}. Valid values are trigger ∈ load|hover|click, onLeave ∈ pause|reset|reverse|continue and onClick ∈ pause|restart|reverse|continue (validInteraction).
| File | Role |
|---|---|
| svg-animation-drawing.js, drawing model, picking | Pen/Pencil, anchor editing and topology, stage selection and movement. |
| svg-animation-gradient-inspector.js, gradient model, gradients | Paint controls, stop validation/interpolation, gradient definitions and scene bindings. |
| svg-animation-import.js, import dialog | Add/Replace operations, reference remapping and import choices. |
| detachable-panels.js, panel-docks.js, editor-dom.js | Shared parent windows, icon strips and flyouts, cross-window live-control lookup. |
| svg-animation.html | Shell page: loads the shared UI CSS, motion.css and svg-animation.css, then svg-animation.js. start() builds all other markup. |
| svg-animation.js | Controller. Owns the module state (doc, selected, currentTime, running, history/future). Handles routing and loading (start), commit, undo, play/stop/seek, render, the layer list, the inspector (propertyRow, morphInspector, motion-path picker, easing and timing sections), import (importSvg, importProject), example(), addShape, deleteElement, local/cloud persistence and desktop hookup. |
| svg-animation-model.js | Pure data model: properties, easings, validateAnimation, validValue, eased, trackValue, putKey, deleteKey, moveKey, resizeDuration, exportKeys, validateMotionPath, setMotionPath. No DOM access, so tests import it under Node. |
| svg-animation-keyframes.js | Pure multi-key operations over a selection of {element, property, time} refs: keyframeId, adjacentKeyframeTime, keyframeEasing/setKeyframeEasing, keyframeMoveDelta, createKeyframeDrag (snapping), moveKeyframes, keyframeTiming/retimeKeyframes, deleteKeyframes, reverseKeyframes, copyKeyframes, pasteKeyframes, pasteKeyframesToElement. Each operation returns a new animation, validated by checked(), or throws without side effects. |
| svg-animation-timeline.js |
installSvgTimeline({...}): the docked #motion-timeline panel with transport controls, ruler/scrubber, tracks, playhead, marquee, snap guide, context menu, keyboard handling, zoom (1–32×) and resize/collapse. Holds the selection and the clipboard. |
| svg-animation-easing.js |
easingEditor({value, mixed, disabled, change}): preset dropdown, draggable Bézier handle SVG and X1/Y1/X2/Y2 fields. Handles support arrow keys, Home/End and Escape. |
| svg-animation-morph.js | Morph value helpers: validMorph, morphPath, sameMorphTopology, interpolateMorph, morphData, moveMorphPoint (moving an anchor carries both of its handles). |
| svg-animation-nodes.js |
installMorphNodes(...): on-canvas overlay of anchors and handles, with pointer drag, keyboard nudging (1 unit; 10 with Shift) and Escape to cancel. |
| svg-animation-path.js |
pathKinds, pathGeometry, captureMotionPath, pathSampler (uses getPointAtLength and computes a tangent angle for auto-rotate). |
| svg-animation-svg.js |
sanitizeSvg, animationLayers, baseValue, animationScene (wrapper construction and seek), animatedSvg (export serializer), normalizeSvgAnimation. |
| svg-animation-transform.js |
(Included since alpha.20, PR #51.) Canvas transform handles: installTransformHandles({host, read, start, preview, restore, change, report}) draws an SVG overlay (#svg-selection) with four corner resize handles, four full-edge stretch targets and four rotation targets just outside the corners; resizedValues(values, bounds, origin, handle, delta, {center, uniform}) computes new scaleX/scaleY and re-anchors x/y so the opposite edge/corner (or the center with Alt) stays fixed. Edits only the existing parent-space properties (x, y, rotation, scaleX, scaleY); imported geometry is never rewritten. |
| svg-animation-interactions.js |
interactionClock (playback state machine), mountSvgInteraction (event wiring scoped to one <svg>), interactionScript (serializes both into a <script>). Both functions are self-contained on purpose because their source text is copied into exported files. |
| svg-animation-export.js |
installSvgExport(...): Export dialog with format, trigger, mouse-out, second-click and repeat options, a sandboxed preview iframe, and the Save settings and Download SVG actions. |
| svg-animation-preview.html / svg-animation-preview.js | Preview document for the export dialog. The JS entry is bundled into web/vendor/svg-animation-preview.js. |
| svg-animation-cloud.js |
installSvgCloudEditing(...): Start/Finish editing lease UI built on TeamSession, with sync every 20 s and write gating. |
| svg-animation.css | Three-column grid (296 px elements panel / canvas / 240 px inspector) above a timeline whose height comes from --timeline-height. Also styles the dialogs, morph overlay and easing editor. |
flowchart LR
subgraph Page["svg-animation.html"]
C["svg-animation.js<br/>controller + inspector"]
T["timeline.js<br/>installSvgTimeline"]
E["export.js<br/>installSvgExport"]
N["nodes.js<br/>morph overlay"]
Z["easing.js<br/>Bezier editor"]
CL["cloud.js<br/>editing lease"]
end
M["model.js<br/>validate, putKey, trackValue"]
K["keyframes.js<br/>group ops"]
S["svg.js<br/>sanitize, animationScene,<br/>animatedSvg"]
P["path.js / morph.js"]
I["interactions.js<br/>clock + mount"]
PV["svg-animation-preview.html<br/>+ vendor/svg-animation-preview.js"]
C --> M & S & P & T & E & N & Z & CL
T --> K --> M
E --> S --> M
S --> P & I
E -. postMessage .-> PV
PV --> I
C --> LP["LocalPersistence / CloudSession"]
- Routes:
projectUrl()in project-navigation.js mapsdesign_type === 'svg-animation'to/editor/svg-animation.html. The older generic URLs still work.editor-entry.jsandcloud-files.jscheckisSvgAnimationand redirect, and importing a.pixlinapp.jsnormalizes the file and then redirects. New documents come fromnewDesign(name, template, 'svg-animation')inlocal-drafts.js. -
start()reads the route. For a local draft it callsdrafts.activate(id)underwithDraftLock. For a cloud file it callscloudRequest('/<id>'). If the body is not an SVG animation, it redirects to/editor/index.html. -
normalizeSvgAnimation(doc)validates the document, re-sanitizessvg, and builds a throwaway scene. That step fails early when a track points to a missing element. - The controller builds the DOM, installs the timeline, export dialog, morph overlay and persistence, then calls
render().
render() sanitizes the stored SVG into an offscreen #svg-measure host. That copy resolves inherited paint and bounding boxes for baseValue and originFor. The controller then lists the layers (animationLayers: drawable elements outside defs, clipPath, mask, pattern, marker, symbol and filter) and builds preview = animationScene(animation()), which goes into #svg-art.
animationScene wraps each animated element in nested <g> groups so that every property gets its own transform channel. Reading from the outside in:
translate(x) → translate(y) → translate(origin) → rotate → scale(sx,1) → scale(1,sy) → translate(-origin) → [element]
A motion track adds its own outer wrapper (translate(px py) rotate(angle) sampled from the path) around a translate(-origin) pivot. The element's original transform stays on the element, inside the wrappers. Attribute tracks bind to the element itself, and inline styles for those attributes are removed so they cannot override the animated value. Each binding is {node, track, attribute, type?, value(v)}. seek(time) runs trackValue on every binding and writes the result.
play() drives a requestAnimationFrame loop. It computes currentTime from performance.now(), wraps the time when loop is on, and calls paint() (which runs preview.seek and repositions the selection outline) along with timeline.update(). Pause stops at the current time, and the next Play resumes from there. Go to start stops playback and seeks to 0. timeline.update() changes the Play/Pause icon only when the label changes. Before PR #49 it replaced the icon on every frame, which detached the button's pointer target partway through a click.
PR #51 (6f3d74b) adds selection handles on the canvas, implemented in svg-animation-transform.js and wired by the controller as transformEditor.
-
Geometry. For the selected element the module reads
frame.getScreenCTM()(the element's parent-space wrapper, exposed asframesbyanimationScene), removes the animation pose (translate(x+origin) · rotate · scale · translate(-origin)) and encloses the element'sgetBBox()in the animation's parent axes. For elements with their own imported rotation/skew this is an enclosing box, not an exact oriented box. -
Preview without commits. During a drag,
animationScene().seek(time, overrides)takes per-element property overrides so the scene previews the new pose without touching the document. Dragging pauses playback. -
Commit. On release, changed
scaleX/scaleY/x/y/rotationkeys are written at the playhead as one undo step, preserving existing key easing. A click without movement writes nothing. - Modifiers and keyboard. Shift keeps proportions (resize) or snaps rotation to 15°; Alt/Option resizes from the center. Focused handles accept arrows (1 SVG unit / 1°, Shift ×10 / 15°).
-
Cancellation. Escape, pointer cancel, lost capture, leaving the window, seeking, selection change, play/undo, or losing the editing lease cancels the drag (
transformEditor.cancel()is called fromcommit,undo,seek,playandselectLayer). - Limits. Scales stay within the model range 0.001–100; dragging past the opposite edge stops at the minimum instead of flipping. Handles hide during morph-node editing and are disabled in read-only shared files.
-
Tests.
tests/browser/svg-animation-transform.spec.mjs(eight handle workflows). Included in Windows alpha.20 and later.
All edits go through commit(next). That call validates the document, rejects no-op changes, checks canEdit() (the team lease), pushes a JSON snapshot onto history (at most 80; redo is cleared), and then calls changed() and render(). changed() notifies LocalPersistence or CloudSession. Undo and redo swap whole-document snapshots. Every timeline group operation produces a single commit, so each one is one undo step.
The inspector has these sections for the selected element:
- Add animator
- A row per property with a keyframe diamond. The diamond adds or removes the key at the playhead.
- Transform origin
- Motion path picker and orientation
-
Morph (
morphInspector): node coordinates and Edit/Done nodes -
Keyframe timing (
keyframeTiming/retimeKeyframes) and Keyframe easing (keyframeEasing/setKeyframeEasing), shown when keys are selected
The toolbar can add a rectangle or an ellipse (addShape). It does this by editing the sanitized source and re-sanitizing it. Deleting an element also removes its tracks and origins, including those of its descendants.
installSvgTimeline takes callbacks rather than importing the controller: read, change, selectKey, seek, time, play, playing, report, addKey, destination and editable. It keeps the following state in its closure:
-
selection: an array of{element, property, time}refs, identified bykeyframeId(JSON.stringify([element, property, time])) -
active: the primary key, which drives the inspector -
clipboard:{version:1, tracks:[…]}, with key times relative to the earliest copied key - zoom
magnification(1–32), panelheight(120 px up to 70% of the viewport) andcollapsed(48 px)
The clipboard is cleared when the source SVG changes (sourceSvg !== a.svg in render()) and on reload. It never crosses projects or tabs.
| Gesture / key (timeline focused) | Implementation |
|---|---|
| Click; Shift/Cmd/Ctrl-click toggles |
choose() → setSelection
|
| Drag empty space (marquee); a modifier adds to the selection |
content.onpointerdown → .svg-keyframe-marquee
|
| Click a property or element label | Selects the keys of that track or element |
| Drag a selected diamond |
keyDrag → createKeyframeDrag(original, selection, anchor, playhead) → moveKeyframes on release |
| Shift while dragging | Snaps the grabbed key to the playhead, unselected keys on any track, or 0/duration. The tolerance is 6 / scale ms (6 screen px at any zoom). Snapping skips targets that would collide on a moving track. With no valid target, Shift snaps to 100 ms. |
| Alt while dragging | Bypasses snapping (free) |
| ← / → (Shift: ×10) | move(±10 / ±100 ms) |
| Cmd/Ctrl+A / C / V / Shift+V / D | select all / copyKeyframes / pasteKeyframes at the playhead / pasteKeyframesToElement / duplicate (copy plus paste at the playhead; the clipboard is untouched) |
| Delete / Backspace | deleteKeyframes |
| Alt/Option+← / → |
navigate(±1) → adjacentKeyframeTime. Visits the nearest distinct key time on any track, does not wrap, pauses playback, and scrolls the playhead into view. It never changes the selection, clipboard or history. Also works on the ruler and while the context menu is open. |
| Right-click, Shift+F10, ContextMenu key |
menu() → showContextMenu with Copy, Paste, Paste to selected element, Duplicate, Reverse, Delete, Select all, Previous keyframe and Next keyframe |
| Space | Play/Pause |
| Escape | Clears the selection, or cancels an active drag without adding history |
| Double-click a property row | Adds a key at that time (addKey) |
| Ruler: drag, ←/→, Home/End | Scrub (10 ms, or 100 ms with Shift) |
Operation semantics, all from svg-animation-keyframes.js:
-
Atomic. Each operation works on a
structuredCloneand runsvalidateAnimation. If any key collides on its own track, falls outside[0, duration], or breaks a document limit, the whole operation throws and nothing changes.selectedKeysalso throws when a selection has gone stale ("The selected keyframes changed"). -
Group move clamps the delta so that the whole group stops at 0 and at
durationtogether. Keys may move into times that other selected keys are vacating. -
Retime (
retimeKeyframes(start, duration)) scales times proportionally from the earliest selected key and rounds them to whole ms. If rounding creates an overlap, the call is rejected. A selection where every key has the same time can only be shifted. -
Reverse mirrors times within one shared
[start, end]across all tracks. Every key inside that range on an affected track must be selected. Each key gets the reversed curve of the segment that now leaves it (reversedEasingswaps and inverts the control points:[1-x2, 1-y2, 1-x1, 1-y1], mapped back to a preset name when one matches). The key at the end of the range keeps its outgoing curve. -
Paste to element requires the clipboard to come from exactly one source element. It rejects
morphandmotionProgresstracks because those are geometry-specific. Values are copied literally, so positions stay offsets and scales stay multipliers. If the destination has no origin, it gets one.
sequenceDiagram
participant U as User
participant D as Export dialog (svg-animation-export.js)
participant S as animatedSvg (svg-animation-svg.js)
participant F as iframe sandbox="allow-scripts"<br/>svg-animation-preview.html
participant B as vendor/svg-animation-preview.js
U->>D: Export (show)
D->>S: animatedSvg(docWithPendingSettings, {animated})
S-->>D: SVG string (SMIL + optional <script>)
D->>F: frame.src = svg-animation-preview.html
F->>B: load bundled IIFE (script-src 'self')
B-->>D: postMessage {type:'pxl-svg-preview-ready'}
D->>B: postMessage {type:'pxl-svg-preview', svg, interaction}
B->>B: parse, strip <script>, mountSvgInteraction (trusted copy)
U->>D: Download SVG
D->>S: animatedSvg(...) again
D->>D: persist() settings if changed and editable, then download(name.svg)
animatedSvg(doc, {animated}) works as follows:
- It builds the scene, so the wrappers and bindings match the editor exactly.
- For each binding it appends one SMIL element:
-
animateMotion(withpath,rotate=0/auto/auto-reverse, andkeyPoints= progress/100) for motion tracks -
animateTransform(withtype=translate/rotate/scale) for wrapper tracks -
animate(withattributeName) for attribute tracks
-
- Every SMIL element uses
calcMode="spline",fill="freeze",dur="<duration>ms",keyTimes= time/duration, andkeySplinestaken from each key's easing except the last.exportKeyspads held keys at 0 and atdurationso that the keyTimes span 0–1. - Static export (
animated:false) emits only the first frame: the scene afterseek(0), with no animation elements and no script. - Editor-only
data-layer-nameattributes are removed. The motion guide and morph overlay never enter the scene.
On-load exports use begin="0s" and repeatCount="indefinite" when looping. They contain no script.
Hover and click exports use begin="indefinite" and repeatCount="1", and they add tabindex="0", role="button", an aria-label, and an inline <script> produced by interactionScript(settings, duration, loop). That script is the stringified source of mountSvgInteraction and interactionClock, plus a JSON options literal that holds only validated enums, numbers and booleans. The embedded runtime is a few dozen lines with no network access and no imports. Apart from a pagehide cleanup listener, it listens only on the exported <svg>. It works like this:
-
mountSvgInteractioncallsroot.pauseAnimations()and callsbeginElement()on every animation. -
interactionClockkeepstime,directionandplayingand advances them withrequestAnimationFrame. It handles looping, reverse playback and stopping at the ends. - Each frame calls
root.setCurrentTime(time/1000), so SMIL still does all interpolation. The script only controls the document clock. -
pointerenter/pointerleaveandfocusin/focusoutdrive hover. A click drives activation. Enter and Space work in both modes.
For motion tracks in interactive exports, the wrapper keeps its static transform and is marked data-pixl-motion. If scripts are disabled (for example in <img>), the file still shows the correct initial pose. The player removes that attribute when it mounts.
Preview isolation. The dialog never uses srcdoc, because that would inherit the editor's CSP and the desktop policy blocks inline scripts. Instead the iframe gets sandbox="allow-scripts" with no allow-same-origin, which gives it an opaque origin, and loads a dedicated document. The preview entry point validates the message: the source must be parent, the SVG must be a string under 10 MB, and the interaction must be valid with a duration of 60 s or less. It then removes every <script> from the SVG and mounts the trusted bundled controller in place of the embedded one. The CSP for that page is default-src 'none'; script-src 'self'; style-src 'unsafe-inline'; img-src data:. It is set in the page <meta>, in desktop/policy.cjs contentSecurityPolicy() (which adds frame-ancestors 'self'), and in server/index.mjs (which adds X-Frame-Options: SAMEORIGIN for this one path). See Desktop-App.
Building the preview bundle. scripts/build.mjs runs esbuild with entryPoints: ['web/svg-animation-preview.js'], bundle: true, format: 'iife' and target: 'es2022', and writes web/vendor/svg-animation-preview.js. It runs as part of npm run build:editor. The bundle is a classic script so that the opaque-origin sandbox can load it without module CORS. After any change to svg-animation-interactions.js or svg-animation-preview.js, rebuild. Otherwise the export preview runs the old player while downloads embed the new one.
Export settings in the dialog are kept in a pending copy. Save settings and Download SVG write them through save() (which goes through commit, so it is undoable) only when they changed and the file is editable. Cancel discards them. Read-only shared files can still preview and download with temporary settings.
-
Native file:
downloadProject()→projectFile(snapshot)produces<name>.pixl(JSON, 5 MB limit). Download .pixl copy sits in the left footer, and desktop Cmd/Ctrl+S maps to the same function. Importing a.pixlnormalizes it and creates a new local draft. Importing an.svgoffers Add (preserve tracks) or Replace (clear tracks and origins). Importing an exported animated SVG brings back only static artwork, because the editable timeline lives only in.pixl. -
Local:
LocalDraftsandLocalPersistence(shared with the main editor) store the draft inlocalStorage, and per-tab recovery lives insessionStorage.localRecoveryrenders conflict recovery in the footer. -
Cloud:
CloudSessionperforms revision-checked saves. Unsaved cloud edits are mirrored tosessionStorageunderpixlprfct.svg-cloud-recovery:<id>. If the server body changed meanwhile, the page shows a 409-style conflict and offers Save on this device (copy to a local draft) or a download. -
Shared/team files: when
record.collaborationis set,installSvgCloudEditingcreates aTeamSession. The user must Start editing (acquire the lease) before writes.session.beforeWritethrows a 423 when the file is not editable, andwriteHeadersadds the lease headers. Files in simultaneous (live) editing mode are read-only here, because SVG timelines do not take part in the engine's merge protocol. - The server stores the body as an ordinary document:
readDocumentinlib/documents.mjschecks only the genericversion,shapesandpagesfields.
sanitizeSvg(source) is a security boundary. It runs on every import, every render() and every export:
- It rejects input over 2 MB, any
<!DOCTYPE/<!ENTITY, a non-SVG root, and more than 5,000 elements. - It copies only allowlisted tags: shapes,
g,defs,use,symbol, gradients,clipPath,mask,pattern,marker,text/tspan,image, and a filter subset. It copies only allowlisted attributes and paint/style properties.safePaintrejectsjavascript:,data:,http(s):,@,expression(and comments, and it rejects everyurl()that is not a local#id. -
hrefmay only be a local#id, or a base64 PNG, JPEG or WebP data URL on<image>. Event attributes, scripts,foreignObject, existing animation and external resources are dropped. Each removal adds a user-visible warning. -
<style>rules are flattened onto the matching elements throughCSSStyleSheetbefore the stylesheet nodes are removed. Unsupported selectors and at-rules produce warnings. -
IDs are rewritten to
pxv<n>. An ID that already has that form is kept, which makes the process idempotent. All#idandurl(#id)references are remapped. The original name is kept indata-layer-namefor the Elements list. - Attributes are sorted into canonical order, so re-sanitizing unchanged input produces identical output. A read-only reopen therefore does not register as an edit.
Add a new animatable property (for example fill-opacity):
- Add an entry to
propertiesinsvg-animation-model.jswithlabel,initial,min/max, andattribute: 'fill-opacity'. Attribute properties need no other scene code:animationScenebinds them andanimatedSvgemits<animate attributeName>automatically. - Make sure the attribute is in the sanitizer allowlist (
paintorattrsinsvg-animation-svg.js). Otherwise imported values are stripped andbaseValuefalls back toinitial. - A new transform-like property needs its own wrapper in
animationSceneand ananimateTransformtype. Keep the wrapper order consistent with the editor seek code. Both use the same bindings. - Add the property to the Add animator list in
svg-animation.js(renderInspector). - Add model tests (interpolation, validation) and a browser case that compares exported SMIL values with the preview. The existing export tests sample
getCTM/getPointAtLengthat several times.
Add a timeline command: write it as a pure function in svg-animation-keyframes.js that takes (animation, selection, …) and returns {animation, selection}. Run the result through checked() and throw on any conflict. Wire it into installSvgTimeline through apply(result), which enforces editable() and produces one commit. Add a menu item in menu() with an enabled predicate. If you add a shortcut, put it in the viewport keydown handler and update the viewport.title help text.
Change the export player: edit svg-animation-interactions.js. Keep both functions free of closures over module scope, because they are stringified. Then run node scripts/build.mjs (or npm run build:editor) to refresh web/vendor/svg-animation-preview.js.
-
One scene builder. The editor preview, thumbnails (
project-preview.jscallsanimatedSvg(file, {animated:false})), the export preview and downloads all go throughanimationScene. Do not special-case the editor. -
Element IDs are the track keys. Track
elementvalues are sanitizedpxv<n>IDs. Anything that rewrites the SVG must keep IDs stable (sanitizeSvgkeeps existingpxvIDs). Choosing Replace in Import SVG clears all tracks and origins; Add preserves them and remaps incoming references. - Easing is per outgoing segment. Moving, reversing or duplicating keys must keep that relationship. The final key's easing has no effect until a key follows it.
- Duration never drops keys. Shrinking past a key is an error, and paste, duplicate and retime never extend the duration.
-
The model throws and the UI reports. Controller callbacks go through
safe()orsafely(), which turn anError.messageinto the#svg-noticetoast and re-render. - The clipboard is in memory and scoped to the tab, and it is cleared when the artwork changes.
-
Solid color tracks are 6-digit hex only. Gradient stop animation uses its own properties; adding a solid color track replaces that channel’s gradient or
nonepaint. -
The preview bundle is a build artifact checked into
web/vendor/and copied topublic/editor/vendor/. Do not hand-edit it. - The Rust engine and MCP do not understand this type. The MCP server (see MCP-Server) does not edit SVG animation documents, and live collaboration, comments and libraries are not available here.
These come from docs/SVG_ANIMATION.md and the validation limits in code:
- Limits: 2 MB of SVG source, 5,000 elements, 1,000 tracks, 200 keys per track, 60 s maximum duration, and a 5 MB
.pixlfile. - Easing control values are limited to 0–1, so overshoot, bounce and spring curves are not possible.
- Morph cannot add or remove nodes, cannot match unrelated shapes automatically, cannot select multiple nodes, and cannot convert text or groups to paths.
- Pen creates open paths that can be used as routes. A motion route is a snapshot; later path edits do not update an already assigned route.
- There are no scroll or programmatic triggers. Video export and editable animation-project import are not supported.
- Fonts are not embedded in exports. Arcs are converted to cubic curves for motion routes. Native SVG and preview path sampling use slightly different flattening tolerances; the tests accept ≤ 0.25 SVG units for curved motion and ≤ 0.03 for morph.
- Interactive exports run only when the SVG is inline or embedded with
<object>. Browsers do not run scripts in<img>or CSS backgrounds. - The cloud tests use a mocked API. No deployed multi-user server has been certified.
| Suite | What it covers |
|---|---|
tests/svg-animation.test.mjs (12 tests, node --test) |
Design-type routing and .pixl round trip, acceptance by readDocument, independent interpolation, segment and custom easing, held export endpoints, validation failures, motion-path retention, morph interpolation and serialization, interaction defaults, and interactionClock click and hover state machines |
| tests/svg-animation-keyframes.test.mjs (24 tests) | Navigation, group easing, moves, drag snapping (tolerance, ties, collisions, stale input), retiming, reversal, copy/paste, paste to element, and geometry-specific restrictions |
| tests/browser/svg-animation.spec.mjs (43 Playwright cases) | End-to-end create → import → animate → export → reopen; sanitization; local tab conflicts; cloud revision conflicts and lease headers (mocked); every timeline gesture; morph and motion-path export versus preview agreement; interactive export playback with and without scripts; read-only gates; the desktop CSP preview case; and the Pause regression |
| tests/desktop.test.mjs, tests/self-host-preview.test.mjs | The preview page's CSP and framing headers on desktop and on the self-hosted server |
Run them with:
node --test tests/svg-animation.test.mjs tests/svg-animation-keyframes.test.mjs
npx playwright test tests/browser/svg-animation.spec.mjs # builds the editor and serves on :4198- Web-Editor-Architecture: the shared modules (local drafts, cloud session, dropdowns, context menu)
-
Document-Model-and-File-Format: the
.pixlenvelope that this type reuses - Prototyping-Behaviors-and-Controls: the main editor's Motion mode, which is a different feature
-
Import-Design-Files: SVG import into the design engine (
svg-import.js), which is a separate path fromsanitizeSvg - Desktop-App: the preview CSP and the packaged protocol
- Teams-Libraries-and-Collaboration: editing leases
- Testing-and-Verification, Build-System
- Code:
web/svg-animation*.js,web/svg-animation*.html,web/svg-animation.css,scripts/build.mjs(preview bundle),desktop/policy.cjsandserver/index.mjs(preview headers),web/project-navigation.js(routing) - Docs: docs/SVG_ANIMATION.md. It is a dated, changelog-style user guide that maps each feature to PR #37–#49 and alpha.15–alpha.21, records verification, and lists reference screenshots under
.local/svg-animation/.
Start
Core
- Rust Document Engine
- Document Model & File Format
- Web Editor Architecture
- Rendering & Export
- Build System
Editor features
- Canvas Tools & Editing
- Layout, Auto Layout & Grid
- Components, Variants & Slots
- Styles, Variables & Paints
- Prototyping, Behaviors & Controls
- Import: Design Files & SVG
- SVG Animator
- Panel Workspace — tear-outs, icons, side flyouts and saved layouts
- Icon Library
Platforms
- Hosting Modes
- Self-Hosted Server
- Cloud API & Database
- Teams, Libraries & Collaboration
- Desktop App
- MCP Server
Practice
{ "version": 2, "design_type": "svg-animation", "name": "Untitled animation", "shapes": [], "pages": [{ "id": 1, "name": "Animation" }], "active_page": 1, "svg_animation": { "version": 1, "svg": "<svg …/>", // sanitized source artwork (≤ 2,000,000 chars) "duration": 3000, // integer ms, 1–60000 "loop": true, "tracks": [ // ≤ 1000; one per (element, property) { "element": "pxv3", "property": "rotation", "keys": [ { "time": 0, "value": 0, "easing": "linear" }, { "time": 3000, "value": 360, "easing": [0.42,0,0.58,1] } ], "motion": { "d": "M…", "name": "Orbit", "rotate": "none" } // motionProgress only } ], "origins": { "pxv3": [256, 256] }, // transform origin per element, local units "interaction": { "trigger": "load", "onLeave": "reverse", "onClick": "restart" } // optional } }