beutl-agent-source-grounding

Beutl Agent Source Grounding

Use this skill as a source-code check layer for Beutl Agent Editing Toolkit work. MCP schemas describe the serializable document shape; they do not fully define runtime semantics such as alignment, transform order, coordinate origin, measured bounds, render scale, or effect units.

Workflow

1. Name the behavior assumption before editing, for example centered TextBlock TranslateTransform coordinates.
2. Search narrowly with rg for the relevant runtime type, test helper, or toolkit analyzer.
3. Read the implementation and at least one nearby test, analyzer, or schema example when available.
4. Record a sourceGrounding note before the relevant apply_edit:
   • assumption: the behavior being relied on.
   • evidence: source/test paths and symbols read.
   • rule: the editing rule derived from the evidence.
   • uncertainty: anything still unverified.
5. Author the smallest MCP patch that applies the rule.
6. When measuring layout-sensitive objects, call measure_object_bounds before or after the patch to inspect render-node size, transform translation, scene-space bounds, center, and padding.
7. Verify with read_document_summary, representative render_still, and the relevant evaluator before export.

If the user explicitly forbids source-code reading, do not use this skill. Record that source grounding was skipped and keep the MCP edit conservative.

Source Map

Placement Rule For Text And Shapes

The current source model for normal Drawable placement is center-aligned by default:

• Drawable.AlignmentX and Drawable.AlignmentY default to Center.
• Drawable.TransformOrigin defaults to RelativePoint.Center.
• Drawable.CalculateTranslate places local drawable bounds at canvasSize / 2 - bounds / 2 for center alignment.
• A pure TranslateTransform(x, y) then acts as an offset from that alignment-resolved position.
• The toolkit quality analyzer models this as object center = scene.FrameSize / 2 + translate.

Practical MCP authoring rule:

• To center a TextBlock, RectShape, RoundedRectShape, or EllipseShape in a default 1920x1080 scene, keep AlignmentX=Center, AlignmentY=Center, and use TranslateTransform(0, 0).
• To place a default-aligned object by desired center coordinate (cx, cy), use X = cx - frameWidth / 2 and Y = cy - frameHeight / 2.
• To place by desired top-left coordinate (left, top), first estimate or know the object size (w, h), then use X = left + w / 2 - frameWidth / 2 and Y = top + h / 2 - frameHeight / 2.
• Do not use TranslateTransform(frameWidth / 2, frameHeight / 2) to center an object; that moves the object's center to the lower-right frame corner.
• If true top-left anchoring is intended, set AlignmentX=Left and AlignmentY=Top deliberately, then verify the transform and backing plates with rendered stills.

Use the same coordinate rule for a text/backing-plate pair: share the same intended center offset, size the plate around the text, then call measure_object_bounds to confirm both objects have the intended render-node center and padding before rendering.

Verified Runtime Behaviors And The Stale-Editor Caveat

Suspect a stale running editor before turning a rendered anomaly into a rule. When a LiveEditor MCP edit renders wrong, the running app may lag repo HEAD. A whole class of apparent toolkit "gotchas" was traced to a stale build, not current code — for example:

• UseGlobalClock=false keyframes on a non-zero-Start element rendering the final value / invisible: fixed at commit 21db38d08 (KeyFrameAnimation{T}.GetAnimatedValue now resolves the logical parent at evaluation time). Do not adopt "always use UseGlobalClock=true + absolute KeyTimes" as a rule; local KeyTimes are correct in current code.
• TransformGroup appearing to drop a Scale for [Scale, Translate] order: TransformGroup.CreateMatrix composes both orders correctly.
• TransformEffect(ApplyToTarget=false) before LayerEffect producing blur/mosaic when scaling a group up: TransformEffect.ApplyTo uses context.Transform(...) (resolution-independent) for ApplyToTarget=false, and LayerEffect.ApplyTo bakes the CTM scale from the target density in ctx.Open — so scaling before the LayerEffect is the intended crisp path.

Before authoring a workaround for an animation/transform/effect anomaly, rebuild the editor and confirm against KeyFrameAnimation{T}.GetAnimatedValue, TransformGroup.CreateMatrix, TransformEffect.ApplyTo, and LayerEffect.ApplyTo.

Genuine current-code behaviors (source-verified):

• GeometryShape is not normalized to its geometry origin. Shape.OnDraw leaves //-shapeBounds.Position commented out, so the drawn center lands at the alignment-resolved center PLUS geometry.Bounds.Position (verified by GeometryShapePlacementTests). A path authored from (0,0) to (w,h) (bounds origin (0,0)) centers correctly; a path centered on (0,0) has bounds origin (-w/2,-h/2) and renders up-left by half its size — this is the classic "GeometryShape appears toward the top-left" failure; scene-absolute coordinates shift by their full offset. RectShape/EllipseShape are unaffected. Rule: author GeometryShape paths with the artwork's top-left at (0,0) (all coordinates non-negative). If coordinates cannot be normalized, add a static TranslateTransform(-geometry.Bounds.X, -geometry.Bounds.Y); measure_object_bounds reports geometryBoundsOrigin plus the exact compensation, and preview_quality_risks raises a geometryPathOffset advisory for uncompensated offsets. For a multi-part vector mark (e.g. a two-color logo), build all parts in one shared (0,0)-top-left coordinate frame and verify the composite center with measure_object_bounds.
• Closed Pen-only GeometryShape paths are valid. A closed PathFigure with Fill=null and a visible Pen still renders its stroke in current code when the path has non-zero bounds. If the result is empty, inspect the path points/segments, pen brush, pen thickness, and rendered bounds before assuming an engine defect.
• TransformGroup + ScaleTransform + TransformOrigin works on GeometryShape, but scale units are percentages. ScaleTransform.Scale, ScaleX, and ScaleY use 100 for 1x; values such as 1.0 or 0.6 mean 1% or 0.6%, which can make a shape effectively invisible. Use 60 for 0.6x and 106 for 1.06x, then verify with render_still or measure_object_bounds.
• measure_object_bounds measures only direct Element.Objects. A Drawable nested inside a DrawableGroup cannot be measured ("unsupported improvement area"). Measure the group as a whole, or temporarily lift the child into its own Element to measure it.
• LayerEffect on a DrawableGroup flattens the children into one layer before the group's Opacity applies — use it when overlapping children would otherwise show the back child through the front during a group-opacity fade.

Source Inspector Output

When delegating the source check to a subagent, ask for this compact format:

ASSUMPTION: ...
EVIDENCE:
- path:line symbol - observed behavior
RULE: ...
PATCH IMPLICATION: ...
VERIFY WITH: ...
UNCERTAINTY: ...

The inspector should not edit files or call Live MCP tools. It should return source-grounded rules that the timeline or look agent can use in the next MCP patch.