canvas-pilot/docs/interfaces/canvas-pilot-clipboard.md

97 lines
5.9 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Canvas Pilot layer clipboard, version 3
Implementation: `clipboard.rs`, `import.rs` and the shared paste review in `gui.rs`.
This is a Canvas Pilot clipboard representation, not a device protocol or a native
clipboard format for other applications. It changes no project/file schema.
## Text envelope
**Copy layer values** and viewport Ctrl/Cmd-C emit the existing readable summary
(center coordinates and dimensions in rounded screen pixels; normal crop zoom as
percent), followed by this exact delimiter:
```text
\n\nCanvas Pilot layer data:\n
```
The escapes above represent actual newlines. The remainder is UTF-8 JSON. The last
literal delimiter identifies the payload; names inside JSON use standard JSON
escaping. The summary is informational: editing it does not override the JSON.
Readers validate the payload and never fall back to rounded geometry when it is
invalid. Raw legacy summaries without this delimiter still use the existing parser.
See the [current example](canvas-pilot-clipboard-v3.example.txt) and
[legacy v2 example](canvas-pilot-clipboard-v2.example.txt) and
[legacy v1 example](canvas-pilot-clipboard-v1.example.txt).
## JSON schema and validation
Objects reject unknown fields. All listed fields are required, including nullable
`fit`. The maximum complete text size is 16 MiB; layers must contain 1–256 entries.
No URLs, file paths, commands, images or arbitrary application state are evaluated.
| Field | Meaning |
| --- | --- |
| `format` | Exactly `canvas-pilot.layers` |
| `version` | Integer `3`; readers also accept `1` and `2`; other versions reject the whole paste |
| `layers` | Ordered array of copied layers; selection order follows document order |
| `layers[].name` | In v2/v3, the actual layer name without an ID prefix; nonblank, at most 256 characters to read, 1–128 to apply. In v1, a review label only |
| `layers[].bounds` | `x`, `y`, `width`, `height`: full-precision screen pixels; top-left coordinates, finite within ±1,000,000 and positive dimensions up to 1,000,000 |
| `layers[].appearance.input_size` | Two positive finite effective source dimensions in pixels, after local input crop; validated by the existing source-size limits |
| `layers[].appearance.crop` | `left`, `right`, `top`, `bottom`: nonnegative finite effective-source pixel crop edges, leaving positive width/height |
| `layers[].appearance.fit` | `null` for normal crop/zoom, or `one_to_one`, `centered`, `fullscreen`, `cropped` |
| `layers[].appearance.mask` | Required `origin`: `layer` or `source`; `left`, `right`, `top`, `bottom`: finite fractions of that reference, each 0–1; opposite sums must be at most 1, with fully blank axes allowed |
Versions 1/2 migrate masks to `origin: "layer"`; supplying `origin` in those
versions is rejected. Version 3 requires the field; unknown origins are rejected.
Normal crop must match the visible-box aspect and supported 1–100 zoom range.
Offsets and zoom are derived from crop and bounds rather than stored twice.
Advanced modes apply crop before fit. Values are not display-rounded in JSON;
mask proportions do not become source-pixel crops.
## Applying a paste
All data enters the existing destination mapping review. Position and Format are
independent. An **Appearance** group offers **Crop & fit** and **Blanking**, enabled
initially for this payload. Appearance-only and name-only pastes are valid. **Rename destination layers** is
off by default, copies v2/v3 names only, and leaves folders/IDs unchanged. External geometry
formats have no such payload; older normal-crop summaries offer their legacy zoom
control instead. Ignored items do not affect availability or mapped values.
Crop & fit requires the destination's effective source dimensions to match the
recorded dimensions within 1e-8 pixels per axis. It copies exact crop and mode;
it does not adapt different inputs silently. Normal-crop aspect must also match
the resulting box. Mismatches block the batch with guidance to include Format,
match the local source dimensions, or disable Crop & fit. Blanking can be applied
independently across different input sizes as proportions of the selected layer/source reference; source mode follows the
destination’s source and crop/fit, rather than copying source pixel distances.
Unchecked appearance fields remain unchanged, except that a selected Format change
may reframe existing crop under the editor's normal resize rules.
Mappings must be unique, visible, unlocked and still refer to the reviewed layer
identities. Apply is atomic and one undo step: malformed data, duplicate mappings,
incompatible crops or invalid masks cannot partially change the document. Device
writes are never part of paste. Copying and opening the review are read-only.
## Omissions and compatibility
Folders, identity, visibility, locks, pivots, source formats,
input crop, shared source relationships, device links, input proposals, captures,
references and workspace settings are not copied by this representation. Only the
recorded source dimensions accompany crop for compatibility validation. Use a
project or embedded export snapshot for the wider state.
Existing normal-crop summaries remain readable, with optional zoom and their
historical integer geometry. Old advanced-container summaries are not upgraded
implicitly because they lack the crop/source information needed to reconstruct
appearance. New copies of all fit modes contain the v2 payload. V1 stays readable for geometry
and appearance; its names may include display ID prefixes and are not offered for
renaming. V1-only readers reject v2 with an unsupported-version error. Older application
versions do not support the appended payload; remove the payload only when
intentionally exchanging the legacy normal-crop geometry/zoom subset.
Regression tests cover every mode, crop offsets, fractional values, masks,
independent appearance controls, legacy summaries, invalid schemas, source/aspect
mismatches, locked destinations, whole-batch rollback and undo/redo.