cutecanvas 1.0.0__tar.gz

cutecanvas-1.0.0/AGENTS.md

@@ -0,0 +1,111 @@
+# CuteCanvas Package Guidance
+
+The root `AGENTS.md` applies. This file defines CuteCanvas's local ownership and
+proof requirements.
+
+## Product identity
+
+CuteCanvas is a performant embeddable PySide6 graphics editor. Its public
+facade makes document, layer, and tool workflows coherent without concentrating
+behavior in one widget or service graph.
+
+## Ownership
+
+CuteCanvas owns:
+
+- independent document identity, canvas, metadata, persistence, and export;
+- ordered editable layer instances, resource identity, sharing, and lifetimes;
+- host capability policy, durable user locks, and one operation resolver;
+- unified chronological undo/redo and atomic edit transactions;
+- editable raster and coverage storage, masks, selections, and painting;
+- placed- and smart-asset provenance, conversion, rasterization, and publication
+  workflows;
+- vector revision authoring around immutable semantic vector values;
+- authored-effect resources, source/graph persistence, model interaction,
+  package trust and resolution, generated controls, preview admission,
+  diagnostics, and undoable effect revisions;
+- layer and pixel movement, floating edits, free transforms, authoring tools,
+  options, overlays, and transient feedback; and
+- autosave, failure recovery, and SAM integration.
+
+## Internal ownership boundaries
+
+Tools translate input into commands and UI objects present state. Neither owns
+durable document, selection, geometry, pixel, history, permission, or rendering
+state. Every durable edit uses the document's single history. Host policy and
+user locks remain separate inputs to the one operation resolver.
+
+`SnapConfiguration` owns durable policy, guides, and grid settings.
+`SnapCandidateProvider` captures stationary scene targets once per gesture.
+Movement and geometric authoring use separate session resolvers.
+`SnapGuideFeedback` owns transient guide presentation. `SnappingSubsystem`
+constructs these collaborators at the editor lifecycle boundary. Shape and path
+tools own their gesture lifecycle and delegate coordinates through their
+authoring port; freehand tools, painting, fills, and intelligent selection do
+not receive that port.
+
+Retained pixel-selection and mask shapes delegate canvas clipping and preview
+projection to `CoverageCanvasAperture`. `ActiveMaskCanvasAperture` owns
+mask-specific aperture geometry. Tools do not reproduce either concern.
+
+`SceneLayerSelectionController` owns an ordered selection with the active member
+last. `SceneLayerMoveController` owns translation-only layer-set sessions.
+`SceneLayerTransformController` owns single-layer affine transforms.
+`SceneLayerMappingPreview` presents affine, projective, piecewise, or bilinear
+workflows as one coherent transient set. `LayerMappingMutationOwner` commits exact mapping sets
+through one layer-store publication and one history edit.
+
+Axis snapping retains its optimized scalar path. Oriented snapping uses exact
+finite manipulation edges, a frozen spatial index, deterministic ranking, and
+device-pixel thresholds. Shared-edge resize infers one current seam between
+exactly two eligible layers. Midpoint drags derive both affine previews from one
+scalar. A common-corner endpoint pivots only along the continuous rail shared by
+both participants and derives paired piecewise previews from immutable bases.
+Both operations commit or cancel atomically. Alpha contours never define the
+seam, and interaction never resamples or bakes layer pixels.
+
+## Facade and public surface
+
+The editor facade is the obvious starting point for integration. Common document,
+layer, and tool workflows require no construction of internal controllers or
+knowledge of storage, rendering, history, or scheduling internals. Expose typed
+document and layer handles with focused document, layer, tool, selection,
+history, and export subfacades. Avoid routine raw identifier pairs, private
+collaborator access, service locators, and a god widget. Programmer errors fail
+clearly; unavailable operations return stable reasons and available alternatives.
+
+`src/cutecanvas/cutecanvas.pyi` is CuteCanvas's authoritative typed contract.
+Public changes update it, the implementation, CuteCanvas documentation, and
+`packages/cutecanvas/examples/cutecanvas_demo.py` together. The demo is a coherent layered editor
+with an intentional canvas, tools and options, layer tree, selections,
+transforms, painting, masks, raster/vector/placed layers, undo/redo, and
+persistence rather than a collection of test panels.
+
+## Test organization and proof
+
+Organize CuteCanvas tests by the behavior owners for facade and public contracts,
+documents and resources, history and transactions, layers and groups, selections
+and masks, raster and vector authoring, painting, movement and transforms, tools
+and policy, authored effects, persistence and recovery, mounted editor workflows,
+and packaging.
+
+`packages/cutecanvas/TEST_POLICY.toml` maps every CuteCanvas production area and
+public boundary to its required test areas. Changes to durable state, mutation,
+history, policy, authoring, persistence, recovery, facade, or workflow contracts
+update that map in the same work.
+
+Every durable mutation proves success, rejection atomicity, chronological undo,
+redo, and restored observable state. Persistence proof covers canonical round
+trips, unavailable resources, interrupted writes, recovery, and preservation of
+valid prior state. Authored-effect proof covers source and graph coordination,
+package and capability admission, generated controls, diagnostics, preview,
+transactional patches, undo, and retention of unavailable operations.
+
+Mounted workflow proof uses real editor widgets for input routing, tool
+lifecycle, overlays, repaint, focus, publication, and teardown. Abuse proof
+covers rapid document switching, edit/undo chains, input storms, stale work,
+source removal, cache pressure, large and sparse content, persistence failure,
+and redraw equality. Performance proof covers interactive latency, bounded
+memory, invalidation scope, painting, transforms, history, and large-document
+workflows. Packaging proof installs the product with only declared dependencies
+and exercises its supported facade.

