Add toolchains, cropping/padding, SVG framing, and expanded test coverage

[ea42gh]

Summary

• Adds multi-toolchain rendering with explicit toolchain definitions and resolver.
• Adds cropping + padding support (tight/page/none crop policies, post-render SVG padding).
• Adds canvas frame support (frame=...) for boxed output.
• Improves render artifacts/diagnostics and temp retention behavior.
• Adds SVG normalization utilities for consistent post-processing.
• Updates docs and adds an enhancements notebook.
• Expands test suite (golden SVGs, post-processing, toolchains, padding/crop, artifacts).

Key changes

• New core modules: toolchains.py, crop.py, svg_box.py, canvas_frame.py, svg_normalize.py
• executor.py updated for toolchain selection, crop/pad, artifacts, frame injection
• Extensive new tests and golden SVG checks
• Documentation updates

API additions

• render_svg(..., crop=..., padding=..., frame=..., exact_bbox=...)
• Toolchain selection by name
• Render artifacts object (paths + stdout/stderr)

Tests
python -m pytest -q tests

[ea42gh]

I fixed the problems uncovered by Codepilot and enhanced the code some more:

Implemented a full hardening/refactor pass focused on correctness/security, API/UX clarity, CI rigor, and docs consistency.

Core behavior/API updates

• Added explicit toolchain diagnostics flow:
  • %tikz --diagnose
  • JSON diagnostics via --json (preferred short flag -j, legacy -json still accepted)
• Enforced --json usage contract:
  • %tikz --json alone is now rejected
  • must be combined with --diagnose
• Added typed public validation errors:
  • JupyterTikzError
  • InvalidToolchainError
  • InvalidOutputStemError
  • InvalidPathError
• Exported typed errors from package root for clean API usage.
• Hardened executor path:
  • render_svg_with_artifacts(...) now validates output_stem (same safety rules as render_svg(...)).
• Improved magic error handling:
  • invalid --keep-temp / --save-* paths are now reported cleanly (no traceback leaks).

Backward-compat/migration clarifications (vs main)

• artifacts_path is directory-only; prefix behavior moved to artifacts_prefix.
• %tikz --json now requires --diagnose.
• stricter output-path validation rejects relative .. segments for user-provided write targets.
• default magic routing for -tp=pdflatex / -tp=xelatex goes through executor/toolchain path.

Refactor

• Consolidated duplicated save-destination logic into shared helper:
  • jupyter_tikz/save_paths.py
  • used by both magic.py and legacy_render.py.

Tests

• Added diagnostics JSON contract tests.
• Added %tikz? help snapshot test to prevent arg/docs drift.
• Added save-path helper tests.
• Added regression tests for invalid save path handling in magic.
• Final local run: full suite passing (383 passed, 1 skipped).

CI

• Added cross-platform validation job (Linux + Windows) for argument/validation/diagnostics coverage.
• Added lint-type CI job:
  • ruff (core subset)
  • mypy (core subset)

Docs / notebooks

• Added concise Option precedence table to README and docs index.
• Added Migration cookbook (main -> current) with common upgrade patterns.
• Updated docs to explicitly describe %tikz --json contract.
• Updated Enhancements.ipynb with diagnostics examples (-dg, -j, legacy -json) and invalid-path expected-
  error snippet.
• Added local quality command workflow docs:
  • make fmt, make lint, make type, make test, make ci-local.