| name | clash-timeline |
| description | Open, inspect, create, and edit Clash Project Timelines through the bundled Timeline GUI and typed MCP tools. |
Clash Timeline
Use the bundled clash_timeline_* tools whenever the user asks to open, inspect,
create, attach, detach, copy, or edit a Clash Timeline.
Workspace scope
Always pass the current task workspace's absolute cwd to Timeline tools. The
workspace should contain .clash/project.toml; the plugin process itself runs
from its installed package directory and must not be treated as the project.
GUI workflow
- Call
clash_timeline_open with the workspace cwd and an optional
timelineId.
- Let the embedded GUI read and edit the returned Timeline state.
- Save GUI edits through
clash_timeline_save. This performs a Timeline read,
writes the normal timelines/<id>.timeline.yaml projection, validates it,
and applies it through the real Clash CLI contract.
Tool workflow
- Call
clash_timeline_schema once with view: "authoring" before authoring
unfamiliar Timeline fields. This compact default projects the authored subset
of every root, track, common
item, and type-specific item field, plus stable semantic
rule IDs, reference semantics, and an executable basic example.
Request view: "full" only when a machine consumer or advanced field needs
the complete JSON Schema and operation catalog. Do not guess field names from
UI labels.
- Treat
assetId and sourceNodeId as downstream references. An upstream
Stage capture follows Stage revision → capture receipt → immutable Project
Asset → downstream Timeline assetId; it never writes the output into the
producer Stage or Action state. A Remotion item similarly references its
Canvas-owned component through sourceNodeId instead of copying its source.
- Every
clash_timeline_create and clash_timeline_save automatically runs
the authoritative JSON Schema and cross-field semantic rules before it can
mutate product state. Invalid submissions return stable rule IDs and leave
product state unchanged.
- When the next intended step is create or save, submit directly—do not call
clash_timeline_validate as a preflight. After a rejected write, fix the
draft and retry that same write.
- Reserve
clash_timeline_validate for diagnostic-only workflows where no
create or save write is intended. Preserve returned rule IDs when repairing
a draft that is not yet being submitted.
- Use
clash_timeline_list or clash_timeline_get before describing current
state. Never infer tracks or revisions from Canvas nodes.
- When calling
clash_timeline_save, pass the revisionId returned by
clash_timeline_get as baseRevisionId. A stale full-state save must be
rejected and rebased, never silently retried over newer work.
- Use
clash_timeline_create with canonical id, name, and optional complete
state for a standalone Project Timeline.
- Use
clash_timeline_attach, clash_timeline_detach, and
clash_timeline_copy only when the user requests an ownership change. For
attach use actionNodeId; for copy use sourceTimelineId, targetCanvasId,
and optional newActionNodeId, exactly as published by the tool schema.
- Treat failed saves as real validation or stale-read failures. Read the
Timeline again, preserve the user's draft, and resolve the conflict instead
of bypassing it.
- Consume the track categories and ordering published by
clash_timeline_schema (effect, text, visual, primary, audio) rather
than maintaining a local list. Do not introduce Main Storyline or
Set as main wording.
Mask DSL
The implementation-side capability annotations define all required mask fields:
shape, position, size, rotation, feather, inverted. The generated animated channels are maskPosition, maskSize, maskRotation, maskFeather.
Coordinates use percent-of-rendered-item-bounds; frames are
item-local in 0..durationInFrames-1;
and interpolation is hold or linear.
The complete editor default is {"shape":"rectangle","position":[50,50],"size":[70,70],"rotation":0,"feather":0,"inverted":false}.
Use clash_timeline_schema with view: "authoring" for compact field
descriptions, runtime semantics, reference bindings, and an executable YAML
example; request view: "full" only for the complete JSON Schema. Create/save
validates edits automatically; use the explicit validator only for diagnosis
when no write is intended. Remove a mask by
removing both item.mask and every generated mask channel.
Do not use Canvas MCP tools as a fallback for Timeline operations. The Timeline
plugin owns this interface; Canvas remains a separate work surface.
