Brushes: brush.freehand is one undo step and refuses strokeless paths and unknown keys

brush.freehand drew the path with one edit and set the brush with a
second, so one Undo left the path without its brush. The brush is now
set in the same edit that draws, continues or redraws the path, and the
step is named Paintbrush whatever the style.

A brush for a path with no stroke (a continued or redrawn path without
one, or a new filled "pencil" path while the stroke is None) was skipped
and the call still succeeded. It is now refused with "cannot apply brush
`<name>`: path has no stroke" before anything changes. The Paintbrush
tool sends brush.freehand when a brush is current, so continuing or
redrawing such a path with it now shows this error. This rule is
VectorCraft's own.

brush.freehand is no longer in UNCHECKED: it takes the path.freehand
keys and `brush`, and any other key is refused with "unknown parameter".
This commit is contained in:
dotCooCoo
2026-11-14 17:31:16 -08:00
parent 895e9493d2
commit ba9acf808e
8 changed files with 186 additions and 26 deletions
+5 -2
View File
@@ -3238,8 +3238,11 @@ already walks Image Trace. Short agent entry points:
`brush.duplicate {name, newName?} | {names}`, `brush.freehand {…path.freehand params, brush?}`,
`object.expandBrush {ids?}`. `brush.freehand` draws the plain path when `brush` is left out or null. It refuses a
`brush` that is not a string with "`brush` must be a string", a name that no brush in the document has (an empty
name included) with "no brush named `<name>`", and a `style` other than "pencil" or "brush"; the document does not
change and no undo step is recorded. The Paintbrush skips a tool brush or current brush that has been deleted and
name included) with "no brush named `<name>`", a `style` other than "pencil" or "brush", a `brush` for a path
with no stroke (a continued or redrawn path without one, or a new filled "pencil" path while the stroke is None)
with "cannot apply brush `<name>`: path has no stroke", and a key that neither `path.freehand` nor `brush` names
with "unknown parameter"; the document does not change and no undo step is recorded. A stroke drawn with a brush
is one undo step: Undo removes the path and its brush together. The Paintbrush skips a tool brush or current brush that has been deleted and
paints with the other, or draws the plain path when neither is in the document. A document or brush
library file whose brushes repeat a name is read with the first brush of that name as stored and each later one
numbered with the first "`<name>` 2", "`<name>` 3"… the file does not have; strokes of the name keep the first
+1
View File
@@ -1200,6 +1200,7 @@ Moved from the ROADMAP's "Shipped so far" on 2026-10-10. Update it when a featur
The Pencil's and the Paintbrush's Fidelity is in screen pixels, the same at any zoom: their Tool Options give it in px, from 0.01 px on the logarithmic slider to 20 px and up to 100 px in the field, and the tool sends `path.freehand` the value in points at the current zoom (#5729). The Smooth tool's and the Blob Brush's Fidelity stays in points.
`path.freehand` and `brush.freehand` take a Fidelity of up to 100 / 0.0313 pt (about 3194.89 pt), the 100 px field maximum at the lowest zoom (3.13 %), and reject a value outside their range with an error, so a Pencil or Paintbrush stroke drawn zoomed out keeps the Fidelity set in pixels (engine tests `pencil_fit_keeps_its_anchors_on_a_stroke_drawn_zoomed_out` and `pencil_takes_fidelity_within_its_range_and_rejects_the_rest`).
`brush.freehand` refuses a `brush` that names no brush in the document, or is not a string, and a `style` other than "pencil" or "brush", with an error and no change or undo step, instead of drawing the plain path; the Paintbrush skips a chosen brush that has since been deleted (engine tests `brush_freehand_refuses_a_brush_or_style_it_cannot_use` and `paintbrush_tool_skips_a_deleted_brush`).
A `brush.freehand` stroke and its brush are one undo step, so one Undo removes both. A `brush` for a path with no stroke (a continued or redrawn path without one, or a new filled "pencil" path while the stroke is None) is refused with "cannot apply brush `<name>`: path has no stroke", and a key the command does not take with "unknown parameter", with no change or undo step; the no-stroke refusal is VectorCraft's own rule (engine tests `brush_freehand_direct_call_has_one_undo_step`, `brush_freehand_refuses_a_brush_on_a_path_without_a_stroke` and `brush_freehand_refuses_unknown_keys`).
Each drag of the Smooth tool smooths the stretch of a selected path in its reach along its length before refitting it within Fidelity, so a wobble wider than Fidelity is smoothed out and another drag over the same place smooths it further, as [the help page](https://helpx.adobe.com/illustrator/using/tool-techniques/smooth-tool.html) describes (`path.smoothRegion`). The smoothing spread (a third of the reach) and the rule that each refit stays within twice the distance the smoothing moved the path, so repeated drags do not drift from it, are VectorCraft's own. A drag over the whole of a closed path smooths it across its first anchor too, so a bump there is smoothed like any other and no corner is left; Object › Path › Smooth smooths a closed path across its first anchor the same way.
When a Smooth tool drag reaches the first anchor of a closed path, the smoothed path starts at its point nearest where that anchor was: at an anchor there, or at a new anchor split into the curve without changing its outline. Dashes and type on the path start from that point. A drag that does not reach the first anchor leaves it first. This is VectorCraft's own rule (engine tests `smoothing_over_a_closed_paths_first_anchor_keeps_its_start` and `smoothing_a_whole_closed_path_with_a_spike_keeps_its_start`).
The Smooth tool shows the Not Allowed cursor while no path is selected that it can act on (an editable path, not a guide, with three or more anchors on one of its subpaths or two anchors joined by a curve), and the release of a drag then sends no command and changes nothing; [the help page](https://helpx.adobe.com/illustrator/using/tool-techniques/smooth-tool.html) has the path selected first. A selected path anywhere on the canvas gives the Smooth cursor wherever the pointer is. The Pencil with Alt key toggles to Smooth Tool on and the Blob Brush show Not Allowed the same way when Alt gives them the Smooth tool; the Paintbrush keeps its closing cursor, since its release with Alt closes the stroke. Use Precise Cursors leaves Not Allowed as it is. This cursor rule is VectorCraft's own (tools `smooth_shows_not_allowed_without_a_selected_path_to_smooth`, `borrowed_smooth_shows_not_allowed_without_a_selected_path_to_smooth`, `smoothing_release_sends_nothing_without_a_selected_path_to_smooth`; engine `use_precise_cursors_keeps_the_smooth_tools_not_allowed_pointer`).