Refine Canvas Strokes
Refine Canvas Strokes is an open Agent Skill and Codex plugin for designing, validating, and integrating safe refinement of editable 2D canvas strokes.
It helps whiteboards, note apps, drawing tools, annotation systems, and pen-input SDKs improve freehand strokes, grouped handwriting, geometric shapes, and constrained diagrams without treating a rendered bitmap as editable source data.
What It Provides
- Dependency-free validation for canonical stroke inputs and refinement patches.
- Conservative local smoothing for editable freehand strokes.
- Automatic and optional font-guided handwriting layout normalization.
- Before-and-after geometry comparison with endpoint, displacement, bounds, and metadata checks.
- Contracts for same-ID replacement, split and merge mapping, preview, undo, rollback, and stale-revision handling.
- Integration guidance for user-selected Text, Shape, Flow, and Automatic actions.
The bundled scripts execute cleanup, handwriting normalization, validation, metrics, and comparison. Primitive fitting beyond the baseline, semantic flow reconstruction, OCR, and raster generation require a host implementation or optional external engine.
Install
Codex Plugin Marketplace
Add this GitHub repository as a Codex marketplace:
codex plugin marketplace add machaomc/refine-canvas-strokes
Start Codex, enter /plugins, select the refine-canvas-strokes-marketplace source, and install Refine Canvas Strokes. Start a new session after installation.
Agent Skills CLI
Install only the portable skill with the cross-agent skills CLI:
npx skills add https://github.com/machaomc/refine-canvas-strokes/tree/main/plugins/refine-canvas-strokes/skills/refine-canvas-strokes
Repository Scope
Copy or link the skill directory into a supported project location such as .agents/skills/refine-canvas-strokes:
plugins/refine-canvas-strokes/skills/refine-canvas-strokes/
Quick Verification
From the repository root:
python3 scripts/check_release.py
python3 scripts/build_release.py
Run a bundled example directly:
cd plugins/refine-canvas-strokes/skills/refine-canvas-strokes
python3 scripts/refine_strokes.py references/example-input.json --output /tmp/refinement-patch.json
python3 scripts/validate_contract.py patch /tmp/refinement-patch.json --input references/example-input.json
python3 scripts/compare_stroke_patch.py references/example-input.json /tmp/refinement-patch.json --fail-on-violation
Python 3.10 or later is required. Core scripts use only the Python standard library. extract_font_profile.py optionally requires FontTools.
Examples
| Automatic handwriting | Shape fitting guidance |
|---|---|
 |  |
Editable source SVGs and additional comparison images are included under the skill's assets/examples/ directory. The handwriting and font examples use synthetic input and a synthetic font profile.
Safety Model
- Source strokes remain recoverable until acceptance.
- Whole-document processing requires explicit scope.
- Explicit Text, Shape, or Flow actions override top-level automatic classification.
- Same-topology refinement preserves stroke identity.
- Split, merge, deletion, and conversion require source-to-result mapping.
- A patch declares transaction requirements; the host must prove preview isolation, rollback, history, persistence, and cache behavior.
- Bundled scripts do not send stroke, handwriting, or font data over the network.
Read Privacy, Security, and Terms before production integration.
Repository Layout
.agents/plugins/marketplace.json Codex repository marketplace
plugins/refine-canvas-strokes/.codex-plugin/ Codex plugin manifest
plugins/refine-canvas-strokes/skills/ Portable Agent Skill
review/ Public submission materials
scripts/ Release validation and packaging
docs/ Privacy, support, terms, publishing
Development
See CONTRIBUTING.md and CODE_OF_CONDUCT.md. All changes must preserve dependency-free core tests and pass the release validator. The release process and Codex submission checklist are documented in docs/PUBLISHING.md.