cutecanvas-1.0.0/ARCHITECTURE_DEBT.toml

@@ -0,0 +1,136 @@
+schema_version = 1
+product = "cutecanvas"
+
+[[debts]]
+id = "CUTECANVAS-ARCH-001"
+owner = "CuteCanvas raster facade"
+paths = ["packages/cutecanvas/src/cutecanvas/facade/raster_api.py"]
+fingerprint = "sha256:f8230c1164a23b016b27956be3dc1b2a1def96665e5a2fdaa39d57206ab5f346"
+issue = "chore:CUTECANVAS-ARCH-001"
+review_by = 2026-12-15
+responsibilities = [
+  "editable raster layer and extent APIs",
+  "painting, brush, clone, and fill APIs",
+  "floating pixel and scene edit history APIs",
+]
+next_extraction = "Extract brush, clone, fill, color, and paint-target workflows into a focused painting facade mixin."
+
+[[debts]]
+id = "CUTECANVAS-ARCH-002"
+owner = "CuteCanvas mask editing"
+paths = ["packages/cutecanvas/src/cutecanvas/masks/edit_service.py"]
+fingerprint = "sha256:da5588d3eeba1e38f5ee917dcd82632f4e1d2c97376b82272d7964dd2c44eef9"
+issue = "chore:CUTECANVAS-ARCH-002"
+review_by = 2026-12-15
+responsibilities = [
+  "mask epoch and cancellation state",
+  "stroke preparation and patch commit",
+  "history presentation, undo, and redo coordination",
+  "coverage, image, and surface application",
+]
+next_extraction = "Move direct stroke sessions, coverage application, and rasterization behind focused mutation owners and leave this service coordinating their transactions."
+
+[[debts]]
+id = "CUTECANVAS-ARCH-003"
+owner = "CuteCanvas mask integration"
+paths = ["packages/cutecanvas/src/cutecanvas/masks/mask_service.py"]
+fingerprint = "sha256:89b5477ed2610b64d78739904e9dc7e83c856476e3f2031e263edcd81c81ef29"
+issue = "chore:CUTECANVAS-ARCH-003"
+review_by = 2026-12-15
+responsibilities = [
+  "asset, layer, activation, and edit workflow facade delegation",
+  "render cache, prefetch, and invalidation routing",
+  "generated-mask application and projection delegation",
+  "autosave, configuration, file workflow, and diagnostics delegation",
+]
+next_extraction = "Extract render scheduling, invalidation, prefetch, and generated-mask delegation into a focused mask presentation service."
+
+[[debts]]
+id = "CUTECANVAS-ARCH-004"
+owner = "CuteCanvas mask presentation cache"
+paths = ["packages/cutecanvas/src/cutecanvas/masks/render_cache.py"]
+fingerprint = "sha256:e3ab8ec629287eaf9797d81c3eefbea67fe714d7cb0c149fa0d0ed334635178d"
+issue = "chore:CUTECANVAS-ARCH-004"
+review_by = 2026-12-15
+responsibilities = [
+  "render product cache admission and eviction",
+  "live-preview raster, patch, and geometry presentation",
+  "asynchronous prefetch and native product adoption",
+  "regional and history-driven presentation metrics",
+]
+next_extraction = "Extract live-preview raster storage, stride policy, composition, invalidation, and settlement into a dedicated live-preview cache owner."
+
+[[debts]]
+id = "CUTECANVAS-ARCH-005"
+owner = "CuteCanvas mask render work"
+paths = ["packages/cutecanvas/src/cutecanvas/masks/render_coordination.py"]
+fingerprint = "sha256:8a461e96b04c0fc502226bf23f4ae22bf4896f0c1104c960750e036374af8b85"
+issue = "chore:CUTECANVAS-ARCH-005"
+review_by = 2026-12-15
+responsibilities = [
+  "overlay prefetch scheduling",
+  "regional snippet work",
+  "asynchronous colorization requests",
+  "deferred publication and diagnostics",
+]
+next_extraction = "Extract scale resolution, prefetch request batching, cancellation, completion adoption, and prefetch statistics into a prefetch coordinator."
+
+[[debts]]
+id = "CUTECANVAS-ARCH-006"
+owner = "CuteCanvas mask workflow"
+paths = ["packages/cutecanvas/src/cutecanvas/masks/workflow.py"]
+fingerprint = "sha256:1c11fa324d437b87be85a5eb5b774ebce108bc46430407a158e7a0a680406840"
+issue = "chore:CUTECANVAS-ARCH-006"
+review_by = 2026-12-15
+responsibilities = [
+  "mask facade and feature lifecycle",
+  "undo and edit API delegation",
+  "SAM workflow integration",
+  "activation, configuration, and diagnostics assembly",
+]
+next_extraction = "Move SAM manager attachment, predictor reset, generated-mask application, and availability delegation into a SAM-owned workflow module."
+
+[[debts]]
+id = "CUTECANVAS-ARCH-007"
+owner = "CuteCanvas persistence"
+paths = ["packages/cutecanvas/src/cutecanvas/persistence/codec.py"]
+fingerprint = "sha256:80f99c91bd78f57007de9e2161863c8c7fa3273ce12d680cf47e51b48f202fe7"
+issue = "chore:CUTECANVAS-ARCH-007"
+review_by = 2026-12-15
+responsibilities = [
+  "archive container IO and version dispatch",
+  "composition document table and root assembly",
+  "raster, coverage, placed, mask, and vector resource codecs",
+  "resource reference and archive graph validation",
+]
+next_extraction = "Extract placed and raster resource encoders and decoders behind typed resource codec owners."
+
+[[debts]]
+id = "CUTECANVAS-ARCH-008"
+owner = "CuteCanvas document events"
+paths = ["packages/cutecanvas/src/cutecanvas/runtime/document_events.py"]
+fingerprint = "sha256:fe4f93aee803d1e9ded7c9bfeb767c912e4a96afde3251cb492f4ad1bc4c948d"
+issue = "chore:CUTECANVAS-ARCH-008"
+review_by = 2026-12-15
+responsibilities = [
+  "composition and scene publication",
+  "resource completion and pixel-content change handling",
+  "selection, paint-target, and vector synchronization",
+  "viewport and diagnostics propagation",
+]
+next_extraction = "Extract vector selection, node selection, text edit, option, and content publication into a vector document-event owner."
+
+[[debts]]
+id = "CUTECANVAS-ARCH-009"
+owner = "CuteCanvas runtime lifecycle"
+paths = ["packages/cutecanvas/src/cutecanvas/runtime/lifecycle.py"]
+fingerprint = "sha256:27dafe82277e8b501415aaa0ecac8562f9843d2197e7bd354799d3a7d419bfcd"
+issue = "chore:CUTECANVAS-ARCH-009"
+review_by = 2026-12-15
+responsibilities = [
+  "core component construction and signal wiring",
+  "mask, SAM, and autosave manager attachment",
+  "viewport, navigation, and rendering facade delegation",
+  "cursor, diagnostics, and cache lifecycle",
+]
+next_extraction = "Extract mask, SAM, and autosave attachment, detachment, shutdown, and feature reconciliation into a feature lifecycle owner."

cutecanvas-1.0.0/ARCHITECTURE_WAIVERS.toml

@@ -0,0 +1,249 @@
+schema_version = 1
+product = "cutecanvas"
+
+[[waivers]]
+id = "CUTECANVAS-WAIVER-001"
+issue = "chore:CUTECANVAS-WAIVER-001"
+owner = "CuteCanvas widget boundary"
+rule = "STRUCT003"
+path = "packages/cutecanvas/src/cutecanvas/canvas.py"
+kind = "structural"
+justification = "CuteCanvas is the single mounted-widget boundary that delegates Qt lifecycle and input events and paints the editor's interaction overlays."
+review_by = 2026-12-15
+max_lines = 596
+
+[[waivers]]
+id = "CUTECANVAS-WAIVER-002"
+issue = "chore:CUTECANVAS-WAIVER-002"
+owner = "CuteCanvas composition layers"
+rule = "STRUCT003"
+path = "packages/cutecanvas/src/cutecanvas/composition/layers.py"
+kind = "structural"
+justification = "CompositionLayerStore is the authoritative owner for layer instance state, ordering, indexes, revisions, validation, and change publication."
+review_by = 2026-12-15
+max_lines = 523
+
+[[waivers]]
+id = "CUTECANVAS-WAIVER-003"
+issue = "chore:CUTECANVAS-WAIVER-003"
+owner = "CuteCanvas coverage storage"
+rule = "STRUCT003"
+path = "packages/cutecanvas/src/cutecanvas/coverage/surface.py"
+kind = "structural"
+justification = "CoverageSurface is the authoritative state owner for mutable coverage storage, bounds, revisions, snapshots, writable regions, and representation conversion."
+review_by = 2026-12-15
+max_lines = 637
+
+[[waivers]]
+id = "CUTECANVAS-WAIVER-004"
+issue = "chore:CUTECANVAS-WAIVER-004"
+owner = "CuteCanvas editor composition"
+rule = "STRUCT003"
+path = "packages/cutecanvas/src/cutecanvas/editor/composition_root.py"
+kind = "structural"
+justification = "EditorCompositionRoot has one assembly responsibility: construct, wire, and return the complete authoritative editor component graph from explicit inputs."
+review_by = 2026-12-15
+max_lines = 731
+
+[[waivers]]
+id = "CUTECANVAS-WAIVER-005"
+issue = "chore:CUTECANVAS-WAIVER-005"
+owner = "CuteCanvas composition facade"
+rule = "STRUCT003"
+path = "packages/cutecanvas/src/cutecanvas/facade/composition_api.py"
+kind = "structural"
+justification = "CompositionApiMixin is the single public task-oriented facade for composition state, layer placement, selection, scene inspection, and composition lifecycle."
+review_by = 2026-12-15
+max_lines = 567
+
+[[waivers]]
+id = "CUTECANVAS-WAIVER-006"
+issue = "chore:CUTECANVAS-WAIVER-006"
+owner = "CuteCanvas raster facade"
+rule = "STRUCT003"
+path = "packages/cutecanvas/src/cutecanvas/facade/raster_api.py"
+kind = "remediation"
+justification = "Raster layer, painting, floating-pixel, and edit-history APIs remain mixed pending painting facade extraction."
+review_by = 2026-12-15
+max_lines = 599
+next_limit = 390
+debt = "CUTECANVAS-ARCH-001"
+
+[[waivers]]
+id = "CUTECANVAS-WAIVER-007"
+issue = "chore:CUTECANVAS-WAIVER-007"
+owner = "CuteCanvas mask autosave"
+rule = "STRUCT003"
+path = "packages/cutecanvas/src/cutecanvas/masks/autosave.py"
+kind = "structural"
+justification = "AutosaveManager is the sole lifecycle owner for mask save coalescing, scheduling, request identity, encoding outcomes, retries, cancellation, and save diagnostics."
+review_by = 2026-12-15
+max_lines = 517
+
+[[waivers]]
+id = "CUTECANVAS-WAIVER-008"
+issue = "chore:CUTECANVAS-WAIVER-008"
+owner = "CuteCanvas mask editing"
+rule = "STRUCT003"
+path = "packages/cutecanvas/src/cutecanvas/masks/edit_service.py"
+kind = "remediation"
+justification = "Stroke mutation, epoch, history, and coverage responsibilities remain mixed until history behavior is fully extracted."
+review_by = 2026-12-15
+max_lines = 655
+next_limit = 480
+debt = "CUTECANVAS-ARCH-002"
+
+[[waivers]]
+id = "CUTECANVAS-WAIVER-010"
+issue = "chore:CUTECANVAS-WAIVER-010"
+owner = "CuteCanvas mask presentation cache"
+rule = "STRUCT003"
+path = "packages/cutecanvas/src/cutecanvas/masks/render_cache.py"
+kind = "remediation"
+justification = "Cache, live-preview, background colorization, and regional presentation state remain mixed pending live-preview extraction."
+review_by = 2026-12-15
+max_lines = 1253
+next_limit = 980
+debt = "CUTECANVAS-ARCH-004"
+
+[[waivers]]
+id = "CUTECANVAS-WAIVER-011"
+issue = "chore:CUTECANVAS-WAIVER-011"
+owner = "CuteCanvas mask render work"
+rule = "STRUCT003"
+path = "packages/cutecanvas/src/cutecanvas/masks/render_coordination.py"
+kind = "remediation"
+justification = "Prefetch, snippet, colorize, deferred publication, and diagnostics lifecycles remain mixed pending prefetch extraction."
+review_by = 2026-12-15
+max_lines = 781
+next_limit = 560
+debt = "CUTECANVAS-ARCH-005"
+
+[[waivers]]
+id = "CUTECANVAS-WAIVER-012"
+issue = "chore:CUTECANVAS-WAIVER-012"
+owner = "CuteCanvas mask strokes"
+rule = "STRUCT003"
+path = "packages/cutecanvas/src/cutecanvas/masks/strokes.py"
+kind = "structural"
+justification = "MaskStrokePipeline is the sole state and lifecycle owner for segment submission, constraints, previews, job identity, result settlement, commit, cancellation, and stroke diagnostics."
+review_by = 2026-12-15
+max_lines = 795
+
+[[waivers]]
+id = "CUTECANVAS-WAIVER-013"
+issue = "chore:CUTECANVAS-WAIVER-013"
+owner = "CuteCanvas mask workflow"
+rule = "STRUCT003"
+path = "packages/cutecanvas/src/cutecanvas/masks/workflow.py"
+kind = "remediation"
+justification = "Mask facade, feature lifecycle, undo, SAM, activation, and diagnostics responsibilities remain mixed pending SAM workflow extraction."
+review_by = 2026-12-15
+max_lines = 710
+next_limit = 610
+debt = "CUTECANVAS-ARCH-006"
+
+[[waivers]]
+id = "CUTECANVAS-WAIVER-014"
+issue = "chore:CUTECANVAS-WAIVER-014"
+owner = "CuteCanvas brush interaction"
+rule = "STRUCT003"
+path = "packages/cutecanvas/src/cutecanvas/painting/tools/brush.py"
+kind = "structural"
+justification = "BrushTool is the single interaction owner for pointer samples, stroke smoothing, previews, cursor and overlay feedback, emission, cancellation, and undo admission."
+review_by = 2026-12-15
+max_lines = 631
+
+[[waivers]]
+id = "CUTECANVAS-WAIVER-015"
+issue = "chore:CUTECANVAS-WAIVER-015"
+owner = "CuteCanvas persistence"
+rule = "STRUCT003"
+path = "packages/cutecanvas/src/cutecanvas/persistence/codec.py"
+kind = "remediation"
+justification = "Archive IO, composition encoding, resource codecs, migration, and reference validation remain mixed pending typed resource codec extraction."
+review_by = 2026-12-15
+max_lines = 1069
+next_limit = 980
+debt = "CUTECANVAS-ARCH-007"
+
+[[waivers]]
+id = "CUTECANVAS-WAIVER-016"
+issue = "chore:CUTECANVAS-WAIVER-016"
+owner = "CuteCanvas placed assets"
+rule = "STRUCT003"
+path = "packages/cutecanvas/src/cutecanvas/placed/workflow.py"
+kind = "structural"
+justification = "PlacedAssetWorkflow is the authoritative request lifecycle for embedded, linked, duplicate, reload, relink, embed, cancellation, decode adoption, and failure publication."
+review_by = 2026-12-15
+max_lines = 578
+
+[[waivers]]
+id = "CUTECANVAS-WAIVER-017"
+issue = "chore:CUTECANVAS-WAIVER-017"
+owner = "CuteCanvas workspace presentation"
+rule = "STRUCT003"
+path = "packages/cutecanvas/src/cutecanvas/presentation/workspace.py"
+kind = "structural"
+justification = "CanvasWorkspace is the authoritative mounted-presentation lifecycle for document session layouts, target canvases, comparison surfaces, activation, reconciliation, and teardown."
+review_by = 2026-12-15
+max_lines = 642
+
+[[waivers]]
+id = "CUTECANVAS-WAIVER-018"
+issue = "chore:CUTECANVAS-WAIVER-018"
+owner = "CuteCanvas document events"
+rule = "STRUCT003"
+path = "packages/cutecanvas/src/cutecanvas/runtime/document_events.py"
+kind = "remediation"
+justification = "Document, resource, selection, vector, viewport, and diagnostics event propagation remain mixed pending vector event extraction."
+review_by = 2026-12-15
+max_lines = 595
+next_limit = 440
+debt = "CUTECANVAS-ARCH-008"
+
+[[waivers]]
+id = "CUTECANVAS-WAIVER-019"
+issue = "chore:CUTECANVAS-WAIVER-019"
+owner = "CuteCanvas runtime lifecycle"
+rule = "STRUCT003"
+path = "packages/cutecanvas/src/cutecanvas/runtime/lifecycle.py"
+kind = "remediation"
+justification = "Component construction, feature-manager attachment, viewport delegation, cursor, diagnostics, and cache lifecycles remain mixed pending feature lifecycle extraction."
+review_by = 2026-12-15
+max_lines = 744
+next_limit = 540
+debt = "CUTECANVAS-ARCH-009"
+
+[[waivers]]
+id = "CUTECANVAS-WAIVER-020"
+issue = "chore:CUTECANVAS-WAIVER-020"
+owner = "CuteCanvas SAM execution"
+rule = "STRUCT003"
+path = "packages/cutecanvas/src/cutecanvas/sam/manager.py"
+kind = "structural"
+justification = "SamManager is the sole SAM session owner for predictor preparation, cache limits, native execution requests, cancellation, adoption, mutation, metrics, and shutdown."
+review_by = 2026-12-15
+max_lines = 575
+
+[[waivers]]
+id = "CUTECANVAS-WAIVER-021"
+issue = "chore:CUTECANVAS-WAIVER-021"
+owner = "CuteCanvas vector conversion"
+rule = "STRUCT003"
+path = "packages/cutecanvas/src/cutecanvas/vector/conversion.py"
+kind = "structural"
+justification = "VectorConversionService is the sole request lifecycle for selection conversion, rasterization, text-path conversion, execution admission, adoption, cancellation, and publication."
+review_by = 2026-12-15
+max_lines = 514
+
+[[waivers]]
+id = "CUTECANVAS-WAIVER-022"
+issue = "chore:CUTECANVAS-WAIVER-022"
+owner = "CuteCanvas vector facade"
+rule = "STRUCT003"
+path = "packages/cutecanvas/src/cutecanvas/vector/facade.py"
+kind = "structural"
+justification = "VectorHostFacade is the single public task-oriented boundary for vector document mutation, text editing, selection, masks, conversion, and synchronized publication."
+review_by = 2026-12-15
+max_lines = 545

cutecanvas-1.0.0/CHANGELOG.md

@@ -0,0 +1,7 @@
+# CHANGELOG
+
+<!-- version list -->
+
+## v1.0.0 (2026-08-11)
+
+- Initial Release